Class Template shared_obj

Description
Headers
Reference
Synopsis
Class Template shared_obj

Description

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

Together with each object managed by a shared_obj is stored a reference count and a deleter. The reference count records the number of instances of shared_obj which manage a given object. When the reference count reaches zero — just before the last shared_obj 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_obj.

To Do

Add pre- and post- conditions, where appropriate.

Headers

<boost/interfaces/shared_obj.hpp>

Reference

Synopsis

namespace boost { namespace interfaces {

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

        // Constructors

    shared_obj();

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

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

    shared_obj(const shared_obj& ptr);

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

        // Destructor

    ~shared_obj();

        // Assignment

    shared_obj& operator=(shared_obj ptr);

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

    operator unspecified-bool-type() const;

    [Member functions from Interface]
};

template<typename Interface>
fixed_view<Interface>* get(const shared_object<Interface>& obj);

template<typename Interface>
void reset(shared_object<Interface>& obj);

template<typename Interface, typename T>
void reset(shared_object<Interface>& obj, T* t);

template<typename Interface&, typename T, typename D>
void reset(shared_object<Interface>& obj, T* t, D d);

template<typename Interface>
bool unique(const shared_object<Interface>& obj);

template<typename Interface>
long use_count(const shared_object<Interface>& obj);

} } // End namespace boost::interfaces

Class Template shared_obj

Template Parameters
Interface-

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

shared_obj::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_obj::shared_obj

    shared_obj();

Constructs an empty shared_obj. Never throws.

    template<typename T>
    explicit shared_obj(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_obj 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_obj(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_obj 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_obj(const shared_obj& ptr);

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

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

shared_obj::~shared_obj

    ~shared_obj();

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

shared_obj::operator=

    shared_obj& operator=(shared_obj ptr);

    template<typename Subinterface>    
    shared_obj& operator=(shared_obj<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_obj is non-empty, takes shared ownership of the managed object and increments the reference count. Never throws.

shared_obj::operator unspecified-bool-type()

    operator unspecified-bool-type() const;

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

Function Template get

    template<typename Interface>
    element_type* get(const shared_obj<Interface>& obj);
Template Parameters
Interface-

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

Returns a pointer through which member functions of object managed by the given instance of shared_obj can be accessed. Never throws.

Function Template reset

    template<typename Interface>
    void reset(shared_obj<Interface>& obj);
Template Parameters
Interface-

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

If the reference count associated with the given instance of shared_obj is non-zero, decrements the reference count and causes the given instance to relinquish ownership of the managed object. 

    template<typename Interface, typename T>
    void reset(shared_obj<Interface>& obj, T* t);
Template Parameters
Interface-

An interface defined using the Interface Definition Language (IDL).
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 associated with the given instance of shared_obj is non-zero, decrements the reference count and causes the given instance to relinquish ownership of the managed object.

Next, causes the given instance of shared_obj to take 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 Interface, typename T, typename D>
    void reset(shared_obj<Interface>& obj, T* t, D d);
Template Parameters
Interface-

An interface defined using the Interface Definition Language (IDL).
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 associated with the given instance of shared_obj is non-zero, decrements the reference count and causes the given instance to relinquish ownership of the managed object.

Next, causes the given instance of shared_obj to take 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).

Function Template unique

    bool unique(shared_obj<Interface>& obj);
Template Parameters
Interface-

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

Returns true if the reference count associated with the given instance of shared_obj is one. Never throws.

Function Template use_count

    long use_count(shared_obj<Interface>& obj);
Template Parameters
Interface-

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

Returns the reference count associated with the given instance of shared_obj. 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