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
.
Parameters
Name | Description |
---|---|
val | The value to be reference counted |
Returns
An initialized RefCounted
containing val
.
See Also
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
(the default option) is convenient but
has the cost of a test whenever the payload is accessed. If autoInit == RefCountedAutoInitialize
, user code must call either
refCountedStore
or refCountedStore
before attempting to access the payload. Not doing so results in null
pointer dereference.
If T
is annotated with @disable
then autoInit
must be
RefCountedAutoInitialize
in order to compile.
Constructors
Name | Description |
---|---|
this
(args)
|
Constructor that initializes the payload. |
Properties
Name | Type | Description |
---|---|---|
refCountedPayload [get]
|
T | Returns a reference to the payload. If (autoInit ==
RefCountedAutoInitialize.yes), calls refCountedStore . Otherwise, just issues assert(refCountedStore . Used with alias
refCountedPayload this; , so callers can just use the RefCounted
object as a T .
|
refCountedStore [get]
|
inout(RefCounted | Returns storage implementation struct. |
Methods
Name | Description |
---|---|
opAssign
(rhs)
|
Assignment operators |
Inner structs
Name | Description |
---|---|
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