std.gc
The garbage collector normally works behind the scenes without needing any specific interaction. These functions are for advanced applications that benefit from tuning the operation of the collector.Source:
std/gc.d
- void addRoot(void* p);
- Add p to list of roots. Roots are references to memory allocated by the
collector that are maintained in memory outside the collector pool. The garbage
collector will by default look for roots in the stacks of each thread, the
registers, and the default static data segment. If roots are held elsewhere,
use addRoot() or addRange() to tell the collector not to free the memory it
points to.
- void removeRoot(void* p);
- Remove p from list of roots.
- void addRange(void* pbot, void* ptop);
- Add range to scan for roots.
- void removeRange(void* pbot);
- Remove range.
- void hasPointers(void* p);
- Mark a gc allocated block of memory as possibly containing pointers.
- void hasNoPointers(void* p);
- Mark a gc allocated block of memory as definitely NOT containing pointers.
- void setTypeInfo(TypeInfo ti, void* p);
- Mark a gc allocated block of memory pointed to by p as being populated with
an array of TypeInfo ti (as many as will fit).
- void[] malloc(size_t nbytes);
- Allocate nbytes of uninitialized data.
The allocated memory will be scanned for pointers during
a gc collection cycle, unless
it is followed by a call to hasNoPointers().
- void[] realloc(void* p, size_t nbytes);
- Resize allocated memory block pointed to by p to be at least nbytes long.
It will try to resize the memory block in place.
If nbytes is 0, the memory block is free'd.
If p is null, the memory block is allocated using malloc.
The returned array may not be at the same location as the original
memory block.
The allocated memory will be scanned for pointers during
a gc collection cycle, unless
it is followed by a call to hasNoPointers().
- size_t extend(void* p, size_t minbytes, size_t maxbytes);
- Attempt to enlarge the memory block pointed to by p
by at least minbytes beyond its current capacity,
up to a maximum of maxbytes.
Returns:
0 if could not extend p, total size of entire memory block if successful.
- size_t capacity(void* p);
- Returns capacity (size of the memory block) that p
points to the beginning of.
If p does not point into the gc memory pool, or does
not point to the beginning of an allocated memory block,
0 is returned.
- void setV1_0();
- Set gc behavior to match that of 1.0.
- void fullCollect();
- Run a full garbage collection cycle.
The collector normally runs synchronously with a storage allocation request (i.e. it never happens when in code that does not allocate memory). In some circumstances, for example when a particular task is finished, it is convenient to explicitly run the collector and free up all memory used by that task. It can also be helpful to run a collection before starting a new task that would be annoying if it ran a collection in the middle of that task. Explicitly running a collection can also be done in a separate very low priority thread, so that if the program is idly waiting for input, memory can be cleaned up.
- void genCollect();
- Run a generational garbage collection cycle.
Takes less time than a fullcollect(), but isn't
as effective.
- void minimize();
- Minimizes physical memory usage
- void disable();
void enable(); - disable() temporarily disables garbage collection cycle, enable()
then reenables them.
This is used for brief time critical sections of code, so the amount of time it will take is predictable. If the collector runs out of memory while it is disabled, it will throw an std.outofmemory.OutOfMemoryException. The disable() function calls can be nested, but must be matched with corresponding enable() calls. By default collections are enabled.
- void* getGCHandle();
- Get handle to the collector.
- void setGCHandle(void* p);
- Set handle to the collector.