:relfileprefix: ../../
[#C78CB675CCEE6578EFDEB0D69E45D6F853DDAE29]

= Class unique_resource

pass:v,q[RAII wrapper for automatically reclaiming arbitrary resources.]


== Synopsis

Declared in header `<https://github.com/Lastique/scope/blob/develop/include/boost/scope/unique_resource.hpp#L1051[boost/scope/unique_resource.hpp,window=blank_]>`

[source,cpp,subs="verbatim,macros,-callouts"]
----
template<
    typename Resource,
    typename Deleter,
    typename Traits = void>
class unique_resource;
----

==  Types
[,cols=2]
|===
|Name |Description
|xref:boost/scope/unique_resource-0c/deleter_type.adoc[`pass:v[deleter_type]`] |
pass:v,q[Deleter type]

|xref:boost/scope/unique_resource-0c/resource_type.adoc[`pass:v[resource_type]`] |
pass:v,q[Resource type]

|xref:boost/scope/unique_resource-0c/traits_type.adoc[`pass:v[traits_type]`] |
pass:v,q[Resource traits]

|===
==  Member Functions
[,cols=2]
|===
|Name |Description
|xref:boost/scope/unique_resource-0c/allocated.adoc[`pass:v[allocated]`] |
pass:v,q[Returns] `true` pass:v,q[if the resource is allocated and to be reclaimed by the deleter, otherwise]
`false.`

|xref:boost/scope/unique_resource-0c/get.adoc[`pass:v[get]`] |
pass:v,q[Returns a reference to the resource object.]

|xref:boost/scope/unique_resource-0c/get_deleter.adoc[`pass:v[get_deleter]`] |
pass:v,q[Returns a reference to the deleter object.]

|xref:boost/scope/unique_resource-0c/operator_star.adoc[`pass:v[operator*]`] |

|xref:boost/scope/unique_resource-0c/operator_ptr.adoc[`pass:v[operator->]`] |

|xref:boost/scope/unique_resource-0c/operator_assign.adoc[`pass:v[operator=]`] |
|xref:boost/scope/unique_resource-0c/release.adoc[`pass:v[release]`] |
pass:v,q[Marks the resource as unallocated. Does not call the deleter if the resource was previously allocated.]

|xref:boost/scope/unique_resource-0c/reset.adoc[`pass:v[reset]`] |
pass:v,q[If the resource is allocated, calls the deleter function on it and marks the resource as unallocated.]

|xref:boost/scope/unique_resource-0c/swap.adoc[`pass:v[swap]`] |

|xref:boost/scope/unique_resource-0c/2constructor.adoc[`pass:v[unique_resource]`] |
|xref:boost/scope/unique_resource-0c/2destructor.adoc[`pass:v[~unique_resource]`] |
pass:v,q[Invokes `reset()` and destroys the resource.]

|===
==  Friends
[,cols=2]
|===
|Name |Description
|xref:boost/scope/unique_resource-0c/08friend.adoc[`pass:v[swap]`] |

|===

== Description

pass:v,q[A] `unique_resource` pass:v,q[object exclusively owns wrapped resource and invokes]
pass:v,q[the deleter function object on it on destruction. The wrapped resource can have]
pass:v,q[any type that is:]

* pass:v,q[Move-constructible, where the move constructor is marked as `noexcept`, or]

* pass:v,q[Copy-constructible, or]

* pass:v,q[An lvalue reference to an object type.]
pass:v,q[The deleter must be a function object type that is callable on an lvalue]
pass:v,q[of the resource type. The deleter must be copy-constructible.]
pass:v,q[An optional resource traits template parameter may be specified. Resource]
pass:v,q[traits can be used to optimize]
`unique_resource`
pass:v,q[implementation when]
pass:v,q[the following conditions are met:]

* pass:v,q[There is at least one value of the resource type that is considered]
pass:v,q[unallocated (that is, no allocated resource shall be equal to one of]
pass:v,q[the unallocated resource values). The unallocated resource values need not]
pass:v,q[be deallocated using the deleter.]

* pass:v,q[One of the unallocated resource values can be considered the default.]
pass:v,q[Constructing the default resource value and assigning it to a resource]
pass:v,q[object (whether allocated or not) shall not throw exceptions.]

* pass:v,q[Resource objects can be tested for being unallocated. Such a test shall]
pass:v,q[not throw exceptions.]
pass:v,q[If specified, the resource traits must be a class that has the following]
pass:v,q[public static members:]

* pass:v,q[`Resource make_default() noexcept` - must return the default resource]
pass:v,q[value.]

* pass:v,q[`bool is_allocated(Resource const]
pass:v,q[&]
pass:v,q[res) noexcept` - must]
pass:v,q[return]
`true`
pass:v,q[if]
`res`
pass:v,q[is not one of the unallocated resource values]
pass:v,q[and]
`false`
pass:v,q[otherwise.]
pass:v,q[Note that `is_allocated(make_default())` must always return]
`false.`
pass:v,q[When conforming resource traits are specified,]
`unique_resource`
pass:v,q[will be able]
pass:v,q[to avoid storing additional indication of whether the owned resource object]
pass:v,q[needs to be deallocated with the deleter on destruction. It will use the default]
pass:v,q[resource value to initialize the owned resource object when]
`unique_resource`
pass:v,q[is not in the allocated state. Additionally, it will be possible to construct]
`unique_resource`
pass:v,q[with unallocated resource values, which will create]
`unique_resource`
pass:v,q[objects in deallocated state (the deleter will not be called]
pass:v,q[on unallocated resource values).]



