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(fileStruct RefCounted
Defines a reference-counted object containing a T value as
payload.
struct RefCounted(T, RefCountedAutoInitialize autoInit = RefCountedAutoInitialize
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