Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.

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;
   };

Ty

The type controlled by the shared pointer.

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.

Header: <memory>

Namespace: std::tr1

Community Additions

ADD
Show:
© 2015 Microsoft