module
UI::JNI
Overview
Factory methods for creating NativeHandle instances that wrap JNI objects.
JNI has two kinds of object references:
-
Local refs: Valid only within the current native method call or
PushLocalFrame/PopLocalFramescope. Automatically freed when the scope ends. Crystal does NOT need to manage these. -
Global refs: Created via
NewGlobalRef, valid across native calls until explicitly freed withDeleteGlobalRef. Crystal MUST manage these.
NativeHandle only wraps global refs, because local refs have scoped
lifetimes that do not need GC safety nets.
All factories are gated behind flag?(:android) to ensure zero JNI code
compiles on non-Android platforms.
Defined in:
ui/native/jni_handle.crClass Method Summary
-
.global(env : Pointer(Void), local_ref : Pointer(Void), label : String | Nil = nil) : NativeHandle
Promote a JNI local ref to a global ref and wrap it in a
NativeHandle. -
.wrap_global(global_ref : Pointer(Void), label : String | Nil = nil) : NativeHandle
Wrap an existing JNI global ref that was already promoted externally.
Class Method Detail
Promote a JNI local ref to a global ref and wrap it in a NativeHandle.
This calls NewGlobalRef(env, local_ref) to create a durable reference,
then wraps the result with JNIGlobalRef strategy. The local ref is NOT
deleted -- the caller or the enclosing local frame will handle that.
The env pointer is needed for the NewGlobalRef call but is NOT stored
in the handle. JNI global refs must be deleted with a valid JNIEnv*
at release time -- this is handled by NativeView, which stores the env.
Wrap an existing JNI global ref that was already promoted externally.
Use this when the global ref was created by Java code or another native
method and passed to Crystal. Crystal takes ownership and will call
DeleteGlobalRef on release.