# PSafePtr< T, BaseClass > Class Template Reference

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

`#include <safecoll.h>`

List of all members.

## Public Member Functions

Construction
| PSafePtr (T *obj=NULL, PSafetyMode mode=PSafeReference)
| Create a new pointer to a PSafeObject.
| PSafePtr (const PSafeCollection &safeCollection, PSafetyMode mode=PSafeReadWrite, PINDEX idx=0)
| Create a new pointer to a PSafeObject.
| PSafePtr (const PSafeCollection &safeCollection, PSafetyMode mode, PSafeObject *obj)
| Create a new pointer to a PSafeObject.
| PSafePtr (const PSafePtr &ptr)
| Copy the pointer to the PSafeObject.
PSafePtr & | operator= (const PSafePtr &ptr)
| Copy the pointer to the PSafeObject.
PSafePtr & | operator= (const PSafeCollection &safeCollection)
| Start an enumerated PSafeObject.
PSafePtr & | operator= (T *obj)
| Set the new pointer to a PSafeObject.
PSafePtr & | operator= (PINDEX idx)
| Set the new pointer to a collection index.
PSafePtr | Set (T *obj)
| Set the safe pointer to the specified object.
Operations
| operator T * () const
| Return the physical pointer to the object.
T & | operator * () const
| Return the physical pointer to the object.
T * | operator-> () const
| Allow access to the physical object the pointer is pointing to.
T * | operator++ (int)
| Post-increment the pointer.
T * | operator++ ()
| Pre-increment the pointer.
T * | operator-- (int)
| Post-decrement the pointer.
T * | operator-- ()
| Pre-decrement the pointer.

## 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>

T& PSafePtr< T, BaseClass >::operator * | ( |  | ) | const`[inline]`

Return the physical pointer to the object.

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++ | ( |  | ) | `[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-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-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-- | ( | 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-> | ( |  | ) | const`[inline]`

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

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 >::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= | ( | 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= | ( | 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 >::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