• Introduction
• Lexical
• Interpolation Expression Sequence
• Grammar
• Modules
• Declarations
• Types
• Properties
• Attributes
• Pragmas
• Expressions
• Statements
• Arrays
• Associative Arrays
• Structs and Unions
• Classes
• Interfaces
• Enums
• Type Qualifiers
• Functions
• Operator Overloading
• Templates
• Template Mixins
• Contract Programming
• Conditional Compilation
• Traits
• Error Handling
• Unit Tests
• Garbage Collection
• Floating Point
• D x86 Inline Assembler
• Embedded Documentation
• Interfacing to C
• Interfacing to C++
• Interfacing to Objective-C
• Portability Guide
• Named Character Entities
• Memory Safety
• Application Binary Interface
• Vector Extensions
• Better C
• ImportC
• Live Functions
• Windows Programming
• Glossary
• Legacy Code
• Editions

Automatic Memory Management

D is a systems programming language with support for optional automatic memory mangagement. Usually it is not necessary to free memory explicitly. Just allocate as needed, and the automatic memory manager's collector will periodically return all unused memory to the pool of available memory.

D also provides the mechanisms to write code where automatic memory mangagement is not involved. More information is provided below.

Programmers accustomed to explicitly managing memory allocation and deallocation will likely be skeptical of the benefits and efficacy of automatic memory management. Experience both with new projects written with automatic memory management in mind, and converting existing projects to automatic memory management shows that:

• Programs using automatic memory management are often faster. This is counterintuitive, but the reasons are:
  • Reference counting is a common solution to solve explicit memory allocation problems. The code to implement the increment and decrement operations whenever assignments are made is one source of slowdown. Hiding it behind smart pointer classes doesn't help the speed. (Reference counting methods are not a general solution anyway, as circular references never get deleted.)
  • Destructors are used to deallocate resources acquired by an object. For most classes, this resource is allocated memory. With automatic memory management, most destructors then become empty and can be discarded entirely.
  • All those destructors freeing memory can become significant when objects are allocated on the stack. For each one, some mechanism must be established so that if an exception happens, the destructors all get called in each frame to release any memory they hold. If the destructors become irrelevant, then there's no need to set up special stack frames to handle exceptions, and the code runs faster.
  • Collection kicks in only when memory gets tight. When memory is not tight, the program runs at full speed and does not spend any time tracing and freeing memory.
  • Programs using automatic memory management do not suffer from gradual deterioration due to an accumulation of memory leaks.
• Automatic memory management's collector reclaims unused memory, therefore it does not suffer from "memory leaks" which can cause long running applications to gradually consume more and more memory until they bring down the system. Automatic memory management programs have longer term stability.
• Programs using automatic memory management have fewer hard-to-find pointer bugs. This is because there are no dangling references to freed memory. There is no code to explicitly manage memory, hence no bugs in such code.
• Programs using automatic memory management are faster to develop and debug, because there's no need for developing, debugging, testing, or maintaining the explicit deallocation code.

Automatic memory management is not a panacea. There are some downsides:

• It is not always obvious when the automatic memory manager allocates memory, which in turn can trigger a collection, so the program can pause unexpectedly.
• The time it takes for a collection to complete is not bounded. While in practice it is very quick, this cannot normally be guaranteed.
• Normally, all threads other than the collector thread must be halted while the collection is in progress.
• Automatic memory managers can keep around some memory that an explicit deallocator would not.
• Automatic memory managing programs must carry around with them the collector implementation. While this can be a shared library, it is still there.

These constraints are addressed by techniques outlined in Memory Management, including the mechanisms provided by D to control allocations outside the collector heap.

There is currently work in progress to make the runtime library free of automatic heap allocations, to allow its use in scenarios where the use of automatic memory management infrastructure is not possible.

How Automatic Memory Management Works

It works by:

1. Stopping all other threads than the thread currently trying to allocate memory.
2. ‘Hijacking’ the current thread for collection work.
3. Scanning all ‘root’ memory ranges for pointers into allocated memory.
4. Recursively scanning all allocated memory pointed to by roots looking for more pointers into allocated memory.
5. Freeing all allocated memory that has no active pointers to it and do not need destructors to run.
6. Queueing all unreachable memory that needs destructors to run.
7. Resuming all other threads.
8. Running destructors for all queued memory.
9. Freeing any remaining unreachable memory.
10. Returning the current thread to whatever work it was doing.

Interfacing Automatic Memory Management Allocated Objects With Foreign Code

The collector looks for roots in:

1. the static data segment
2. the stacks and register contents of each thread
3. the TLS (thread-local storage) areas of each thread
4. any roots added by core.memory.GC.addRoot() or core.memory.GC.addRange()

If the only pointer to an object is held outside of these areas, then the collector will miss it and free the memory.

To avoid this from happening, either

• maintain a pointer to the object in an area the collector does scan for pointers;
• add a root where a pointer to the object is stored using core.memory.GC.addRoot() or core.memory.GC.addRange().
• reallocate and copy the object using the foreign code's storage allocator or using the C runtime library's malloc/free.

Pointers and the Automatic Memory Management Collector

Pointers in D can be broadly divided into two categories: Those that point to collector memory, and those that do not. Examples of the latter are pointers created by calls to C's malloc(), pointers received from C library routines, pointers to static data, pointers to objects on the stack, etc. For those pointers, anything that is legal in C can be done with them.

For collector pointers and references, however, there are some restrictions. These restrictions are minor, but they are intended to enable the maximum flexibility in collector design.

Things that are reliable and can be done:

• Use a union to share storage with a pointer:

  union U { void* ptr; int value }
  

• A pointer to the start of a collector object need not be maintained if a pointer to the interior of the object exists.

  char[] p = new char[10];
  char[] q = p[3..6];
  // q is enough to hold on to the object, don't need to keep
  // p as well.
  

One can avoid using pointers anyway for most tasks. D provides features rendering most explicit pointer uses obsolete, such as reference objects, dynamic arrays, and automatic memory management. Pointers are provided in order to interface successfully with C APIs and for some low level work.

Working with the Collector

Automatic memory allocation doesn't solve every memory deallocation problem. For example, if a pointer to a large data structure is kept, the collector cannot reclaim it, even if it is never referred to again. To eliminate this problem, it is good practice to set a reference or pointer to an object to null when no longer needed.

This advice applies only to static references or references embedded inside other objects. There is not much point for such stored on the stack to be nulled because new stack frames are initialized anyway.

Object Pinning and a Moving Collector

Although D does not currently use a moving collector, by following the rules listed above one can be implemented. No special action is required to pin objects. A moving collector will only move objects for which there are no ambiguous references, and for which it can update those references. All other objects will be automatically pinned.

D Operations That Involve the Collector

Some sections of code may need to avoid using the collector. The following constructs may allocate memory using the collector:

• NewExpression
• Array appending
• Array concatenation
• Array literals (see exceptions)
• Associative array literals
• Any insertion or removal in an associative array
• Extracting keys or values from an associative array
• Taking the address of (i.e. making a delegate to) a nested function that accesses variables in an outer scope
• A function literal that accesses variables in an outer scope
• An AssertExpression that fails its condition

There is a @nogc function attribute which will error at compile-time if any construct is used which would make a collector allocation.

Configuring the Collector

Since version 2.067, The collector can now be configured through the command line, the environment or by options embedded into the executable.

By default, GC options can only be passed on the command line of the program to run, e.g.

app "--DRT-gcopt=profile:1 minPoolSize:16" arguments to app

Available GC options are:

• disable:0|1 - start disabled
• profile:0|1 - enable profiling with summary when terminating program
• gc:conservative|precise|manual - select collector implementation (default = conservative)
• initReserve:N - initial memory to reserve in MB
• minPoolSize:N - initial and minimum pool size in MB
• maxPoolSize:N - maximum pool size in MB
• incPoolSize:N - pool size increment MB
• parallel:N - number of additional threads for marking
• heapSizeFactor:N - targeted heap size to used memory ratio
• cleanup:none|collect|finalize - how to treat live objects when terminating
  • collect: run a collection (the default for backward compatibility)
  • none: do nothing
  • finalize: all live objects are finalized unconditionally

In addition, --DRT-gcopt=help will show the list of options and their current settings.

Command line options starting with "--DRT-" are filtered out before calling main, so the program will not see them. They are still available via rt_args.

Configuration via the command line can be disabled by declaring a variable for the linker to pick up before using its default from the runtime:

extern(C) __gshared bool rt_cmdline_enabled = false;

Likewise, declare a boolean rt_envvars_enabled to enable configuration via the environment variable DRT_GCOPT:

extern(C) __gshared bool rt_envvars_enabled = true;

Setting default configuration properties in the executable can be done by specifying an array of options named rt_options:

extern(C) __gshared string[] rt_options = [ "gcopt=initReserve:100 profile:1" ];

Evaluation order of options is rt_options, then environment variables, then command line arguments, i.e. if command line arguments are not disabled, they can override options specified through the environment or embedded in the executable.

Precise Heap Scanning

Selecting precise as the collector via the options above means type information will be used to identify actual or possible pointers or references within heap allocated data objects. Non-pointer data will not be interpreted as a reference to other memory as a "false pointer". The collector has to make pessimistic assumptions if a memory slot can contain both a pointer or an integer value, it will still be scanned (e.g. in a union).

To use the collector memory functions from core.memory for data with a mixture of pointers and non-pointer data, pass the TypeInfo of the allocated struct, class, or type as the optional parameter. The default null is interpreted as memory that might contain pointers everywhere.

struct S { size_t hash; Data* data; }
S* s = cast(S*)GC.malloc(S.sizeof, 0, typeid(S));

Attention: Enabling precise scanning needs slightly more caution with type declarations. For example, when reserving a buffer as part of a struct and later emplacing an object instance with references to other allocations into this memory, do not use basic integer types to reserve the space. Doing so will cause the garbage collector not to detect the references. Instead, use an array type that will scan this area conservatively. Using void* is usually the best option as it also ensures proper alignment for pointers being scanned by the GC.

Precise Scanning of the DATA and TLS segment

Windows only: As of version 2.075, the DATA (global shared data) and TLS segment (thread local data) of an executable or DLL can be configured to be scanned precisely by the garbage collector instead of conservatively. This takes advantage of information emitted by the compiler to identify possible mutable pointers inside these segments. Immutable pointers with initializers are excluded from scanning, too, as they can only point to preallocated memory.

Precise scanning can be enabled with the D runtime option "scanDataSeg". Possible option values are "conservative" (default) and "precise". As with the collector options, it can be specified on the command line, in the environment or embedded into the executable, e.g.

extern(C) __gshared string[] rt_options = [ "scanDataSeg=precise" ];

Attention: Enabling precise scanning needs slightly more caution typing global memory. For example, to pre-allocate memory in the DATA/TLS segment and later emplace an object instance with references to other allocations into this memory, do not use basic integer types to reserve the space. Doing so will cause the garbage collector not to detect the references. Instead, use an array type that will scan this area conservatively. Using void* is usually the best option as it also ensures proper alignment for pointers being scanned by the GC.

class Singleton { void[] mem; }
align(__traits(classInstanceAlignment, Singleton))
    void*[(__traits(classInstanceSize, Singleton) - 1) / (void*).sizeof + 1]
    singleton_store;
static this()
{
    emplace!Singleton(singleton_store).mem = allocateMem();
}
Singleton singleton() { return cast(Singleton)singleton_store.ptr; }

For precise typing of that area, let the compiler generate the class instance into the DATA segment:

class Singleton { void[] mem; }
shared(Singleton) singleton = new Singleton;
shared static this() { singleton.mem = allocateSharedMem(); }

This doesn't work for TLS memory, though. See also: void arrays.

Parallel marking

By default the collector uses all available CPU cores to mark the heap.

This might affect your application if it has threads that are not suspended during the mark phase of the collection. Configure the number of additional threads used for marking by collector option parallel, e.g. by passing --DRT-gcopt=parallel:2 on the command line or embedding the option into the binary via rt_options. The number of threads actually created is limited to core.cpuid.threadsPerCPU-1. A value of 0 disables parallel marking completely.

Adding your own Collector

Collector implementations are added to a registry that allows to supply more implementations by just linking them into the binary. To do so add a function that is executed before the D runtime initialization using pragma(crt_constructor):

import core.gc.gcinterface, core.gc.registry;
extern (C) pragma(crt_constructor) void registerMyGC()
{
    registerGCFactory("mygc", &createMyGC);
}

GC createMyGC()
{
    __gshared instance = new MyGC;
    instance.initialize();
    return instance;
}

class MyGC : GC { /*...*/ }

[The collector modules defining the interface (gc.interface) and registration (gc.registry) are currently not public and are subject to change from version to version. Add an import search path to the druntime/src path to compile the example.]

The new collector is added to the list of available collectors that can be selected via the usual configuration options, e.g. by embedding rt_options into the binary:

extern (C) __gshared string[] rt_options = ["gcopt=gc:mygc"];

The standard GC implementation from a statically linked binary can be removed by redefining the function extern(C) void* register_default_gcs(). If no custom garbage collector has been registered all attempts to allocate collector managed memory will terminate the application with an appropriate message.

References

• Wikipedia
• GC FAQ
• Uniprocessor Garbage Collector Techniques
• Garbage Collection: Algorithms for Automatic Dynamic Memory Management