core.memory
- This module provides an interface to the garbage collector used by
- applications written in the D programming language. It allows the
- garbage collector in the runtime to be swapped without affecting
- binary compatibility of applications.
- Using this module is not necessary in typical D code. It is mostly
- useful when doing low-level _memory management.
- Notes_to_users: *
- The GC is a conservative mark-and-sweep collector. It only runs a collection cycle when an allocation is requested of it, never otherwise. Hence, if the program is not doing allocations, there will be no GC collection pauses. The pauses occur because all threads the GC knows about are halted so the threads' stacks and registers can be scanned for references to GC allocated data.
the OS/C runtime thread creation APIs and D threads that were detached from the D runtime after creation. Such threads will not be paused for a GC collection, and the GC might not detect references to GC allocated data held by them. This can cause memory corruption. There are several ways to resolve this issue:
- Do not hold references to GC allocated data in such threads.
- Register/unregister such data with calls to addRoot/removeRoot and
- Maintain another reference to that same data in another thread that the
GC does know about.
- Disable GC collection cycles while that thread is active with disable/enable.
- Register the thread with the GC using
thread_attachThis/thread_detachThis.
- Notes_to_implementors:
- On POSIX systems, the signals
SIGRTMINandSIGRTMIN + 1are reserved - by this module for use in the garbage collector implementation.
- Typically, they will be used to stop and resume other threads
- when performing a collection, but an implementation may choose
- not to use this mechanism (or not stop the world at all, in the
- case of concurrent garbage collectors).
- On POSIX systems, the signals
- Registers, the stack, and any other _memory locations added through
- the
GC.addRangefunction are always scanned conservatively. - This means that even if a variable is e.g. of type
float, - it will still be scanned for possible GC pointers. And, if the
- word-interpreted representation of the variable matches a GC-managed
- _memory block's address, that _memory block is considered live.
- Implementations are free to scan the non-root heap in a precise
- manner, so that fields of types like
floatwill not be considered - relevant when scanning the heap. Thus, casting a GC pointer to an
- integral type (e.g.
size_t) and storing it in a field of that - type inside the GC heap may mean that it will not be recognized
- if the _memory block was allocated with precise type info or with
- the
GC.BlkAttr.NO_SCANattribute. - Destructors will always be executed while other threads are
- active; that is, an implementation that stops the world must not
- execute destructors until the world has been resumed.
- A destructor of an object must not access object references
- within the object. This means that an implementation is free to
- optimize based on this rule.
- An implementation is free to perform heap compaction and copying
- so long as no valid GC pointers are invalidated in the process.
- However, _memory allocated with
GC.BlkAttr.NO_MOVEmust - not be moved/copied.
- Implementations must support interior pointers. That is, if the
- only reference to a GC-managed _memory block points into the
- middle of the block rather than the beginning (for example), the
- GC must consider the _memory block live. The exception to this
- rule is when a _memory block is allocated with the
GC.BlkAttr.NO_INTERIORattribute; it is the user's- responsibility to make sure such _memory blocks have a proper pointer
- to them when they should be considered live.
- It is acceptable for an implementation to store bit flags into
- pointer values and GC-managed _memory blocks, so long as such a
- trick is not visible to the application. In practice, this means
- that only a stop-the-world collector can do this.
- Implementations are free to assume that GC pointers are only
- stored on word boundaries. Unaligned pointers may be ignored
- entirely.
- Implementations are free to run collections at any point. It is,
- however, recommendable to only do so when an allocation attempt
- happens and there is insufficient _memory available.
Copyright
Copyright Sean Kelly 2005 - 2015.
var pageSize
Types 2
structBlkInfo_
Fields
void * basesize_t sizeuint attrstructGC
This struct encapsulates all garbage collection functionality for the D programming language.
Methods
void enable() @safe nothrow pure;Enables automatic garbage collection behavior if collections have previously been suspended by a call to `GC.disable()`. This function is reentrant, and must be called once for every call to `GC.d...void disable() @safe nothrow pure;Disables automatic garbage collections performed to minimize the process footprint. Collections may continue to occur in instances where the implementation deems necessary for correct program beha...void collect() @safe nothrow pure;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 block...void minimize() @safe nothrow pure;Indicates that the managed memory space be minimized by returning free physical memory to the operating system. The amount of free memory returned depends on the allocator design and on program be...uint getAttr( const scope void * p ) nothrowReturns a bit field representing all block attributes set for the memory referenced by p. If p references memory not originally allocated by this garbage collector, points to the interior of a mem...uint setAttr( const scope void * p, uint a ) nothrowSets the specified bits for the memory references by p. If p references memory not originally allocated by this garbage collector, points to the interior of a memory block, or if p is null, no act...uint clrAttr( const scope void * p, uint a ) nothrowClears the specified bits for the memory references by p. If p references memory not originally allocated by this garbage collector, points to the interior of a memory block, or if p is null, no a...size_t reserve(size_t sz) nothrow pure;Requests that at least sz bytes of memory be obtained from the operating system and marked as free.void free(void * p) pure nothrow @nogcDeallocates the memory referenced by p. If p is null, no action occurs. If p references memory not originally allocated by this garbage collector, if p points to the interior of a memory block, or...inout(void) * addrOf( inout(void) * p ) nothrow @nogc pure @trustedReturns the base address of the memory block containing p. This value is useful to determine whether p is an interior pointer, and the result may be passed to routines such as sizeOf which may oth...size_t sizeOf( const scope void * p ) nothrow @nogcReturns the true size of the memory block referenced by p. This value represents the maximum number of bytes for which a call to realloc may resize the existing block in place. If p references me...BlkInfo query(return scope const void * p) nothrowReturns aggregate information about the memory block containing p. If p references memory not originally allocated by this garbage collector, if p is null, or if the garbage collector does not sup...Stats stats() @safe nothrow @nogcReturns runtime stats for currently active GC implementation See `core.memory.GC.Stats` for list of available metrics.ProfileStats profileStats() nothrow @nogc @safeReturns runtime profile stats for currently active GC implementation See `core.memory.GC.ProfileStats` for list of available metrics.void addRoot(const void * p) nothrow @nogc pure;Adds an internal root pointing to the GC memory block referenced by p. As a result, the block referenced by p itself and any blocks accessible via it will be considered live until the root is remov...void removeRoot(const void * p) nothrow @nogc pure;Removes the memory block referenced by p from an internal list of roots to be scanned during a collection. If p is null or is not a value previously passed to addRoot() then no operation is perfor...void addRange(const void * p, size_t sz, const TypeInfo ti = null) @nogc nothrow pure;Adds p[0 .. sz] to the list of memory ranges to be scanned for pointers during a collection. If p is null, no operation is performed.void removeRange(const void * p) nothrow @nogc pure;Removes the memory range starting at p from an internal list of ranges to be scanned during a collection. If p is null or does not represent a value previously passed to addRange() then no operatio...void runFinalizers(const scope void[] segment)Runs any finalizer that is located in address range of the given code segment. This is used before unloading shared libraries. All matching objects which have a finalizer in this code segment are...bool inFinalizer() nothrow @nogc @safeQueries the GC whether the current thread is running object finalization as part of a GC collection, or an explicit call to runFinalizers.ulong allocatedInCurrentThread() nothrow;Returns the number of bytes allocated for the current thread since program start. It is the same as GC.stats().allocatedInCurrentThread, but faster.Constructors
this()Nested Templates
StatsAggregation of GC stats to be exposed via public APIProfileStatsAggregation of current profile informationBlkAttrElements for a bit field representing memory block attributes. These are manipulated via the getAttr, setAttr, clrAttr functions.Functions 21
fn
void * pureMalloc()(size_t size) @trusted pure @nogc nothrowPure variants of C's memory allocation functions `malloc`, `calloc`, and `realloc` and deallocation function `free`.fn
void * fakePureMalloc(size_t)fn
void * fakePureCalloc(size_t nmemb, size_t size)fn
void * fakePureRealloc(void * ptr, size_t size)fn
void fakePureFree(void * ptr)Variables 1
var
size_t pageSizeThe size of a system page in bytes.
This value is set at startup time of the application. It's safe to use early in the start process, like in shared module constructors and initialization of the D runtime itself.