Crystal FFI to C library: who owns a Crystal object pointer retained by C?

Answer

No, Crystal's Boehm GC does not automatically scan C-allocated memory for references to Crystal heap objects. If a C library retains a pointer to a Crystal object beyond the scope of the initial FFI call, that object is eligible for collection unless it is also referenced by the Crystal stack or heap. To prevent premature collection, you must explicitly register the pointer as a root using the Boehm GC API or copy the necessary data into C-managed memory.

Implementation Options

1. Registering a GC Root

Since Crystal does not provide a high-level pinning API, you must use the underlying Boehm GC functions in your C code. Use GC_add_root_ptr to tell the collector that the pointer is a valid root, and GC_remove_root_ptr when the C library is finished with the object.

#include <gc.h>

void store_crystal_object(void *obj) {
    // Mark the pointer as a root so the GC doesn't collect it
    GC_add_root_ptr(obj);
    // Store obj in your C structure/global
}

void release_crystal_object(void *obj) {
    // Remove the root to allow the GC to reclaim the memory
    GC_remove_root_ptr(obj);
}

2. Copying Data

If the C library only needs specific values rather than a live reference to a Crystal object, copying the data into a C struct is the safest approach. This removes the dependency on the Crystal GC entirely for that specific piece of data.

Comparison of Strategies

Strategy	Pros	Cons
GC Rooting	No data duplication; object stays live.	Risk of memory leaks if not deregistered; GC root set corruption if pointer is freed.
Data Copying	Complete isolation from GC; safer memory boundaries.	Overhead of copying; data may become stale if Crystal object is mutated.

Verification and Safety

To verify the behavior on Linux (Crystal 1.x), you can implement a test case using a finalizer:

1. Create a Crystal object with a finalizer that prints a log message.
2. Pass the object to C and call GC_add_root_ptr.
3. Trigger a collection via GC_collect_a_little; the finalizer should not run.
4. Call GC_remove_root_ptr and trigger collection again; the finalizer should now run.

Critical Warning: Never call free() on a pointer registered via GC_add_root_ptr, and ensure the root is removed before the C memory holding that pointer is reallocated, as this will corrupt the GC's internal root set.

Diagnostic Detail: Does the C library store this pointer in a global variable or a dynamically allocated structure? This determines whether you need a single global root or multiple dynamic roots.