Description

template<class T>
class Sawyer::SharedPointer< T >

Reference-counting intrusive smart pointer.

This class implements a reference-counting pointer to an object that inherits from SharedObject. See SharedObject for a detailed description of how to prepare objects to be referenced by SharedPointer.

Usage is similar to std::shared_ptr to the extent that the number of pointers pointing to an object is recorded somewhere, and when that reference count reaches zero the object is destroyed and freed by calling delete. The main difference is that SharedPointer stores the reference count in the object itself (i.e., "intrusive"). The effects are:

SharedPointer is faster than non-intrusive reference-counting pointers like std::shared_ptr and boost::shared_ptr.

The concepts of weak pointers and unique pointers are not supported because there is no separate pointer group object.

A class is declared as either having a reference count (inheriting from SharedObject) or not having a reference count (not inheriting). All objects that have such a built-in reference count are expected to have a working "delete" and therefore must always be allocated on the heap.

Some best practices (see also, SharedObject):

When returning a shared pointer from a function, return a new SharedPointer rather than a reference.

When a shared pointer is used as a function argument, the function can take a const reference argument to avoid incrementing the reference count in the object. This is safe since the caller will hold a reference to the object for the duration of the call.

Avoid creating circular data structures since the cycle will be self-referencing and thus the objects are not freed even after the last external reference to the cycle is removed. Breaking the cycle is the only way to cause the objects to be freeable. An example of a cycle is a tree data structure where a parent has pointers to the children and the children in turn point back to their parent–each parent-child pair is a cycle.

Use SharedPointer if you need utmost speed, and are able to modify the definition of the pointee class to inherit from SharedObject, and are willing to always allocate all such objects on the heap not the stack, and don't need weak or unique pointers to such objects. Otherwise default to using std::shared_ptr et. al. (or boost::shared_ptr for C++03 and earlier).

Thread safety: Similar to raw pointers. Different threads can access different pointers to the same object, but operations on the pointer itself (such as assignment, comparison with null, and dereferencing in the presence of other writers needs to be synchronized by the callers.

See also: SharedObject, SharedFromThis

Definition at line 65 of file SharedPointer.h.

#include <Sawyer/SharedPointer.h>

Inheritance diagram for Sawyer::SharedPointer< T >:

[legend]

Public Types
typedef T	Pointee

Public Member Functions
template<class Y >
	SharedPointer (Y *rawPtr)
	Constructs a shared pointer for an object.

	~SharedPointer ()
	Conditionally deletes the pointed-to object.

T &	operator* () const
	Reference to the pointed-to object.

T *	operator-> () const
	Dereference pointed-to object.

template<class U >
SharedPointer< U >	dynamicCast () const
	Dynamic cast.

bool	operator! () const
	Boolean complement.

	operator unspecified_bool () const
	Type for Boolean context.

Pointee *	getRawPointer ()
	Obtain the pointed-to object.

Pointee *	getRawPointer () const


	SharedPointer (const Sawyer::Nothing &)
	Constructs an empty shared pointer.

	SharedPointer (std::nullptr_t)
	Constructs an empty shared pointer.


	SharedPointer (const SharedPointer &other)
	Constructs a new pointer that shares ownership of the pointed-to object with the `other` pointer.

template<class Y >
	SharedPointer (const SharedPointer< Y > &other)
	Constructs a new pointer that shares ownership of the pointed-to object with the `other` pointer.


SharedPointer &	operator= (const SharedPointer &other)
	Assignment.

template<class Y >
SharedPointer &	operator= (const SharedPointer< Y > &other)
	Assignment.


SharedPointer &	operator= (const Sawyer::Nothing &)
	Assignment.

SharedPointer &	operator= (std::nullptr_t)
	Assignment.


template<class U >
bool	operator== (const SharedPointer< U > &other) const
	Comparison of two pointers.

template<class U >
bool	operator!= (const SharedPointer< U > &other) const
	Comparison of two pointers.

template<class U >
bool	operator< (const SharedPointer< U > &other) const
	Comparison of two pointers.

template<class U >
bool	operator<= (const SharedPointer< U > &other) const
	Comparison of two pointers.

template<class U >
bool	operator> (const SharedPointer< U > &other) const
	Comparison of two pointers.

template<class U >
bool	operator>= (const SharedPointer< U > &other) const
	Comparison of two pointers.

template<class U >
bool	operator== (const U *ptr) const
	Comparison of two pointers.

template<class U >
bool	operator!= (const U *ptr) const
	Comparison of two pointers.

template<class U >
bool	operator< (const U *ptr) const
	Comparison of two pointers.

template<class U >
bool	operator<= (const U *ptr) const
	Comparison of two pointers.

template<class U >
bool	operator> (const U *ptr) const
	Comparison of two pointers.

template<class U >
bool	operator>= (const U *ptr) const
	Comparison of two pointers.

Member Typedef Documentation

◆ Pointee

template<class T >

typedef T Sawyer::SharedPointer< T >::Pointee

Definition at line 67 of file SharedPointer.h.

Constructor & Destructor Documentation

◆ SharedPointer() [1/6]

template<class T >

Sawyer::SharedPointer< T >::SharedPointer ( )

inline

Constructs an empty shared pointer.

Definition at line 120 of file SharedPointer.h.

◆ SharedPointer() [2/6]

template<class T >

Sawyer::SharedPointer< T >::SharedPointer ( const Sawyer::Nothing & )

inlineexplicit

Constructs an empty shared pointer.

Definition at line 122 of file SharedPointer.h.

◆ SharedPointer() [3/6]

template<class T >

Sawyer::SharedPointer< T >::SharedPointer ( std::nullptr_t )

inlineexplicit

Constructs an empty shared pointer.

Definition at line 124 of file SharedPointer.h.

◆ SharedPointer() [4/6]

template<class T >

Sawyer::SharedPointer< T >::SharedPointer ( const SharedPointer< T > & other )

inline

Constructs a new pointer that shares ownership of the pointed-to object with the other pointer.

The pointed-to object will only be deleted after both pointers are deleted.

Definition at line 131 of file SharedPointer.h.

◆ SharedPointer() [5/6]

template<class T >

template<class Y >

Sawyer::SharedPointer< T >::SharedPointer ( const SharedPointer< Y > & other )

inline

Constructs a new pointer that shares ownership of the pointed-to object with the other pointer.

The pointed-to object will only be deleted after both pointers are deleted.

Definition at line 135 of file SharedPointer.h.

◆ SharedPointer() [6/6]

template<class T >

template<class Y >

Sawyer::SharedPointer< T >::SharedPointer ( Y * rawPtr )

inlineexplicit

Constructs a shared pointer for an object.

If obj is non-null then its reference count is incremented. It is possible to create any number of shared pointers to the same object using this constructor. The expression "delete obj" must be well formed and must not invoke undefined behavior.

Definition at line 146 of file SharedPointer.h.

◆ ~SharedPointer()

template<class T >

Sawyer::SharedPointer< T >::~SharedPointer ( )

inline

Conditionally deletes the pointed-to object.

The object is deleted when its reference count reaches zero.

Definition at line 152 of file SharedPointer.h.

Member Function Documentation

◆ operator=() [1/4]

template<class T >

SharedPointer & Sawyer::SharedPointer< T >::operator= ( const SharedPointer< T > & other )

inline

Assignment.

This pointer is caused to point to the same object as other, decrementing the reference count for the object originally pointed to by this pointer and incrementing the reference count for the object pointed by other.

Definition at line 160 of file SharedPointer.h.

◆ operator=() [2/4]

template<class T >

template<class Y >

SharedPointer & Sawyer::SharedPointer< T >::operator= ( const SharedPointer< Y > & other )

inline

Assignment.

This pointer is caused to point to the same object as other, decrementing the reference count for the object originally pointed to by this pointer and incrementing the reference count for the object pointed by other.

Definition at line 164 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::getRawPointer().

◆ operator=() [3/4]

template<class T >

SharedPointer & Sawyer::SharedPointer< T >::operator= ( const Sawyer::Nothing & )

inline

Assignment.

This pointer is caused to point to nothing.

Definition at line 178 of file SharedPointer.h.

◆ operator=() [4/4]

template<class T >

SharedPointer & Sawyer::SharedPointer< T >::operator= ( std::nullptr_t )

inline

Assignment.

This pointer is caused to point to nothing.

Definition at line 184 of file SharedPointer.h.

◆ operator*()

template<class T >

T & Sawyer::SharedPointer< T >::operator* ( ) const

inline

Reference to the pointed-to object.

An assertion will fail if assertions are enabled and this method is invoked on an empty pointer.

Definition at line 194 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::ownershipCount.

◆ operator->()

template<class T >

T * Sawyer::SharedPointer< T >::operator-> ( ) const

inline

Dereference pointed-to object.

The pointed-to object is returned. Returns null for empty pointers.

Definition at line 201 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::ownershipCount.

◆ dynamicCast()

template<class T >

template<class U >

SharedPointer Sawyer::SharedPointer< T >::dynamicCast ( ) const

inline

Dynamic cast.

Casts the specified pointer to a new pointer type using dynamic_cast.

Definition at line 211 of file SharedPointer.h.

Referenced by Sawyer::CommandLine::ListParser::nextMember(), and Sawyer::CommandLine::StringSetParser::with().

◆ operator==() [1/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator== ( const SharedPointer & other ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 221 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::getRawPointer().

◆ operator!=() [1/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator!= ( const SharedPointer & other ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 225 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::getRawPointer().

◆ operator<() [1/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator< ( const SharedPointer & other ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 229 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::getRawPointer().

◆ operator<=() [1/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator<= ( const SharedPointer & other ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 233 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::getRawPointer().

◆ operator>() [1/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator> ( const SharedPointer & other ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 237 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::getRawPointer().

◆ operator>=() [1/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator>= ( const SharedPointer & other ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 241 of file SharedPointer.h.

References Sawyer::SharedPointer< T >::getRawPointer().

◆ operator==() [2/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator== ( const U * ptr ) const

inline

Comparison of two pointers.

Compares the underlying pointer with the specified pointer.

Definition at line 251 of file SharedPointer.h.

◆ operator!=() [2/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator!= ( const U * ptr ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 255 of file SharedPointer.h.

◆ operator<() [2/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator< ( const U * ptr ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 259 of file SharedPointer.h.

◆ operator<=() [2/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator<= ( const U * ptr ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 263 of file SharedPointer.h.

◆ operator>() [2/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator> ( const U * ptr ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 267 of file SharedPointer.h.

◆ operator>=() [2/2]

template<class T >

template<class U >

bool Sawyer::SharedPointer< T >::operator>= ( const U * ptr ) const

inline

Comparison of two pointers.

Comparisons operators compare the underlying pointers to objects.

Definition at line 271 of file SharedPointer.h.

◆ operator!()

template<class T >

bool Sawyer::SharedPointer< T >::operator! ( ) const

inline

Boolean complement.

This operator allows shared pointers to be used in situations like this:

SharedPointer<Object> obj = ...;

if (!obj) ...

Sawyer::SharedPointer

Reference-counting intrusive smart pointer.

Definition SharedPointer.h:65

Definition at line 284 of file SharedPointer.h.

◆ operator unspecified_bool()

template<class T >

Sawyer::SharedPointer< T >::operator unspecified_bool ( ) const

inline

Type for Boolean context.

Implicit conversion to a type that can be used in a boolean context such as an if or while statement. For instance:

SharedPointer<Object> x = ...;
if (x) {
   //this is reached
}

Definition at line 311 of file SharedPointer.h.

◆ getRawPointer() [1/2]

template<class T >

Pointee * Sawyer::SharedPointer< T >::getRawPointer ( )

inline

Obtain the pointed-to object.

The pointed-to object is returned. Returns null for empty pointers. An idiom for getting a raw pointer for a shared pointer that's known to be non-null is to dereference the shared pointer and then take the address:

SharedPointer<MyType> ptr = ...;

MyType *obj = &*ptr;

Definition at line 334 of file SharedPointer.h.

Referenced by Sawyer::SharedPointer< T >::operator!=(), Sawyer::SharedPointer< T >::operator<(), Sawyer::SharedPointer< T >::operator<=(), Sawyer::SharedPointer< T >::operator=(), Sawyer::SharedPointer< T >::operator==(), Sawyer::SharedPointer< T >::operator>(), and Sawyer::SharedPointer< T >::operator>=().

◆ getRawPointer() [2/2]

template<class T >

Pointee * Sawyer::SharedPointer< T >::getRawPointer ( ) const

inline

Definition at line 337 of file SharedPointer.h.

The documentation for this class was generated from the following file:

SharedPointer.h

Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ Pointee

Constructor & Destructor Documentation

◆ SharedPointer() [1/6]

◆ SharedPointer() [2/6]

◆ SharedPointer() [3/6]

◆ SharedPointer() [4/6]

◆ SharedPointer() [5/6]

◆ SharedPointer() [6/6]

◆ ~SharedPointer()

Member Function Documentation

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ operator*()

◆ operator->()

◆ dynamicCast()

◆ operator==() [1/2]

◆ operator!=() [1/2]

◆ operator<() [1/2]

◆ operator<=() [1/2]

◆ operator>() [1/2]

◆ operator>=() [1/2]

◆ operator==() [2/2]

◆ operator!=() [2/2]

◆ operator<() [2/2]

◆ operator<=() [2/2]

◆ operator>() [2/2]

◆ operator>=() [2/2]

◆ operator!()

◆ operator unspecified_bool()

◆ getRawPointer() [1/2]

◆ getRawPointer() [2/2]