Mercurial > hg > truffle

comparison graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionInterface.java @ 13895:4731c1a0b1f3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
consolidated GNFI code into graal.hotspot project and cleaned up the documentation and code
author Doug Simon <doug.simon@oracle.com>
date Thu, 06 Feb 2014 18:44:14 +0100
parents e30bae026c93
children fac51a64fda0
comparison
equal deleted inserted replaced
13894:4fa77c58ad8f 13895:4731c1a0b1f3
21 * questions. 21 * questions.
22 */ 22 */
23 package com.oracle.graal.api.code; 23 package com.oracle.graal.api.code;
24 24
25 /** 25 /**
26 * Interface to resolve a {@code NativeFunctionHandle} or a {@code NativeFunctionPointer} to a 26 * Interface to get a {@linkplain NativeFunctionHandle handle} or {@linkplain NativeFunctionPointer
27 * native foreign function and a {@code NativeLibraryHandle} of a library. A 27 * pointer} to a native function or a {@linkplain NativeLibraryHandle handle} to an open native
28 * {@code NativeFunctionPointer} wraps the raw function pointer. A {@code NativeFunctionHandle} is a 28 * library.
29 * callable representation of a native target function in Java.
30 * <p>
31 * To resolve a {@code NativeFunctionHandle}, one has to provide the signature of the native target
32 * function according to the calling convention of the target platform (e.g. Unix AMD64:
33 * {@link "http://www.uclibc.org/docs/psABI-x86_64.pdf"}). The signature contains the type (e.g.
34 * {@code int.class} for a C integer, ( {@code long.class} for a 64bit pointer) of each value, which
35 * is passed to the native target function.
36 */ 29 */
37 public interface NativeFunctionInterface { 30 public interface NativeFunctionInterface {
38 31
39 /** 32 /**
40 * Resolves and returns a library handle. 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.
41 * 35 *
42 * @param libPath the absolute path to the library 36 * @param libPath the absolute path to the library
43 * @return the resolved library handle 37 * @return the resolved library handle
38 * @throws UnsatisfiedLinkError if the library could not be found or opened
44 */ 39 */
45 NativeLibraryHandle getLibraryHandle(String libPath); 40 NativeLibraryHandle getLibraryHandle(String libPath);
46 41
47 /** 42 /**
48 * Resolves the {@code NativeFunctionHandle} of a native function that can be called. Use a 43 * Resolves the function pointer {@code NativeFunctionPointer} of a native function.
49 * {@code NativeFunctionHandle} to invoke the native target function.
50 * 44 *
51 * @param libraryHandle the handle to a resolved library 45 * @param libraries the ordered list of libraries to search for the function
52 * @param functionName the name of the function to be resolved 46 * @param name the name of the function to be resolved
47 * @return a pointer to the native function
48 * @throws UnsatisfiedLinkError if the function could not be resolved
49 */
50 NativeFunctionPointer getFunctionPointer(NativeLibraryHandle[] libraries, String name);
51
52 /**
53 * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
54 * with a given signature. The signature contains the types of the arguments that will be passed
55 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
56 *
57 * @param library the handle to a resolved library
58 * @param name the name of the function to be resolved
53 * @param returnType the type of the return value 59 * @param returnType the type of the return value
54 * @param argumentTypes the types of the arguments 60 * @param argumentTypes the types of the arguments
55 * @return the function handle of the native foreign function 61 * @return the function handle of the native function
62 * @throws UnsatisfiedLinkError if the function handle could not be resolved
56 */ 63 */
57 NativeFunctionHandle getFunctionHandle(NativeLibraryHandle libraryHandle, String functionName, Class returnType, Class[] argumentTypes); 64 NativeFunctionHandle getFunctionHandle(NativeLibraryHandle library, String name, Class returnType, Class... argumentTypes);
58 65
59 /** 66 /**
60 * Resolves the {@code NativeFunctionHandle} of a native function that can be called. Use a 67 * Resolves a function pointer to a {@linkplain NativeFunctionHandle handle} that can be called
61 * {@code NativeFunctionHandle} to invoke the native target function. 68 * with a given signature. The signature contains the types of the arguments that will be passed
69 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
62 * 70 *
63 * @param functionPointer the function pointer 71 * @param functionPointer a function pointer
64 * @param returnType the type of the return value 72 * @param returnType the type of the return value
65 * @param argumentTypes the types of the arguments 73 * @param argumentTypes the types of the arguments
66 * @return the function handle of the native foreign function 74 * @return the function handle of the native function
75 * @throws UnsatisfiedLinkError if the function handle could not be created
67 */ 76 */
68 NativeFunctionHandle getFunctionHandle(NativeFunctionPointer functionPointer, Class returnType, Class[] argumentTypes); 77 NativeFunctionHandle getFunctionHandle(NativeFunctionPointer functionPointer, Class returnType, Class... argumentTypes);
69 78
70 /** 79 /**
71 * Resolves the function pointer {@code NativeFunctionPointer} of a native function. A 80 * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
72 * {@code NativeFunctionPointer} wraps the raw pointer value. 81 * with a given signature. The signature contains the types of the arguments that will be passed
82 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
73 * 83 *
74 * @param libraryHandles the handles to a various resolved library, the first library containing 84 * @param libraries the ordered list of libraries to search for the function
75 * the method wins 85 * @param name the name of the function to be resolved
76 * @param functionName the name of the function to be resolved 86 * @param returnType the type of the return value
77 * @return the function handle of the native foreign function 87 * @param argumentTypes the types of the arguments
88 * @return the function handle of the native function
89 * @throws UnsatisfiedLinkError if the function handle could not be created
78 */ 90 */
79 NativeFunctionPointer getFunctionPointer(NativeLibraryHandle[] libraryHandles, String functionName); 91 NativeFunctionHandle getFunctionHandle(NativeLibraryHandle[] libraries, String name, Class returnType, Class... argumentTypes);
80 92
81 /** 93 /**
82 * Resolves the {@code NativeFunctionHandle} of a native function that can be called. Use a 94 * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
83 * {@code NativeFunctionHandle} to invoke the native target function. 95 * with a given signature. The signature contains the types of the arguments that will be passed
96 * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
84 * 97 *
85 * @param libraryHandles the handles to a various resolved library, the first library containing 98 * @param name the name of the function to be resolved
86 * the method wins
87 * @param functionName the name of the function to be resolved
88 * @param returnType the type of the return value 99 * @param returnType the type of the return value
89 * @param argumentTypes the types of the arguments 100 * @param argumentTypes the types of the arguments
90 * @return the function handle of the native foreign function 101 * @return the function handle of the native function
102 * @throws UnsatisfiedLinkError if the function could not be resolved
91 */ 103 */
92 NativeFunctionHandle getFunctionHandle(NativeLibraryHandle[] libraryHandles, String functionName, Class returnType, Class[] argumentTypes); 104 NativeFunctionHandle getFunctionHandle(String name, Class returnType, Class... argumentTypes);
93 105
94 /** 106 /**
95 * Resolves the {@code NativeFunctionHandle} of a native function that can be called. Use a 107 * Creates a {@link NativeFunctionPointer} from a raw value.
96 * {@code NativeFunctionHandle} to invoke the native target function.
97 * 108 *
98 * @param functionName the name of the function to be resolved 109 * @param rawValue raw function pointer
99 * @param returnType the type of the return value 110 * @return {@code NativeFunctionPointer} for {@code rawValue}
100 * @param argumentTypes the types of the arguments
101 * @return the function handle of the native foreign function
102 */
103 NativeFunctionHandle getFunctionHandle(String functionName, Class returnType, Class[] argumentTypes);
104
105 /**
106 * Creates {@code NativeFunctionPointer} from raw value. A {@code NativeFunctionPointer} wraps
107 * the raw pointer value.
108 *
109 * @param rawValue Raw pointer value
110 * @return {@code NativeFunctionPointer} of the raw pointer
111 */ 111 */
112 NativeFunctionPointer getNativeFunctionPointerFromRawValue(long rawValue); 112 NativeFunctionPointer getNativeFunctionPointerFromRawValue(long rawValue);
113 } 113 }