std.memory

struct GC;

This struct encapsulates all garbage collection functionality for the D programming language. Currently, the garbage collector is decided at link time, but this design could adapt to dynamic garbage collector loading with few semantic changes.

void enable();

Enables the garbage collector if collections have previously been suspended by a call to disable. This function is reentrant, and must be called once for every call to disable before the garbage collector is enabled.

void disable();

Disables the garbage collector. This function is reentrant, but enable must be called once for each call to disable.

void collect();

Begins a full collection. While the meaning of this may change based on the garbage collector implementation, typical behavior is to scan all stack segments for roots, mark accessible memory blocks as alive, and then to reclaim free space. This action may need to suspend all running threads for at least part of the collection process.

void* malloc(uint sz, bool df = false);

Requests an aligned block of managed memory from the garbage collector. This memory may be deleted at will with a call to free, or it may be discarded and cleaned up automatically during a collection run. If allocation fails, this function will call onOutOfMemory which is expected to throw an OutOfMemoryException.

Params:

uint sz	The desired allocation size in bytes.
bool df	True if this memory block should be finalized.

Returns:
A reference to the allocated memory or null if insufficient memory is available.

Throws:
OutOfMemoryException on allocation failure.

void* calloc(uint sz, bool df = false);

Requests an aligned block of managed memory from the garbage collector, which is initialized with all bits set to zero. This memory may be deleted at will with a call to free, or it may be discarded and cleaned up automatically during a collection run. If allocation fails, this function will call onOutOfMemory which is expected to throw an OutOfMemoryException.

Params:

uint sz	The desired allocation size in bytes.
bool df	True if this memory block should be finalized.

Returns:
A reference to the allocated memory or null if insufficient memory is available.

Throws:
OutOfMemoryException on allocation failure.

void* realloc(void* p, uint sz, bool df = false);

If sz is zero, the memory referenced by p will be deallocated as if by a call to free. A new memory block of size sz will then be allocated as if by a call to malloc, or the implementation may instead resize the memory block in place. The contents of the new memory block will be the same as the contents of the old memory block, up to the lesser of the new and old sizes. Note that existing memory will only be freed by realloc if sz is equal to zero. The garbage collector is otherwise expected to later reclaim the memory block if it is unused. If allocation fails, this function will call onOutOfMemory which is expected to throw an OutOfMemoryException. If p references memory not originally allocated by this garbage collector, or if it points to the interior of a memory block, no action will be taken.

Params:

void* p	A pointer to the root of a valid memory block or to null.
uint sz	The desired allocation size in bytes.
bool df	True if this memory block should be finalized.

Returns:
A reference to the allocated memory on success or null if sz is zero. On failure, the original value of p is returned.

Throws:
OutOfMemoryException on allocation failure.

void free(void* p);

Deallocates the memory references by p. If p is null, no action occurs. If p references memory not originally allocated by this garbage collector, or if it points to the interior of a memory block, no action will be taken.

Params:

void* p

A pointer to the root of a valid memory block or to null.

uint sizeOf(void* p);

Determines the allocated size of a memory block, equivalent to the length property for arrays. If p references memory not originally allocated by this garbage collector, or if it points to the interior of a memory block, zero will be returned.

Params:

void* p

A pointer to the root of a valid memory block or to null.

Returns:
The size in bytes of the memory block referenced by p or zero on error.

uint capacityOf(void* p);

Determines the free space including and immediately following the memory block referenced by p. If p references memory not originally allocated by this garbage collector, or if it points to the interior of a memory block, zero will be returned. The purpose of this function is to provide a means to determine the maximum number of bytes for which a call to realloc may resize the existing block in place.

Params:

void* p

A pointer to the root of a valid memory block or to null.

Returns:
The size in bytes of the memory block referenced by p or zero on error.

void add(void* p);

Adds the memory block referenced by p to an internal list of roots to be scanned during a collection. If p is null, no operation is performed.

Params:

void* p

A pointer to the root of a valid memory block or to null.

void add(void* pbeg, void* pend);

Adds the memory range beginning with pbeg and ending immediately before pend to to an internal list of memory blocks to be scanned during a collection. If pbeg and pend are null, no operation is performed.

Params:

void* pbeg	A pointer to the a valid memory location or to null.
void* pend	A pointer to one past the end of a valid memory block, or null if pbeg is null.

void remove(void* p);

Removes the memory block referenced by p from an internal list of roots to be scanned during a collection. If p is null, no operation is performed.

p = A pointer to the root of a valid memory block or to null.

void remove(void* pbeg, void* pend);

Removes the memory block range beginning with pbeg and ending immediately before pend from an internal list of roots to be scanned during a collection. If pbeg and pend were not previously passed to the garbage collector by a call to add, the result is undefined. If pbeg and pend are null, no operation is performed.

Params:

void* pbeg	A pointer to the a valid memory location or to null.
void* pend	A pointer to one past the end of a valid memory block, or null if pbeg is null.

void pin(void* p);

Ensures that the memory referenced by p will not be moved by the garbage collector. This function is reentrant, but unpin must be called once for each call to pin. If p is null, no operation is performed.

Params:

void* p

A pointer to the root of a valid memory block or to null.

void unpin(void* p);

Allows the garbage collector to move the memory block referenced by p during a collection, if pin has previously been called with the supplied value of p as a parameter. This function is reentrant, and must be called once for every call to pin before the garbage collector is free to move this block.

Params:

void* p

A pointer to the root of a valid memory block or to null.

GC gc;

All GC routines are accessed through this variable. This is done to follow the established D coding style guidelines and to reduce the impact of future design changes.