GlueGen is a compiler
for function and data-structure declarations, generating Java and JNI C
code offline at compile time and allows using native libraries within
your Java application.
It reads ANSI C header files and separate configuration files which
provide control over many aspects of the glue code generation. GlueGen
uses a complete ANSI C parser and an internal representation (IR)
capable of representing all C types to represent the APIs for which it
generates interfaces. It has the ability to perform significant
transformations on the IR before glue code emission.
GlueGen supports registering Java™
callback methods to receive asynchronous and off-thread native
toolkit events, where a generated native callback function dispatches
the events to Java™.
GlueGen is capable to bind low-level APIs such as the Java™ Native
Interface (JNI) and the AWT Native Interface (JAWT) back up to the Java
programming language.
Further, GlueGen supports generating JNI_OnLoad(..) for
dynamic and JNI_OnLoad_<LibraryBasename>(..) for
static libraries via LibraryOnLoad LibraryBasename,
which also provides JVMUtil_GetJNIEnv(..) to resolve the
JNIEnv* as used by Java™ callback
methods.
GlueGen utilizes JCPP, migrated C
preprocessor written in Java™.
Gluegen has build-in types (terminal symbols) for:
type
java-bits
native-bits x32
native bits x64
type
signed
origin
void
0
0
0
void
void
ANSI-C
char
8
8
8
integer
any
ANSI-C
short
16
16
16
integer
any
ANSI-C
int
32
32
32
integer
any
ANSI-C
long
64
32
32†
integer
any
ANSI-C - Windows
long
64
32
64
integer
any
ANSI-C - Unix
float
32
32
32
float
signed
ANSI-C
double
64
64
64
double
signed
ANSI-C
__int32
32
32
32
integer
any
windows
__int64
64
64
64
integer
any
windows
int8_t
8
8
8
integer
signed
stdint.h
uint8_t
8
8
8
integer
unsigned
stdint.h
int16_t
16
16
16
integer
signed
stdint.h
uint16_t
16
16
16
integer
unsigned
stdint.h
int32_t
32
32
32
integer
signed
stdint.h
uint32_t
32
32
32
integer
unsigned
stdint.h
int64_t
64
64
64
integer
signed
stdint.h
uint64_t
64
64
64
integer
unsigned
stdint.h
intptr_t
64
32
64
integer
signed
stdint.h
uintptr_t
64
32
64
integer
unsigned
stdint.h
ptrdiff_t
64
32
64
integer
signed
stddef.h
size_t
64
32
64
integer
unsigned
stddef.h
wchar_t
32
32
32
integer
signed
stddef.h
Warning: Try to avoid unspecified bit sized types,
especially long, since it differs on Unix and
Windows! Notes:
† Type long will result in broken code on Windows,
since we don't differentiate the OS and it's bit size is ambiguous.
Anonymous void-pointer void* are mapped to NIO
Buffer.
Pointers to pointer-size types like intptr_t*,
uintptr_t*, ptrdiff_t* and size_t* are mapped
to PointerBuffer, to reflect the architecture depending storage
size.
Pointer Mapping
Pointer values itself are represented as long
values on the Java side while using the native pointer-size, e.g. 32-bit
or 64-bit, on the native end.
They may simply be accessible via long or
long[] primitives in Java, or are exposed via
com.jogamp.common.nio.PointerBuffer.
FIXME: This might need more flexibility in case UTF-8 is not
suitable for 8-bit wide char mappings or wide characters,
e.g. for UTF-16 needs to be supported.
Function argument String
values
Function argument values are either mapped from char* to
Java String using UTF-8 via JNI function
String value mapping for Struct fields is performed
solely from the Java side using Charset and is hence most
flexible.
By default, UTF-8 is being used for getter and setter of
String values.
The Struct class provides two methods to get and set the used
Charset for conversion
/** Returns the Charset for this class's String mapping, default is StandardCharsets.UTF_8. */
public static Charset getCharset() { return _charset; };
/** Sets the Charset for this class's String mapping, default is StandardCharsets.UTF_8. */
public static void setCharset(Charset cs) { _charset = cs; }
In case the String length has not been configured via
ReturnedArrayLength, it will be dynamically calculated via
strnlen(aptr, max_len).
The maximum length default for the strnlen(..) operation is
8192 bytes and can be get and set using:
/** Returns the maximum number of bytes to read to determine native string length using `strnlen(..)`, default is 8192. */
public static int getMaxStrnlen() { return _max_strnlen; };
/** Sets the maximum number of bytes to read to determine native string length using `strnlen(..)`, default is 8192. */
public static void setMaxStrnlen(int v) { _max_strnlen = v; }
FIXME: This only works reliable using an 8-bit Charset
encoding, e.g. the default UTF-8.
Alignment for Compound Data
In general, depending on CPU and it's configuration (OS), alignment
is set up for each type (char, short, int, long, ..).
Compounds (structures) are aligned naturally, i.e. their inner
components are aligned
and are itself aligned to it's largest element.
A field may be a direct aggregation, i.e. instance, within the struct
including an array or a reference to a single element or array via a
pointer.
Both, primitive, struct and pointer field
type mappings only produce pure Java code, utilizing the GlueGen
Runtime. Hence no additional native code must be compiled nor a
resulting additional library loaded to use the mapping.
Only when mapping function-pointer within structs,
additional native glue-code is produced to call the underlying native
function which has to be compiled and its library loaded.
The generated method
public static boolean usesNativeCode() can be used to
validate whether the produced Java class requires a corresponding
library for additional native code.
Struct Mapping Notes
Opaque
configured pointer-types are treated as long values
from the Java side
while maintaining their architecture dependent pointer size within
native memory.
ConstElemCount via ReturnedArrayLength
<int> implies native ownership for a
Pointer referenced native memory if the expression is
constant. Otherwise the native memory has java
ownership. See ReturnedArrayLength
Setting below.
Utilizing a flexibleelemCount via
ReturnedArrayLength getValElements() renders us unable
to determine ownership of pointer referenced native memory
segment and hence renders ownership mixed or ambiguous, see
[5]. This is due to the fact, that native code may allocate memory
and writes its elemCount into the designated field
valElements. In such cases, the user being aware of the
underlying API shall utilize setVal(..) and
releaseVal() with care.
To release native memory with java ownership, i.e. a
native ByteBuffer, releaseVal() can be used.
Pointers to T2_UndefStruct will be handled opaque, i.e.
as long values from the Java side while maintaining their
architecture dependent pointer size within native memory.
ImmutableAccesssymbol
Immutable access can be set for a whole struct or a single field of a
struct.
Immutable access will simply suppress generating setters in the Java
code and hence also reduces the footprint of the generated Java class
for such struct.
ImmutableAccess TK_Struct
Immutable access for the whole struct `TK_Struct
Sets pseudo-code flag ImmutableAccess, see below.
ImmutableAccess TK_Struct.val
Immutable access for the single field val within struct
TK_Struct
Sets pseudo-code flag ImmutableAccess, see below.
MaxOneElementsymbol
MaxOneElement TK_Struct.val
Sets field pointer val to point to a array with a
maximum of one element and unset initial value (zero elements).
Sets pseudo-code flag MaxOneElement, see below.
ReturnedArrayLengthsymbolexpression
ReturnedArrayLength TK_Struct.val 3
Sets field pointer val to point to a array with three
elements.
Sets pseudo-code flag ConstElemCount, see below.
Having set ConstElemCount also implies native
ownership for a Pointer referenced native
memory.
ReturnedArrayLength TK_Struct.val 1
Sets field pointer val to point to a array with one
element.
Sets pseudo-code flags ConstElemCount and
MaxOneElement, see below.
Having set ConstElemCount also implies native
ownership for a Pointer referenced native
memory.
Sets field pointer val to point to a array with a
variable length as described by the field valElements
retrievable via its getter getValElements().
Sets pseudo-code flag VariaElemCount, see below.
ReturnsStringsymbol
A direct C code char array or indirect array via pointer
can be interpreted as a Java String.
ReturnsString TK_Struct.name
Sets field char-array or char-pointer name to be
additionally interpreted as a Java String. Besides the
byte[] and ByteBuffer getter and setter
variants, a String variant will be added.
Sets field char-array or char-pointer name to be
exclusively interpreted as a Java String. Instead of the
byte[] and ByteBuffer getter and setter
variants, a String variant will be produced.
ConstElemCount: Reuse native memory and store
value with matching elemCount 1, otherwise Exception
VariaElemCount: Reuse native memory and store
value with matching elemCount 1, otherwise allocates new memory
(had elemCount 0)
Array & VariaValue: Reuse native
memory and store value (has const elemCount 1)
else: SKIP setter for const single-primitive
array
AnyElementCount
String & isByteBuffer & Pointer
ConstElemCount: Reuse native memory and store
UTF-8 bytes with EOS with matching elemCount, otherwise
Exception
StringOnly: End, no more setter for this field, otherwise
continue
VariaElemCount: Allocate new native memory and
store UTF-8 bytes with EOS
StringOnly: End, no more setter for this field, otherwise
continue
ConstValue
Pointer
VariaElemCount: Allocates new native memory and
store value
else: SKIP setter for const primitive array
Array | ConstElemCount: Reuse native
memory and store value with <= elemCount, otherwise
Exception
Pointer & VariaElemCount: Reuse
native memory and store value with <= elemCount,
otherwise allocate new native memory
Struct ...
Struct Java Signature Table
Please find below signature table as generated by the C
Declaration including its C Modifier, e.g.
const for constant, [const] for const and
non-const and empty for non-const (variable).
Further, the GlueGen Setting (see above) impacts the code
generation as well.
Below table demonstrates primitive types being mapped within
a struct named TK_Struct. A similar mapping is
produced for struct types, i.e. compounds.
C Mod
C Declaration
Java Setter
Java Getter
GlueGen Setting
Ownership
Remarks
static boolean usesNativeCode()
Java, static, true if using
native code
static int size()
Java, static, native size in
bytes
static TK_Struct create()
Java, static ctor
static TK_Struct create(ByteBuffer)
Java, static ctor w/ existing
ByteBuffer
static TK_Struct derefPointer(long
addr)
Java, static ctor dereferencing
ByteBuffer at native address of size()
Copies the given source elements into the respective field's existing
memory.
Parameters:
src the source array of elements
srcPos starting element position within the source array with
'srcPos >= 0&&srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown
destPos starting element position within the destination with
'destPos >= 0&&destPos + length <=
elemCount`, otherwise an exception is thrown
length the element count to be copied with 'length >=
0&&srcPos + length <=
src.length&&destPos + length <= elemCount`,
otherwise an IndexOutOfBoundsException is thrown
Copies the given source elements into the respective field's existing
memory.
Parameters:
src the source array of elements
srcPos starting element position within the source array with
'srcPos >= 0&&srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown
destPos starting element position within the destination with
'destPos >= 0&&destPos + length <=
elemCount`, otherwise an exception is thrown
length the element count to be copied with 'length >=
0&&srcPos + length <=
src.length&&destPos + length <= elemCount`,
otherwise an IndexOutOfBoundsException is thrown
Returns:
this instance of chaining
Signature
int32_t * FreeSize, Java owned
TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerVariaLen(boolean subset, int[] src, int srcPos, int destPos, int length)
Setter for native field variaInt32PointerVariaLen, referencing a Java
owned array with variable element count of 0 initial elements.
Copies the given source elements into the respective field, either
writing into the existing memory or creating a new memory and
referencing it.
Parameters:
subset if true keeps the underlying memory and only
allows to set up to elemCount elements. Otherwise may
replace the underlying memory if
destPos + length != elemCount.
src the source array of elements
srcPos starting element position within the source array with
'srcPos >= 0&&srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown
destPos starting element position within the destination with
'destPos >= 0. If subset == true, destPos +
length <= elemCountalso must be betrue`. Otherwise an
exception is thrown
length the element count to be copied with 'length >=
0&&srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown
Returns:
this instance of chaining
Signature
const int32_t * FreeSize, Java owned
TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerVariaLen(int[] src, int srcPos, int length)
Setter for native field constInt32PointerVariaLen, referencing a Java
owned array with variable element count of 0 initial elements.
Replaces the respective field's memory with a new memory segment
containing given source elements and referencing it.
Parameters:
src the source array of elements
srcPos starting element position within the source array with
'srcPos >= 0&&srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown
length the element count to be copied with 'length >=
0&&srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown
TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerCustomLen(boolean subset, int[] src, int srcPos, int destPos, int length)
Setter for native field variaInt32PointerCustomLen, referencing a
mixed and ambigously owned (warning) array with variable element count
of getVariaInt32PointerCustomLenElemCount() elements.
Copies the given source elements into the respective field, either
writing into the existing memory or creating a new memory and
referencing it.
Parameters:
subset if true keeps the underlying memory and only
allows to set up to elemCount elements. Otherwise may
replace the underlying memory if
destPos + length != elemCount.
src the source array of elements
srcPos starting element position within the source array with
'srcPos >= 0&&srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown
destPos starting element position within the destination with
'destPos >= 0. If subset == true, destPos +
length <= elemCountalso must be betrue`. Otherwise an
exception is thrown
length the element count to be copied with 'length >=
0&&srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown
TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerCustomLen(int[] src, int srcPos, int length)
Setter for native field constIntxxPointerCustomLen, referencing a
mixed and ambigously owned (warning) array with
variable element count of getConstIntxxPointerCustomLenElemCount()
elements.
Replaces the respective field's memory with a new memory segment
containing given source elements and referencing it.
Parameters:
src the source array of elements
srcPos starting element position within the source array with
'srcPos >= 0&&srcPos + length <= src.length`,
otherwise an IndexOutOfBoundsException is thrown
length the element count to be copied with 'length >=
0&&srcPos + length <= src.length`, otherwise an
IndexOutOfBoundsException is thrown
GlueGen supports function pointers as struct fields,
generating function calls as methods as well function-pointer opaque
getter and setter as long types.
The latter only in case if mutable, i.e. non-const.
This will lead to the following result for
const T2_CustomFuncA customFuncA1
/**
* Getter for native field <code>CustomFuncA1</code>, being a <i>struct</i> owned function pointer.
* <p>
* Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncA' -> int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code>
* </p>
*/
public final long getCustomFuncA1() { .. }
/** Interface to C language function: <br> <code>int32_t CustomFuncA1(void * aptr)</code><br> */
public final int CustomFuncA1(long aptr) { ... }
and similar to T2_CustomFuncB customFuncB1
/**
* Setter for native field <code>CustomFuncB1</code>, being a <i>struct</i> owned function pointer.
* <p>
* Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code>
* </p>
*/
public final T2_InitializeOptions setCustomFuncB1(long src) { .. }
/**
* Getter for native field <code>CustomFuncB1</code>, being a <i>struct</i> owned function pointer.
* <p>
* Native Field Signature <code>(PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer</code>
* </p>
*/
public final long getCustomFuncB1() { .. }
/** Interface to C language function: <br> <code>int32_t CustomFuncB1(T2_UserData * pUserData)</code><br> */
public final int CustomFuncB1(T2_UserData pUserData) { .. }
Java Callback from
Native C-API Support
GlueGen supports registering Java callback methods to receive
asynchronous and off-thread native toolkit events, where a generated
native callback function dispatches the events to Java.
C-API header snippet:
typedef void ( * T2_CallbackFunc01)(size_t id, const char* msg, void* usrParam);
/** Sets the given `cbFunc` and associated `usrParam` as the callback. Passing NULL for `func` _and_ same `usrParam` removes the callback and its associated resources. */
void MessageCallback01(T2_CallbackFunc01 cbFunc, void* usrParam);
void InjectMessageCallback01(size_t id, const char* msg);
and the following GlueGen configuration
# JavaCallback requires `JNI_OnLoad*(..)` and `JVMUtil_GetJNIEnv(..)`
LibraryOnLoad Bindingtest2
ArgumentIsString T2_CallbackFunc01 1
ArgumentIsString InjectMessageCallback01 1
# Define a JavaCallback.
# Set JavaCallback via function `MessageCallback01` if `T2_CallbackFunc01` argument is non-null, otherwise removes the callback and associated resources.
# It uses `usrParam` as the resource-key to map to the hidden native-usrParam object,
# hence a matching 'usrParam' must be passed for setting and removal of the callback.
#
# It uses the function-pointer argument `T2_CallbackFunc01` as the callback function type
# and marks `T2_CallbackFunc01`s 3rd argument (index 2) as the mandatory user-param for Java Object mapping.
#
# Note: An explicit `isMessageCallback01Mapped(Object usrParam)` is being created to explicitly query whether `usrParam` maps to the associated resources.
JavaCallbackDef MessageCallback01 T2_CallbackFunc01 2
Note that LibraryOnLoad Bindingtest2
must be specified in exactly one native code-unit. It provides code to
allow the generated native callback-function to attach the current
thread to the JavaVM* generating a new
JNIEnv*in daemon mode - or just to retrieve the thread's
JNIEnv*, if already attached to the
JavaVM*.
This will lead to the following result
public interface Bindingtest2 {
/** JavaCallback interface: T2_CallbackFunc01 -> void (*T2_CallbackFunc01)(size_t id, const char * msg, void * usrParam) */
public static interface T2_CallbackFunc01 {
/** Interface to C language function: <br> <code>void callback(size_t id, const char * msg, void * usrParam)</code><br>Alias for: <code>T2_CallbackFunc01</code> */
public void callback(long id, String msg, Object usrParam);
}
...
/** Entry point (through function pointer) to C language function: <br> <code>void MessageCallback01(T2_CallbackFunc01 cbFunc, void * usrParam)</code><br> */
public void MessageCallback01(T2_CallbackFunc01 cbFunc, Object usrParam);
public boolean isMessageCallback01Mapped(final Object usrParam);
/** Entry point (through function pointer) to C language function: <br> <code>void InjectMessageCallback01(size_t id, const char * msg)</code><br> */
public void InjectMessageCallback01(long id, String msg);
JavaCallback Constraints
Please consider the following currently enabled constraints
using JavaCallbackDef
Only one interface callback-method binding is allowed for a native
callback function, e.g. T2_CallbackFunc01 (see above).
The native callback function can only return no-value, i.e.
void, or a primitive type. Usually void is
being used in toolkit APIs.
The native callback function argument types must be able to be
mapped to JNI Java types as supported for return values of all native
functions, the same code path is being used within
CMethodBindingEmitter.emitBodyMapCToJNIType(..).
To remove a JavaCallback the specified and mapped setter function,
e.g. MessageCallback01, must be called with
null for the callback interface but the very same
userParam instance as previously called to set the
callback.
LibraryOnLoad <LibraryBasename>
for JNI_OnLoad*(..) ...
LibraryOnLoad <LibraryBasename> generates native
JNI code JNI_OnLoad(..) used for dynamic libraries,
JNI_OnLoad_<LibraryBasename>(..) used for static
libraries, JVMUtil_GetJNIEnv(..) and the instance of
JavaVM* <LibraryBasename>_jvmHandle.
The JNI_OnLoad*(..) methods set the
JavaVM* <LibraryBasename>_jvmHandle, which in turn is
utilized by JVMUtil_GetJNIEnv(..) to attach a new thread to
the JavaVM* generating a new JNIEnv*in daemon
mode - or just to retrieve the thread's JNIEnv*, if already
attached to the JavaVM*.
The LibraryBasename parameter is used to generate the
JNI_OnLoad_<LibraryBasename>(..) variant for
statically linked libraries. JNI_OnLoad(..),
JNI_OnLoad_<LibraryBasename>(..) and
JVMUtil_GetJNIEnv(..)
Platform Header Files
GlueGen provides convenient platform headers,
which can be included in your C header files for native compilation and
GlueGen code generation.
