Logo Search packages:      
Sourcecode: pwlib version File versions  Download package

PSafeObject Class Reference

#include <safecoll.h>

Inheritance diagram for PSafeObject:


List of all members.

Detailed Description

This class defines a thread-safe 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.

The act of adding a new object is simple and only requires locking the collection itself during the add.

Locating an object is more complicated. The obvious lock on the collection is made for the initial search. But we wish to have the full collection lock for as short a period as possible (for performance reasons) so we lock the individual object and release the lock on the collection.

A simple mutex on the object however is very dangerous as it can be (and should be able to be!) locked from other threads independently of the collection. If one of these threads subsequently needs to get at the collection (eg it wants to remove the object) then we will have a deadlock. Also, to avoid a race condition with the object begin deleted, the objects lock must be made while the collection lock is set. The performance gains are then lost as if something has the object locked for a long time, then another object wanting that object will actually lock the collection for a long time as well.

So, an object has 4 states: unused, referenced, reading & writing. With the additional rider of "being removed". This flag prevents new locks from being acquired and waits for all locks to be relinquished before removing the object from the system. This prevents numerous race conditions and accesses to deleted objects.

The "unused" state indicates the object exists in the collection but no threads anywhere is using it. It may be moved to any state by any thread while in this state. An object cannot be deleted (ie memory deallocated) until it is unused.

The "referenced" state indicates that a thread has a reference (eg pointer) to the object and it should not be deleted. It may be locked for reading or writing at any time thereafter.

The "reading" state is a form of lock that indicates that a thread is reading from the object but not writing. Multiple threads can obtain a read lock. Note the read lock has an implicit "reference" state in it.

The "writing" state is a form of lock where the data in the object may be changed. It can only be obtained exclusively and if there are no read locks present. Again there is an implicit reference state in this lock.

Note that threads going to the "referenced" state may do so regardless of the read or write locks present.

Access to safe objects (especially when in a safe collection) is recommended to by the PSafePtr<> class which will manage reference counting and the automatic unlocking of objects ones the pointer goes out of scope. It may also be used to lock each object of a collection in turn.

The enumeration

Definition at line 157 of file safecoll.h.

Comparison functions

virtual Comparison Compare (const PObject &obj) const
virtual Comparison CompareObjectMemoryDirect (const PObject &obj) const
bool operator!= (const PObject &obj) const
bool operator< (const PObject &obj) const
bool operator<= (const PObject &obj) const
bool operator== (const PObject &obj) const
bool operator> (const PObject &obj) const
bool operator>= (const PObject &obj) const
enum  Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }

Run Time Type functions

virtual const char * GetClass (unsigned=0) const
virtual BOOL InternalIsDescendant (const char *clsName) const
BOOL IsClass (const char *cls) const
static const char * Class ()

I/O functions

virtual void PrintOn (ostream &strm) const
virtual void ReadFrom (istream &strm)
ostream & operator<< (ostream &strm, const PObject &obj)
istream & operator>> (istream &strm, PObject &obj)

Public Member Functions

Miscellaneous functions
virtual PObjectClone () const
virtual PINDEX HashFunction () const
BOOL LockReadOnly () const
BOOL LockReadWrite ()
void SafeDereference ()
BOOL SafelyCanBeDeleted () const
BOOL SafeReference ()
void SafeRemove ()
void UnlockReadOnly () const
void UnlockReadWrite ()
 PSafeObject ()

Protected Attributes

PReadWriteMutex safeInUseFlag
BOOL safelyBeingRemoved
unsigned safeReferenceCount
PMutex safetyMutex

Private Member Functions

 PCLASSINFO (PSafeObject, PObject)

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

Generated by  Doxygen 1.6.0   Back to index