# PSafePtrBase Class Reference

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

`#include <safecoll.h>`

Inheritance diagram for PSafePtrBase:

List of all members.

## Construction

| ~PSafePtrBase ()
| Unlock and dereference the PSafeObject this is pointing to.
| PSafePtrBase (PSafeObject *obj=NULL, PSafetyMode mode=PSafeReference)
| Create a new pointer to a PSafeObject.
| PSafePtrBase (const PSafeCollection &safeCollection, PSafetyMode mode, PINDEX idx)
| Create a new pointer to a PSafeObject.
| PSafePtrBase (const PSafeCollection &safeCollection, PSafetyMode mode, PSafeObject *obj)
| Create a new pointer to a PSafeObject.
| PSafePtrBase (const PSafePtrBase &enumerator)
| Copy the pointer to the PSafeObject.

## 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.
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream.
Operations
virtual void | SetNULL ()
| Set the pointer to NULL, unlocking/dereferencing existing pointer value.
bool | operator! () const
| Return true if pointer is NULL.
PSafetyMode | GetSafetyMode () const
| Get the locking mode used by this pointer.
virtual PBoolean | SetSafetyMode (PSafetyMode mode)
| Change the locking mode used by this pointer.
const PSafeCollection * | GetCollection () const
| Get the associated collection this pointer may be contained in.

## Protected Types

| WithReference
| AlreadyReferenced
| WithDereference
| NoDereference
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 Attributes

const PSafeCollection * | collection
PSafeObject * | currentObject
PSafetyMode | lockMode

## 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 | ( | PINDEX | idx | ) | `[virtual]`

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Assign | ( | PSafeObject * | obj | ) | `[virtual]`

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Assign | ( | const PSafeCollection & | safeCollection | ) | `[virtual]`

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Assign | ( | const PSafePtrBase & | ptr | ) | `[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 | ) | `[protected, virtual]`

Reimplemented in PSafePtrMultiThreaded.

PBoolean PSafePtrBase::EnterSafetyMode | ( | EnterSafetyModeOption | ref | ) | `[protected]`

void PSafePtrBase::ExitSafetyMode | ( | ExitSafetyModeOption | ref | ) | `[protected]`

const PSafeCollection* PSafePtrBase::GetCollection | ( |  | ) | const`[inline]`

Get the associated collection this pointer may be contained in.

PSafetyMode PSafePtrBase::GetSafetyMode | ( |  | ) | const`[inline]`

Get the locking mode used by this pointer.

virtual void PSafePtrBase::LockPtr | ( |  | ) | `[inline, protected, virtual]`

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::Next | ( |  | ) | `[protected, virtual]`

Reimplemented in PSafePtrMultiThreaded.

bool PSafePtrBase::operator! | ( |  | ) | const`[inline]`

Return true if pointer is NULL.

virtual void PSafePtrBase::Previous | ( |  | ) | `[protected, virtual]`

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.

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:

  mode | New locking mode

Reimplemented in PSafePtrMultiThreaded.

virtual void PSafePtrBase::UnlockPtr | ( |  | ) | `[inline, protected, virtual]`

Reimplemented in PSafePtrMultiThreaded.

## Member Data Documentation

const PSafeCollection* PSafePtrBase::collection `[protected]`

PSafeObject* PSafePtrBase::currentObject `[protected]`

PSafetyMode PSafePtrBase::lockMode `[protected]`

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

- safecoll.h