PTLib Version 2.12.9

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | List of all members
PSafePtrBase Class Reference

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

`#include <safecoll.h>`

Inheritance diagram for PSafePtrBase:
[legend]
Collaboration diagram for PSafePtrBase:
[legend]

## 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 | ) |
| protected virtual

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 | ( |  | ) |
| 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.

References currentObject.

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.

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

  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

Referenced by GetObject(), GetObjectAs(), and operator!().

PSafetyMode PSafePtrBase::lockMode
| protected

Referenced by GetSafetyMode().

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

- safecoll.h