aboutsummaryrefslogtreecommitdiffstats
path: root/doc/GlueGen_Mapping.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/GlueGen_Mapping.md')
-rw-r--r--doc/GlueGen_Mapping.md79
1 files changed, 50 insertions, 29 deletions
diff --git a/doc/GlueGen_Mapping.md b/doc/GlueGen_Mapping.md
index 1fbaf39..3105a66 100644
--- a/doc/GlueGen_Mapping.md
+++ b/doc/GlueGen_Mapping.md
@@ -300,7 +300,57 @@ A direct C code `char` array or indirect array via pointer can be interpreted as
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
+* Array owned by parent struct itself
+ * `int32_t val[10]`
+ * Setter of `val` within range, keeping memory
+ * `const int32_t val[10]`
+ * No setter allowed due to const value
+* Referenced Memory (array) owned by Java
+ * `int32_t* val`
+ * Setter within range, keeping memory, or replacing memory
+ * `const int32_t* val`
+ * Setter replacing memory, since memory is non-const but value is const
+* Referenced Memory (array) owned by Native Code due to set *ConstElemCount*
+ * `int32_t* val`
+ * Setter of `val` within range, keeping memory owned by native code
+ * `const int32_t* val`
+ * No setter allowed, since memory is owned by native code and value is const
+
+#### Implemented Pseudo Code
+* *ImmutableAccess*: Drops setter, immutable
+* *Pointer* & *ConstValue* & *ConstElemCount*: Drops setter, native ownership on const-value
+* *Array* & *ConstValue* : Drops setter, const-value array
+* *Primitive*
+ * Single aggregated instance
+ * Store value within *native* memory
+ * *Array* | *Pointer*
+ * *MaxOneElement*
+ * *Pointer*
+ * *ConstValue*: Allocate new memory and store value
+ * *VariaValue*:
+ * *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*,
@@ -487,36 +537,7 @@ A similar mapping is produced for `struct` types, i.e. *compounds*.
Returns:
* this instance of chaining
-### Struct Setter Pseudo-Code
-* *ImmutableAccess*: Drops setter, immutable
-* *Pointer* & *ConstValue* & *ConstElemCount*: Drops setter, native ownership on const-value
-* *Array* & *ConstValue* : Drops setter, const-value array
-* *Primitive*
- * Single aggregated instance
- * Store value within *native* memory
- * *Array* | *Pointer*
- * *MaxOneElement*
- * *Pointer*
- * *ConstValue*: Allocate new memory and store value
- * *VariaValue*:
- * *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* ...
## Platform Header Files