aboutsummaryrefslogtreecommitdiffstats
path: root/doc
Commit message (Collapse)AuthorAgeFilesLines
* doc/GlueGen_Mapping.md: Fix GlueGen Manual read consideration ...Sven Gothel2023-08-142-3/+2
|
* Bug 1449: Fix link style in manual refs ..Sven Gothel2023-08-142-5/+1
|
* Bug 1449: Convert manual/index.html to `gfm` (GitHub-Flavored Markdown) ↵Sven Gothel2023-08-146-2322/+4474
| | | | | | | | using markdown -> manual/index.md and add conversion recipes + make/scripts/md2html_update.sh Noyte: Additionally edited 'doc/misc/macos_nativelib_dependencies.md` to include `Use explicit OpenJDK/Temurin JDK `java` executable path` as a workaround to pass `DYLD_LIBRARY_PATH` to `/usr/bin/java`.
* feat(manual): Update configuration documentation.Féry Mathieu (Mathius)2023-08-131-2/+126
| | | | | | | | | | | | | | | | | Add following configuration : * CustomJNICode * ExtendedInterfaceSymbolsIgnore * ExtendedInterfaceSymbolsOnly * ExtendedImplementationSymbolsIgnore * ExtendedImplementationSymbolsOnly * ExtendedIntfAndImplSymbolsIgnore * ExtendedIntfAndImplSymbolsOnly * MaxOneElement * ParentClass * ReturnsStringOnly Update following configuration : * Extends
* Drop PCPP, GlueGen exclusively uses JCPP; Adopt test case Test{P->J}CPPSven Gothel2023-08-081-63/+16
|
* JavaCallback: Add Mathieu Féry's detailed git comment regarding ↵Sven Gothel2023-08-052-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | 2abb40b0ca9a6a06bdbe3e66b4235301ed15c693; Updated GlueGen_Mapping.md Original comment of commit 2abb40b0ca9a6a06bdbe3e66b4235301ed15c693 wip(test_case): Example of test case for issue related of 927bbc7160a812bb29c0e7120d4a3009bfb13bbf Revised comment taken from unmerged updated branch f6de3646acf0fdadf55708fd8a1c42fbd8663bc5 wip(test_case): Example of test case for issue related of 927bbc7160a812bb29c0e7120d4a3009bfb13bbf Some short summary of modifications : * Add tests with each emitters for test2, but tests are shared and run for each emitters * Update JavaParser.g to allow parsing of bindings generated after test2 processing * Add basic management of generic type (But not yet retrieved inside classTypeSpec args) * Add basic management of annotations (with or w/o parameter(s)) (Retrieved in statement, classes and interfaces but not used) * Align lexer constants in JavaParser.g * Update JavaParser.g to allow fetching all inner classes and inner interfaces to allow excluding by ExtendedInterfaceSymbolsIgnore * Modify JavaConfiguration::requiresJavaCallbackCode because all callback need to force generation not only callback without user param * Functions not generated w/o JavaConfiguration::requiresJavaCallbackCode : * SetLogCallBack12a * SetLogCallBack12b * MessageCallback11b * alBufferCallback0
* Add notes `Loading a MacOS Native Library's Dependencies` and use absolute ↵Sven Gothel2023-08-051-0/+30
| | | | path in unit test script for library-path
* wip(test_case): Example of test case for issue related of ↵Mathieu Féry2023-08-042-2/+2
| | | | | | 927bbc7160a812bb29c0e7120d4a3009bfb13bbf Almost done
* doc/GlueGen_Mapping.md: Shorten UserParamIndex '<0' to disable 'UserParam' ↵Sven Gothel2023-08-042-4/+65
| | | | and produce html page
* doc/GlueGen_Mapping.md: Add some documentation with JavaCallback without ↵Mathieu Féry2023-08-011-2/+68
| | | | userData
* doc/GlueGen_Mapping.md: Using 'UserParamClass' .. grammar (3 commits for 1 ↵rcSven Gothel2023-07-102-3/+3
| | | | | | discount today) Cough cough .. should have reviewed the whole thing once. Must be the summer distraction causing premature commits. Sorry about that :)
* doc/GlueGen_Mapping.md: Typos 'UserParam' -> 'UserParamClass' (2 more ↵Sven Gothel2023-07-102-8/+8
| | | | occassions)
* doc/GlueGen_Mapping.md: Typos 'UserParam' -> 'UserParamClass'Sven Gothel2023-07-102-4/+4
|
* GlueGen JavaCallback: Add optional custom 'Callback-UserParamClass` for ↵Sven Gothel2023-07-102-107/+137
| | | | non-compound `UserParam` types to have more clarity in resulting API
* Manual: Fix ArgumentIsPascalStringSven Gothel2023-07-081-2/+2
|
* GlueGen JavaCallback: Add capability to have UserParam as (part of) keySven Gothel2023-07-082-0/+99
| | | | | | | | | Resolves use case where UserParam reflects e.g. a context (AL_SOFT_events) and will be (part of) the key mapping. Implementation required an additional userParamID -> userParam mapping for default Object/ID usage. Added 2 test cases.
* GlueGen JavaCallback Doc: Remove reasoning (avoiding ambiguity) to ↵Sven Gothel2023-07-062-10/+4
| | | | CallbackFunction parameter index
* GlueGen JavaCallback: Remove ambiguity: Config ↵Sven Gothel2023-07-062-69/+97
| | | | JavaCallbackDef/JavaCallbackKey: Always define both parameter indices; emitJavaStaticCallback(): Use cbFuncBinding and cbFuncKeyIndices from callback parameter to build key
* Manual: Refine `ArgumentIsPascalString`Sven Gothel2023-07-051-3/+3
|
* GlueGen: Add 'PascalString' string semantics (length + value-ptr), added ↵Sven Gothel2023-07-051-0/+13
| | | | | | | | | | | | | | | | | | | | | | | | | prelim code for JavaCallback use-case emitBodyMapCToJNIType() It is common in toolkit APIs that a string might not be passed as a 'nul' terminated (EOS) C string, but as a Pascal string with a given length argument. A C string is specied as ArgumentIsString alEventCallbackInject 3 while allowing multiple indices .. A Pascal string can be specified as ArgumentIsPascalString ALEVENTPROCSOFT 3 4 while allowing multiple indice-tuples for length and value .. The tuple consist of the length agrument-index first (usually an int) followed by the value argument-index (usually a 'char*'). +++ CMethodBindingEmitter.emitBodyMapCToJNIType(), where PascalString is implemented, is currently being used for - JNI return statement (no PascalString impact possible) - JavaCallback C type -> JNI type, PascalString impacting
* GlueGen JavaCallback/LibraryOnLoad: Always include the `libraryBasename` ↵Sven Gothel2023-07-052-39/+61
| | | | agnostic 'emitJNIEnvDecl()' (declaration) in JNI code; Detach the thread from the JVM if newly attach in callback!
* doc/GlueGen_Mapping.md: Quote `void*` correctly ..Sven Gothel2023-07-042-4/+5
|
* GlueGen JavaCallback: Revised: Static Java callback dispatcher, dropping ↵Sven Gothel2023-07-042-65/+464
| | | | | | | | | | | | | | | | | | | | | | | | | native heap, support Struct UserParam ... Implementation now generates a static Java callback dispatcher for each defined SetCallbackFunction, which gets invoked by the generated native static counterpart with all arguments required. The static callback utilizes its own synchronization for thread-safety and fetches the required data set stored at SetCallbackFunction to dispatch the call to the users' CallbackFunction. In case the callback has been removed already, the static callback simply bails out quietly. The native code does not create, release or manage heap memory and therefore is considered safe. +++ Further Struct Type UserParam are now supported including Heterogeneous UserParam mapping (read GlueGen_Mapping.*). +++ Cleaned up code by extracting all JavaCallback emitter code into JavaCallbackEmitter class in one place, leaving JavaMethodbindingEmitter and CMethodbindingEmitter mostly in their original stage (non-convoluted). In this regard, I had to refactor a few function, i.e. moving CMethodbindingEmitter.getJNIMangledArg(..) into JavaType.appendDescriptor(..) and JavaType.appendJNIDescriptor(..) while reusing the toJNIMethodDescriptor(..) conversion. Test4JavaCallback covers and passes all cases.
* doc/GlueGen_Mapping.md: TypoSven Gothel2023-07-022-2/+2
|
* GlueGen JavaCallback: Emphasize all methods are thread-safeSven Gothel2023-07-022-2/+3
|
* GlueGen JavaCallback: Use `SetCallback-KeyClass` if manually specified, even ↵Sven Gothel2023-07-012-9/+9
| | | | if no keys are defined!
* GlueGen JavaCallback: Only produce default 'Key' class if keys are used, ↵Sven Gothel2023-07-012-100/+178
| | | | | | | | | | | expose 'Key' to public and use it. Expose release*() and get*Keys() methods Further we use a dedicated lock Object used in the Java implementation. TODO: Native static callback dispatch code shall - (also) acquire the lock - handle case where the data has been released already to render this solution thread-safe and data-race free
* GlueGen Intro: Add section about its comprehensive runtime library, shorten ↵Sven Gothel2023-07-012-16/+40
| | | | the JNI_OnLoad section
* GlueGen JavaCallback: Resolve key mapping of callback and associated ↵Sven Gothel2023-06-302-52/+518
| | | | | | | | | | | | | | | | resources via 'JavaCallbackKey' config and custom `SetCallback-KeyClass` Updated unit test and doc accordingly. Unit tests handle OpenAL's AL_SOFT_callback_buffer and AL_SOFT_events. Tested global scope (no key, default) and 1 key (default) and 1 key (custom class). Added more query functions, which all only take the `SetCallbackFunction` key arguments as specified. Cleaned up JavaCallback* config class field naminig scheme. Added 'synchronized (..Map) { }' block in crucial `SetCallbackFunction`, rendering implementation thread safe.
* Doc intro: Fix LibraryOnLoad using generic LibraryBasenameSven Gothel2023-06-292-2/+2
|
* Doc: Align GlueGen_Mapping.md intro w/ README.md and www/index.htmlSven Gothel2023-06-292-14/+14
|
* GlueGen JavaCallback: 1st Working Draft: Changed 'JavaCallbackDef' config, ↵Sven Gothel2023-06-292-62/+253
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | added code generation incl. native to Java dispatch and resource management Tested via Test4JavaCallback.java (using test2.[hc]). Please read the GlueGen_Mapping.md as well as Test4JavaCallback.java . +++ Some implementation details: JavaConfiguration maps JavaCallbackDef to JavaCallback set-function and maintains a list. JavaCallbackDef itself holds all configured details. JavaConfiguration also maps JavaCallbackInfo to JavaCallback set-function. JavaCallbackInfo itself holds all compile time information, as produced by JavaEmitter.beginFunctions(..). This extends JavaCallbackDef and avoid repetetive computation for the callback-function-type and its MethodBinding, parameter indices for the callback interface and userParam, etc. CMethodBindingEmitter: Native callback to Java dispatch - The JavaCallback setter function creates a native 'UserParam' struct instance, which holds the callback-interface-jobject, its callback-jmethodID and the userParam-jobject for invocation of the actual JavaCallback interface method. - To produce the C-Type -> JNI-Type conversion, An internal CMethodBindingEmitter instance for the native-callback function binding is created inside the CMethodBindingEmitter of the callback setter method. It is being used to map the types to JNI within the generated native callback function, passed to the actual JavaCallback method. JavaMethodBindingEmitter: Native callback to Java dispatch - The JavaCallbacl setter passes the callback-interface-object, the userParam-object and the callback-method-signature (to have the native method retrieve the jmethodID). - It receives the native pointer of the native `UserParam` struct instance, which gets mapped to the userParam-object. (*TODO: Refine ownership + release*).
* GlueGen LibraryOnLoad Config: Generate `JNI_OnLoad(..)` for dynamic and ↵Sven Gothel2023-06-291-1/+16
| | | | `JNI_OnLoad_<LibraryBasename>(..)` for static libraries and `JVMUtil_GetJNIEnv(..)` to resolve the `JNIEnv*` as used by JavaCallback
* GlueGen doc/GlueGen_Mapping.md: Mentiond OO-Style API mapping and add ↵Sven Gothel2023-06-291-3/+74
| | | | section for it
* GlueGen Struct [17]: Handle void pointers, i.e. `void*`, within a struct as ↵Sven Gothel2023-06-292-33/+69
| | | | | | `Opaque` configured pointer-types .. includes cross-ref'ed doc and unit test
* GlueGen JavaCallback: Add more related documentationSven Gothel2023-06-252-4/+62
|
* GlueGen Struct [16]: Add support for pointer-pointer and function-pointer valuesSven Gothel2023-06-232-18/+161
| | | | See documentation and unit test test2.h, Test2FuncPtr.java and Test3PtrStorage.java
* GlueGen Struct [15b]: FunctionPointer: Drop is<FuncName>Null() -> use ↵Sven Gothel2023-06-202-89/+26
| | | | get<FuncName>()
* GlueGen Struct [15]: Add FunctionPointer getter and setter support w/ ↵Sven Gothel2023-06-202-75/+307
| | | | documentation
* doc/GlueGen_Mapping.md: Place `Struct Setter Pseudo-Code` above 'Signature ↵Sven Gothel2023-06-201-29/+50
| | | | Table' and add a brief signature to mapping description to the former
* Doc: Manual: Adding disclaimer being slightly outdated and hint to ↵Sven Gothel2023-06-181-0/+5
| | | | GlueGen_Mapping document
* GlueGen Struct [14]: Update doc/GlueGen_Mapping.mdSven Gothel2023-06-182-24/+151
| | | | Completing a few cases and fix some signatures in table
* Bring back produced html5 standalone files, having fixed pandoc usage.Sven Gothel2023-06-182-0/+2157
| | | | | | | See my pandoc-buttondown git repo <https://jausoft.com/cgit/users/sgothel/pandoc-buttondown-cgit.git/about/> Latest config <https://jausoft.com/cgit/users/sgothel/pandoc-buttondown-cgit.git/commit/?id=fb38ada0c8d71a2b26bd3ee9d075acce84d76b2c> fixed creation of standalone html5 files.
* GlueGen Struct [13]: Adopt GlueGen_Mapping.md to changes, added `Struct Java ↵Sven Gothel2023-06-181-66/+113
| | | | Signature Examples` w/ Java API Doc snippets
* Drop .md -> .html generated docs (ugly), use our cgit md -> html via refined ↵Sven Gothel2023-06-172-1238/+0
| | | | | | pandoc styles Would need to fix my standalone pandoc setup to produce proper standalone docs.
* doc/GlueGen_Mapping.md: Remove note regarding shrinking array, resolvedSven Gothel2023-06-172-9/+0
|
* doc/JogAmpMacOSVersions.html: Replaced w/ standalone html5 w/ header (utf8)Sven Gothel2023-06-171-405/+21
|
* GlueGen Struct [8]: Revised setter (resolved shrinking array, using 'subset' ↵Sven Gothel2023-06-172-412/+166
| | | | | | | | | | | | | | | | | | | | | | flag), added (detailed) JavaDoc in generated code Revised setter: A) int32_t val[10] -> setter for a subset change only, as-is with args[src, srcPos, destPos, length] - no new memory, reuse only - no special action to be performed B) int32_t* val -> setter with toggle 'subset' with args[subset, src, srcPos, destPos, length], - replace memory w/ 'subset==false' where it also may copy 'destPos' gap from old -> new - reuse memory w/ 'subset==true', where destPos+length <= elementCount C) const int32_t* val -> setter to replace referenced memory only args[src, srcPos, length] - always replaces memory, no copy of a gap (no destPos) Hence: - case (A) stays as is - case (B) will be revised and argument 'boolean subset' added - case (C) will be revised (simplified) and argument 'destPos' removed
* GlueGen Struct [5]: Revised Struct Mapping + DocumentationSven Gothel2023-06-164-1/+2349
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | GlueGen Revised Struct Mapping (esp pointer to array or single element), Struct String Charset, .. and Documentation - Documentation: - Added README.md Let's have a proper face for the git repo - Added doc/GlueGen_Mapping.md (and its html conversion doc/GlueGen_Mapping.html) Created a new document covering application and implementation details suitable for users/devs. - Added doc/JogAmpMacOSVersions.md conversion to doc/JogAmpMacOSVersions.html - Updated www/index.html - Use *CodeUnit instead of PrintWriter, representing a Java or C code unit covering a set of functions and structs. The CCodeUnit also handles common code shared by its unit across functions etc. - Dropping 'static initializer', as its no more required due to simplified `JVMUtil_NewDirectByteBufferCopy()` variant. - Revised Struct Mapping: - Pure Java implementation to map primitive and struct fields within a struct by utilizing ElementBuffer. Only 'Function Pointer' fields within a struct require native code. Exposes `static boolean usesNativeCode()` to query whether native code is used/required. - Transparent native memory address API Expose `long getDirectBufferAddress()` and `static TK_Struct derefPointer(long addr)`, allowing to - pass the native struct-pointer with native code - reconstruct the struct from a native struct-pointer - have a fully functional `TK_Struct.derefPointer(struct.getDirectBufferAddress())` cycle. - Add 'boolean is<Val>Null() to query whether a pointer (array) is NULL - *Changed* array get/set method for more flexibility alike `System.arraycopy(src, srcPos, dest, destPos, len)`, where 'src' is being dropped for the getter and 'dest' is being dropped for the setter as both objects are reflected by the struct instance. - *Changed* `get<Val>ArrayLength()` -> `get<Val>ElemCount()` for clarity - Considering all ConstElemCount values with config 'ReturnedArrayLength <int>' to be owned by native code -> NativeOwnership -> Not changing the underlying memory region! JavaOwnership is considered for all pointer-arrays not of NativeOwnership. Hence any setter on a NativeOwnership pointer-array will fail with non-matching elem-count. - Add 'release<Val>()' for JavaOwnership pointer-arrays, allowing to release the Java owned native memory incl. null-ing pointer and set<Val>ElemCount(0). - Support setter for 'const <type>*' w/ JavaOwnership, i.e. pointer to const value of a primitive or struct, setter and getter using pointer to array or single element in general. - Added Config `ImmutableAccess symbol` to disable all setter for whole struct or a field - Added Config `MaxOneElement symbol` to restrict a pointer to maximum one element and unset initial value (zero elements) - Added Config `ReturnsStringOnly symbol` to restrict mapping only to a Java String, dropping the ByteBuffer variant for 'char' - String mapping default is UTF-8 and can be read and set via [get|set]Charset(..) per class. - Dynamic string length retrieval in case no `ReturnedArrayLength` has been configured has changed from `strlen()` to `strnlen(aptr, max_len)` to be on the safe site. The maximum length default is 8192 bytes and can be read and set via [get|set]MaxStrnlen(..) per class. FIXME: strnlen(..) using EOS byte non-functional for non 8-bit codecs like UTF-8, US-ASCII. This is due to e.g. UTF-16 doesn't use an EOS byte, but interprets it as part of a code point. - TODO: Perhaps a few more unit tests - TODO: Allow plain 'int' to be mapped in structs IFF their size is same for all MachineDescriptions used. Currently this is the case -> 4 bytes like int32_t.
* doc/JogAmpMacOSVersions.md: Fix 'Build node 12.6.5' row (11 -> 12)Sven Gothel2023-05-151-2/+2
|
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-01 10:36:53 +0000