Question: thread safety and correct usage of mono_gc_reference_queue_* APIs when embedding Mono (rare crash)

[ffbh123456]

I’m embedding Mono and using the reference queue APIs to track when managed C# objects become unreachable so I can clean up associated native resources.

Specifically, I’m using:
mono_gc_reference_queue_new
mono_gc_reference_queue_add
mono_gc_reference_queue_free

I would like to know how to use these APIs when embedding Mono.
In my case, all three APIs are called directly from my main thread when needed and encounter below crash (rare).

thread_start
GC_start_routine
start_wrapper
start_wrapper_internal
finalizer_thread
reference_queue_process_all
malloc_report
malloc_vreport

malloc: *** error for object 0x600002ea4635:
pointer being freed was not allocated

[ffbh123456]

From what I see,
mono_gc_reference_queue_add does not appear to be thread-safe for direct calls from my main thread.

In my main thread, the call sequence is:
mono_gc_reference_queue_add → mono_gc_reference_queue_add_internal → ref_list_push

Meanwhile, the GC finalizer created by Mono itself runs in another thread with the following calls:
finalizer_thread → mono_runtime_do_background_work → reference_queue_process_all → reference_queue_process → ref_list_remove_element

In ref_list_remove_element, there is also a comment mentioning an issue when the head changes concurrently:
/* Guard if head is changed concurrently. */

[ffbh123456]

I’d like to implement this mechanism myself using the weak ref API. Could you confirm if these three APIs are safe to call from my main thread?

• mono_gchandle_new_weakref_v2
• mono_gchandle_get_target_v2
• mono_gchandle_free_v2

[SkyDevLab]

Here is the concrete runtime breakdown regarding mono_gc_reference_queue_* concurrency and the weak reference alternatives:

1. Is mono_gc_reference_queue_add Thread-Safe?

No, calling mono_gc_reference_queue_add concurrently with Mono's background finalizer processing is not safe.

In src/mono/mono/metadata/gc.c:

• mono_gc_reference_queue_add_internal enqueues items using ref_list_push(&queue->queue, entry).
• Meanwhile, the runtime finalizer thread (finalizer_thread -> reference_queue_process_all -> reference_queue_process) iterates through queue->queue and unlinks entries via ref_list_remove_element(iter, entry) before invoking g_free(entry).
• Although ref_list_push uses mono_atomic_cas_ptr at the head, ref_list_remove_element modifies interior pointers while iterating:

  while (*prev != element)
      prev = &(*prev)->next;

  Concurrent pushes and removals on this singly-linked list are vulnerable to classic concurrent deletion and ABA corruption. When list pointers are corrupted, reference_queue_process passes an invalid or already-freed node address to g_free(entry), directly triggering the malloc: pointer being freed was not allocated crash you observed.
• Furthermore, mono_gc_reference_queue_add is marked MONO_EXTERNAL_ONLY_GC_UNSAFE. If your native main thread is not attached to the Mono runtime, invoking this function violates GC state transition invariants.

---

2. Are mono_gchandle_*_v2 Weak Reference APIs Thread-Safe?

Yes, the mono_gchandle_*_v2 family is thread-safe, provided one prerequisite is met:

• Prerequisite (Thread Attachment): Your native main thread must be attached to the Mono runtime by calling:

  MonoThread *mono_thread = mono_thread_attach (mono_domain_get());

  If an unmanaged thread calls Mono GC handle APIs without attaching, the runtime cannot coordinate cooperative GC suspension, leading to deadlocks or assertion failures.
• Internal Synchronization: In src/mono/mono/metadata/mono-gc.c / sgen-mono.c, handle allocation and deallocation (mono_gchandle_new_weakref_v2, mono_gchandle_get_target_v2, mono_gchandle_free_v2) acquire the internal handle table lock (mono_gc_handle_lock). You can safely allocate and free weak handles from your main thread while the finalizer or worker threads operate concurrently.

---

Recommended Pattern for Native Resource Tracking

If you manage object lifecycle tracking manually:

1. Ensure your thread is attached: mono_thread_attach(domain);
2. Store a weak handle: uint32_t handle = mono_gchandle_new_weakref_v2(obj, FALSE);
3. Periodically or on update ticks, query the target: MonoObject *target = mono_gchandle_get_target_v2(handle);
4. If target == NULL, the object has been collected: free your associated native resources, and release the handle via mono_gchandle_free_v2(handle).