This class defines a thread-safe enumeration of object in a collection. More...

#include <safecoll.h>

Inheritance diagram for PSafePtr< T, BaseClass >:

Public Member Functions
Construction
	PSafePtr (T *obj=NULL, PSafetyMode mode=PSafeReference)
	Create a new pointer to a PSafeObject. More...

	PSafePtr (const PSafeCollection &safeCollection, PSafetyMode mode=PSafeReadWrite, PINDEX idx=0)
	Create a new pointer to a PSafeObject. More...

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

	PSafePtr (const PSafePtr &ptr)
	Copy the pointer to the PSafeObject. More...

PSafePtr &	operator= (const PSafePtr &ptr)
	Copy the pointer to the PSafeObject. More...

PSafePtr &	operator= (const PSafeCollection &safeCollection)
	Start an enumerated PSafeObject. More...

PSafePtr &	operator= (T *obj)
	Set the new pointer to a PSafeObject. More...

PSafePtr &	operator= (PINDEX idx)
	Set the new pointer to a collection index. More...

PSafePtr	Set (T *obj)
	Set the safe pointer to the specified object. More...

Operations
	operator T * () const
	Return the physical pointer to the object. More...

T &	operator* () const
	Return the physical pointer to the object. More...

T *	operator-> () const
	Allow access to the physical object the pointer is pointing to. More...

T *	operator++ (int)
	Post-increment the pointer. More...

T *	operator++ ()
	Pre-increment the pointer. More...

T *	operator-- (int)
	Post-decrement the pointer. More...

T *	operator-- ()
	Pre-decrement the pointer. More...

Detailed Description

template<class T, class BaseClass = PSafePtrBase>
class PSafePtr< T, BaseClass >

This class defines a thread-safe enumeration of object in a collection.

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.

There are two modes of safe pointer: one that is enumerating a collection; and one that is independent of the collection that the safe object is in. There are subtle semantics that must be observed in each of these two modes especially when switching from one to the other.

NOTE: the PSafePtr will allow safe and mutexed access to objects but may not be thread safe itself! This depends on the base class being used. If the more efficient PSafePtrBase class is used you should not share PSafePtr instances across threads.

See the PSafeObject class for more details, especially in regards to enumeration of collections.

Constructor & Destructor Documentation

template<class T, class BaseClass = PSafePtrBase>

PSafePtr< T, BaseClass >::PSafePtr	(	T *	obj = `NULL`,
		PSafetyMode	mode = `PSafeReference`
	)

inline

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

template<class T, class BaseClass = PSafePtrBase>

PSafePtr< T, BaseClass >::PSafePtr	(	const PSafeCollection &	safeCollection,
		PSafetyMode	mode = `PSafeReadWrite`,
		PINDEX	idx = `0`
	)

inline

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

template<class T, class BaseClass = PSafePtrBase>

PSafePtr< T, BaseClass >::PSafePtr	(	const PSafeCollection &	safeCollection,
		PSafetyMode	mode,
		PSafeObject *	obj
	)

inline

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

template<class T, class BaseClass = PSafePtrBase>

PSafePtr< T, BaseClass >::PSafePtr ( const PSafePtr< T, BaseClass > & ptr )

inline

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

ptr	Pointer to copy

Member Function Documentation

template<class T, class BaseClass = PSafePtrBase>

PSafePtr< T, BaseClass >::operator T * ( ) const

inline

Return the physical pointer to the object.

template<class T, class BaseClass = PSafePtrBase>

T& PSafePtr< T, BaseClass >::operator* ( ) const

inline

Return the physical pointer to the object.

template<class T, class BaseClass = PSafePtrBase>

T* PSafePtr< T, BaseClass >::operator++ ( int )

inline

Post-increment the pointer.

This requires that the pointer has been created with a PSafeCollection object so that it can enumerate the collection.

template<class T, class BaseClass = PSafePtrBase>

T* PSafePtr< T, BaseClass >::operator++ ( )

inline

Pre-increment the pointer.

This requires that the pointer has been created with a PSafeCollection object so that it can enumerate the collection.

template<class T, class BaseClass = PSafePtrBase>

T* PSafePtr< T, BaseClass >::operator-- ( int )

inline

Post-decrement the pointer.

This requires that the pointer has been created with a PSafeCollection object so that it can enumerate the collection.

template<class T, class BaseClass = PSafePtrBase>

T* PSafePtr< T, BaseClass >::operator-- ( )

inline

Pre-decrement the pointer.

This requires that the pointer has been created with a PSafeCollection object so that it can enumerate the collection.

template<class T, class BaseClass = PSafePtrBase>

T* PSafePtr< T, BaseClass >::operator-> ( ) const

inline

Allow access to the physical object the pointer is pointing to.

template<class T, class BaseClass = PSafePtrBase>

PSafePtr& PSafePtr< T, BaseClass >::operator= ( const PSafePtr< T, BaseClass > & ptr )

inline

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.

template<class T, class BaseClass = PSafePtrBase>

PSafePtr& PSafePtr< T, BaseClass >::operator= ( const PSafeCollection & safeCollection )

inline

Start an enumerated PSafeObject.

This will create a read/write locked reference to teh first element in the collection.

template<class T, class BaseClass = PSafePtrBase>

PSafePtr& PSafePtr< T, BaseClass >::operator= ( T * obj )

inline

Set the new pointer to a PSafeObject.

This will set the pointer to the new object. The old object pointed to will be unlocked and dereferenced and the new object referenced.

If the safe pointer has an associated collection and the new object is in that collection, then the object is set to the same locking mode as the previous pointer value. This, in effect, jumps the enumeration of a collection to the specifed object.

If the safe pointer has no associated collection or the object is not in the associated collection, then the object is always only referenced and there is no read only or read/write lock done. In addition any associated collection is removed so this becomes a non enumerating safe pointer.

template<class T, class BaseClass = PSafePtrBase>

PSafePtr& PSafePtr< T, BaseClass >::operator= ( PINDEX idx )

inline

Set the new pointer to a collection index.

This will set the pointer to the new object to the index entry in the colelction that the pointer was created with. The old object pointed to will be unlocked and dereferenced and the new object referenced and set to the same locking mode as the previous pointer value.

If the idx'th object is not in the collection, then the safe pointer is set to NULL.

template<class T, class BaseClass = PSafePtrBase>

PSafePtr PSafePtr< T, BaseClass >::Set ( T * obj )

inline

Set the safe pointer to the specified object.

This will return a PSafePtr for the previous value of this. It does this in a thread safe manner so "test and set" semantics are obeyed.

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

safecoll.h

Public Member Functions

Detailed Description

template<class T, class BaseClass = PSafePtrBase> class PSafePtr< T, BaseClass >

Constructor & Destructor Documentation

Member Function Documentation

template<class T, class BaseClass = PSafePtrBase>
class PSafePtr< T, BaseClass >