Struct std.typecons.Unique
Encapsulates unique ownership of a resource.
struct Unique(T)
;
When a Unique!T
goes out of scope it will call destroy
on the resource T
that it manages, unless it is transferred.
One important consequence of destroy
is that it will call the
destructor of the resource T
. 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 resource
T
to deallocate or clean up any non-GC resources.
If it is desirable to persist a Unique!T
outside of its original
scope, then it can be transferred. The transfer can be explicit, by
calling release
, or implicit, when returning Unique from a
function. The resource T
can be a polymorphic class object or
instance of an interface, in which case Unique behaves polymorphically
too.
If T
is a value type, then Unique!T
will be implemented
as a reference to a T
.
Constructors
Name | Description |
---|---|
this
(p)
|
Constructor that takes an rvalue. It will ensure uniqueness, as long as the rvalue isn't just a view on an lvalue (e.g., a cast). Typical usage: |
this
(p)
|
Constructor that takes an lvalue. It nulls its source. The nulling will ensure uniqueness as long as there are no previous aliases to the source. |
this
(u)
|
Constructor that takes a Unique of a type that is convertible to our type.
|
Properties
Name | Type | Description |
---|---|---|
isEmpty [get]
|
bool | Returns whether the resource exists. |
Methods
Name | Description |
---|---|
create
(args)
|
Allows safe construction of Unique . It creates the resource and
guarantees unique ownership of it (unless T publishes aliases of
this ).
|
opAssign
(u)
|
Transfer ownership from a Unique of a type that is convertible to our type.
|
release
()
|
Transfer ownership to a Unique rvalue. Nullifies the current contents.
Same as calling std.algorithm.move on it.
|
Aliases
Name | Description |
---|---|
RefT
|
Represents a reference to T . Resolves to T* if T is a value type.
|
Example
static struct S
{
int i;
this(int i){this .i = i;}
}
Unique!S produce()
{
// Construct a unique instance of S on the heap
Unique!S ut = new S(5);
// Implicit transfer of ownership
return ut;
}
// Borrow a unique resource by ref
void increment(ref Unique!S ur)
{
ur .i++;
}
void consume(Unique!S u2)
{
writeln(u2 .i); // 6
// Resource automatically deleted here
}
Unique!S u1;
assert(u1 .isEmpty);
u1 = produce();
increment(u1);
writeln(u1 .i); // 6
//consume(u1); // Error: u1 is not copyable
// Transfer ownership of the resource
consume(u1 .release);
assert(u1 .isEmpty);
Authors
Andrei Alexandrescu, Bartosz Milewski, Don Clugston, Shin Fujishiro, Kenji Hara