View source code
Display the source code in std/typecons.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

std.typecons.RefCounted/refCounted - multiple declarations

Function refCounted

Initializes a RefCounted with val. The template parameter T of RefCounted is inferred from val. This function can be used to move non-copyable values to the heap. It also disables the autoInit option of RefCounted.

RefCounted!(T,RefCountedAutoInitialize.no) refCounted(T) (
  T val
);

Parameters

NameDescription
val The value to be reference counted

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

Struct RefCounted

Defines a reference-counted object containing a T value as payload.

struct RefCounted(T, RefCountedAutoInitialize autoInit = RefCountedAutoInitialize.yes)
  
if (!is(T == class) && !is(T == interface));

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

NameDescription
this (args) Constructor that initializes the payload.

Properties

NameTypeDescription
refCountedPayload[get] TReturns a reference to the payload. If (autoInit == RefCountedAutoInitialize.yes), calls refCountedStore.ensureInitialized. Otherwise, just issues assert(refCountedStore.isInitialized). Used with alias refCountedPayload this;, so callers can just use the RefCounted object as a T.
refCountedStore[get] inout(RefCounted.RefCountedStore)Returns storage implementation struct.

Methods

NameDescription
opAssign (rhs) Assignment operators

Inner structs

NameDescription
RefCountedStore RefCounted storage implementation.

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.