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
Protected Member Functions | Protected Attributes | List of all members
PSafeCollection Class Reference

This class defines a thread-safe collection of objects. More...

`#include <safecoll.h>`

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

## Public Member Functions
Construction
| PSafeCollection (PCollection *collection)
| Create a thread safe collection of objects. More...
| ~PSafeCollection ()
| Destroy the thread safe collection. 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 | Compare (const PObject &obj) const
| Compare the two objects and return their relative rank. 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
void | CopySafeCollection (PCollection *other)
void | CopySafeDictionary (PAbstractDictionary *other)
bool | SafeAddObject (PSafeObject *obj, PSafeObject *old)
void | SafeRemoveObject (PSafeObject *obj)
| PDECLARE_NOTIFIER (PTimer, PSafeCollection, DeleteObjectsTimeout)
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes
PCollection * | collection
PMutex | collectionMutex
bool | deleteObjects
PList< PSafeObject > | toBeRemoved
PMutex | removalMutex
PTimer * | m_deleteObjectsTimer
Protected Attributes inherited from PObject
unsigned | m_traceContextIdentifier

## Operations
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | RemoveAll (PBoolean synchronous=false)
| Remove all objects in collection. More...
void | AllowDeleteObjects (PBoolean yes=true)
| Disallow the automatic delete any objects that have been removed. More...
void | DisallowDeleteObjects ()
| Disallow the automatic delete any objects that have been removed. More...
virtual PBoolean | DeleteObjectsToBeRemoved ()
| Delete any objects that have been removed. More...
virtual void | DeleteObject (PObject *object) const
| Delete an objects that has been removed. More...
virtual void | SetAutoDeleteObjects ()
| Start a timer to automatically call DeleteObjectsToBeRemoved(). More...
PINDEX | GetSize () const
| Get the current size of the collection. More...
PBoolean | IsEmpty () const
| Determine if the collection is empty. More...
const PMutex & | GetMutex () const
| Get the mutex for the collection. More...
virtual PBoolean | SafeRemove (PSafeObject *obj)
| Remove an object to the collection. More...
virtual PBoolean | SafeRemoveAt (PINDEX idx)
| Remove an object to the collection. 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 thread-safe collection of objects.

This class is a wrapper around a standard PCollection class which allows only safe, mutexed, access to the 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.

See the PSafeObject class for more details. Especially in regard to enumeration of collections.

## Constructor & Destructor Documentation

PSafeCollection::PSafeCollection | ( | PCollection * | collection | ) |

Create a thread safe collection of objects.

Note the collection is automatically deleted on destruction.

Parameters

  collection | Actual collection of objects

PSafeCollection::~PSafeCollection | ( |  | ) |

Destroy the thread safe collection.

The will delete the collection object provided in the constructor.

## Member Function Documentation

void PSafeCollection::AllowDeleteObjects | ( | PBoolean | yes = `true` | ) |
| inline

Disallow the automatic delete any objects that have been removed.

Objects are simply removed from the collection and not marked for deletion using PSafeObject::SafeRemove() and DeleteObject().

Parameters

  yes | New value for flag for deleting objects

References deleteObjects.

void PSafeCollection::CopySafeCollection | ( | PCollection * | other | ) |
| protected

Referenced by PSafeColl< PArray< Base >, Base >::operator=(), and PSafeColl< PArray< Base >, Base >::PSafeColl().

void PSafeCollection::CopySafeDictionary | ( | PAbstractDictionary * | other | ) |
| protected

Referenced by PSafeDictionaryBase< PDictionary< K, D >, K, D >::operator=(), and PSafeDictionaryBase< PDictionary< K, D >, K, D >::PSafeDictionaryBase().

virtual void PSafeCollection::DeleteObject | ( | PObject * | object | ) | const
| virtual

Delete an objects that has been removed.

virtual PBoolean PSafeCollection::DeleteObjectsToBeRemoved | ( |  | ) |
| virtual

Delete any objects that have been removed.

Returns true if all objects in the collection have been removed and their pending deletions carried out.

void PSafeCollection::DisallowDeleteObjects | ( |  | ) |
| inline

Disallow the automatic delete any objects that have been removed.

Objects are simply removed from the collection and not marked for deletion using PSafeObject::SafeRemove() and DeleteObject().

References deleteObjects.

const PMutex& PSafeCollection::GetMutex | ( |  | ) | const
| inline

Get the mutex for the collection.

References collectionMutex.

PINDEX PSafeCollection::GetSize | ( |  | ) | const

Get the current size of the collection.

Note that usefulness of this function is limited as it is merely an instantaneous snapshot of the state of the collection.

Referenced by IsEmpty().

PBoolean PSafeCollection::IsEmpty | ( |  | ) | const
| inline

Determine if the collection is empty.

Note that usefulness of this function is limited as it is merely an instantaneous snapshot of the state of the collection.

References GetSize().

PSafeCollection::PDECLARE_NOTIFIER | ( | PTimer | ,
|  | PSafeCollection | ,
|  | DeleteObjectsTimeout |
| ) |  |
| protected

virtual void PSafeCollection::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 PSafeCollection::RemoveAll | ( | PBoolean | synchronous = `false` | ) |
| virtual

Remove all objects in collection.

Parameters

  synchronous | Wait till objects are deleted before returning

Referenced by PSafeColl< PArray< Base >, Base >::operator=(), and PSafeDictionaryBase< PDictionary< K, D >, K, D >::operator=().

bool PSafeCollection::SafeAddObject | ( | PSafeObject * | obj,
|  | PSafeObject * | old
| ) |  |
| protected

Referenced by PSafeColl< PArray< Base >, Base >::Append(), and PSafeDictionaryBase< PDictionary< K, D >, K, D >::SetAt().

virtual PBoolean PSafeCollection::SafeRemove | ( | PSafeObject * | obj | ) |
| protected virtual

Remove an object to the collection.

This function removes the object from the collection itself, but does not actually delete the object. It simply moves the object to a list of objects to be garbage collected at a later time.

As for Append() full mutual exclusion locking on the collection itself is maintained.

Parameters

  obj | Object to remove from collection

Referenced by PSafeColl< PArray< Base >, Base >::Remove(), and PSafeDictionaryBase< PDictionary< K, D >, K, D >::RemoveAt().

virtual PBoolean PSafeCollection::SafeRemoveAt | ( | PINDEX | idx | ) |
| protected virtual

Remove an object to the collection.

This function removes the object from the collection itself, but does not actually delete the object. It simply moves the object to a list of objects to be garbage collected at a later time.

As for Append() full mutual exclusion locking on the collection itself is maintained.

Parameters

  idx | Object index to remove

Referenced by PSafeColl< PArray< Base >, Base >::RemoveAt().

void PSafeCollection::SafeRemoveObject | ( | PSafeObject * | obj | ) |
| protected

virtual void PSafeCollection::SetAutoDeleteObjects | ( |  | ) |
| virtual

Start a timer to automatically call DeleteObjectsToBeRemoved().

## Member Data Documentation

PCollection* PSafeCollection::collection
| protected

Referenced by PSafeColl< PArray< Base >, Base >::Append(), PSafeColl< PArray< Base >, Base >::FindWithLock(), PSafeColl< PArray< Base >, Base >::operator=(), PSafeDictionaryBase< PDictionary< K, D >, K, D >::operator=(), PSafeColl< PArray< Base >, Base >::PSafeColl(), and PSafeDictionaryBase< PDictionary< K, D >, K, D >::PSafeDictionaryBase().

PMutex PSafeCollection::collectionMutex
| mutable protected

Referenced by PSafeColl< PArray< Base >, Base >::Append(), PSafeDictionaryBase< PDictionary< K, D >, K, D >::Contains(), PSafeColl< PArray< Base >, Base >::FindWithLock(), PSafeDictionaryBase< PDictionary< K, D >, K, D >::FindWithLock(), PSafeDictionaryBase< PDictionary< K, D >, K, D >::GetKeys(), GetMutex(), PSafeColl< PArray< Base >, Base >::operator=(), PSafeDictionaryBase< PDictionary< K, D >, K, D >::operator=(), PSafeColl< PArray< Base >, Base >::PSafeColl(), PSafeDictionaryBase< PDictionary< K, D >, K, D >::PSafeDictionaryBase(), PSafeDictionaryBase< PDictionary< K, D >, K, D >::RemoveAt(), and PSafeDictionaryBase< PDictionary< K, D >, K, D >::SetAt().

bool PSafeCollection::deleteObjects
| protected

Referenced by AllowDeleteObjects(), and DisallowDeleteObjects().

PTimer* PSafeCollection::m_deleteObjectsTimer
| protected

PMutex PSafeCollection::removalMutex
| protected

PList<PSafeObject> PSafeCollection::toBeRemoved
| protected

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

- safecoll.h