Table Of Contents

GC and Tuning

Explicitly invoke GC

(Usually you don’t need to explicitly invoke GC as the system will do that automatically when necessary.)


You can invoke GC explicitly by calling HXSystem_gc(), it returns after garbage collection is done.


If you don’t want to wait, call HXSystem_gcNoWait() instead. It will trigger GC and return immediately in multi-threading mode. For single threading, it runs GC in the current thread and returns to caller after the GC is done.

The background collector

Auto-launched in multi-threading

When the system detects more than one thread has started, it creates a background collector thread dedicated to performing garbage collection at the next managed object creation. The background collector thread runs fully concurrently with application threads, it never suspend application threads comparing to other GCs, including those on-the-fly GCs.

When app calls HXSystem_gc() or HXSystem_gcNoWait(), it notifies the background thread to perform GC. If there is no background thread running, then it runs garbage collection in the caller thread.

Manually launch it in single-threading

You can manually enter multi-threading mode before actually starting any new threads. Calling _hnxgc_enter_multithreading() in single threading mode will immediately start the background collector thread.

Automatic GC invocations

The system automatically invokes garbage collection when necessary. Below we are going to discuss this topic.

Triggered at new object creation

When application code calls HnxGC functions, such as for creating a new managed object, the system checks and determines whether it needs a garbage collection. If so, it set a flag and wake up background collector to work, and then it continues.

Once the background collector wakes up and see the flag, it begins garbage collection concurrently with the caller thread and other application threads.

After the completion of garbage collection, the collector thread is back to sleep again.

Triggered for every few moments

Even if there is no new objects created, there may be many live objects become garbage. To collect these objects, the collector thread wakes up periodically. It checks the conditions for garbage collection, runs GC if necessary, and falls back to sleep again.

Triggered at low memory warning

When memory is tight, the operating system issues a warning of low-memory. The background collector will be triggered by this warning, and perform a garbage collection unconditionally.

The threshold of garbage collection

The sytem dynamically adjusts the threshold of garbage collection. For example, at beginning of execution, the threshold might be low to run garbage collection more frequently, because the heap size is small and the initiation cost of HnxGC is very low due to the sucessful removal of suspending applicaton threads.

later, the threshold may increases to run GC less frequently if the result of GC is so little or none. And the threshold may drops if large amount of objects are collected, or on the contrary, when memory is tight.

Please notice that, when the collector is sleeping, there may be many objects reclaimed by reference counting and the usage of memory may drop. That is a point of difference from other pure (non-hybrid) GCs.

Add memory pressure for non-managed data

If a managed object allocates a large amount of non-managed memory, the system may underestimates the urgency of garbage collection. You can call _hnxgc_add_memory_pressure to notify the sytem an extra amount of memory should be taken into account for garbage collection.

For example, you can call _hnxgc_add_memory_pressure() in a managed object constructor and destructor methods for unmanaged memory allocated and owned by the object.

Tailor GC features

Disable Auto-GC temporarily or permanently

You can disable automatic running garbage collection by calling HXSystem_configure with kHXFeature_DisableAutoGC parameter. Once the AutoGC is disable, garbage collection is not triggered at new object creation or periodically by collector thread. This function is safe to be invoked multiple times.

HXSystem_configure(kHXFeature_DisableAutoGC, true); // disable AutoGC

HXSystem_configure(kHXFeature_DisableAutoGC, false); // resume AutoGC


Under AutoGC disabled, explicit calling GC is still performed by background collector thread as usual.

Skip reclaiming objects

Application programs might have bugs. Some types of bugs make app crash when “garbage” were collected by GC. For example, an app creates an unreachable cycle (it exists forever), but still uses them though unretained references. If GC reclaims these types of cycles, app may crash at the next access.

Calling HXSystem_configure with kHXFeature_SkipGCReclamation will stop reclamation of GC collected objects. Unreachable objects are just reported but not reclaimed. Any bugs that access these objects are still working without causing crashes.

Disable others features of iGC

You can also disable some features of iGC via HXSystem_configure. For example,

  • HXSystem_configure(kHXFeature_ManageCocoaArray, false)

    Disable garbage collecting cycles of NSArray, NSMutableArray

  • HXSystem_configure(kHXFeature_ManageCocoaCollection, false)

    Disable garbage collecting NSDictionary, NSSet and their mutable versions.

  • HXSystem_configure(kHXFeature_ManageObjCBlock, false)

    Disable garbage collecting cycles of Block

The above features should not be changed more than once, i.e. these calls should be invoked at HXApplication_initialize() before full initialization of iGC.