Free sd_ctx_t at process exit before ggml-metal teardown, and a one-argument way to clear the progress callback #10

Release triage — 2026-10-05

Priority: P1 · production macOS lifecycle correctness. Flutter macOS quit with an image model loaded reaches ggml-metal's static destructor with live buffers and aborts; an unhandled Dart error during load or generation aborts the VM through the progress callback. The Dart finalizer repair in leehack/llamadart#823 covers only orderly isolate shutdown. Mirror of leehack/llamadart-native#96; reuse its registry design once that lands rather than designing a second one.

Release disposition: resolve the production quit path, or record an explicit owner-approved limitation with the onExitRequested disposal workaround and its qualified scope. Debug hot restart is a separate acceptance case.

Acceptance: normal context disposal, idle loaded-model quit, quit during new_sd_ctx/generate_image, repeated create/free, hot restart then quit; bounded coordination, no free under an active native call, no double free, no hanging exit; and a one-argument progress-callback clear (or native no-op sink) so no Dart callback is invoked after VM shutdown. This triage reviewed the existing reproduction evidence; it did not rerun the crash.

Need

Two exports that llamadart can call from Dart FFI, each a plain C function taking at most one pointer argument:

1. A way to free every live sd_ctx_t during C exit(), before ggml-metal's static device destructor runs, when the process exits without shutting its Dart isolates down.
2. A one-argument (or zero-argument) function that clears the process-wide progress callback, for example void sd_dart_clear_progress_callback(void *). llamadart can then attach it as a NativeFinalizer on the isolate that owns the progress callback.

Why

On macOS Metal, exit → __cxa_finalize_ranges → ggml_metal_device_free → ggml_metal_rsets_free aborts with GGML_ASSERT([rsets->data count] == 0) while an image model is loaded.

leehack/llamadart#823 frees the context from a NativeFinalizer when the image worker isolate shuts down. That covers plain Dart programs that return from main or throw. Two paths remain open:

• Flutter macOS quit and hot restart (macOS Metal: quitting after a Flutter hot restart aborts on models the discarded isolate loaded llamadart#813): no isolate is shut down, so the Dart side gets no chance to free the context. The crash report shows frames in libstable-diffusion.dylib under -[NSApplication terminate:]. The same need is filed for llama.cpp in Free remaining llama.cpp objects at process exit before ggml-metal teardown (Flutter quit, hot restart) llamadart-native#96.
• Unhandled error during a generation: llamadart routes progress to a NativeCallable.listener. When main dies mid-generation, generate_image keeps calling that callback while the VM shuts down, and the VM aborts with GetFfiCallbackMetadata called after shutdown. Reproduced 3 of 3 times with SDXS 512x512. With (2), llamadart would clear the callback when the calling isolate shuts down, which happens before the VM stops accepting callbacks.

Constraints

• The atexit-time free must not free a context while a worker thread is inside generate_image or new_sd_ctx. It can wait with a bound, or skip.
• Contexts freed normally must be untracked, so they are never freed twice.