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 62 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 320 of file lockptr.h.

◆ ~LockPtr()

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

Destructor - decrements reference count.

Definition at line 325 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 350 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 377 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 395 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 363 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 224 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 184 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 206 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 505 of file lockptr.h.

Referenced by ROSNodeThread::finalize(), OpenNiContextThread::finalize(), CLIPSThread::finalize(), OpenPRSThread::finalize(), NavGraphThread::finalize(), and OpenNiContextThread::init().

◆ lock()

◆ objmutex_ptr()

◆ operator bool()

template<class T_CppObject >
fawkes::LockPtr< T_CppObject >::operator bool
inline

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

Mimics usage of ordinary pointers:

if (ptr)
do_something();

Definition at line 498 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 492 of file lockptr.h.

◆ operator*()

template<class T_CppObject >
T_CppObject * fawkes::LockPtr< T_CppObject >::operator*
inline

Get underlying pointer.

Use with care!

Returns
pointer to encapsulated object

Definition at line 314 of file lockptr.h.

◆ operator->()

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

Dereferencing.

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

Returns
pointer to encapsulated object

Definition at line 308 of file lockptr.h.

◆ operator=() [1/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 476 of file lockptr.h.

◆ operator=() [2/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 433 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 466 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 485 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 244 of file lockptr.h.

Referenced by 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 256 of file lockptr.h.

◆ 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 266 of file lockptr.h.

◆ 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 413 of file lockptr.h.

◆ 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 282 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

The documentation for this class was generated from the following file:
fawkes::LockPtr::cast_const
static LockPtr< T_CppObject > cast_const(const LockPtr< T_CastFrom > &src)
Cast to non-const.
Definition: lockptr.h:224
fawkes::LockPtr::cast_static
static LockPtr< T_CppObject > cast_static(const LockPtr< T_CastFrom > &src)
Static cast to derived class.
Definition: lockptr.h:206
fawkes::LockPtr::cast_dynamic
static LockPtr< T_CppObject > cast_dynamic(const LockPtr< T_CastFrom > &src)
Dynamic cast to derived class.
Definition: lockptr.h:184