std.gc - D Programming Language - Digital Mars

D Programming Language 1.0

- Comments
- D
- Search
- Home

Last update Wed Sep 2 00:11:32 2009

# 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.

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(uint 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, uint 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().
uint extend(void* p, uint minbytes, uint 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.
uint 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.

Copyright © 1999-2009 by Digital Mars, All Rights Reserved | Page generated by Ddoc.