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.
- 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.
- Set gc behavior to match that of 1.0.
- 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.
- Run a generational garbage collection cycle.
Takes less time than a fullcollect(), but isn't
as effective.
- 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.
- Get handle to the collector.
void
setGCHandle(void*
p);
- Set handle to the collector.