Garbage Collection

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

D also provides the mechanisms to write code where the garbage collector 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 garbage collection. Experience both with new projects written with garbage collection in mind, and converting existing projects to garbage collection shows that:

• Garbage collected programs 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 garbage collection, 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.
  • Garbage 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.
  • Garbage collected programs do not suffer from gradual deterioration due to an accumulation of memory leaks.
• Garbage collectors reclaim unused memory, therefore they do not suffer from "memory leaks" which can cause long running applications to gradually consume more and more memory until they bring down the system. GC programs have longer term stability.
• Garbage collected programs 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.
• Garbage collected programs are faster to develop and debug, because there's no need for developing, debugging, testing, or maintaining the explicit deallocation code.

Garbage collection is not a panacea. There are some downsides:

• It is not always obvious when the GC 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.
• Garbage collectors can keep around some memory that an explicit deallocator would not.
• Garbage collection should be implemented as a basic operating system kernel service. But since it is not, garbage collecting programs must carry around with them the garbage collection 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 GC heap.

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

How Garbage Collection Works

The GC works by:

1. Stopping all other threads than the thread currently trying to allocate GC memory.
2. ‘Hijacking’ the current thread for GC work.
3. Scanning all ‘root’ memory ranges for pointers into GC allocated memory.
4. Recursively scanning all allocated memory pointed to by roots looking for more pointers into GC allocated memory.
5. Freeing all GC 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 Garbage Collected Objects With Foreign Code

The garbage 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 Garbage Collector

Pointers in D can be broadly divided into two categories: Those that point to garbage collected 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 garbage collected pointers and references, however, there are some restrictions. These restrictions are minor, but they are intended to enable the maximum flexibility in garbage 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 garbage collected 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 garbage collection. Pointers are provided in order to interface successfully with C APIs and for some low level work.

Working with the Garbage Collector

Garbage collection doesn't solve every memory deallocation problem. For example, if a pointer to a large data structure is kept, the garbage 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 Garbage Collector

Although D does not currently use a moving garbage 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 Garbage Collector

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

• NewExpression
• Array appending
• Array concatenation
• Array literals (except when used to initialize static data)
• Associative array literals
• Any insertion, removal, or lookups 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

Configuring the Garbage Collector

Since version 2.067, The garbage 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|manual - select gc 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
• heapSizeFactor:N - targeted heap size to used memory ratio

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 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 GC 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, if you pre-allocate memory in the DATA/TLS segment and later emplace an object instance with references to other allocations into this memory, you must 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; }
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, you can also let the compiler generate the class instance into the DATA segment for you:

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

This doesn't work for TLS memory, though.

References

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