PSafePtrMultiThreaded Class Reference

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

`#include <safecoll.h>`

Inheritance diagram for PSafePtrMultiThreaded:

## Public Member Functions

virtual void | Assign (const PSafePtrMultiThreaded &ptr)
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...
Operations
virtual void | SetNULL ()
| Set the pointer to NULL, unlocking/dereferencing existing pointer value. More...
virtual PBoolean | SetSafetyMode (PSafetyMode mode)
| Change the locking mode used by this pointer. More...
Public Member Functions inherited from PSafePtrBase
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
bool | operator! () const
| Return true if pointer is NULL. More...
PSafetyMode | GetSafetyMode () const
| Get the locking mode used by this pointer. More...
const PSafeCollection * | GetCollection () const
| Get the associated collection this pointer may be contained in. More...
| ~PSafePtrBase ()
| Unlock and dereference the PSafeObject this is pointing to. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. 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...
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 Member Functions

virtual void | Next ()
virtual void | Previous ()
virtual void | DeleteObject (PSafeObject *obj)
virtual void | LockPtr ()
virtual void | UnlockPtr ()
Protected Member Functions inherited from PSafePtrBase
PBoolean | EnterSafetyMode (EnterSafetyModeOption ref)
void | ExitSafetyMode (ExitSafetyModeOption ref)
| 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...
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes

PMutex | m_mutex
PSafeObject * | m_objectToDelete
Protected Attributes inherited from PSafePtrBase
const PSafeCollection * | collection
PSafeObject * | currentObject
PSafetyMode | lockMode

## Construction

| PSafePtrMultiThreaded (PSafeObject *obj=NULL, PSafetyMode mode=PSafeReference)
| Create a new pointer to a PSafeObject. More...
| PSafePtrMultiThreaded (const PSafeCollection &safeCollection, PSafetyMode mode, PINDEX idx)
| Create a new pointer to a PSafeObject. More...
| PSafePtrMultiThreaded (const PSafeCollection &safeCollection, PSafetyMode mode, PSafeObject *obj)
| Create a new pointer to a PSafeObject. More...
| PSafePtrMultiThreaded (const PSafePtrMultiThreaded &enumerator)
| Copy the pointer to the PSafeObject. More...
| ~PSafePtrMultiThreaded ()
| 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 Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
Protected Types inherited from PSafePtrBase
enum | EnterSafetyModeOption { WithReference, AlreadyReferenced }
enum | ExitSafetyModeOption { WithDereference, NoDereference }

## 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: unlikel PSafePtrBase, pointers based on this class are thread safe themseleves, at the expense of performance on every operation.

See the PSafeObject class for more details.

## Constructor & Destructor Documentation

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

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

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

PSafePtrMultiThreaded::PSafePtrMultiThreaded | ( | const PSafePtrMultiThreaded & | 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

PSafePtrMultiThreaded::~PSafePtrMultiThreaded | ( |  | ) |

Unlock and dereference the PSafeObject this is pointing to.

## Member Function Documentation

virtual void PSafePtrMultiThreaded::Assign | ( | const PSafePtrMultiThreaded & | ptr | ) |

virtual

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

virtual

Reimplemented from PSafePtrBase.

virtual void PSafePtrMultiThreaded::Assign | ( | const PSafeCollection & | safeCollection | ) |

virtual

Reimplemented from PSafePtrBase.

virtual void PSafePtrMultiThreaded::Assign | ( | PSafeObject * | obj | ) |

virtual

Reimplemented from PSafePtrBase.

virtual void PSafePtrMultiThreaded::Assign | ( | PINDEX | idx | ) |

virtual

Reimplemented from PSafePtrBase.

virtual Comparison PSafePtrMultiThreaded::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 PSafePtrBase.

virtual void PSafePtrMultiThreaded::DeleteObject | ( | PSafeObject * | obj | ) |

protected virtual

Reimplemented from PSafePtrBase.

virtual void PSafePtrMultiThreaded::LockPtr | ( |  | ) |

inline protected virtual

Reimplemented from PSafePtrBase.

References m_mutex.

virtual void PSafePtrMultiThreaded::Next | ( |  | ) |

protected virtual

Reimplemented from PSafePtrBase.

virtual void PSafePtrMultiThreaded::Previous | ( |  | ) |

protected virtual

Reimplemented from PSafePtrBase.

virtual void PSafePtrMultiThreaded::SetNULL | ( |  | ) |

virtual

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

Reimplemented from PSafePtrBase.

virtual PBoolean PSafePtrMultiThreaded::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

  mode | New locking mode

Reimplemented from PSafePtrBase.

virtual void PSafePtrMultiThreaded::UnlockPtr | ( |  | ) |

protected virtual

Reimplemented from PSafePtrBase.

## Member Data Documentation

PMutex PSafePtrMultiThreaded::m_mutex

mutable protected

Referenced by LockPtr().

PSafeObject* PSafePtrMultiThreaded::m_objectToDelete

protected

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

- safecoll.h