diff options
Diffstat (limited to 'doc/GlueGen_Mapping.md')
-rw-r--r-- | doc/GlueGen_Mapping.md | 79 |
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 |