Mercurial > hg > graal-jvmci-8

comparison graal/com.oracle.nfi/src/com/oracle/nfi/api/NativeFunctionInterface.java @ 16691:dd8449afc086

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
GNFI: move GNFI interfaces to oracle.nfi - interface does not depend on graal
author Matthias Grimmer <grimmer@ssw.jku.at>
date Tue, 05 Aug 2014 15:58:11 +0200
parents
children e92bc7d8e2dd
comparison
equal deleted inserted replaced
16690:7e8ecfe7d2e5 16691:dd8449afc086
1 /*
2 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 */
23 package com.oracle.nfi.api;
24
25 /**
26 * Interface to get a {@linkplain NativeFunctionHandle handle} or {@linkplain NativeFunctionPointer
27 * pointer} to a native function or a {@linkplain NativeLibraryHandle handle} to an open native
28 * library.
29 */
30 public interface NativeFunctionInterface {
31
32 /**
33 * Resolves and returns a handle to an open native library. This method will open the library
34 * only if it is not already open.
35 *
36 * @param libPath the absolute path to the library
37 * @return the resolved library handle
38 * @throws UnsatisfiedLinkError if the library could not be found or opened
39 */
40 NativeLibraryHandle getLibraryHandle(String libPath);
41
42 /**
43 * Determines if the underlying platform/runtime supports the notion of a default library search
44 * path. For example, on *nix systems, this is typically defined by the {@code LD_LIBRARY_PATH}
45 * environment variable.
46 */
47 boolean isDefaultLibrarySearchSupported();
48
49 /**
50 * Resolves the function pointer {@code NativeFunctionPointer} of a native function.
51 *
52 * @param libraries the ordered list of libraries to search for the function
53 * @param name the name of the function to be resolved
54 * @return a pointer to the native function
55 * @throws UnsatisfiedLinkError if the function could not be resolved
56 */
57 NativeFunctionPointer getFunctionPointer(NativeLibraryHandle[] libraries, String name);
58
59 /**
60 * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
61 * with a given signature. The signature contains the types of the arguments that will be passed
62 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
63 *
64 * @param library the handle to a resolved library
65 * @param name the name of the function to be resolved
66 * @param returnType the type of the return value
67 * @param argumentTypes the types of the arguments
68 * @return the function handle of the native function
69 * @throws UnsatisfiedLinkError if the function handle could not be resolved
70 */
71 NativeFunctionHandle getFunctionHandle(NativeLibraryHandle library, String name, Class<?> returnType, Class<?>... argumentTypes);
72
73 /**
74 * Resolves a function pointer to a {@linkplain NativeFunctionHandle handle} that can be called
75 * with a given signature. The signature contains the types of the arguments that will be passed
76 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
77 *
78 * @param functionPointer a function pointer
79 * @param returnType the type of the return value
80 * @param argumentTypes the types of the arguments
81 * @return the function handle of the native function
82 * @throws UnsatisfiedLinkError the function handle could not be created
83 */
84 NativeFunctionHandle getFunctionHandle(NativeFunctionPointer functionPointer, Class<?> returnType, Class<?>... argumentTypes);
85
86 /**
87 * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
88 * with a given signature. The signature contains the types of the arguments that will be passed
89 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
90 *
91 * @param libraries the ordered list of libraries to search for the function
92 * @param name the name of the function to be resolved
93 * @param returnType the type of the return value
94 * @param argumentTypes the types of the arguments
95 * @return the function handle of the native function
96 * @throws UnsatisfiedLinkError if the function handle could not be created
97 */
98 NativeFunctionHandle getFunctionHandle(NativeLibraryHandle[] libraries, String name, Class<?> returnType, Class<?>... argumentTypes);
99
100 /**
101 * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
102 * with a given signature. The signature contains the types of the arguments that will be passed
103 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
104 *
105 * @param name the name of the function to be resolved
106 * @param returnType the type of the return value
107 * @param argumentTypes the types of the arguments
108 * @return the function handle of the native function
109 * @throws UnsatisfiedLinkError if default library searching is not
110 * {@linkplain #isDefaultLibrarySearchSupported() supported} or if the function
111 * could not be resolved
112 */
113 NativeFunctionHandle getFunctionHandle(String name, Class<?> returnType, Class<?>... argumentTypes);
114
115 /**
116 * Creates a {@link NativeFunctionPointer} from a raw value.
117 *
118 * @param rawValue raw function pointer
119 * @return {@code NativeFunctionPointer} for {@code rawValue}
120 */
121 NativeFunctionPointer getNativeFunctionPointerFromRawValue(long rawValue);
122 }