mirror of
https://github.com/autc04/Retro68.git
synced 2024-09-07 13:54:33 +00:00
921 lines
32 KiB
D
921 lines
32 KiB
D
/**
|
|
* 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:
|
|
*
|
|
$(OL
|
|
$(LI 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.
|
|
)
|
|
|
|
$(LI The GC does not know about threads that were created by directly calling
|
|
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:
|
|
$(OL
|
|
$(LI Do not hold references to GC allocated data in such threads.)
|
|
$(LI Register/unregister such data with calls to $(LREF addRoot)/$(LREF removeRoot) and
|
|
$(LREF addRange)/$(LREF removeRange).)
|
|
$(LI Maintain another reference to that same data in another thread that the
|
|
GC does know about.)
|
|
$(LI Disable GC collection cycles while that thread is active with $(LREF disable)/$(LREF enable).)
|
|
$(LI Register the thread with the GC using $(REF thread_attachThis, core,thread)/$(REF thread_detachThis, core,thread).)
|
|
)
|
|
)
|
|
)
|
|
*
|
|
* Notes_to_implementors:
|
|
* $(UL
|
|
* $(LI On POSIX systems, the signals SIGUSR1 and SIGUSR2 are 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).)
|
|
*
|
|
* $(LI Registers, the stack, and any other _memory locations added through
|
|
* the $(D GC.$(LREF addRange)) function are always scanned conservatively.
|
|
* This means that even if a variable is e.g. of type $(D 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.)
|
|
*
|
|
* $(LI Implementations are free to scan the non-root heap in a precise
|
|
* manner, so that fields of types like $(D float) will not be considered
|
|
* relevant when scanning the heap. Thus, casting a GC pointer to an
|
|
* integral type (e.g. $(D 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 $(D GC.BlkAttr.$(LREF NO_SCAN)) attribute.)
|
|
*
|
|
* $(LI 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.)
|
|
*
|
|
* $(LI 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.)
|
|
*
|
|
* $(LI 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 $(D GC.BlkAttr.$(LREF NO_MOVE)) must
|
|
* not be moved/copied.)
|
|
*
|
|
* $(LI 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
|
|
* $(D GC.BlkAttr.$(LREF NO_INTERIOR)) attribute; it is the user's
|
|
* responsibility to make sure such _memory blocks have a proper pointer
|
|
* to them when they should be considered live.)
|
|
*
|
|
* $(LI 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.)
|
|
*
|
|
* $(LI Implementations are free to assume that GC pointers are only
|
|
* stored on word boundaries. Unaligned pointers may be ignored
|
|
* entirely.)
|
|
*
|
|
* $(LI 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.
|
|
* License: $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost License 1.0)
|
|
* Authors: Sean Kelly, Alex Rønne Petersen
|
|
* Source: $(DRUNTIMESRC core/_memory.d)
|
|
*/
|
|
|
|
module core.memory;
|
|
|
|
|
|
private
|
|
{
|
|
extern (C) void gc_init();
|
|
extern (C) void gc_term();
|
|
|
|
extern (C) void gc_enable() nothrow;
|
|
extern (C) void gc_disable() nothrow;
|
|
extern (C) void gc_collect() nothrow;
|
|
extern (C) void gc_minimize() nothrow;
|
|
|
|
extern (C) uint gc_getAttr( void* p ) pure nothrow;
|
|
extern (C) uint gc_setAttr( void* p, uint a ) pure nothrow;
|
|
extern (C) uint gc_clrAttr( void* p, uint a ) pure nothrow;
|
|
|
|
extern (C) void* gc_malloc( size_t sz, uint ba = 0, const TypeInfo = null ) pure nothrow;
|
|
extern (C) void* gc_calloc( size_t sz, uint ba = 0, const TypeInfo = null ) pure nothrow;
|
|
extern (C) BlkInfo_ gc_qalloc( size_t sz, uint ba = 0, const TypeInfo = null ) pure nothrow;
|
|
extern (C) void* gc_realloc( void* p, size_t sz, uint ba = 0, const TypeInfo = null ) pure nothrow;
|
|
extern (C) size_t gc_extend( void* p, size_t mx, size_t sz, const TypeInfo = null ) pure nothrow;
|
|
extern (C) size_t gc_reserve( size_t sz ) nothrow;
|
|
extern (C) void gc_free( void* p ) pure nothrow;
|
|
|
|
extern (C) void* gc_addrOf( void* p ) pure nothrow;
|
|
extern (C) size_t gc_sizeOf( void* p ) pure nothrow;
|
|
|
|
struct BlkInfo_
|
|
{
|
|
void* base;
|
|
size_t size;
|
|
uint attr;
|
|
}
|
|
|
|
extern (C) BlkInfo_ gc_query( void* p ) pure nothrow;
|
|
extern (C) GC.Stats gc_stats ( ) nothrow @nogc;
|
|
|
|
extern (C) void gc_addRoot( in void* p ) nothrow @nogc;
|
|
extern (C) void gc_addRange( in void* p, size_t sz, const TypeInfo ti = null ) nothrow @nogc;
|
|
|
|
extern (C) void gc_removeRoot( in void* p ) nothrow @nogc;
|
|
extern (C) void gc_removeRange( in void* p ) nothrow @nogc;
|
|
extern (C) void gc_runFinalizers( in void[] segment );
|
|
|
|
package extern (C) bool gc_inFinalizer();
|
|
}
|
|
|
|
|
|
/**
|
|
* This struct encapsulates all garbage collection functionality for the D
|
|
* programming language.
|
|
*/
|
|
struct GC
|
|
{
|
|
@disable this();
|
|
|
|
/**
|
|
* Aggregation of GC stats to be exposed via public API
|
|
*/
|
|
static struct Stats
|
|
{
|
|
/// number of used bytes on the GC heap (might only get updated after a collection)
|
|
size_t usedSize;
|
|
/// number of free bytes on the GC heap (might only get updated after a collection)
|
|
size_t freeSize;
|
|
}
|
|
|
|
/**
|
|
* Enables automatic garbage collection behavior 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
|
|
* automatic collections are enabled.
|
|
*/
|
|
static void enable() nothrow /* FIXME pure */
|
|
{
|
|
gc_enable();
|
|
}
|
|
|
|
|
|
/**
|
|
* 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 behavior,
|
|
* such as during an out of memory condition. This function is reentrant,
|
|
* but enable must be called once for each call to disable.
|
|
*/
|
|
static void disable() nothrow /* FIXME pure */
|
|
{
|
|
gc_disable();
|
|
}
|
|
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
static void collect() nothrow /* FIXME pure */
|
|
{
|
|
gc_collect();
|
|
}
|
|
|
|
/**
|
|
* 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 behavior.
|
|
*/
|
|
static void minimize() nothrow /* FIXME pure */
|
|
{
|
|
gc_minimize();
|
|
}
|
|
|
|
|
|
/**
|
|
* Elements for a bit field representing memory block attributes. These
|
|
* are manipulated via the getAttr, setAttr, clrAttr functions.
|
|
*/
|
|
enum BlkAttr : uint
|
|
{
|
|
NONE = 0b0000_0000, /// No attributes set.
|
|
FINALIZE = 0b0000_0001, /// Finalize the data in this block on collect.
|
|
NO_SCAN = 0b0000_0010, /// Do not scan through this block on collect.
|
|
NO_MOVE = 0b0000_0100, /// Do not move this memory block on collect.
|
|
/**
|
|
This block contains the info to allow appending.
|
|
|
|
This can be used to manually allocate arrays. Initial slice size is 0.
|
|
|
|
Note: The slice's usable size will not match the block size. Use
|
|
$(LREF capacity) to retrieve actual usable capacity.
|
|
|
|
Example:
|
|
----
|
|
// Allocate the underlying array.
|
|
int* pToArray = cast(int*)GC.malloc(10 * int.sizeof, GC.BlkAttr.NO_SCAN | GC.BlkAttr.APPENDABLE);
|
|
// Bind a slice. Check the slice has capacity information.
|
|
int[] slice = pToArray[0 .. 0];
|
|
assert(capacity(slice) > 0);
|
|
// Appending to the slice will not relocate it.
|
|
slice.length = 5;
|
|
slice ~= 1;
|
|
assert(slice.ptr == p);
|
|
----
|
|
*/
|
|
APPENDABLE = 0b0000_1000,
|
|
|
|
/**
|
|
This block is guaranteed to have a pointer to its base while it is
|
|
alive. Interior pointers can be safely ignored. This attribute is
|
|
useful for eliminating false pointers in very large data structures
|
|
and is only implemented for data structures at least a page in size.
|
|
*/
|
|
NO_INTERIOR = 0b0001_0000,
|
|
|
|
STRUCTFINAL = 0b0010_0000, // the block has a finalizer for (an array of) structs
|
|
}
|
|
|
|
|
|
/**
|
|
* Contains aggregate information about a block of managed memory. The
|
|
* purpose of this struct is to support a more efficient query style in
|
|
* instances where detailed information is needed.
|
|
*
|
|
* base = A pointer to the base of the block in question.
|
|
* size = The size of the block, calculated from base.
|
|
* attr = Attribute bits set on the memory block.
|
|
*/
|
|
alias BlkInfo = BlkInfo_;
|
|
|
|
|
|
/**
|
|
* Returns 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 memory block, or if
|
|
* p is null, zero will be returned.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root of a valid memory block or to null.
|
|
*
|
|
* Returns:
|
|
* A bit field containing any bits set for the memory block referenced by
|
|
* p or zero on error.
|
|
*/
|
|
static uint getAttr( in void* p ) nothrow
|
|
{
|
|
return getAttr(cast()p);
|
|
}
|
|
|
|
|
|
/// ditto
|
|
static uint getAttr(void* p) pure nothrow
|
|
{
|
|
return gc_getAttr( p );
|
|
}
|
|
|
|
|
|
/**
|
|
* Sets 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 action will be
|
|
* performed.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root of a valid memory block or to null.
|
|
* a = A bit field containing any bits to set for this memory block.
|
|
*
|
|
* Returns:
|
|
* The result of a call to getAttr after the specified bits have been
|
|
* set.
|
|
*/
|
|
static uint setAttr( in void* p, uint a ) nothrow
|
|
{
|
|
return setAttr(cast()p, a);
|
|
}
|
|
|
|
|
|
/// ditto
|
|
static uint setAttr(void* p, uint a) pure nothrow
|
|
{
|
|
return gc_setAttr( p, a );
|
|
}
|
|
|
|
|
|
/**
|
|
* Clears 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 action
|
|
* will be performed.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root of a valid memory block or to null.
|
|
* a = A bit field containing any bits to clear for this memory block.
|
|
*
|
|
* Returns:
|
|
* The result of a call to getAttr after the specified bits have been
|
|
* cleared.
|
|
*/
|
|
static uint clrAttr( in void* p, uint a ) nothrow
|
|
{
|
|
return clrAttr(cast()p, a);
|
|
}
|
|
|
|
|
|
/// ditto
|
|
static uint clrAttr(void* p, uint a) pure nothrow
|
|
{
|
|
return gc_clrAttr( p, a );
|
|
}
|
|
|
|
|
|
/**
|
|
* 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 OutOfMemoryError.
|
|
*
|
|
* Params:
|
|
* sz = The desired allocation size in bytes.
|
|
* ba = A bitmask of the attributes to set on this block.
|
|
* ti = TypeInfo to describe the memory. The GC might use this information
|
|
* to improve scanning for pointers or to call finalizers.
|
|
*
|
|
* Returns:
|
|
* A reference to the allocated memory or null if insufficient memory
|
|
* is available.
|
|
*
|
|
* Throws:
|
|
* OutOfMemoryError on allocation failure.
|
|
*/
|
|
static void* malloc( size_t sz, uint ba = 0, const TypeInfo ti = null ) pure nothrow
|
|
{
|
|
return gc_malloc( sz, ba, ti );
|
|
}
|
|
|
|
|
|
/**
|
|
* 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 OutOfMemoryError.
|
|
*
|
|
* Params:
|
|
* sz = The desired allocation size in bytes.
|
|
* ba = A bitmask of the attributes to set on this block.
|
|
* ti = TypeInfo to describe the memory. The GC might use this information
|
|
* to improve scanning for pointers or to call finalizers.
|
|
*
|
|
* Returns:
|
|
* Information regarding the allocated memory block or BlkInfo.init on
|
|
* error.
|
|
*
|
|
* Throws:
|
|
* OutOfMemoryError on allocation failure.
|
|
*/
|
|
static BlkInfo qalloc( size_t sz, uint ba = 0, const TypeInfo ti = null ) pure nothrow
|
|
{
|
|
return gc_qalloc( sz, ba, ti );
|
|
}
|
|
|
|
|
|
/**
|
|
* 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
|
|
* OutOfMemoryError.
|
|
*
|
|
* Params:
|
|
* sz = The desired allocation size in bytes.
|
|
* ba = A bitmask of the attributes to set on this block.
|
|
* ti = TypeInfo to describe the memory. The GC might use this information
|
|
* to improve scanning for pointers or to call finalizers.
|
|
*
|
|
* Returns:
|
|
* A reference to the allocated memory or null if insufficient memory
|
|
* is available.
|
|
*
|
|
* Throws:
|
|
* OutOfMemoryError on allocation failure.
|
|
*/
|
|
static void* calloc( size_t sz, uint ba = 0, const TypeInfo ti = null ) pure nothrow
|
|
{
|
|
return gc_calloc( sz, ba, ti );
|
|
}
|
|
|
|
|
|
/**
|
|
* 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 OutOfMemoryError. 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. If ba is zero
|
|
* (the default) and p references the head of a valid, known memory block
|
|
* then any bits set on the current block will be set on the new block if a
|
|
* reallocation is required. If ba is not zero and p references the head
|
|
* of a valid, known memory block then the bits in ba will replace those on
|
|
* the current memory block and will also be set on the new block if a
|
|
* reallocation is required.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root of a valid memory block or to null.
|
|
* sz = The desired allocation size in bytes.
|
|
* ba = A bitmask of the attributes to set on this block.
|
|
* ti = TypeInfo to describe the memory. The GC might use this information
|
|
* to improve scanning for pointers or to call finalizers.
|
|
*
|
|
* 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:
|
|
* OutOfMemoryError on allocation failure.
|
|
*/
|
|
static void* realloc( void* p, size_t sz, uint ba = 0, const TypeInfo ti = null ) pure nothrow
|
|
{
|
|
return gc_realloc( p, sz, ba, ti );
|
|
}
|
|
|
|
/// Issue 13111
|
|
unittest
|
|
{
|
|
enum size1 = 1 << 11 + 1; // page in large object pool
|
|
enum size2 = 1 << 22 + 1; // larger than large object pool size
|
|
|
|
auto data1 = cast(ubyte*)GC.calloc(size1);
|
|
auto data2 = cast(ubyte*)GC.realloc(data1, size2);
|
|
|
|
BlkInfo info = query(data2);
|
|
assert(info.size >= size2);
|
|
}
|
|
|
|
|
|
/**
|
|
* Requests that the managed memory block referenced by p be extended in
|
|
* place by at least mx bytes, with a desired extension of sz bytes. If an
|
|
* extension of the required size is not possible or if p references memory
|
|
* not originally allocated by this garbage collector, no action will be
|
|
* taken.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root of a valid memory block or to null.
|
|
* mx = The minimum extension size in bytes.
|
|
* sz = The desired extension size in bytes.
|
|
* ti = TypeInfo to describe the full memory block. The GC might use
|
|
* this information to improve scanning for pointers or to
|
|
* call finalizers.
|
|
*
|
|
* Returns:
|
|
* The size in bytes of the extended memory block referenced by p or zero
|
|
* if no extension occurred.
|
|
*
|
|
* Note:
|
|
* Extend may also be used to extend slices (or memory blocks with
|
|
* $(LREF APPENDABLE) info). However, use the return value only
|
|
* as an indicator of success. $(LREF capacity) should be used to
|
|
* retrieve actual usable slice capacity.
|
|
*/
|
|
static size_t extend( void* p, size_t mx, size_t sz, const TypeInfo ti = null ) pure nothrow
|
|
{
|
|
return gc_extend( p, mx, sz, ti );
|
|
}
|
|
/// Standard extending
|
|
unittest
|
|
{
|
|
size_t size = 1000;
|
|
int* p = cast(int*)GC.malloc(size * int.sizeof, GC.BlkAttr.NO_SCAN);
|
|
|
|
//Try to extend the allocated data by 1000 elements, preferred 2000.
|
|
size_t u = GC.extend(p, 1000 * int.sizeof, 2000 * int.sizeof);
|
|
if (u != 0)
|
|
size = u / int.sizeof;
|
|
}
|
|
/// slice extending
|
|
unittest
|
|
{
|
|
int[] slice = new int[](1000);
|
|
int* p = slice.ptr;
|
|
|
|
//Check we have access to capacity before attempting the extend
|
|
if (slice.capacity)
|
|
{
|
|
//Try to extend slice by 1000 elements, preferred 2000.
|
|
size_t u = GC.extend(p, 1000 * int.sizeof, 2000 * int.sizeof);
|
|
if (u != 0)
|
|
{
|
|
slice.length = slice.capacity;
|
|
assert(slice.length >= 2000);
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* Requests that at least sz bytes of memory be obtained from the operating
|
|
* system and marked as free.
|
|
*
|
|
* Params:
|
|
* sz = The desired size in bytes.
|
|
*
|
|
* Returns:
|
|
* The actual number of bytes reserved or zero on error.
|
|
*/
|
|
static size_t reserve( size_t sz ) nothrow /* FIXME pure */
|
|
{
|
|
return gc_reserve( sz );
|
|
}
|
|
|
|
|
|
/**
|
|
* Deallocates 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 if this
|
|
* method is called from a finalizer, no action will be taken. The block
|
|
* will not be finalized regardless of whether the FINALIZE attribute is
|
|
* set. If finalization is desired, use delete instead.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root of a valid memory block or to null.
|
|
*/
|
|
static void free( void* p ) pure nothrow
|
|
{
|
|
gc_free( p );
|
|
}
|
|
|
|
|
|
/**
|
|
* Returns 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 otherwise fail. If p
|
|
* references memory not originally allocated by this garbage collector, if
|
|
* p is null, or if the garbage collector does not support this operation,
|
|
* null will be returned.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root or the interior of a valid memory block or to
|
|
* null.
|
|
*
|
|
* Returns:
|
|
* The base address of the memory block referenced by p or null on error.
|
|
*/
|
|
static inout(void)* addrOf( inout(void)* p ) nothrow /* FIXME pure */
|
|
{
|
|
return cast(inout(void)*)gc_addrOf(cast(void*)p);
|
|
}
|
|
|
|
|
|
/// ditto
|
|
static void* addrOf(void* p) pure nothrow
|
|
{
|
|
return gc_addrOf(p);
|
|
}
|
|
|
|
|
|
/**
|
|
* Returns 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 memory not
|
|
* originally allocated by this garbage collector, points to the interior
|
|
* of a memory block, or if p is null, zero will be returned.
|
|
*
|
|
* Params:
|
|
* 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.
|
|
*/
|
|
static size_t sizeOf( in void* p ) nothrow
|
|
{
|
|
return gc_sizeOf(cast(void*)p);
|
|
}
|
|
|
|
|
|
/// ditto
|
|
static size_t sizeOf(void* p) pure nothrow
|
|
{
|
|
return gc_sizeOf( p );
|
|
}
|
|
|
|
// verify that the reallocation doesn't leave the size cache in a wrong state
|
|
unittest
|
|
{
|
|
auto data = cast(int*)realloc(null, 4096);
|
|
size_t size = GC.sizeOf(data);
|
|
assert(size >= 4096);
|
|
data = cast(int*)GC.realloc(data, 4100);
|
|
size = GC.sizeOf(data);
|
|
assert(size >= 4100);
|
|
}
|
|
|
|
/**
|
|
* Returns 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 support this operation,
|
|
* BlkInfo.init will be returned. Typically, support for this operation
|
|
* is dependent on support for addrOf.
|
|
*
|
|
* Params:
|
|
* p = A pointer to the root or the interior of a valid memory block or to
|
|
* null.
|
|
*
|
|
* Returns:
|
|
* Information regarding the memory block referenced by p or BlkInfo.init
|
|
* on error.
|
|
*/
|
|
static BlkInfo query( in void* p ) nothrow
|
|
{
|
|
return gc_query(cast(void*)p);
|
|
}
|
|
|
|
|
|
/// ditto
|
|
static BlkInfo query(void* p) pure nothrow
|
|
{
|
|
return gc_query( p );
|
|
}
|
|
|
|
/**
|
|
* Returns runtime stats for currently active GC implementation
|
|
* See `core.memory.GC.Stats` for list of available metrics.
|
|
*/
|
|
static Stats stats() nothrow
|
|
{
|
|
return gc_stats();
|
|
}
|
|
|
|
/**
|
|
* 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 removed again.
|
|
*
|
|
* If p is null, no operation is performed.
|
|
*
|
|
* Params:
|
|
* p = A pointer into a GC-managed memory block or null.
|
|
*
|
|
* Example:
|
|
* ---
|
|
* // Typical C-style callback mechanism; the passed function
|
|
* // is invoked with the user-supplied context pointer at a
|
|
* // later point.
|
|
* extern(C) void addCallback(void function(void*), void*);
|
|
*
|
|
* // Allocate an object on the GC heap (this would usually be
|
|
* // some application-specific context data).
|
|
* auto context = new Object;
|
|
*
|
|
* // Make sure that it is not collected even if it is no
|
|
* // longer referenced from D code (stack, GC heap, …).
|
|
* GC.addRoot(cast(void*)context);
|
|
*
|
|
* // Also ensure that a moving collector does not relocate
|
|
* // the object.
|
|
* GC.setAttr(cast(void*)context, GC.BlkAttr.NO_MOVE);
|
|
*
|
|
* // Now context can be safely passed to the C library.
|
|
* addCallback(&myHandler, cast(void*)context);
|
|
*
|
|
* extern(C) void myHandler(void* ctx)
|
|
* {
|
|
* // Assuming that the callback is invoked only once, the
|
|
* // added root can be removed again now to allow the GC
|
|
* // to collect it later.
|
|
* GC.removeRoot(ctx);
|
|
* GC.clrAttr(ctx, GC.BlkAttr.NO_MOVE);
|
|
*
|
|
* auto context = cast(Object)ctx;
|
|
* // Use context here…
|
|
* }
|
|
* ---
|
|
*/
|
|
static void addRoot( in void* p ) nothrow @nogc /* FIXME pure */
|
|
{
|
|
gc_addRoot( p );
|
|
}
|
|
|
|
|
|
/**
|
|
* 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 performed.
|
|
*
|
|
* Params:
|
|
* p = A pointer into a GC-managed memory block or null.
|
|
*/
|
|
static void removeRoot( in void* p ) nothrow @nogc /* FIXME pure */
|
|
{
|
|
gc_removeRoot( p );
|
|
}
|
|
|
|
|
|
/**
|
|
* Adds $(D 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.
|
|
*
|
|
* Note that $(D p[0 .. sz]) is treated as an opaque range of memory assumed
|
|
* to be suitably managed by the caller. In particular, if p points into a
|
|
* GC-managed memory block, addRange does $(I not) mark this block as live.
|
|
*
|
|
* Params:
|
|
* p = A pointer to a valid memory address or to null.
|
|
* sz = The size in bytes of the block to add. If sz is zero then the
|
|
* no operation will occur. If p is null then sz must be zero.
|
|
* ti = TypeInfo to describe the memory. The GC might use this information
|
|
* to improve scanning for pointers or to call finalizers
|
|
*
|
|
* Example:
|
|
* ---
|
|
* // Allocate a piece of memory on the C heap.
|
|
* enum size = 1_000;
|
|
* auto rawMemory = core.stdc.stdlib.malloc(size);
|
|
*
|
|
* // Add it as a GC range.
|
|
* GC.addRange(rawMemory, size);
|
|
*
|
|
* // Now, pointers to GC-managed memory stored in
|
|
* // rawMemory will be recognized on collection.
|
|
* ---
|
|
*/
|
|
static void addRange( in void* p, size_t sz, const TypeInfo ti = null ) @nogc nothrow /* FIXME pure */
|
|
{
|
|
gc_addRange( p, sz, ti );
|
|
}
|
|
|
|
|
|
/**
|
|
* 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 operation is
|
|
* performed.
|
|
*
|
|
* Params:
|
|
* p = A pointer to a valid memory address or to null.
|
|
*/
|
|
static void removeRange( in void* p ) nothrow @nogc /* FIXME pure */
|
|
{
|
|
gc_removeRange( p );
|
|
}
|
|
|
|
|
|
/**
|
|
* 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 assumed to be dead, using them while or after
|
|
* calling this method has undefined behavior.
|
|
*
|
|
* Params:
|
|
* segment = address range of a code segment.
|
|
*/
|
|
static void runFinalizers( in void[] segment )
|
|
{
|
|
gc_runFinalizers( segment );
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Pure variants of C's memory allocation functions `malloc`, `calloc`, and
|
|
* `realloc` and deallocation function `free`.
|
|
*
|
|
* Purity is achieved by saving and restoring the value of `errno`, thus
|
|
* behaving as if it were never changed.
|
|
*
|
|
* See_Also:
|
|
* $(LINK2 https://dlang.org/spec/function.html#pure-functions, D's rules for purity),
|
|
* which allow for memory allocation under specific circumstances.
|
|
*/
|
|
void* pureMalloc(size_t size) @trusted pure @nogc nothrow
|
|
{
|
|
const errno = fakePureGetErrno();
|
|
void* ret = fakePureMalloc(size);
|
|
if (!ret || errno != 0)
|
|
{
|
|
cast(void)fakePureSetErrno(errno);
|
|
}
|
|
return ret;
|
|
}
|
|
/// ditto
|
|
void* pureCalloc(size_t nmemb, size_t size) @trusted pure @nogc nothrow
|
|
{
|
|
const errno = fakePureGetErrno();
|
|
void* ret = fakePureCalloc(nmemb, size);
|
|
if (!ret || errno != 0)
|
|
{
|
|
cast(void)fakePureSetErrno(errno);
|
|
}
|
|
return ret;
|
|
}
|
|
/// ditto
|
|
void* pureRealloc(void* ptr, size_t size) @system pure @nogc nothrow
|
|
{
|
|
const errno = fakePureGetErrno();
|
|
void* ret = fakePureRealloc(ptr, size);
|
|
if (!ret || errno != 0)
|
|
{
|
|
cast(void)fakePureSetErrno(errno);
|
|
}
|
|
return ret;
|
|
}
|
|
/// ditto
|
|
void pureFree(void* ptr) @system pure @nogc nothrow
|
|
{
|
|
const errno = fakePureGetErrno();
|
|
fakePureFree(ptr);
|
|
cast(void)fakePureSetErrno(errno);
|
|
}
|
|
|
|
///
|
|
@system pure nothrow @nogc unittest
|
|
{
|
|
ubyte[] fun(size_t n) pure
|
|
{
|
|
void* p = pureMalloc(n);
|
|
p !is null || n == 0 || assert(0);
|
|
scope(failure) p = pureRealloc(p, 0);
|
|
p = pureRealloc(p, n *= 2);
|
|
p !is null || n == 0 || assert(0);
|
|
return cast(ubyte[]) p[0 .. n];
|
|
}
|
|
|
|
auto buf = fun(100);
|
|
assert(buf.length == 200);
|
|
pureFree(buf.ptr);
|
|
}
|
|
|
|
@system pure nothrow @nogc unittest
|
|
{
|
|
const int errno = fakePureGetErrno();
|
|
|
|
void* x = pureMalloc(10); // normal allocation
|
|
assert(errno == fakePureGetErrno()); // errno shouldn't change
|
|
assert(x !is null); // allocation should succeed
|
|
|
|
x = pureRealloc(x, 10); // normal reallocation
|
|
assert(errno == fakePureGetErrno()); // errno shouldn't change
|
|
assert(x !is null); // allocation should succeed
|
|
|
|
fakePureFree(x);
|
|
|
|
void* y = pureCalloc(10, 1); // normal zeroed allocation
|
|
assert(errno == fakePureGetErrno()); // errno shouldn't change
|
|
assert(y !is null); // allocation should succeed
|
|
|
|
fakePureFree(y);
|
|
|
|
// subtract 2 because snn.lib adds 2 unconditionally before passing
|
|
// the size to the Windows API
|
|
void* z = pureMalloc(size_t.max - 2); // won't affect `errno`
|
|
assert(errno == fakePureGetErrno()); // errno shouldn't change
|
|
assert(z is null);
|
|
}
|
|
|
|
// locally purified for internal use here only
|
|
extern (C) private pure @system @nogc nothrow
|
|
{
|
|
pragma(mangle, "getErrno") int fakePureGetErrno();
|
|
pragma(mangle, "setErrno") int fakePureSetErrno(int);
|
|
|
|
pragma(mangle, "malloc") void* fakePureMalloc(size_t);
|
|
pragma(mangle, "calloc") void* fakePureCalloc(size_t nmemb, size_t size);
|
|
pragma(mangle, "realloc") void* fakePureRealloc(void* ptr, size_t size);
|
|
|
|
pragma(mangle, "free") void fakePureFree(void* ptr);
|
|
}
|