MCLock Class Reference

Provides automatic locking and unlocking based on scope. More...

#include <mcllib/MCLock.h>

Inheritance diagram for MCLock:

List of all members.

Public Member Functions
bool	isLocked () const
	Test to see if the mutex is locked.
void	lock ()
	Lock the mutex.
	MCLock (MCMutex *pMutex, bool locked)
	Construct a lock, optionally locking the provided mutex.
	MCLock (MCMutex *pMutex)
	Construct a lock, locking the provided mutex.
bool	testLock ()
	Test Lock the mutex (which must be derived from MCTestMutex).
void	unlock ()
	Unlock the mutex.
	~MCLock ()
	Unlock the mutex provided at construction if it is locked.

---

Detailed Description

Provides automatic locking and unlocking based on scope.

Lock objects lock a mutex (provided at construction time) and unlock the mutex at destruction. Methods are provided for locking and unlocking the mutex other than at construction/destruction. However the easiest way to use this object is in the automatic mode.

Example.

  class C {
  public:
    void push_back(int i) {
        MCLock lck(&mtx);        // A. Lock the mutex
        l.push_back(i);          // B. Only one thread will do this
    }
  private:
    MCInMutex mtx;
    std::list<int> l;
  }
 

This example shows how the std::list push_back() method can easily be made thread safe (if it isn't in your implementation). At most one thread will be able to execute the push_back() at B. All other threads will be blocked at A. until the thread at B. returns. At this point the MCLock object will be destructed thereby automatically unlocking the mutex. This kind of scoped locking frees the developer from the need to worry about remembering to do an unlock for each lock.

---

Constructor & Destructor Documentation

MCLock (  MCMutex *  pMutex  )

Construct a lock, locking the provided mutex. Parameters: pMutex  a mutex object which cannot be a NULL pointer. pMutex is typically the address of a member variable of an object.

MCLock (  MCMutex *  pMutex, bool  locked )

Construct a lock, optionally locking the provided mutex. Parameters: pMutex  a mutex object which cannot be a NULL pointer. pMutex is typically the address of a member variable of an object. locked  if is true the mutex is locked

~MCLock (   )

Unlock the mutex provided at construction if it is locked. This provides for scoped locking. When the lock object goes out of scope, the mutex is unlocked if it was locked. This prevents mutexes being held onto inadvertently

---

Member Function Documentation

bool isLocked (   )  const

Test to see if the mutex is locked. Returns: true if the mutex is locked.

void lock (   )

Lock the mutex. If the mutex is already locked a fatal exception is thrown. This is indicative of an application programming error. lock() waits indefinitely until the mutex becomes available.

bool testLock (   )

Test Lock the mutex (which must be derived from MCTestMutex). If the mutex can be locked it is locked and testLock() returns true. If the mutex cannot be locked testLock() returns false. Returns: true if the mutex could be locked (and has been locked), false if the mutex could not be locked.

void unlock (   )

Unlock the mutex. If the mutex is already unlocked a fatal exception is thrown. This is indicative of an application programming error. Unlock() typically frees a single thread waiting to lock() the mutex. However, refer to documentation on individual MCMutex derived classes for further details.

---