Garbage Collector

The garbage collector API is intended to serve a number of complimentary needs. First, it should be possible for all C-compatible code in an application to interact with the garbage collector, not just the D code specifically. This both simplifies the interaction of mixed-language applications, and allows the D runtime to more easily leverage existing garbage collectors with little or no rewriting or wrapping in a D code layer. Second, while the bulk of D applications desire and expect the existence of a garbage collector, some applications may not, be it for code size or for other reasons. For these reasons, the garbage collector interface was designed as a set of specifically defined C routines, and requirements are such that not all API calls must be fully functional for an implementation to be considered conforming.

Interface Definition

This is a concise definition of the routines that every garbage collector implementation must expose:

extern (C) void gc_init();
extern (C) void gc_term();

extern (C) void gc_enable();
extern (C) void gc_disable();
extern (C) void gc_collect();
extern (C) void gc_minimize();

extern (C) uint gc_getAttr( void* p );
extern (C) uint gc_setAttr( void* p, uint a );
extern (C) uint gc_clrAttr( void* p, uint a );

extern (C) void*  gc_malloc( size_t sz, uint ba = 0 );
extern (C) void*  gc_calloc( size_t sz, uint ba = 0 );
extern (C) void*  gc_realloc( void* p, size_t sz, uint ba = 0 );
extern (C) size_t gc_extend( void* p, size_t mx, size_t sz );
extern (C) size_t gc_reserve( size_t sz );
extern (C) void   gc_free( void* p );

extern (C) void*   gc_addrOf( void* p );
extern (C) size_t  gc_sizeOf( void* p );

struct BlkInfo
{
    void*  base;
    size_t size;
    uint   attr;
}

extern (C) BlkInfo gc_query( void* p );

extern (C) void gc_addRoot( void* p );
extern (C) void gc_addRange( void* p, size_t sz );

extern (C) void gc_removeRoot( void* p );
extern (C) void gc_removeRange( void* p );

Bit significance of the uint value used for block attribute passing is as follows, by position:

0: Block contains a class - finalize this block on collection
1: Block contains no pointers - do not scan through this block on collections
2: Block is pinned - do not move this block during collections
3-15: Reserved for future use by the D standard library
16-31: Reserved for internal use by the garbage collector and compiler

Implementation Requirements

The package name "gc" is reserved for use by the garbage collector, and all modules defined should live within this namespace to avoid collisions with user code. More requirements coming soon.