Class Template shared_ptr

Description
Headers
Reference
Synopsis
Class Template shared_ptr

Description

The class template shared_ptr is a reference-counted Smart Interface Pointer patterned on the template boost::shared_ptr.

Together with each object managed by a shared_ptr is stored a reference count and a deleter. The reference count records the number of instances of shared_ptr which manage a given object. When the reference count reaches zero — just before the last shared_ptr managing a given object is destroyed — the object is freed using the stored deleter. By default, the deleter is an instance of boost::checked_deleter, but a user supplied deleter may be specified when an object is bound to an instance of shared_ptr.

To Do

Add pre- and post- conditions, where appropriate.

Headers

<boost/interfaces/shared_ptr.hpp>

Reference

Synopsis

namespace boost { namespace interfaces {

template<typename Interface>
class shared_ptr {
public:
    typedef typename fixed_view<Interface> element_type;

        // Constructors

    shared_ptr();

    template<typename T>
    explicit shared_ptr(T* t);

    template<typename T, typename D>
    shared_ptr(T* t, D d);

    shared_ptr(const shared_ptr& ptr);

    template<typename Subinterface>
    shared_ptr(const shared_ptr<Subinterface>& ptr);

        // Destructor

    ~shared_ptr();

        // Assignment

    shared_ptr& operator=(shared_ptr ptr);

    template<typename Subinterface>    
    shared_ptr& operator=(shared_ptr<Subinterface> ptr);

    [Member functions from Interface]

        // Smart pointer interface

    element_type* get() const;

    element_type& operator*() const;

    element_type* operator->() const;

    void reset();

    template<typename T>
    void reset(T* t);

    template<typename T, typename D>
    void reset(T* t, D d);

    operator unspecified-bool-type() const;

    void swap(shared_ptr& p);

    bool unique() const;

    long use_count() const;
};

} } // End namespace boost::interfaces

Class Template shared_ptr

Template Parameters
Interface-

An interface defined using the Interface Definition Language (IDL).

shared_ptr::element_type

    typedef typename fixed_view<T> element_type;

Used by the dereferencing operators, in place of the template parameter Interface, to help prevent resource leaks and double deletes. See Example.

shared_ptr::shared_ptr

    shared_ptr();

Constructs an empty shared_ptr. Never throws.

    template<typename T>
    explicit shared_ptr(T* t);
Template Parameters
T-

A class implementing Interface. The type T must be complete and have an accessible destructor which does not throw, but need not be complete at the point t is freed.

Constructs an instance of shared_ptr which takes ownership of t. The reference count is initialized to one; when it reaches zero, t will be freed using delete.

If an exception is thrown, t will be freed using delete. 

    template<typename T, typename D>
    shared_ptr(T* t, D d);
Template Parameters
T-

A class implementing Interface.

D-

A type with an accessible copy constructor and destructor which do not throw. The expression d(t), where d is an instance of D and t has type T*, must be well-formed, must not lead to undefined behavior and must not throw.

Constructs an instance of shared_ptr which takes ownership of t. The reference count is initialized to one; when it reaches zero, t will be freed using a copy of d.

If an exception is thrown, t will be freed by invoking d(t). 

    shared_ptr(const shared_ptr& ptr);

    template<typename Subinterface>
    shared_ptr(const shared_ptr<Subinterface>& ptr);

If the given instance of shared_ptr is non-empty, constructs a shared_ptr which manages the same object as the given instance and increments the reference count. Otherwise, constructs an empty shared_ptr. Never throws.

shared_ptr::~shared_ptr

    ~shared_ptr();

If the reference count is non-zero, decrements the reference count and relinquishes ownership of the managed object.

shared_ptr::operator=

    shared_ptr& operator=(shared_ptr ptr);

    template<typename Subinterface>    
    shared_ptr& operator=(shared_ptr<Subinterface> ptr);

If the reference count is non-zero, decrements the reference count and relinquishes ownership of the managed object.

Next, if the given instance of shared_ptr is non-empty, takes shared ownership of the managed object and increments the reference count. Never throws.

shared_ptr::get

    element_type* get() const;

Returns a pointer through which member functions of the bound object can be accessed. Never throws.

shared_ptr::operator*

    element_type& operator*() const;

Returns a reference through which member functions of the bound object can be accessed. Never throws.

shared_ptr::operator->

    element_type* operator->() const;

Returns a pointer through which member functions of the bound object can be accessed. Never throws.

shared_ptr::reset

    void reset();

If the reference count is non-zero, decrements the reference count and relinquishes ownership of the managed object.

shared_ptr::reset

    template<typename T>
    void reset(T* t);
Template Parameters
T-

A class implementing Interface. The type T must be complete and have an accessible destructor which does not throw, but need not be complete at the point t is freed.

If the reference count is non-zero, decrements the reference count and relinquishes ownership of the managed object.

Next, takes ownership of t. The reference count is initialized to one; when it reaches zero, t will be freed using delete.

If an exception is thrown, t will be freed using delete. 

    template<typename T, typename D>
    void reset(T* t, D d);
Template Parameters
T-

A class implementing Interface.

D-

A type with an accessible copy constructor and destructor which do not throw. The expression d(t), where d is an instance of D and t has type T*, must be well-formed, must not lead to undefined behavior and must not throw.

If the reference count is non-zero, decrements the reference count and relingues ownership of the managed object.

Next, takes ownership of t. The reference count is initialized to one; when it reaches zero, t will be freed using a copy of d.

If an exception is thrown, t will be freed by invoking d(t).

shared_ptr::operator unspecified-bool-type()

    operator unspecified-bool-type() const;

Returns an unspecified value which, when used in boolean contexts, is equivalent to get() != 0. Never throws.

shared_ptr::swap

    void swap(shared_ptr& p);

Exchanges the content of this instance of shared_ptr with that of the given instance. Never throws.

shared_ptr::unique

    bool unique() const;

Returns true if the reference count is one. Never throws.

shared_ptr::use_count

    long use_count() const;

Returns the reference count. Should be used only for testing and debugging. Never throws.

Revised 16 Jan, 2005

© Copyright Jonathan Turkanis, 2005

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Sha'arei Tefila, an Orthodox Shul (Synagogue) in Salt Lake City, Utah Chabad Lubavitch of Utah