cbits::ResourceLock Class Reference

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

#include <ResourceLock.h>

Inheritance diagram for cbits::ResourceLock:

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

Hosted by

cbits::ResourceLock Class Reference

Public Types

Public Methods

Static Public Methods

Protected Methods

Protected Attributes

Private Methods

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation