GC Internals API

This page describes an internal API intended to separate two components of the Mozilla 2 garbage collector: the (jemalloc-based) allocator and the GC engine which runs atop it. (Both pieces also provide other public APIs, described at GC API.)

/* APIs for marking */

/* Begin the process of mark/sweep: after this call, gc_is_marked should
   return GC_UNMARKED for all allocations */
void gc_begin_mark(gcheap *heap);

/* @param object must be the outermost pointer to the allocation */
void gc_mark_object(gcheap *heap, void *object);

/* Get the "next" object which has been marked but not yet processed.
   The GC engine needs to know about the object layout, but I don't know
   the best way to expose this (or whether the allocator ought to do that?) */
void * gc_get_next_unprocessed(gcheap *heap, some_kind_of_layout_object);

typedef enum gcmarkstate {
  GC_NOT_GCOBJECT, /* this pointer is not a gc allocation */
  GC_UNMARKED,
  GC_MARKED,     /* gc_mark_object, but not yet gc_get_next_unprocessed */
  GC_PROCESSED   /* processed by gc_get_next_unprocessed */
} gcmarkstate;

/* @param object must be an exterior pointer to an object in this heap */
gcmarkstate gc_get_markstate(gcheap *heap, void *object);

/* @param object inout - in is a conservative pointer
                 if the function returns something other than GC_NOT_GCOBJECT,
                 it will be set to the "outer" pointer */
gcmarkstate gc_conservative_beginning(gcheap *heap, void **object);

/* Inform the allocator that we're done marking. The allocator will sweep
   all unmarked objects, firing finalizers where appropriate. */
gc_end_mark(gcheap *heap);

Things to be specified:

• Synchronization
• RCObjects - other than write barriers and a flag bit, I don't think the allocator itself needs to know anything about RCObjects

jasone asks:

• Are "outermost pointer" and ("exterior pointer" or "outer pointer") distinct concepts? bsmedberg says no, they are synonyms. We should really use a typedef to make it explicitly clear.