target-openfl-native

OpenFL/Lime Native (hxcpp) — Gotchas & Pitfalls

See references/ for build config and version notes.

Versions

Reference baseline (verify against current toolchain): OpenFL 9.5.0, Lime 8.3.0. Android: NDK r28c, SDK 35 (JDK 17+), 16KB alignment. Default Android archs: ARM64 + x86_64 (ARMv7 removed). iOS: ARM64 only.

hxcpp GC ↔ C++ Interop

GC roots — heap-stored Haxe objects are invisible to GC

GC scans the stack, not the C++ heap. Storing a Haxe object in a C++ member → premature collection.

// WRONG — invisible to GC
class NativeHelper { value myHaxeObj; };

// RIGHT
class NativeHelper {
    AutoGCRoot *root;
    NativeHelper(value obj) { root = new AutoGCRoot(obj); }
    value get() { return root->get(); }
};

@:unreflective suppresses GC scanning

@:unreflective on a field prevents GC from tracing it. Only use on fields with native C++ types, never on fields holding Haxe objects.

Moving GC (HXCPP_GC_MOVING)

Invalidates raw C++ pointers to Haxe objects after collection. Also shows erratic memory growth during long load/unload cycles — may exceed non-moving GC over time.

Pointer Types

Type	C++	GC?	Use case
cpp.RawPointer<T>	T*	No	Native C++ function params
cpp.Pointer<T>	wrapper	Yes	Dynamic typing, array indexing
cpp.Star<T>	T* typedef	No	Extern signatures
cpp.Reference<T>	T&	No	C++ reference params

addressOf() on Dynamic → pointer to stack wrapper, NOT the object. Crashes after stack frame changes.

Threading

Foreign threads MUST register with GC

void foreign_thread_func() {
    int stackTop;
    SetTopOfStack(&stackTop, true);  // MUST be stack variable, not heap
    // ... use hxcpp APIs ...
    SetTopOfStack(0, false);
}

Blocking operations need GC-free zone

GC is stop-the-world. Blocking without GC-free zone deadlocks entire GC. This includes mutex waits — Thread A holds mutex, GC triggers on Thread B, deadlock.