Fawkes API  Fawkes Development Version
fawkes::LockPtr Class Reference

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

#include <lockptr.h>

Inheritance diagram for fawkes::LockPtr:

List of all members.

Public Member Functions

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

Static Public Member Functions

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

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.

Detailed Description

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!


Constructor & Destructor Documentation

fawkes::LockPtr::LockPtr ( ) [inline]

Default constructor.

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

Definition at line 266 of file lockptr.h.

fawkes::LockPtr::~LockPtr ( ) [inline]

Destructor - decrements reference count.

Definition at line 276 of file lockptr.h.

fawkes::LockPtr::LockPtr ( T_CppObject *  cpp_object) [inline, explicit]

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

Definition at line 305 of file lockptr.h.

fawkes::LockPtr::LockPtr ( const LockPtr< T_CppObject > &  src) [inline]

Copy constructor This increments the shared reference count.

Parameters:
srcrefptr to copy

Definition at line 337 of file lockptr.h.

References fawkes::Mutex::lock(), and fawkes::Mutex::unlock().

template<class T_CastFrom >
fawkes::LockPtr::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 358 of file lockptr.h.

References fawkes::Mutex::lock(), and fawkes::Mutex::unlock().

fawkes::LockPtr::LockPtr ( T_CppObject *  cpp_object,
Mutex objmutex,
int *  refcount,
Mutex refmutex 
) [inline, explicit]

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

References fawkes::Mutex::lock(), and fawkes::Mutex::unlock().


Member Function Documentation

template<class T_CastFrom >
LockPtr< T_CppObject > fawkes::LockPtr::cast_const ( const LockPtr< T_CastFrom > &  src) [inline, static]

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

template<class T_CastFrom >
LockPtr< T_CppObject > fawkes::LockPtr::cast_dynamic ( const LockPtr< T_CastFrom > &  src) [inline, static]

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

template<class T_CastFrom >
LockPtr< T_CppObject > fawkes::LockPtr::cast_static ( const LockPtr< T_CastFrom > &  src) [inline, static]

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

void fawkes::LockPtr::clear ( ) [inline]

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

Definition at line 470 of file lockptr.h.

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

void fawkes::LockPtr::lock ( ) const [inline]

Lock access to the encapsulated object.

Definition at line 225 of file lockptr.h.

Referenced by OpenNiContextThread::loop().

Mutex* fawkes::LockPtr::objmutex_ptr ( ) const [inline]
fawkes::LockPtr::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 464 of file lockptr.h.

bool fawkes::LockPtr::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 458 of file lockptr.h.

T_CppObject * fawkes::LockPtr::operator* ( ) const [inline]

Get underlying pointer.

Use with care!

Returns:
pointer to encapsulated object

Definition at line 260 of file lockptr.h.

T_CppObject * fawkes::LockPtr::operator-> ( ) const [inline]

Dereferencing.

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

Returns:
pointer to encapsulated object

Definition at line 254 of file lockptr.h.

LockPtr< T_CppObject > & fawkes::LockPtr::operator= ( const LockPtr< T_CppObject > &  src) [inline]

Copy from another LockPtr.

Parameters:
srcrefptr to copy from
Returns:
reference to this instance

Definition at line 397 of file lockptr.h.

template<class T_CastFrom >
LockPtr< T_CppObject > & fawkes::LockPtr::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 442 of file lockptr.h.

LockPtr< T_CppObject > & fawkes::LockPtr::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 430 of file lockptr.h.

bool fawkes::LockPtr::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 451 of file lockptr.h.

int fawkes::LockPtr::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 207 of file lockptr.h.

Referenced by OpenNiContextThread::init(), and OpenNiContextThread::loop().

int* fawkes::LockPtr::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 215 of file lockptr.h.

Mutex* fawkes::LockPtr::refmutex_ptr ( ) const [inline]

For use only in the internal implementation of sharedptr.

Get reference mutex.

Returns:
pointer to refcount mutex

Definition at line 221 of file lockptr.h.

void fawkes::LockPtr::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 377 of file lockptr.h.

bool fawkes::LockPtr::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 230 of file lockptr.h.

void fawkes::LockPtr::unlock ( ) const [inline]

Unlock object mutex.

Definition at line 233 of file lockptr.h.

Referenced by OpenNiContextThread::loop().


Friends And Related Function Documentation

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


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