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 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 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 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 Allows safe construction of Unique. It creates the resource and guarantees unique ownership of it (unless T publishes aliases of this).
opAssign 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.

Comments