diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/GlueGen_Mapping.html | 65 | ||||
| -rw-r--r-- | doc/GlueGen_Mapping.md | 37 |
2 files changed, 69 insertions, 33 deletions
diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html index 96c56c5..9739082 100644 --- a/doc/GlueGen_Mapping.html +++ b/doc/GlueGen_Mapping.html @@ -940,6 +940,8 @@ fields</p> <ul> <li>See <a href="#primitive-mapping"><em>Primitive Mapping</em></a> above.</li> +<li>See <a href="#struct-mapping-notes"><em>Opaque and +<code>void*</code> notes</em></a> below.</li> <li>See <a href="#pointer-mapping"><em>Pointer Mapping</em></a> for <em>pointer-to-pointer</em> values above and <a href="#struct-pointer-pointer-support">Struct Pointer-Pointer @@ -969,7 +971,48 @@ function which has to be compiled and its library loaded.</p> <code>public static boolean usesNativeCode()</code> can be used to validate whether the produced Java class requires a corresponding library for additional native code.</p> +<h3 id="struct-mapping-notes">Struct Mapping Notes</h3> +<ul> +<li><p><a href="#opaque-java-primitive-type-symbol"><code>Opaque</code> +configured pointer-types</a> are treated as <code>long</code> values +from the Java side<br /> +while maintaining their architecture dependent pointer size within +native memory.</p></li> +<li><p>Void pointers, i.e. <code>void*</code>, within a struct are +handled as <a +href="#opaque-java-primitive-type-symbol"><code>Opaque</code> configured +pointer-types</a>.</p></li> +<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength +<int></strong> implies <em>native ownership</em> for a +<em>Pointer</em> referenced <em>native</em> memory if the expression is +constant. Otherwise the <em>native</em> memory has <em>java +ownership</em>. See <a +href="#returnedarraylength-symbol-expression">ReturnedArrayLength +Setting</a> below.</p></li> +<li><p>Utilizing a <em>flexible</em> <em>elemCount</em> via +<strong>ReturnedArrayLength getValElements()</strong> renders us unable +to determine ownership of pointer referenced <em>native</em> memory +segment and hence renders ownership <em>mixed or ambiguous</em>, <a +href="#signature-const-int32_t--customsize-ambiguous-java-owned">see +[5]</a>. This is due to the fact, that native code may allocate memory +and writes its <em>elemCount</em> into the designated field +<em>valElements</em>. In such cases, the user being aware of the +underlying API shall utilize <code>setVal(..)</code> and +<code>releaseVal()</code> with care.</p></li> +<li><p>To release native memory with <em>java ownership</em>, i.e. a +native ByteBuffer, <code>releaseVal()</code> can be used.</p></li> +</ul> <h3 id="gluegen-struct-settings">GlueGen Struct Settings</h3> +<h4 id="opaque-java-primitive-type-symbol"><strong>Opaque</strong> +<em>Java-primitive-type</em> <em>symbol</em></h4> +<p>See also <a href="manual/index.html#SecOpaque">Opaque section in +manual</a>.</p> +<ul> +<li><p><code>Opaque long T2_UndefStruct*</code></p> +<p>Pointers to <code>T2_UndefStruct</code> will be handled opaque, i.e. +as <code>long</code> values from the Java side while maintaining their +architecture dependent pointer size within native memory.</p></li> +</ul> <h4 id="immutableaccess-symbol"><strong>ImmutableAccess</strong> <em>symbol</em></h4> <p>Immutable access can be set for a whole struct or a single field of a @@ -1045,28 +1088,6 @@ variants, a <code>String</code> variant will be produced.</p> <p>See <a href="#string-mapping"><em>String Mapping</em></a> above.</p></li> </ul> -<h3 id="struct-mapping-notes">Struct Mapping Notes</h3> -<ul> -<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength -<int></strong> implies <em>native ownership</em> for a -<em>Pointer</em> referenced <em>native</em> memory if the expression is -constant. Otherwise the <em>native</em> memory has <em>java -ownership</em>. See <a -href="#returnedarraylength-symbol-expression">ReturnedArrayLength -Setting</a> above.</p></li> -<li><p>Utilizing a <em>flexible</em> <em>elemCount</em> via -<strong>ReturnedArrayLength getValElements()</strong> renders us unable -to determine ownership of pointer referenced <em>native</em> memory -segment and hence renders ownership <em>mixed or ambiguous</em>, <a -href="#signature-const-int32_t--customsize-ambiguous-java-owned">see -[5]</a>. This is due to the fact, that native code may allocate memory -and writes its <em>elemCount</em> into the designated field -<em>valElements</em>. In such cases, the user being aware of the -underlying API shall utilize <code>setVal(..)</code> and -<code>releaseVal()</code> with care.</p></li> -<li><p>To release native memory with <em>java ownership</em>, i.e. a -native ByteBuffer, <code>releaseVal()</code> can be used.</p></li> -</ul> <h3 id="struct-setter-pseudo-code">Struct Setter Pseudo-Code</h3> <h4 id="overview-1">Overview</h4> <p>In general we have the following few cases</p> diff --git a/doc/GlueGen_Mapping.md b/doc/GlueGen_Mapping.md index 8965dd6..b6a9514 100644 --- a/doc/GlueGen_Mapping.md +++ b/doc/GlueGen_Mapping.md @@ -208,6 +208,7 @@ A *Struct* is a C compound type declaration, which can be mapped to a Java class A *Struct* may utilize the following data types for its fields * *Primitive*, i.e. *char*, *int32_t*, ... * See [*Primitive Mapping*](#primitive-mapping) above. + * See [*Opaque and `void*` notes*](#struct-mapping-notes) below. * See [*Pointer Mapping*](#pointer-mapping) for *pointer-to-pointer* values above and [Struct Pointer-Pointer Support](#struct-pointer-pointer-support) below. * See [*String Mapping*](#string-mapping) above. * *Struct*, i.e. an aggregated or referenced compound variable @@ -226,8 +227,33 @@ call the underlying native function which has to be compiled and its library loa 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](#opaque-java-primitive-type-symbol) are treated as `long` values from the Java side + while maintaining their architecture dependent pointer size within native memory. + +* Void pointers, i.e. `void*`, within a struct are handled as [`Opaque` configured pointer-types](#opaque-java-primitive-type-symbol). + +* *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](#returnedarraylength-symbol-expression) below. + +* Utilizing a *flexible* *elemCount* via **ReturnedArrayLength getValElements()** renders us unable to determine ownership + of pointer referenced *native* memory segment and hence renders ownership *mixed or ambiguous*, [see \[5\]](#signature-const-int32_t--customsize-ambiguous-java-owned). 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. + ### GlueGen Struct Settings +#### **Opaque** *Java-primitive-type* *symbol* + +See also [Opaque section in manual](manual/index.html#SecOpaque). + +* `Opaque long T2_UndefStruct*` + + 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. + #### **ImmutableAccess** *symbol* Immutable access can be set for a whole struct or a single field of a struct. @@ -301,17 +327,6 @@ A direct C code `char` array or indirect array via pointer can be interpreted as See [*String Mapping*](#string-mapping) above. -### Struct Mapping Notes - -* *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](#returnedarraylength-symbol-expression) above. - -* Utilizing a *flexible* *elemCount* via **ReturnedArrayLength getValElements()** renders us unable to determine ownership - of pointer referenced *native* memory segment and hence renders ownership *mixed or ambiguous*, [see \[5\]](#signature-const-int32_t--customsize-ambiguous-java-owned). 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. - ### Struct Setter Pseudo-Code #### Overview In general we have the following few cases |