From f70b43a543e05ff239499752a8cd4e55da7e8f1e Mon Sep 17 00:00:00 2001 From: Joseph Cloutier Date: Fri, 3 Jun 2022 18:04:32 -0400 Subject: [PATCH] Explain `ForegroundWorker`'s main use case. --- src/lime/system/ForegroundWorker.hx | 2 ++ src/lime/system/JNI.hx | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/src/lime/system/ForegroundWorker.hx b/src/lime/system/ForegroundWorker.hx index 084f48ad0..984ea2d56 100644 --- a/src/lime/system/ForegroundWorker.hx +++ b/src/lime/system/ForegroundWorker.hx @@ -14,6 +14,8 @@ import neko.vm.Thread; /** An object whose instance functions always run on the main thread. If called from any other thread, they'll switch to the main thread before proceeding. + This is important for Android apps that use JNI, as most times a Java class + calls a Haxe function, it does so on the UI thread. Usage: diff --git a/src/lime/system/JNI.hx b/src/lime/system/JNI.hx index e1944d3cc..1d240aff3 100644 --- a/src/lime/system/JNI.hx +++ b/src/lime/system/JNI.hx @@ -3,6 +3,24 @@ package lime.system; #if (!lime_doc_gen || android) import lime._internal.backend.native.NativeCFFI; +/** + The Java Native Interface (JNI) allows C++ code to call Java functions, and + vice versa. On Android, Haxe code compiles to C++, but only Java code can + access the Android system API, so it's often necessary to use both. + + For a working example, run `lime create extension MyExtension`, then look at + MyExtension.hx and MyExtension.java. + + You can pass Haxe objects to Java, much like any other data. In Java, + they'll have type `org.haxe.lime.HaxeObject`, meaning the method that + receives them might have signature `(Lorg/haxe/lime/HaxeObject;)V`. Once + sent, the Java class can store the object and call its functions. + + Note that most Java code runs on a different thread than Haxe, meaning that + you can get thread-related errors in both directions. Java functions can + use `Extension.callbackHandler.post()` to switch to the UI thread, while + Haxe code can avoid the problem using `lime.system.ForegroundWorker`. +**/ #if !lime_debug @:fileXml('tags="haxe,release"') @:noDebug