This class defines a base class for thread-safe pointer to an object. More...

#include <safecoll.h>

Inheritance diagram for PSafePtrBase:

Collaboration diagram for PSafePtrBase:

Public Member Functions
virtual void	Assign (const PSafePtrBase &ptr)

virtual void	Assign (const PSafeCollection &safeCollection)

virtual void	Assign (PSafeObject *obj)

virtual void	Assign (PINDEX idx)

Overrides from class PObject
virtual Comparison	Compare (const PObject &obj) const
	Compare the pointers. More...

virtual void	PrintOn (ostream &strm) const
	Output the contents of the object to the stream. More...

Operations
virtual void	SetNULL ()
	Set the pointer to NULL, unlocking/dereferencing existing pointer value. More...

bool	operator! () const
	Return true if pointer is NULL. More...

PSafeObject *	GetObject () const
	Return pointer to safe object. More...

template<class T >
T *	GetObjectAs () const
	Return pointer to safe object. More...

PSafetyMode	GetSafetyMode () const
	Get the locking mode used by this pointer. More...

virtual PBoolean	SetSafetyMode (PSafetyMode mode)
	Change the locking mode used by this pointer. More...

Public Member Functions inherited from PObject
unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

void	SetTraceContextIdentifier (unsigned id)

void	GetTraceContextIdentifier (PObject &obj)

void	GetTraceContextIdentifier (PObject *obj)

void	SetTraceContextIdentifier (const PObject &obj)

void	SetTraceContextIdentifier (const PObject *obj)

virtual	~PObject ()

virtual PObject *	Clone () const
	Create a copy of the class on the heap. More...

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual PINDEX	HashFunction () const
	This function yields a hash value required by the `PDictionary` class. More...

virtual const char *	GetClass (unsigned ancestor=0) const
	Get the current dynamic type of the object instance. More...

PBoolean	IsClass (const char *cls) const

virtual PBoolean	InternalIsDescendant (const char *clsName) const
	Determine if the dynamic type of the current instance is a descendent of the specified class. More...

__inline const PObject *	PTraceObjectInstance () const

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

virtual void	ReadFrom (istream &strm)
	Input the contents of the object from the stream. More...

Protected Types
enum	EnterSafetyModeOption { WithReference, AlreadyReferenced }

enum	ExitSafetyModeOption { WithDereference, NoDereference }

Protected Member Functions
virtual void	Next ()

virtual void	Previous ()

virtual void	DeleteObject (PSafeObject *obj)

PBoolean	EnterSafetyMode (EnterSafetyModeOption ref)

void	ExitSafetyMode (ExitSafetyModeOption ref)

virtual void	LockPtr ()

virtual void	UnlockPtr ()

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Attributes
const PSafeCollection *	collection

PSafeObject *	currentObject

PSafetyMode	lockMode

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Construction
	PSafePtrBase (PSafeObject *obj=NULL, PSafetyMode mode=PSafeReference)
	Create a new pointer to a PSafeObject. More...

	PSafePtrBase (const PSafeCollection &safeCollection, PSafetyMode mode, PINDEX idx)
	Create a new pointer to a PSafeObject. More...

	PSafePtrBase (const PSafeCollection &safeCollection, PSafetyMode mode, PSafeObject *obj)
	Create a new pointer to a PSafeObject. More...

	PSafePtrBase (const PSafePtrBase &enumerator)
	Copy the pointer to the PSafeObject. More...

	~PSafePtrBase ()
	Unlock and dereference the PSafeObject this is pointing to. More...

Additional Inherited Members
Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Static Public Member Functions inherited from PObject
static const char *	Class ()
	Get the name of the class as a C string. More...

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

Friends inherited from PObject

Detailed Description

This class defines a base class for thread-safe pointer to an object.

This is part of a set of classes to solve the general problem of a collection (eg a PList or PDictionary) of objects that needs to be a made thread safe. Any thread can add, read, write or remove an object with both the object and the database of objects itself kept thread safe.

NOTE: the PSafePtr will allow safe and mutexed access to objects but is not thread safe itself! You should not share PSafePtr instances across threads.

See the PSafeObject class for more details.

Member Enumeration Documentation

enum PSafePtrBase::EnterSafetyModeOption

protected

Enumerator
WithReference
AlreadyReferenced

enum PSafePtrBase::ExitSafetyModeOption

protected

Enumerator
WithDereference
NoDereference

Constructor & Destructor Documentation

PSafePtrBase::PSafePtrBase	(	PSafeObject *	obj = `NULL`,
		PSafetyMode	mode = `PSafeReference`
	)

protected

Create a new pointer to a PSafeObject.

An optional locking mode may be provided to lock the object for reading or writing and automatically unlock it on destruction.

Note that this version is not associated with a collection so the ++ and – operators will not work.

Parameters

obj	Physical object to point to.
mode	Locking mode for the object

PSafePtrBase::PSafePtrBase	(	const PSafeCollection &	safeCollection,
		PSafetyMode	mode,
		PINDEX	idx
	)

protected

Create a new pointer to a PSafeObject.

An optional locking mode may be provided to lock the object for reading or writing and automatically unlock it on destruction.

The idx'th entry of the collection is pointed to by this object. If the idx is beyond the size of the collection, the pointer is NULL.

Parameters

safeCollection	Collection pointer will enumerate
mode	Locking mode for the object
idx	Index into collection to point to

PSafePtrBase::PSafePtrBase	(	const PSafeCollection &	safeCollection,
		PSafetyMode	mode,
		PSafeObject *	obj
	)

protected

Create a new pointer to a PSafeObject.

An optional locking mode may be provided to lock the object for reading or writing and automatically unlock it on destruction.

The obj parameter is only set if it contained in the collection, otherwise the pointer is NULL.

Parameters

safeCollection	Collection pointer will enumerate
mode	Locking mode for the object
obj	Inital object in collection to point to

PSafePtrBase::PSafePtrBase ( const PSafePtrBase & enumerator )

protected

Copy the pointer to the PSafeObject.

This will create a copy of the pointer with the same locking mode and lock on the PSafeObject. It will also increment the reference count on the PSafeObject as well.

Parameters

enumerator Pointer to copy

PSafePtrBase::~PSafePtrBase ( )

Unlock and dereference the PSafeObject this is pointing to.

Member Function Documentation

virtual void PSafePtrBase::Assign ( const PSafePtrBase & ptr )

virtual

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Assign ( const PSafeCollection & safeCollection )

virtual

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Assign ( PSafeObject * obj )

virtual

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Assign ( PINDEX idx )

virtual

Reimplemented in PSafePtrMultiThreaded.

virtual Comparison PSafePtrBase::Compare ( const PObject & obj ) const

virtual

Compare the pointers.

Note this is not a value comparison and will only return EqualTo if the two PSafePtrBase instances are pointing to the same instance.

Parameters

obj	Other instance to compare against

Reimplemented from PObject.

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::DeleteObject ( PSafeObject * obj )

protectedvirtual

Reimplemented in PSafePtrMultiThreaded.

PBoolean PSafePtrBase::EnterSafetyMode ( EnterSafetyModeOption ref )

protected

void PSafePtrBase::ExitSafetyMode ( ExitSafetyModeOption ref )

protected

PSafeObject* PSafePtrBase::GetObject ( ) const

inline

Return pointer to safe object.

References currentObject.

Referenced by PSafeWork::Work().

template<class T >

T* PSafePtrBase::GetObjectAs ( ) const

inline

Return pointer to safe object.

References currentObject.

PSafetyMode PSafePtrBase::GetSafetyMode ( ) const

inline

Get the locking mode used by this pointer.

References lockMode.

virtual void PSafePtrBase::LockPtr ( )

inlineprotectedvirtual

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Next ( )

protectedvirtual

Reimplemented in PSafePtrMultiThreaded.

bool PSafePtrBase::operator! ( ) const

inline

Return true if pointer is NULL.

References currentObject.

virtual void PSafePtrBase::Previous ( )

protectedvirtual

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::PrintOn ( ostream & strm ) const

virtual

Output the contents of the object to the stream.

The exact output is dependent on the exact semantics of the descendent class. This is primarily used by the standard operator<< function.

The default behaviour is to print the class name.

Reimplemented from PObject.

virtual void PSafePtrBase::SetNULL ( )

virtual

Set the pointer to NULL, unlocking/dereferencing existing pointer value.

Reimplemented in PSafePtrMultiThreaded.

Referenced by PSafeDictionary< K, D >::iterator_base::SetPosition().

virtual PBoolean PSafePtrBase::SetSafetyMode ( PSafetyMode mode )

virtual

Change the locking mode used by this pointer.

If the function returns false, then the object has been flagged for deletion and the calling thread should immediately cease use of the object. This instance pointer will be set to NULL.

Parameters