#include <refcount.hpp>
Public Types | |
typedef HandleT | type |
The basic type of object pointed to. | |
typedef type * | pointer_type |
The basic pointer type. | |
typedef FinalizerT | finalizer_type |
The type of functor used to clean up pointer_type objects. | |
typedef Detail::ref_type < type >::type | reference_type |
reference_type is the same as (T&) unless T is void, in which case it is the same as (void*&) because (void&) is not legal. | |
Public Member Functions | |
rcptr (pointer_type h) | |
Transfers ownership of h, or allows h to participate in ownership with other rcptr objects pointing at h. | |
rcptr (rcptr const &rhs) | |
rhs and this object will both manage the same underlying pointer. | |
rcptr & | operator= (rcptr const &rhs) |
First disowns any connected pointer (using take(0)), then rhs and this object will both manage the same underlying pointer. | |
rcptr () | |
An empty shared pointer, useful only as a target of assigment or take(). | |
void | swap (rcptr &rhs) |
Efficiently swaps this object and rhs, such that they swap ownership of their underlying pointers. | |
~rcptr () | |
See decrement();. | |
bool | operator== (rcptr const &rhs) const |
Returns (this->m_ptr == rhs.m_ptr). | |
bool | operator!= (rcptr const &rhs) const |
Returns (this->m_ptr != rhs.m_ptr). | |
bool | operator< (rcptr const &rhs) const |
Returns this->get() < rhs.get(). | |
pointer_type | get () const |
Returns this object's underlying pointer, which may be 0. | |
void | take (pointer_type p) |
Gives ownership of p to this object (or a collection of like-types rcptr objects). | |
pointer_type | take () |
Transfers ownership of this->get() to the caller. | |
pointer_type | operator-> () const |
The same as this->get(). | |
reference_type | operator * () const |
The same as *(this->get()). | |
size_t | ref_count () const |
Returns the number of references to this object's pointer, or zero if no pointer is bound. | |
bool | empty () const |
Returns the same as (!this->get()). |
HandleT must be a non-CVP-qualified type. As a special case, if HandleT is void then some code in this class will work a bit differently, notably the operator*(), because we cannot form a reference to void. Void is supported because (void *) is commonly used for opaque handles (e.g. libdl) or multibyte string pointers (e.g. libsqlite3).
FinalizerT must be a type compatible with the plain_delete_finalizer interface. A default-constructed instance of that FinalizerT type will be created to "finalize" an object when the reference count for that object drops to zero. The exact behaviour of the FinalizerT is not specified here, but semantically it must "finalize" the object passed to it. The default finalizer simply deletes the object, whereas a more advanced finalizer might push the object into a garbage collection pool. For purposes of this class, after finalization of an object, client code (and this type) should no longer use the object
This type does not currently have any built-in support for copy-on-write, so all copies are extremely shallow.
Notes of Utmost Significance to Potential Users:
Design notes:
typedef RCIPtr<MyType> myPtrType; MyType * t = new MyType; myPtrType x(t); myPtrType y(t);
In theory, his presentation (admittedly 10+ years old now) would cause a double-delete for that case. In this model, that case is handled as if we had constructed y using y(x) instead of y(t), so both x and y share the reference count.
rcptr<T1,finalizerT1> p1( new T1 );
rcptr<T2,finalizerT2> p2( p1.get() );
because the actual finalizer used would be the one for which the rcptr is destroyed *last*. Since destruction order is not always determinate, this mixture would be a bad idea. Note that it is still illegal to add the same pointer to multiple different shared pointer types. The above example, while illegal, will at least cause determinate behaviour: a double finalization (but the order is still unspecified in the general case)!
Definition at line 196 of file refcount.hpp.
typedef HandleT s11n::refcount::rcptr< HandleT, FinalizerT >::type |
typedef type* s11n::refcount::rcptr< HandleT, FinalizerT >::pointer_type |
typedef FinalizerT s11n::refcount::rcptr< HandleT, FinalizerT >::finalizer_type |
The type of functor used to clean up pointer_type objects.
Definition at line 208 of file refcount.hpp.
typedef Detail::ref_type<type>::type s11n::refcount::rcptr< HandleT, FinalizerT >::reference_type |
reference_type is the same as (T&) unless T is void, in which case it is the same as (void*&) because (void&) is not legal.
Definition at line 403 of file refcount.hpp.
s11n::refcount::rcptr< HandleT, FinalizerT >::rcptr | ( | pointer_type | h | ) | [inline, explicit] |
Transfers ownership of h, or allows h to participate in ownership with other rcptr objects pointing at h.
Definition at line 268 of file refcount.hpp.
s11n::refcount::rcptr< HandleT, FinalizerT >::rcptr | ( | rcptr< HandleT, FinalizerT > const & | rhs | ) | [inline] |
rhs and this object will both manage the same underlying pointer.
Definition at line 276 of file refcount.hpp.
s11n::refcount::rcptr< HandleT, FinalizerT >::rcptr | ( | ) | [inline] |
An empty shared pointer, useful only as a target of assigment or take().
Definition at line 300 of file refcount.hpp.
s11n::refcount::rcptr< HandleT, FinalizerT >::~rcptr | ( | ) | [inline] |
rcptr& s11n::refcount::rcptr< HandleT, FinalizerT >::operator= | ( | rcptr< HandleT, FinalizerT > const & | rhs | ) | [inline] |
First disowns any connected pointer (using take(0)), then rhs and this object will both manage the same underlying pointer.
If by chance rhs.get() == this->get() when this function starts then this function does nothing and has no side effects.
Definition at line 288 of file refcount.hpp.
void s11n::refcount::rcptr< HandleT, FinalizerT >::swap | ( | rcptr< HandleT, FinalizerT > & | rhs | ) | [inline] |
Efficiently swaps this object and rhs, such that they swap ownership of their underlying pointers.
This does not require fiddling with the reference counts, so it is much faster than using an rcptr copy to perform a swap.
Definition at line 310 of file refcount.hpp.
bool s11n::refcount::rcptr< HandleT, FinalizerT >::operator== | ( | rcptr< HandleT, FinalizerT > const & | rhs | ) | const [inline] |
bool s11n::refcount::rcptr< HandleT, FinalizerT >::operator!= | ( | rcptr< HandleT, FinalizerT > const & | rhs | ) | const [inline] |
bool s11n::refcount::rcptr< HandleT, FinalizerT >::operator< | ( | rcptr< HandleT, FinalizerT > const & | rhs | ) | const [inline] |
Returns this->get() < rhs.get().
Implemented so that this type can be used as keys in STL containers.
Definition at line 344 of file refcount.hpp.
pointer_type s11n::refcount::rcptr< HandleT, FinalizerT >::get | ( | ) | const [inline] |
Returns this object's underlying pointer, which may be 0.
This does not transfer ownership. This object still owns (or participates in the ownership of) the returned pointer.
Definition at line 354 of file refcount.hpp.
void s11n::refcount::rcptr< HandleT, FinalizerT >::take | ( | pointer_type | p | ) | [inline] |
Gives ownership of p to this object (or a collection of like-types rcptr objects).
Drops ownership of this->get() before making the takeover. If (this->get() == p) then this function does nothing.
Definition at line 363 of file refcount.hpp.
pointer_type s11n::refcount::rcptr< HandleT, FinalizerT >::take | ( | ) | [inline] |
Transfers ownership of this->get() to the caller.
ALL rcptr<> objects which point to that object (except this rcptr) STILL point to that object, but they will not activate the destructor functor when they die, so they are safe as long as they remain unsued or are destroyed before the "raw" pointer returned from this function is destroyed.
Definition at line 380 of file refcount.hpp.
pointer_type s11n::refcount::rcptr< HandleT, FinalizerT >::operator-> | ( | ) | const [inline] |
reference_type s11n::refcount::rcptr< HandleT, FinalizerT >::operator * | ( | ) | const [inline] |
The same as *(this->get()).
Behaviour is undefined if (!this->get()). We would throw an exception, but this code is specifically intended for use on platforms where exceptions are not allowed or not supported (e.g. some embedded platforms).
SPECIAL CASE: rcptr::type is void
If rcptr::type is void then this function returns a refernce to a pointer instead of a reference. This is to allow this type to work with (void*) handle types, such as handles returned from dlopen() or memory returned from malloc(). Finalizers for such handles could call dlclose() or free(), as appropriate.
Definition at line 422 of file refcount.hpp.
size_t s11n::refcount::rcptr< HandleT, FinalizerT >::ref_count | ( | ) | const [inline] |
Returns the number of references to this object's pointer, or zero if no pointer is bound.
This function should be considered a debugging/informational function, and not a "feature" of this type.
Complexity = that of a std::map lookup.
Definition at line 434 of file refcount.hpp.
bool s11n::refcount::rcptr< HandleT, FinalizerT >::empty | ( | ) | const [inline] |