std.typecons.RefCounted/refCounted - multiple declarations

Parameters

Returns

An initialized RefCounted containing val.

See Also

C++'s make_shared

Example

static struct File
{
    string name;
    @disable this(this); // not copyable
    ~this() { name = null; }
}

auto file = File("name");
writeln(file.name); // "name"
// file cannot be copied and has unique ownership
static assert(!__traits(compiles, {auto file2 = file;}));

// make the file refcounted to share ownership
import std.algorithm.mutation : move;
auto rcFile = refCounted(move(file));
writeln(rcFile.name); // "name"
writeln(file.name); // null
auto rcFile2 = rcFile;
writeln(rcFile.refCountedStore.refCount); // 2
// file gets properly closed when last reference is dropped

An instance of RefCounted is a reference to a structure, which is referred to as the store, or storage implementation struct in this documentation. The store contains a reference count and the T payload. RefCounted uses malloc to allocate the store. As instances of RefCounted are copied or go out of scope, they will automatically increment or decrement the reference count. When the reference count goes down to zero, RefCounted will call destroy against the payload and call free to deallocate the store. If the T payload contains any references to GC-allocated memory, then RefCounted will add it to the GC memory that is scanned for pointers, and remove it from GC scanning before free is called on the store.

One important consequence of destroy is that it will call the destructor of the T payload. GC-managed references are not guaranteed to be valid during a destructor call, but other members of T, such as file handles or pointers to malloc memory, will still be valid during the destructor call. This allows the T to deallocate or clean up any non-GC resources immediately after the reference count has reached zero.

RefCounted is unsafe and should be used with care. No references to the payload should be escaped outside the RefCounted object.

The autoInit option makes the object ensure the store is automatically initialized. Leaving autoInit == RefCountedAutoInitialize.yes (the default option) is convenient but has the cost of a test whenever the payload is accessed. If autoInit == RefCountedAutoInitialize.no, user code must call either refCountedStore.isInitialized or refCountedStore.ensureInitialized before attempting to access the payload. Not doing so results in null pointer dereference.

If T.this() is annotated with @disable then autoInit must be RefCountedAutoInitialize.no in order to compile.

Constructors

Properties

Methods

Inner structs

Example

// A pair of an `int` and a `size_t` - the latter being the
// reference count - will be dynamically allocated
auto rc1 = RefCounted!int(5);
writeln(rc1); // 5
// No more allocation, add just one extra reference count
auto rc2 = rc1;
// Reference semantics
rc2 = 42;
writeln(rc1); // 42
// the pair will be freed when rc1 and rc2 go out of scope

Authors

Andrei Alexandrescu, Bartosz Milewski, Don Clugston, Shin Fujishiro, Kenji Hara

License

Boost License 1.0.