Class template unique_ptr

boost::interprocess::unique_ptr

Synopsis

// In header: <boost/interprocess/smart_ptr/unique_ptr.hpp>

template<typename T, typename D> 
class unique_ptr {
public:
  // types
  typedef T           element_type;
  typedef D           deleter_type;
  typedef unspecified pointer;     

  // construct/copy/destruct
  unique_ptr();
  unique_ptr(pointer);
  unique_ptr(pointer, unspecified);
  unique_ptr(unique_ptr &&);
  template<typename U, typename E> 
    unique_ptr(unique_ptr &&, unspecified = nat());
  unique_ptr& operator=(unique_ptr &&);
  template<typename U, typename E> unique_ptr& operator=(unique_ptr &&);
  unique_ptr& operator=(int nat::*);
  ~unique_ptr();

  // public member functions
  unspecified operator*() const;
  pointer operator->() const;
  pointer get() const;
  deleter_reference get_deleter() ;
  deleter_const_reference get_deleter() const;
  operator int nat::*() const;
  pointer release() ;
  void reset(pointer = 0) ;
  void swap(unique_ptr &) ;
};

Description

Template unique_ptr stores a pointer to an object and deletes that object using the associated deleter when it is itself destroyed (such as when leaving block scope.

The unique_ptr provides a semantics of strict ownership. A unique_ptr owns the object it holds a pointer to.

A unique_ptr is not CopyConstructible, nor CopyAssignable, however it is MoveConstructible and Move-Assignable.

The uses of unique_ptr include providing exception safety for dynamically allocated memory, passing ownership of dynamically allocated memory to a function, and returning dynamically allocated memory from a function

A client-supplied template argument D must be a function pointer or functor for which, given a value d of type D and a pointer ptr to a type T*, the expression d(ptr) is valid and has the effect of deallocating the pointer as appropriate for that deleter. D may also be an lvalue-reference to a deleter.

If the deleter D maintains state, it is intended that this state stay with the associated pointer as ownership is transferred from unique_ptr to unique_ptr. The deleter state need never be copied, only moved or swapped as pointer ownership is moved around. That is, the deleter need only be MoveConstructible, MoveAssignable, and Swappable, and need not be CopyConstructible (unless copied into the unique_ptr) nor CopyAssignable.

`unique_ptr` public construct/copy/destruct

```
unique_ptr();
```
Requires: D must be default constructible, and that construction must not throw an exception. D must not be a reference type.

Effects: Constructs a unique_ptr which owns nothing.

Postconditions: get() == 0. get_deleter() returns a reference to a default constructed deleter D.

Throws: nothing.
```
unique_ptr(pointer p);
```
Requires: The expression D()(p) must be well formed. The default constructor of D must not throw an exception.

D must not be a reference type.

Effects: Constructs a unique_ptr which owns p.

Postconditions: get() == p. get_deleter() returns a reference to a default constructed deleter D.

Throws: nothing.
```
unique_ptr(pointer p, unspecified d);
```
Requires: The expression d(p) must be well formed.

Postconditions: get() == p. get_deleter() returns a reference to the internally stored deleter. If D is a reference type then get_deleter() returns a reference to the lvalue d.

Throws: nothing.
```
unique_ptr(unique_ptr && u);
```
Requires: If the deleter is not a reference type, construction of the deleter D from an lvalue D must not throw an exception.

Effects: Constructs a unique_ptr which owns the pointer which u owns (if any). If the deleter is not a reference type, it is move constructed from u's deleter, otherwise the reference is copy constructed from u's deleter.

After the construction, u no longer owns a pointer. [ Note: The deleter constructor can be implemented with boost::interprocess::forward<D>. -end note ]

Postconditions: get() == value u.get() had before the construction. get_deleter() returns a reference to the internally stored deleter which was constructed from u.get_deleter(). If D is a reference type then get_- deleter() and u.get_deleter() both reference the same lvalue deleter.

Throws: nothing.
```
template<typename U, typename E> 
  unique_ptr(unique_ptr && u, unspecified = nat());
```
Requires: If D is not a reference type, construction of the deleter D from an rvalue of type E must be well formed and not throw an exception. If D is a reference type, then E must be the same type as D (diagnostic required). unique_ptr<U, E>::pointer must be implicitly convertible to pointer.

Effects: Constructs a unique_ptr which owns the pointer which u owns (if any). If the deleter is not a reference type, it is move constructed from u's deleter, otherwise the reference is copy constructed from u's deleter.

After the construction, u no longer owns a pointer.

postconditions get() == value u.get() had before the construction, modulo any required offset adjustments resulting from the cast from U* to T*. get_deleter() returns a reference to the internally stored deleter which was constructed from u.get_deleter().

Throws: nothing.
```
unique_ptr& operator=(unique_ptr && u);
```
Requires: Assignment of the deleter D from an rvalue D must not throw an exception.

Effects: reset(u.release()) followed by a move assignment from u's deleter to this deleter.

Postconditions: This unique_ptr now owns the pointer which u owned, and u no longer owns it.

Returns: *this.

Throws: nothing.
```
template<typename U, typename E> unique_ptr& operator=(unique_ptr && u);
```
Requires: Assignment of the deleter D from an rvalue D must not throw an exception. U* must be implicitly convertible to T*.

Effects: reset(u.release()) followed by a move assignment from u's deleter to this deleter. If either D or E is a reference type, then the referenced lvalue deleter participates in the move assignment.

Postconditions: This unique_ptr now owns the pointer which u owned, and u no longer owns it.

Returns: *this.

Throws: nothing.
```
unique_ptr& operator=(int nat::*);
```
Assigns from the literal 0 or NULL.

Effects: reset().

Postcondition: get() == 0

Returns: *this.

Throws: nothing.
```
~unique_ptr();
```
Effects: If get() == 0 there are no effects. Otherwise get_deleter()(get()).

Throws: nothing.

`unique_ptr` public member functions

```
unspecified operator*() const;
```
Requires: get() != 0. Returns: *get(). Throws: nothing.
```
pointer operator->() const;
```
Requires: get() != 0. Returns: get(). Throws: nothing.
```
pointer get() const;
```
Returns: The stored pointer. Throws: nothing.
```
deleter_reference get_deleter() ;
```
Returns: A reference to the stored deleter.

Throws: nothing.
```
deleter_const_reference get_deleter() const;
```
Returns: A const reference to the stored deleter.

Throws: nothing.
```
operator int nat::*() const;
```
Returns: An unspecified value that, when used in boolean contexts, is equivalent to get() != 0.

Throws: nothing.
```
pointer release() ;
```
Postcondition: get() == 0.

Returns: The value get() had at the start of the call to release.

Throws: nothing.
```
void reset(pointer p = 0) ;
```
Effects: If p == get() there are no effects. Otherwise get_deleter()(get()).

Postconditions: get() == p.

Throws: nothing.
```
void swap(unique_ptr & u) ;
```
Requires: The deleter D is Swappable and will not throw an exception under swap.

Effects: The stored pointers of this and u are exchanged. The stored deleters are swapped (unqualified). Throws: nothing.

Boost C++ Libraries