Fawkes API  Fawkes Development Version
fawkes::LockPtr< T_CppObject > Class Template Reference

LockPtr<> is a reference-counting shared lockable smartpointer. More...

#include <lockptr.h>

Inheritance diagram for fawkes::LockPtr< T_CppObject >:

Public Member Functions

 LockPtr ()
 Default constructor. More...
 
 ~LockPtr ()
 Destructor - decrements reference count. More...
 
 LockPtr (T_CppObject *cpp_object, bool recursive_mutex=false)
 Constructor that takes ownership. More...
 
 LockPtr (const LockPtr< T_CppObject > &src)
 Copy constructor This increments the shared reference count. More...
 
template<class T_CastFrom >
 LockPtr (const LockPtr< T_CastFrom > &src)
 Copy constructor (from different, but castable type). More...
 
void swap (LockPtr< T_CppObject > &other)
 Swap the contents of two LockPtr<>. More...
 
LockPtr< T_CppObject > & operator= (const LockPtr< T_CppObject > &src)
 Copy from another LockPtr. More...
 
template<class T_CastFrom >
LockPtr< T_CppObject > & operator= (const LockPtr< T_CastFrom > &src)
 Copy from different, but castable type). More...
 
LockPtr< T_CppObject > & operator= (T_CppObject *ptr)
 Assign object and claim ownership. More...
 
bool operator== (const LockPtr< T_CppObject > &src) const
 Tests whether the LockPtr<> point to the same underlying instance. More...
 
bool operator!= (const LockPtr< T_CppObject > &src) const
 Tests whether the LockPtr<> do not point to the same underlying instance. More...
 
T_CppObject * operator-> () const
 Dereferencing. More...
 
T_CppObject * operator* () const
 Get underlying pointer. More...
 
 operator bool () const
 Test whether the LockPtr<> points to any underlying instance. More...
 
void clear ()
 Set underlying instance to 0, decrementing reference count of existing instance appropriately. More...
 
 LockPtr (T_CppObject *cpp_object, Mutex *objmutex, int *refcount, Mutex *refmutex)
 For use only in the internal implementation of LockPtr. More...
 
int refcount () const
 Get current refcount. More...
 
int * refcount_ptr () const
 For use only in the internal implementation of sharedptr. More...
 
Mutexrefmutex_ptr () const
 For use only in the internal implementation of sharedptr. More...
 
void lock () const
 Lock access to the encapsulated object. More...
 
bool try_lock () const
 Try to acquire lock for the encapsulated object. More...
 
void unlock () const
 Unlock object mutex. More...
 
Mutexobjmutex_ptr () const
 Get object mutex. More...
 

Static Public Member Functions

template<class T_CastFrom >
static LockPtr< T_CppObject > cast_dynamic (const LockPtr< T_CastFrom > &src)
 Dynamic cast to derived class. More...
 
template<class T_CastFrom >
static LockPtr< T_CppObject > cast_static (const LockPtr< T_CastFrom > &src)
 Static cast to derived class. More...
 
template<class T_CastFrom >
static LockPtr< T_CppObject > cast_const (const LockPtr< T_CastFrom > &src)
 Cast to non-const. More...
 

Related Functions

(Note that these are not member functions.)

template<class T_CppObject >
void swap (LockPtr< T_CppObject > &lrp, LockPtr< T_CppObject > &rrp)
 Swap refptr instances. More...
 

Detailed Description

template<class T_CppObject>
class fawkes::LockPtr< T_CppObject >

LockPtr<> is a reference-counting shared lockable smartpointer.

Reference counting means that a shared reference count is incremented each time a LockPtr is copied, and decremented each time a LockPtr is destroyed, for instance when it leaves its scope. When the reference count reaches zero, the contained object is deleted

Fawkes uses LockPtr so that you don't need to remember to delete the object explicitly, or know when a method expects you to delete the object that it returns.

It is similar to RefPtr, but additionally it provides one shared lock which can be used to coordinate locking for the encapsulated object.

Note that LockPtr is thread-safe, but that you need to handle locking and unlocking for the shared resource yourself!

Definition at line 57 of file lockptr.h.

Constructor & Destructor Documentation

◆ LockPtr() [1/5]

template<class T_CppObject >
fawkes::LockPtr< T_CppObject >::LockPtr ( )
inline

Default constructor.

Afterwards it will be null and use of -> will cause a segmentation fault.

Definition at line 288 of file lockptr.h.

Referenced by fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_const().

◆ ~LockPtr()

template<class T_CppObject >
fawkes::LockPtr< T_CppObject >::~LockPtr ( )
inline

Destructor - decrements reference count.

Definition at line 298 of file lockptr.h.

◆ LockPtr() [2/5]

template<class T_CppObject>
fawkes::LockPtr< T_CppObject >::LockPtr ( T_CppObject *  cpp_object,
bool  recursive_mutex = false 
)
inlineexplicit

Constructor that takes ownership.

This takes ownership of cpp_object, so it will be deleted when the last LockPtr is deleted, for instance when it goes out of scope.

Parameters
cpp_objectC++ object to take ownership of
recursive_mutextrue to create a recursive mutex (with deadlock prevention when locked from the same thread) for the object mutex, false to create a normal mutex
See also
Mutex

Definition at line 327 of file lockptr.h.

◆ LockPtr() [3/5]

template<class T_CppObject>
fawkes::LockPtr< T_CppObject >::LockPtr ( const LockPtr< T_CppObject > &  src)
inline

Copy constructor This increments the shared reference count.

Parameters
srcrefptr to copy

Definition at line 359 of file lockptr.h.

◆ LockPtr() [4/5]

template<class T_CppObject >
template<class T_CastFrom >
fawkes::LockPtr< T_CppObject >::LockPtr ( const LockPtr< T_CastFrom > &  src)
inline

Copy constructor (from different, but castable type).

Increments the reference count.

Parameters
srcrefptr to copy

Definition at line 380 of file lockptr.h.

◆ LockPtr() [5/5]

template<class T_CppObject>
fawkes::LockPtr< T_CppObject >::LockPtr ( T_CppObject *  cpp_object,
Mutex objmutex,
int *  refcount,
Mutex refmutex 
)
inlineexplicit

For use only in the internal implementation of LockPtr.

Parameters
cpp_objectC++ object to wrap
objmutexobject mutex
refcountreference count
refmutexreference count mutex

Definition at line 344 of file lockptr.h.

Member Function Documentation

◆ cast_const()

template<class T_CppObject>
template<class T_CastFrom >
static LockPtr<T_CppObject> fawkes::LockPtr< T_CppObject >::cast_const ( const LockPtr< T_CastFrom > &  src)
inlinestatic

Cast to non-const.

The LockPtr can't be cast with the usual notation so instead you can use

ptr_unconst = LockPtr<UnConstType>::cast_const(ptr_const);
Parameters
srcsource refptr to cast
Returns
refptr to object casted to given type

Definition at line 209 of file lockptr.h.

◆ cast_dynamic()

template<class T_CppObject>
template<class T_CastFrom >
static LockPtr<T_CppObject> fawkes::LockPtr< T_CppObject >::cast_dynamic ( const LockPtr< T_CastFrom > &  src)
inlinestatic

Dynamic cast to derived class.

The LockPtr can't be cast with the usual notation so instead you can use

ptr_derived = LockPtr<Derived>::cast_dynamic(ptr_base);
Parameters
srcsource refptr to cast
Returns
refptr to object casted to given type

Definition at line 172 of file lockptr.h.

◆ cast_static()

template<class T_CppObject>
template<class T_CastFrom >
static LockPtr<T_CppObject> fawkes::LockPtr< T_CppObject >::cast_static ( const LockPtr< T_CastFrom > &  src)
inlinestatic

Static cast to derived class.

Like the dynamic cast; the notation is

ptr_derived = LockPtr<Derived>::cast_static(ptr_base);
Parameters
srcsource refptr to cast
Returns
refptr to object casted to given type

Definition at line 192 of file lockptr.h.

◆ clear()

template<class T_CppObject >
void fawkes::LockPtr< T_CppObject >::clear ( )
inline

Set underlying instance to 0, decrementing reference count of existing instance appropriately.

Definition at line 492 of file lockptr.h.

Referenced by ROSNodeThread::finalize(), OpenNiContextThread::finalize(), CLIPSThread::finalize(), OpenPRSThread::finalize(), NavGraphThread::finalize(), OpenNiContextThread::init(), fawkes::CLIPSAspect::~CLIPSAspect(), and fawkes::ROSAspect::~ROSAspect().

◆ lock()

◆ objmutex_ptr()

◆ operator bool()

template<class T_CppObject >
fawkes::LockPtr< T_CppObject >::operator bool ( ) const
inline

Test whether the LockPtr<> points to any underlying instance.

Mimics usage of ordinary pointers:

if (ptr)
do_something();

Definition at line 486 of file lockptr.h.

◆ operator!=()

template<class T_CppObject>
bool fawkes::LockPtr< T_CppObject >::operator!= ( const LockPtr< T_CppObject > &  src) const
inline

Tests whether the LockPtr<> do not point to the same underlying instance.

Parameters
srcrefptr to compare to
Returns
true if both refptrs do not point to the same instance.

Definition at line 480 of file lockptr.h.

◆ operator*()

template<class T_CppObject >
T_CppObject * fawkes::LockPtr< T_CppObject >::operator* ( ) const
inline

Get underlying pointer.

Use with care!

Returns
pointer to encapsulated object

Definition at line 282 of file lockptr.h.

◆ operator->()

template<class T_CppObject >
T_CppObject * fawkes::LockPtr< T_CppObject >::operator-> ( ) const
inline

Dereferencing.

Use the methods of the underlying instance like so: refptr->memberfun().

Returns
pointer to encapsulated object

Definition at line 276 of file lockptr.h.

◆ operator=() [1/3]

template<class T_CppObject>
LockPtr< T_CppObject > & fawkes::LockPtr< T_CppObject >::operator= ( const LockPtr< T_CppObject > &  src)
inline

Copy from another LockPtr.

Parameters
srcrefptr to copy from
Returns
reference to this instance

Definition at line 419 of file lockptr.h.

◆ operator=() [2/3]

template<class T_CppObject >
template<class T_CastFrom >
LockPtr< T_CppObject > & fawkes::LockPtr< T_CppObject >::operator= ( const LockPtr< T_CastFrom > &  src)
inline

Copy from different, but castable type).

Increments the reference count.

Parameters
srcrefptr to copy from
Returns
reference to this instance

Definition at line 464 of file lockptr.h.

◆ operator=() [3/3]

template<class T_CppObject>
LockPtr< T_CppObject > & fawkes::LockPtr< T_CppObject >::operator= ( T_CppObject *  ptr)
inline

Assign object and claim ownership.

Parameters
ptrpointer to object, this refptr will claim ownership of the src!
Returns
reference to this instance

Definition at line 452 of file lockptr.h.

◆ operator==()

template<class T_CppObject>
bool fawkes::LockPtr< T_CppObject >::operator== ( const LockPtr< T_CppObject > &  src) const
inline

Tests whether the LockPtr<> point to the same underlying instance.

Parameters
srcrefptr to compare to
Returns
true if both refptrs point to the same instance.

Definition at line 473 of file lockptr.h.

◆ refcount()

template<class T_CppObject>
int fawkes::LockPtr< T_CppObject >::refcount ( ) const
inline

Get current refcount.

Get reference count. Use this with care, as it may change any time.

Returns
current reference count

Definition at line 229 of file lockptr.h.

Referenced by fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_const(), OpenNiContextThread::init(), and OpenNiContextThread::loop().

◆ refcount_ptr()

template<class T_CppObject>
int* fawkes::LockPtr< T_CppObject >::refcount_ptr ( ) const
inline

For use only in the internal implementation of sharedptr.

Get reference count pointer. Warning: This is for internal use only. Do not manually modify the reference count with this pointer.

Returns
pointer to refcount integer

Definition at line 237 of file lockptr.h.

Referenced by fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_const(), fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_dynamic(), and fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_static().

◆ refmutex_ptr()

template<class T_CppObject>
Mutex* fawkes::LockPtr< T_CppObject >::refmutex_ptr ( ) const
inline

For use only in the internal implementation of sharedptr.

Get reference mutex.

Returns
pointer to refcount mutex

Definition at line 243 of file lockptr.h.

Referenced by fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_const(), fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_dynamic(), and fawkes::LockPtr< fawkes::CLIPSEnvManager >::cast_static().

◆ swap()

template<class T_CppObject>
void fawkes::LockPtr< T_CppObject >::swap ( LockPtr< T_CppObject > &  other)
inline

Swap the contents of two LockPtr<>.

This method swaps the internal pointers to T_CppObject. This can be done safely without involving a reference/unreference cycle and is therefore highly efficient.

Parameters
otherother instance to swap with.

Definition at line 399 of file lockptr.h.

Referenced by fawkes::LockPtr< fawkes::CLIPSEnvManager >::swap().

◆ try_lock()

template<class T_CppObject>
bool fawkes::LockPtr< T_CppObject >::try_lock ( ) const
inline

Try to acquire lock for the encapsulated object.

Returns
true if the lock has been acquired, false otherwise

Definition at line 252 of file lockptr.h.

◆ unlock()

Friends And Related Function Documentation

◆ swap()

template<class T_CppObject >
void swap ( LockPtr< T_CppObject > &  lrp,
LockPtr< T_CppObject > &  rrp 
)
related

Swap refptr instances.

Parameters
lrp"left" refptr
rrp"right" refptr

Definition at line 506 of file lockptr.h.


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