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

Mutex Class Reference

#include <Mutex.h>

Inheritance diagram for Mutex:

Lockable NonCopyable List of all members.

Public Methods

 Mutex ()
 Create a new Mutex.

virtual ~Mutex () throw ()
 Destroy this Mutex.

virtual void acquire ()
virtual bool tryAcquire (unsigned long)
virtual void release ()

Detailed Description

Author:
Eric Crahen <crahen@cse.buffalo.edu>
Date:
<2002-06-02T08:10:54-0400>
Version:
2.2.1
A Mutex is used to provide serialized (one thread at a time) access to some portion of code. This is accomplished by attempting to acquire() the Mutex before entering that piece of code, and by release()ing the Mutex when leaving that region. It is a non-reentrant, MUTual EXclusion Lockable object.

Using a Mutex requires special care. It is often easy to forget to release() a Mutex after having acquire()ed it. Especially in situations where the flow of execution is not linear because of branching and/or exception. The Guard class is an application of the Scoped Locking pattern which helps to remove this difficulty from multi-threaded code.

See also:
Guard
Scheduling

Threads competing to acquire() a Mutex are granted access in FIFO order.

Error Checking

A Mutex will throw a Deadlock_Exception if an attempt to acquire() a Mutex more than once is made from the context of the same thread.

A Mutex will throw an InvalidOp_Exception if an attempt to release() a Mutex is made from the context of a thread that does not currently own that Mutex.


Member Function Documentation

virtual void acquire   [virtual]
 

Acquire a Mutex, possbily blocking until the the current owner of the Mutex release()es it or until an exception is thrown.

Only one thread may acquire() the Mutex at any given time.

Exceptions:
Interrupted_Exception  thrown when the calling thread is interupt()ed. A thread may be interrupted at any time, prematurely ending any wait.
Deadlock_Exception  thrown when the same thread attempts to acquire() a Mutex more than once, without having first release()ed it.
Precondition:
the calling thread must not have already acquire()ed Mutex
Postcondition:
the calling thread succesfully acquire()ed Mutex only if no exception was thrown.
See also:
Lockable::acquire()

Implements Lockable.

virtual void release   [virtual]
 

Release a Mutex allowing another thread to acquire() it.

see Lockable::release()

Exceptions:
InvalidOp_Exception  - thrown if there is an attempt to release() this Mutex from the context of a thread that had not previously acquire()ed it.
Precondition:
the calling thread must have first acquire()d the Mutex.
Postcondition:
the calling thread succesfully release()d Mutex only if no exception was thrown.
See also:
Lockable::acquire()

Implements Lockable.

virtual bool tryAcquire unsigned    long [virtual]
 

Acquire a Mutex, possbily blocking until the the current owner of the Mutex release()es it, until an exception is thrown or until the given amount of time expires.

Only one thread may acquire() the Mutex at any given time.

Parameters:
timeout  - maximum amount of time (milliseconds) this method could block
Returns :
bool true if the Mutex was acquire()ed before the timeout expired, otherwise false
Exceptions:
Interrupted_Exception  thrown when the calling thread is interupt()ed. A thread may be interrupted at any time, prematurely ending any wait.
Deadlock_Exception  thrown when the same thread attempts to acquire() a Mutex more than once, without having first release()ed it.
Precondition:
the calling thread must not have already acquire()ed Mutex
Postcondition:
the calling thread succesfully acquire()ed Mutex only if no exception was thrown.
See also:
Lockable::tryAcquire(unsigned long)

Implements Lockable.


The documentation for this class was generated from the following file:
Generated on Tue Aug 27 07:43:13 2002 for ZThread by doxygen1.2.17