shared_ptr Class

Wraps a shareable pointer.

template<class Ty>
   class shared_ptr {
public:
   typedef Ty element_type;

   shared_ptr();
   template<class Other>
      explicit shared_ptr(Other*);
   template<class Other, class D>
      shared_ptr(Other*, D);
   template<class Other, class D, class A>
      shared_ptr(Other *ptr, D dtor, A ator);
   shared_ptr(const shared_ptr&);
   template<class Other>
      shared_ptr(const shared_ptr<Other>&);
   template<class Other>
      shared_ptr(const weak_ptr<Other>&);
   template<class &>
      shared_ptr(const std::auto_ptr<Other>&);
   ~shared_ptr();

   shared_ptr& operator=(const shared_ptr&);
   template<class Other>
      shared_ptr& operator=(const shared_ptr<Other>&);
   template<class Other>
      shared_ptr& operator=(auto_ptr<Other>&);

   void swap(shared_ptr&);
   void reset();
   template<class Other>
      void reset(Other*);
   template<class Other, class D>
      void reset(Other*, D);

   Ty *get() const;
   Ty& operator*() const;
   Ty *operator->() const;
   long use_count() const;
   bool unique() const;
   operator boolean-type() const;
   };

Parameters

• Ty
  The type controlled by the shared pointer.

Remarks

The template class describes an object that uses reference counting to manage resources. Each shared_ptr object effectively holds a pointer to the resource that it owns or holds a null pointer. A resource can be owned by more than one shared_ptr object; when the last shared_ptr object that owns a particular resource is destroyed the resource is freed.

The template argument Ty may be an incomplete type except as noted for certain operand sequences.

When a shared_ptr<Ty> object is constructed from a resource pointer of type D* or from a shared_ptr<D>, the pointer type D* must be convertible to Ty*. If it is not, the code will not compile. For example:

class B {};
class D : public B {};

shared_ptr<D> sp0(new D);   // okay, template parameter D and argument D*
shared_ptr<D> sp1(sp0);     // okay, template parameter D and argument shared_ptr<D>
shared_ptr<B> sp2(new D);   // okay, D* convertible to B*
shared_ptr<B> sp3(sp0);     // okay, template parameter B and argument shared_ptr<D>
shared_ptr<B> sp4(sp2);     // okay, template parameter B and argument shared_ptr<B>
shared_ptr<int> sp4(new D); // error, D* not convertible to int*
shared_ptr<int> sp5(sp2);   // error, template parameter int and argument shared_ptr<B>

A shared_ptr object owns a resource:

if it was constructed with a pointer to that resource,

if it was constructed from a shared_ptr object that owns that resource,

if it was constructed from a weak_ptr Class object that points to that resource, or

if ownership of that resource was assigned to it, either with shared_ptr::operator= or by calling the member function shared_ptr::reset.

All the shared_ptr objects that own a single resource share a control block which holds the number of shared_ptr objects that own the resource, the number of weak_ptr objects that point to the resource, and the deleter for that resource if it has one. A shared_ptr object that was initialized with a null pointer has a control block; thus it is not an empty shared_ptr. After a shared_ptr object releases a resource it no longer owns that resource. After a weak_ptr object releases a resource it no longer points to that resource. When the number of shared_ptr objects that own a resource becomes zero the resource is freed, either by deleting it or by passing its address to a deleter, depending on how ownership of the resource was originally created. When the number of shared_ptr objects that own a resource is zero and the number of weak_ptr objects that point to that resource is zero the control block is freed.

An empty shared_ptr object does not own any resources and has no control block.

A deleter is a function pointer or an object of a type with a member function operator(). Its type must be copy constructible and its copy constructor and destructor must not throw exceptions. A deleter is bound to a shared_ptr object with an operand sequence of the form ptr, dtor.

Some functions take an operand sequence that defines properties of the resulting shared_ptr<Ty> or weak_ptr<Ty> object. You can specify such an operand sequence several ways:

no arguments -- the resulting object is an empty shared_ptr object or an empty weak_ptr object.

ptr -- a pointer of type Other* to the resource to be managed. Ty must be a complete type. If the function fails it evaluates the expression delete ptr.

ptr, dtor -- a pointer of type Other* to the resource to be managed and a deleter for that resource. If the function fails it calls dtor(ptr), which must be well defined.

sp -- a shared_ptr<Other> object that owns the resource to be managed.

wp -- a weak_ptr<Other> object that points to the resource to be managed.

ap -- an auto_ptr<Other> object that holds a pointer to the resource to be managed. If the function succeeds it calls ap.release(); otherwise it leaves ap unchanged.

In all cases, the pointer type Other* must be convertible to Ty*.

Thread Safety

Multiple threads can simultaneously read and write different shared_ptr objects, even when the objects are copies that share ownership.

Requirements

Header: <memory>

Namespace: std::tr1

See Also

Reference

<memory> (TR1)

weak_ptr Class

Thread Safety in the Standard C++ Library