Subversion Repositories openrisc

      ISO C++

      ISO C++

      shared_ptr

      shared_ptr

The shared_ptr class template stores a pointer, usually obtained via new,

The shared_ptr class template stores a pointer, usually obtained via new,

and implements shared ownership semantics.

and implements shared ownership semantics.

    The standard deliberately doesn't require a reference-counted

    The standard deliberately doesn't require a reference-counted

    implementation, allowing other techniques such as a

    implementation, allowing other techniques such as a

    circular-linked-list.

    circular-linked-list.

    At the time of writing the C++0x working paper doesn't mention how

    At the time of writing the C++0x working paper doesn't mention how

    threads affect shared_ptr, but it is likely to follow the existing

    threads affect shared_ptr, but it is likely to follow the existing

    practice set by boost::shared_ptr.  The

    practice set by boost::shared_ptr.  The

    shared_ptr in libstdc++ is derived from Boost's, so the same rules

    shared_ptr in libstdc++ is derived from Boost's, so the same rules

    apply.

    apply.

The shared_ptr code is kindly donated to GCC by the Boost

The shared_ptr code is kindly donated to GCC by the Boost

project and the original authors of the code. The basic design and

project and the original authors of the code. The basic design and

algorithms are from Boost, the notes below describe details specific to

algorithms are from Boost, the notes below describe details specific to

the GCC implementation. Names have been uglified in this implementation,

the GCC implementation. Names have been uglified in this implementation,

but the design should be recognisable to anyone familiar with the Boost

but the design should be recognisable to anyone familiar with the Boost

1.32 shared_ptr.

1.32 shared_ptr.

The basic design is an abstract base class, _Sp_counted_base that

The basic design is an abstract base class, _Sp_counted_base that

does the reference-counting and calls virtual functions when the count

does the reference-counting and calls virtual functions when the count

drops to zero.

drops to zero.

Derived classes override those functions to destroy resources in a context

Derived classes override those functions to destroy resources in a context

where the correct dynamic type is known. This is an application of the

where the correct dynamic type is known. This is an application of the

technique known as type erasure.

technique known as type erasure.

A shared_ptr<T> contains a pointer of

A shared_ptr<T> contains a pointer of

type T* and an object of type

type T* and an object of type

__shared_count. The shared_count contains a

__shared_count. The shared_count contains a

pointer of type _Sp_counted_base* which points to the

pointer of type _Sp_counted_base* which points to the

object that maintains the reference-counts and destroys the managed

object that maintains the reference-counts and destroys the managed

resource.

resource.

  _Sp_counted_base<Lp>

  _Sp_counted_base<Lp>

The base of the hierarchy is parameterized on the lock policy alone.

The base of the hierarchy is parameterized on the lock policy alone.

_Sp_counted_base doesn't depend on the type of pointer being managed,

_Sp_counted_base doesn't depend on the type of pointer being managed,

it only maintains the reference counts and calls virtual functions when

it only maintains the reference counts and calls virtual functions when

the counts drop to zero. The managed object is destroyed when the last

the counts drop to zero. The managed object is destroyed when the last

strong reference is dropped, but the _Sp_counted_base itself must exist

strong reference is dropped, but the _Sp_counted_base itself must exist

until the last weak reference is dropped.

until the last weak reference is dropped.

  _Sp_counted_base_impl<Ptr, Deleter, Lp>

  _Sp_counted_base_impl<Ptr, Deleter, Lp>

Inherits from _Sp_counted_base and stores a pointer of type Ptr

Inherits from _Sp_counted_base and stores a pointer of type Ptr

and a deleter of type Deleter.  _Sp_deleter is

and a deleter of type Deleter.  _Sp_deleter is

used when the user doesn't supply a custom deleter. Unlike Boost's, this

used when the user doesn't supply a custom deleter. Unlike Boost's, this

default deleter is not "checked" because GCC already issues a warning if

default deleter is not "checked" because GCC already issues a warning if

delete is used with an incomplete type.

delete is used with an incomplete type.

This is the only derived type used by shared_ptr<Ptr>

This is the only derived type used by shared_ptr<Ptr>

and it is never used by shared_ptr, which uses one of

and it is never used by shared_ptr, which uses one of

the following types, depending on how the shared_ptr is constructed.

the following types, depending on how the shared_ptr is constructed.

  _Sp_counted_ptr<Ptr, Lp>

  _Sp_counted_ptr<Ptr, Lp>

Inherits from _Sp_counted_base and stores a pointer of type Ptr,

Inherits from _Sp_counted_base and stores a pointer of type Ptr,

which is passed to delete when the last reference is dropped.

which is passed to delete when the last reference is dropped.

This is the simplest form and is used when there is no custom deleter or

This is the simplest form and is used when there is no custom deleter or

allocator.

allocator.

  _Sp_counted_deleter<Ptr, Deleter, Alloc>

  _Sp_counted_deleter<Ptr, Deleter, Alloc>

Inherits from _Sp_counted_ptr and adds support for custom deleter and

Inherits from _Sp_counted_ptr and adds support for custom deleter and

allocator. Empty Base Optimization is used for the allocator. This class

allocator. Empty Base Optimization is used for the allocator. This class

is used even when the user only provides a custom deleter, in which case

is used even when the user only provides a custom deleter, in which case

allocator is used as the allocator.

allocator is used as the allocator.

  _Sp_counted_ptr_inplace<Tp, Alloc, Lp>

  _Sp_counted_ptr_inplace<Tp, Alloc, Lp>

Used by allocate_shared and make_shared.

Used by allocate_shared and make_shared.

Contains aligned storage to hold an object of type Tp,

Contains aligned storage to hold an object of type Tp,

which is constructed in-place with placement new.

which is constructed in-place with placement new.

Has a variadic template constructor allowing any number of arguments to

Has a variadic template constructor allowing any number of arguments to

be forwarded to Tp's constructor.

be forwarded to Tp's constructor.

Unlike the other _Sp_counted_* classes, this one is parameterized on the

Unlike the other _Sp_counted_* classes, this one is parameterized on the

type of object, not the type of pointer; this is purely a convenience

type of object, not the type of pointer; this is purely a convenience

that simplifies the implementation slightly.

that simplifies the implementation slightly.

The interface of tr1::shared_ptr was extended for C++0x

The interface of tr1::shared_ptr was extended for C++0x

with support for rvalue-references and the other features from

with support for rvalue-references and the other features from

N2351. As with other libstdc++ headers shared by TR1 and C++0x,

N2351. As with other libstdc++ headers shared by TR1 and C++0x,

boost_shared_ptr.h uses conditional compilation, based on the macros

boost_shared_ptr.h uses conditional compilation, based on the macros

_GLIBCXX_INCLUDE_AS_CXX0X and

_GLIBCXX_INCLUDE_AS_CXX0X and

_GLIBCXX_INCLUDE_AS_TR1, to enable and disable

_GLIBCXX_INCLUDE_AS_TR1, to enable and disable

features.

features.

C++0x-only features are: rvalue-ref/move support, allocator support,

C++0x-only features are: rvalue-ref/move support, allocator support,

aliasing constructor, make_shared & allocate_shared. Additionally,

aliasing constructor, make_shared & allocate_shared. Additionally,

the constructors taking auto_ptr parameters are

the constructors taking auto_ptr parameters are

deprecated in C++0x mode.

deprecated in C++0x mode.

The

The

Thread

Thread

Safety section of the Boost shared_ptr documentation says "shared_ptr

Safety section of the Boost shared_ptr documentation says "shared_ptr

objects offer the same level of thread safety as built-in types."

objects offer the same level of thread safety as built-in types."

The implementation must ensure that concurrent updates to separate shared_ptr

The implementation must ensure that concurrent updates to separate shared_ptr

instances are correct even when those instances share a reference count e.g.

instances are correct even when those instances share a reference count e.g.

shared_ptr<A> a(new A);

shared_ptr<A> a(new A);

shared_ptr<A> b(a);

shared_ptr<A> b(a);

// Thread 1     // Thread 2

// Thread 1     // Thread 2

   a.reset();      b.reset();

   a.reset();      b.reset();

The dynamically-allocated object must be destroyed by exactly one of the

The dynamically-allocated object must be destroyed by exactly one of the

threads. Weak references make things even more interesting.

threads. Weak references make things even more interesting.

The shared state used to implement shared_ptr must be transparent to the

The shared state used to implement shared_ptr must be transparent to the

user and invariants must be preserved at all times.

user and invariants must be preserved at all times.

The key pieces of shared state are the strong and weak reference counts.

The key pieces of shared state are the strong and weak reference counts.

Updates to these need to be atomic and visible to all threads to ensure

Updates to these need to be atomic and visible to all threads to ensure

correct cleanup of the managed resource (which is, after all, shared_ptr's

correct cleanup of the managed resource (which is, after all, shared_ptr's

job!)

job!)

On multi-processor systems memory synchronisation may be needed so that

On multi-processor systems memory synchronisation may be needed so that

reference-count updates and the destruction of the managed resource are

reference-count updates and the destruction of the managed resource are

race-free.

race-free.

The function _Sp_counted_base::_M_add_ref_lock(), called when

The function _Sp_counted_base::_M_add_ref_lock(), called when

obtaining a shared_ptr from a weak_ptr, has to test if the managed

obtaining a shared_ptr from a weak_ptr, has to test if the managed

resource still exists and either increment the reference count or throw

resource still exists and either increment the reference count or throw

bad_weak_ptr.

bad_weak_ptr.

In a multi-threaded program there is a potential race condition if the last

In a multi-threaded program there is a potential race condition if the last

reference is dropped (and the managed resource destroyed) between testing

reference is dropped (and the managed resource destroyed) between testing

the reference count and incrementing it, which could result in a shared_ptr

the reference count and incrementing it, which could result in a shared_ptr

pointing to invalid memory.

pointing to invalid memory.

The Boost shared_ptr (as used in GCC) features a clever lock-free

The Boost shared_ptr (as used in GCC) features a clever lock-free

algorithm to avoid the race condition, but this relies on the

algorithm to avoid the race condition, but this relies on the

processor supporting an atomic Compare-And-Swap

processor supporting an atomic Compare-And-Swap

instruction. For other platforms there are fall-backs using mutex

instruction. For other platforms there are fall-backs using mutex

locks.  Boost (as of version 1.35) includes several different

locks.  Boost (as of version 1.35) includes several different

implementations and the preprocessor selects one based on the

implementations and the preprocessor selects one based on the

compiler, standard library, platform etc. For the version of

compiler, standard library, platform etc. For the version of

shared_ptr in libstdc++ the compiler and library are fixed, which

shared_ptr in libstdc++ the compiler and library are fixed, which

makes things much simpler: we have an atomic CAS or we don't, see Lock

makes things much simpler: we have an atomic CAS or we don't, see Lock

Policy below for details.

Policy below for details.

There is a single _Sp_counted_base class,

There is a single _Sp_counted_base class,

which is a template parameterized on the enum

which is a template parameterized on the enum

__gnu_cxx::_Lock_policy.  The entire family of classes is

__gnu_cxx::_Lock_policy.  The entire family of classes is

parameterized on the lock policy, right up to

parameterized on the lock policy, right up to

__shared_ptr, __weak_ptr and

__shared_ptr, __weak_ptr and

__enable_shared_from_this. The actual

__enable_shared_from_this. The actual

std::shared_ptr class inherits from

std::shared_ptr class inherits from

__shared_ptr with the lock policy parameter

__shared_ptr with the lock policy parameter

selected automatically based on the thread model and platform that

selected automatically based on the thread model and platform that

libstdc++ is configured for, so that the best available template

libstdc++ is configured for, so that the best available template

specialization will be used. This design is necessary because it would

specialization will be used. This design is necessary because it would

not be conforming for shared_ptr to have an

not be conforming for shared_ptr to have an

extra template parameter, even if it had a default value.  The

extra template parameter, even if it had a default value.  The

available policies are:

available policies are:

       _S_Atomic

       _S_Atomic

Selected when GCC supports a builtin atomic compare-and-swap operation

Selected when GCC supports a builtin atomic compare-and-swap operation

on the target processor (see Atomic

on the target processor (see Atomic

Builtins.)  The reference counts are maintained using a lock-free

Builtins.)  The reference counts are maintained using a lock-free

algorithm and GCC's atomic builtins, which provide the required memory

algorithm and GCC's atomic builtins, which provide the required memory

synchronisation.

synchronisation.

       _S_Mutex

       _S_Mutex

The _Sp_counted_base specialization for this policy contains a mutex,

The _Sp_counted_base specialization for this policy contains a mutex,

which is locked in add_ref_lock(). This policy is used when GCC's atomic

which is locked in add_ref_lock(). This policy is used when GCC's atomic

builtins aren't available so explicit memory barriers are needed in places.

builtins aren't available so explicit memory barriers are needed in places.

       _S_Single

       _S_Single

This policy uses a non-reentrant add_ref_lock() with no locking. It is

This policy uses a non-reentrant add_ref_lock() with no locking. It is

used when libstdc++ is built without --enable-threads.

used when libstdc++ is built without --enable-threads.

       For all three policies, reference count increments and

       For all three policies, reference count increments and

       decrements are done via the functions in

       decrements are done via the functions in

       ext/atomicity.h, which detect if the program

       ext/atomicity.h, which detect if the program

       is multi-threaded.  If only one thread of execution exists in

       is multi-threaded.  If only one thread of execution exists in

       the program then less expensive non-atomic operations are used.

       the program then less expensive non-atomic operations are used.

The classes derived from _Sp_counted_base (see Class Hierarchy

The classes derived from _Sp_counted_base (see Class Hierarchy

below) and __shared_count are implemented separately for C++0x

below) and __shared_count are implemented separately for C++0x

and TR1, in bits/boost_sp_shared_count.h and

and TR1, in bits/boost_sp_shared_count.h and

tr1/boost_sp_shared_count.h respectively.  All other classes

tr1/boost_sp_shared_count.h respectively.  All other classes

including _Sp_counted_base are shared by both implementations.

including _Sp_counted_base are shared by both implementations.

The TR1 implementation is considered relatively stable, so is unlikely to

The TR1 implementation is considered relatively stable, so is unlikely to

change unless bug fixes require it.  If the code that is common to both

change unless bug fixes require it.  If the code that is common to both

C++0x and TR1 modes needs to diverge further then it might be necessary to

C++0x and TR1 modes needs to diverge further then it might be necessary to

duplicate additional classes and only make changes to the C++0x versions.

duplicate additional classes and only make changes to the C++0x versions.

  dynamic_pointer_cast, static_pointer_cast,

  dynamic_pointer_cast, static_pointer_cast,

const_pointer_cast

const_pointer_cast

As noted in N2351, these functions can be implemented non-intrusively using

As noted in N2351, these functions can be implemented non-intrusively using

the alias constructor.  However the aliasing constructor is only available

the alias constructor.  However the aliasing constructor is only available

in C++0x mode, so in TR1 mode these casts rely on three non-standard

in C++0x mode, so in TR1 mode these casts rely on three non-standard

constructors in shared_ptr and __shared_ptr.

constructors in shared_ptr and __shared_ptr.

In C++0x mode these constructors and the related tag types are not needed.

In C++0x mode these constructors and the related tag types are not needed.

  enable_shared_from_this

  enable_shared_from_this

The clever overload to detect a base class of type

The clever overload to detect a base class of type

enable_shared_from_this comes straight from Boost.

enable_shared_from_this comes straight from Boost.

There is an extra overload for __enable_shared_from_this to

There is an extra overload for __enable_shared_from_this to

work smoothly with __shared_ptr<Tp, Lp> using any lock

work smoothly with __shared_ptr<Tp, Lp> using any lock

policy.

policy.

  make_shared, allocate_shared

  make_shared, allocate_shared

make_shared simply forwards to allocate_shared

make_shared simply forwards to allocate_shared

with std::allocator as the allocator.

with std::allocator as the allocator.

Although these functions can be implemented non-intrusively using the

Although these functions can be implemented non-intrusively using the

alias constructor, if they have access to the implementation then it is

alias constructor, if they have access to the implementation then it is

possible to save storage and reduce the number of heap allocations. The

possible to save storage and reduce the number of heap allocations. The

newly constructed object and the _Sp_counted_* can be allocated in a single

newly constructed object and the _Sp_counted_* can be allocated in a single

block and the standard says implementations are "encouraged, but not required,"

block and the standard says implementations are "encouraged, but not required,"

to do so. This implementation provides additional non-standard constructors

to do so. This implementation provides additional non-standard constructors

(selected with the type _Sp_make_shared_tag) which create an

(selected with the type _Sp_make_shared_tag) which create an

object of type _Sp_counted_ptr_inplace to hold the new object.

object of type _Sp_counted_ptr_inplace to hold the new object.

The returned shared_ptr<A> needs to know the address of the

The returned shared_ptr<A> needs to know the address of the

new A object embedded in the _Sp_counted_ptr_inplace,

new A object embedded in the _Sp_counted_ptr_inplace,

but it has no way to access it.

but it has no way to access it.

This implementation uses a "covert channel" to return the address of the

This implementation uses a "covert channel" to return the address of the

embedded object when get_deleter<_Sp_make_shared_tag>()

embedded object when get_deleter<_Sp_make_shared_tag>()

is called.  Users should not try to use this.

is called.  Users should not try to use this.

As well as the extra constructors, this implementation also needs some

As well as the extra constructors, this implementation also needs some

members of _Sp_counted_deleter to be protected where they could otherwise

members of _Sp_counted_deleter to be protected where they could otherwise

be private.

be private.

-->

      Examples of use can be found in the testsuite, under

      Examples of use can be found in the testsuite, under

      testsuite/tr1/2_general_utilities/shared_ptr.

      testsuite/tr1/2_general_utilities/shared_ptr.

      The resolution to C++ Standard Library issue 674,

      The resolution to C++ Standard Library issue 674,

      "shared_ptr interface changes for consistency with N1856" will

      "shared_ptr interface changes for consistency with N1856" will

      need to be implemented after it is accepted into the working

      need to be implemented after it is accepted into the working

      paper. Issue 743

      paper. Issue 743

      might also require changes.

      might also require changes.

      The _S_single policy uses atomics when used in MT

      The _S_single policy uses atomics when used in MT

      code, because it uses the same dispatcher functions that check

      code, because it uses the same dispatcher functions that check

      __gthread_active_p(). This could be

      __gthread_active_p(). This could be

      addressed by providing template specialisations for some members

      addressed by providing template specialisations for some members

      of _Sp_counted_base<_S_single>.

      of _Sp_counted_base<_S_single>.

      Unlike Boost, this implementation does not use separate classes

      Unlike Boost, this implementation does not use separate classes

      for the pointer+deleter and pointer+deleter+allocator cases in

      for the pointer+deleter and pointer+deleter+allocator cases in

      C++0x mode, combining both into _Sp_counted_deleter and using

      C++0x mode, combining both into _Sp_counted_deleter and using

      allocator when the user doesn't specify

      allocator when the user doesn't specify

      an allocator.  If it was found to be beneficial an additional

      an allocator.  If it was found to be beneficial an additional

      class could easily be added.  With the current implementation,

      class could easily be added.  With the current implementation,

      the _Sp_counted_deleter and __shared_count constructors taking a

      the _Sp_counted_deleter and __shared_count constructors taking a

      custom deleter but no allocator are technically redundant and

      custom deleter but no allocator are technically redundant and

      could be removed, changing callers to always specify an

      could be removed, changing callers to always specify an

      allocator. If a separate pointer+deleter class was added the

      allocator. If a separate pointer+deleter class was added the

      __shared_count constructor would be needed, so it has been kept

      __shared_count constructor would be needed, so it has been kept

      for now.

      for now.

      The hack used to get the address of the managed object from

      The hack used to get the address of the managed object from

      _Sp_counted_ptr_inplace::_M_get_deleter()

      _Sp_counted_ptr_inplace::_M_get_deleter()

      is accessible to users. This could be prevented if

      is accessible to users. This could be prevented if

      get_deleter<_Sp_make_shared_tag>()

      get_deleter<_Sp_make_shared_tag>()

      always returned NULL, since the hack only needs to work at a

      always returned NULL, since the hack only needs to work at a

      lower level, not in the public API. This wouldn't be difficult,

      lower level, not in the public API. This wouldn't be difficult,

      but hasn't been done since there is no danger of accidental

      but hasn't been done since there is no danger of accidental

      misuse: users already know they are relying on unsupported

      misuse: users already know they are relying on unsupported

      features if they refer to implementation details such as

      features if they refer to implementation details such as

      _Sp_make_shared_tag.

      _Sp_make_shared_tag.

      tr1::_Sp_deleter could be a private member of tr1::__shared_count but it

      tr1::_Sp_deleter could be a private member of tr1::__shared_count but it

      would alter the ABI.

      would alter the ABI.

      Exposing the alias constructor in TR1 mode could simplify the

      Exposing the alias constructor in TR1 mode could simplify the

      *_pointer_cast functions.  Constructor could be private in TR1

      *_pointer_cast functions.  Constructor could be private in TR1

      mode, with the cast functions as friends.

      mode, with the cast functions as friends.

    The original authors of the Boost shared_ptr, which is really nice

    The original authors of the Boost shared_ptr, which is really nice

    code to work with, Peter Dimov in particular for his help and

    code to work with, Peter Dimov in particular for his help and

    invaluable advice on thread safety.  Phillip Jordan and Paolo

    invaluable advice on thread safety.  Phillip Jordan and Paolo

    Carlini for the lock policy implementation.

    Carlini for the lock policy implementation.

          Improving shared_ptr for C++0x, Revision 2

          Improving shared_ptr for C++0x, Revision 2

      N2351

      N2351

          C++ Standard Library Active Issues List

          C++ Standard Library Active Issues List

      N2456

      N2456

          Working Draft, Standard for Programming Language C++

          Working Draft, Standard for Programming Language C++

      N2461

      N2461

      shared_ptr

      shared_ptr

          Boost C++ Libraries documentation, shared_ptr

          Boost C++ Libraries documentation, shared_ptr

      N2461

      N2461