Home C-Bits Package Documentation Project Page

Main Page   Namespace List   Class Hierarchy   Compound List   File List   Compound Members   File Members  

cbits::ResourceLock Class Reference

A lockable object used to synchronize multithreaded access to sensitive resources. More...

#include <ResourceLock.h>

Inheritance diagram for cbits::ResourceLock:

[legend]
List of all members.

Public Types

enum  LockType { NONE = -1, READ = +1, WRITE = +2 }
 Lock types and states. More...


Public Methods

const bool lock (const LockType)
 Lock the resource. More...

const bool unlock ()
 Release the resource. More...

const bool isLocked () const
 Test if the resource is locked (READ or WRITE). More...

const bool isOwner (const bool lockit=true) const
 Test if this thread owns a lock on the resource. More...

const LockType getLockType () const
 Determine the type of resource lock owned by this thread, if any. More...

virtual ~ResourceLock ()
 Destructor. More...


Static Public Methods

ResourceLock * create ()
 Create a resource lock. More...


Protected Methods

 ResourceLock ()
 Default Constructor. More...

virtual const bool impl_lock_obj () const=0
 Lock a unique, internal, platform-specific 'lock' object. More...

virtual const bool impl_unlock_obj () const=0
 Release the internal lock after the object's state has stablized. More...

virtual const long impl_get_threadid () const=0
 Get platform-specific thread ID. More...

virtual const bool impl_wait_for_event ()=0
 Wait for an event that indicates that another attempt can be made to lock the resource. More...

virtual const bool impl_send_event ()=0
 Emit an event that indicates that the oldes queued thread waiting for the resource can attempt to lock it. More...


Protected Attributes

std::list< long > _queue

Private Methods

const bool get_read_lock ()
 Service a request to READ lock the resource. More...

const bool get_write_lock ()
 Service a request to WRITE lock the resource. More...


Private Attributes

std::set< long > _read_locks
 list of threads with a READ lock. More...

long _write_lock
 ID of the thread that has the WRITE lock (if any). More...


Detailed Description

A lockable object used to synchronize multithreaded access to sensitive resources.

This class supports separate 'read' and 'write' locks. A thread that only requires read access to the resource can acquire a 'read' lock on the resource. Any number of threads can simultaneously hold 'read' locks on the same resource.

A thread that requires 'write' access to the resource should get a 'write' lock. A 'write' lock can only be obtained if no other threads hold a lock of any type (including 'read') on the resource.

A thread can hold not more than one type of lock on a given resource at a time.

See the description of the 'lock()' method for more details.


Member Enumeration Documentation

enum cbits::ResourceLock::LockType
 

Lock types and states.

Enumeration values:
NONE  No lock in effect.
READ  Read lock.
WRITE  Write lock.


Constructor & Destructor Documentation

ResourceLock::~ResourceLock   [virtual]
 

Destructor.

ResourceLock::ResourceLock   [protected]
 

Default Constructor.


Member Function Documentation

ResourceLock * ResourceLock::create   [static]
 

Create a resource lock.

Returns:
pointer to new ResourceLock instance.

const bool ResourceLock::get_read_lock   [private]
 

Service a request to READ lock the resource.

The READ lock will be quickly effected unless there is WRITE lock in effect or a WRITE lock request pending.

const bool ResourceLock::get_write_lock   [private]
 

Service a request to WRITE lock the resource.

The WRITE lock request will be effected as soon as all current READ locks are released.

const ResourceLock::LockType ResourceLock::getLockType   const
 

Determine the type of resource lock owned by this thread, if any.

Returns:
an element of LockType corresponding to the type of lock owned by this thread. If the thread does not own a lock on the resource, a LockType of NONE is returned.

virtual const long cbits::ResourceLock::impl_get_threadid   const [protected, pure virtual]
 

Get platform-specific thread ID.

Returns:
a long value representing this threads ID.

Implemented in cbits::ResourceLock_PTHREAD.

virtual const bool cbits::ResourceLock::impl_lock_obj   const [protected, pure virtual]
 

Lock a unique, internal, platform-specific 'lock' object.

This method is only used by the ResourceLock implementation to protect the object's internal state while it is being changed.

Returns:
true if the object was successfully locked; otherwise, false.

Implemented in cbits::ResourceLock_PTHREAD.

virtual const bool cbits::ResourceLock::impl_send_event   [protected, pure virtual]
 

Emit an event that indicates that the oldes queued thread waiting for the resource can attempt to lock it.

Returns:
true if the thread should try again to lock the resource; false if an error occurred.

Implemented in cbits::ResourceLock_PTHREAD.

virtual const bool cbits::ResourceLock::impl_unlock_obj   const [protected, pure virtual]
 

Release the internal lock after the object's state has stablized.

Returns:
true if the lock was successfully released; otherwise, false.

Implemented in cbits::ResourceLock_PTHREAD.

virtual const bool cbits::ResourceLock::impl_wait_for_event   [protected, pure virtual]
 

Wait for an event that indicates that another attempt can be made to lock the resource.

Returns:
true if the thread should try again to lock the resource; false if an error occurred.

Implemented in cbits::ResourceLock_PTHREAD.

const bool ResourceLock::isLocked   const
 

Test if the resource is locked (READ or WRITE).

Returns:
true if the resource has at least one lock in effect.

const bool ResourceLock::isOwner const bool    lockit = true const
 

Test if this thread owns a lock on the resource.

Returns:
true if this thread owns either a READ or WRITE lock on the resource.
Parameters:
lockit  lock object before checking *

const bool ResourceLock::lock const    LockType
 

Lock the resource.

Any number of READ locks can be acquired on a resource that is not WRITE locked. If a READ lock is requested on a resource that is WRITE locked, this method will block until the WRITE lock is released.

A WRITE lock can only be acquired on a resource that has no locks of any kind in effect. If a WRITE lock is requested on a resource that has either an existing WRITE lock or one or more READ locks, then this method will block until all locks have been released.

If a lock can not be acquired on the resource due to one of the aforementioned conditions, the lock request is queued in a FIFO (and the method will block). Queued lock requests are handled in the order that they are placed on the queue.

A WRITE lock request can not be 'starved' by multiple threads continually requesting READ locks on the resource.

For example: If a thread requests a WRITE lock on a resource that has one or more READ locks in effect, the WRITE lock request will be queued as described above. If another thread then requests a READ lock on the same resource, before the WRITE lock request is effected, the READ lock request will also be queued even though only READ locks are in effect on the resource at the time.

A lock request on a resource that is already owned by the thread is ignored even if the currently held lock is of a different type than the requested lock.

Returns:
true if the resource is successfully locked; otherwise false.
Parameters:
LockType  Level of protection to apply.

const bool ResourceLock::unlock  
 

Release the resource.

If one or more lock requests are pending, the oldest one is serviced.

Returns:
true if the resource is successfully unlocked; otherwise false.


Member Data Documentation

std::list<long> cbits::ResourceLock::_queue [protected]
 

std::set<long> cbits::ResourceLock::_read_locks [private]
 

list of threads with a READ lock.

long cbits::ResourceLock::_write_lock [private]
 

ID of the thread that has the WRITE lock (if any).


The documentation for this class was generated from the following files:
Generated by
doxygen
Hosted by
SourceForge