Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
PrevUpHomeNext

Class template shared_ptr

boost::interprocess::shared_ptr

Synopsis

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

template<typename T, typename VoidAllocator, typename Deleter> 
class shared_ptr {
public:
  // types
  typedef T                                                                                                  element_type;           
  typedef T                                                                                                  value_type;             
  typedef boost::container::allocator_traits< VoidAllocator >::pointer                                       void_ptr;               
  typedef boost::intrusive::pointer_traits< void_ptr >::template rebind_pointer< T >::type                   pointer;                
  typedef unspecified                                                                                        reference;              
  typedef unspecified                                                                                        const_reference;        
  typedef boost::intrusive::pointer_traits< void_ptr >::template rebind_pointer< const Deleter >::type       const_deleter_pointer;  
  typedef boost::intrusive::pointer_traits< void_ptr >::template rebind_pointer< const VoidAllocator >::type const_allocator_pointer;

  // construct/copy/destruct
  shared_ptr();
  explicit shared_ptr(const pointer &, 
                      const VoidAllocator & = VoidAllocator(), 
                      const Deleter & = Deleter());
  shared_ptr(const shared_ptr &);
  shared_ptr(const shared_ptr &, const pointer &);
  template<typename Y> 
    shared_ptr(shared_ptr< Y, VoidAllocator, Deleter > const &);
  template<typename Y> 
    explicit shared_ptr(weak_ptr< Y, VoidAllocator, Deleter > const &);
  explicit shared_ptr(shared_ptr &&);
  template<typename Y> 
    shared_ptr & operator=(shared_ptr< Y, VoidAllocator, Deleter > const &);
  shared_ptr & operator=(BOOST_COPY_ASSIGN_REF(shared_ptr));
  shared_ptr & operator=(shared_ptr &&);

  // public member functions
  void reset();
  template<typename Pointer> 
    void reset(const Pointer &, const VoidAllocator & = VoidAllocator(), 
               const Deleter & = Deleter());
  template<typename Y> 
    void reset(shared_ptr< Y, VoidAllocator, Deleter > const &, 
               const pointer &);
  reference operator *() const;
  pointer operator->() const;
  pointer get() const;
  bool operator!() const;
  bool unique() const;
  long use_count() const;
  void swap(shared_ptr< T, VoidAllocator, Deleter > &);
};

Description

shared_ptr stores a pointer to a dynamically allocated object. The object pointed to is guaranteed to be deleted when the last shared_ptr pointing to it is destroyed or reset.

shared_ptr is parameterized on T (the type of the object pointed to), VoidAllocator (the void allocator to be used to allocate the auxiliary data) and Deleter (the deleter whose operator() will be used to delete the object.

The internal pointer will be of the same pointer type as typename VoidAllocator::pointer type (that is, if typename VoidAllocator::pointer is offset_ptr<void>, the internal pointer will be offset_ptr<T>).

Because the implementation uses reference counting, cycles of shared_ptr instances will not be reclaimed. For example, if main() holds a shared_ptr to A, which directly or indirectly holds a shared_ptr back to A, A's use count will be 2. Destruction of the original shared_ptr will leave A dangling with a use count of 1. Use weak_ptr to "break cycles."

shared_ptr public construct/copy/destruct

  1. shared_ptr();

    Constructs an empty shared_ptr. Use_count() == 0 && get()== 0.

  2. explicit shared_ptr(const pointer & p, 
                        const VoidAllocator & a = VoidAllocator(), 
                        const Deleter & d = Deleter());

    Constructs a shared_ptr that owns the pointer p. Auxiliary data will be allocated with a copy of a and the object will be deleted with a copy of d. Requirements: Deleter and A's copy constructor must not throw.

  3. shared_ptr(const shared_ptr & r);

    Copy constructs a shared_ptr. If r is empty, constructs an empty shared_ptr. Otherwise, constructs a shared_ptr that shares ownership with r. Never throws.

  4. shared_ptr(const shared_ptr & other, const pointer & p);

    Constructs a shared_ptr that shares ownership with other and stores p. Postconditions: get() == p && use_count() == r.use_count(). Throws: nothing.

  5. template<typename Y> 
      shared_ptr(shared_ptr< Y, VoidAllocator, Deleter > const & r);

    If r is empty, constructs an empty shared_ptr. Otherwise, constructs a shared_ptr that shares ownership with r. Never throws.

  6. template<typename Y> 
      explicit shared_ptr(weak_ptr< Y, VoidAllocator, Deleter > const & r);

    Constructs a shared_ptr that shares ownership with r and stores a copy of the pointer stored in r.

  7. explicit shared_ptr(shared_ptr && other);

    Move-Constructs a shared_ptr that takes ownership of other resource and other is put in default-constructed state. Throws: nothing.

  8. template<typename Y> 
      shared_ptr & operator=(shared_ptr< Y, VoidAllocator, Deleter > const & r);

    Equivalent to shared_ptr(r).swap(*this). Never throws

  9. shared_ptr & operator=(BOOST_COPY_ASSIGN_REF(shared_ptr) r);

    Equivalent to shared_ptr(r).swap(*this). Never throws

  10. shared_ptr & operator=(shared_ptr && other);

    Move-assignment. Equivalent to shared_ptr(other).swap(*this). Never throws

shared_ptr public member functions

  1. void reset();

    This is equivalent to: this_type().swap(*this);

  2. template<typename Pointer> 
      void reset(const Pointer & p, const VoidAllocator & a = VoidAllocator(), 
                 const Deleter & d = Deleter());

    This is equivalent to: this_type(p, a, d).swap(*this);

  3. template<typename Y> 
      void reset(shared_ptr< Y, VoidAllocator, Deleter > const & r, 
                 const pointer & p);
  4. reference operator *() const;

    Returns a reference to the pointed type

  5. pointer operator->() const;

    Returns the pointer pointing to the owned object

  6. pointer get() const;

    Returns the pointer pointing to the owned object

  7. bool operator!() const;

    Not operator. Returns true if this->get() != 0, false otherwise

  8. bool unique() const;

    Returns use_count() == 1. unique() might be faster than use_count()

  9. long use_count() const;

    Returns the number of shared_ptr objects, *this included, that share ownership with *this, or an unspecified nonnegative value when *this is empty. use_count() is not necessarily efficient. Use only for debugging and testing purposes, not for production code.

  10. void swap(shared_ptr< T, VoidAllocator, Deleter > & other);

    Exchanges the contents of the two smart pointers.


PrevUpHomeNext