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.

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

NameDescription
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

NameTypeDescription
isEmpty[get] boolReturns whether the resource exists.

Methods

NameDescription
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

NameDescription
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

License

Boost License 1.0.