Loki/include/loki/LevelMutex.h

////////////////////////////////////////////////////////////////////////////////
//
// LevelMutex facility for the Loki Library
// Copyright (c) 2008 Richard Sposato
// The copyright on this file is protected under the terms of the MIT license.
//
// Permission to use, copy, modify, distribute and sell this software for any 
// purpose is hereby granted without fee, provided that the above copyright 
// notice appear in all copies and that both that copyright notice and this 
// permission notice appear in supporting documentation.
//
// The author makes no representations about the suitability of this software
// for any purpose. It is provided "as is" without express or implied warranty.
//
////////////////////////////////////////////////////////////////////////////////

// $Id$

/// @file LevelMutex.h Defines classes and functions for LevelMutex facility.

#ifndef LOKI_LEVEL_MUTEX_H_INCLUDED
#define LOKI_LEVEL_MUTEX_H_INCLUDED


// ----------------------------------------------------------------------------

#include <vector>
#include <assert.h>
#include <time.h>

#if defined( _MSC_VER )
    #include <Windows.h>
#else
    #include <pthread.h>
#endif

#if !defined(_WIN32) && !defined(_WIN64)
    #include <unistd.h> // declares sleep under Linux
#endif

/** @par thread_local Keyword
 The mutexes require compilers to provide thread local storage - meaning each
 thread gets its own copy of the data.  The next version of C++ will have a
 new keyword, thread_local for that purpose.  Some existing compilers already
 provide thread local storage using different syntax, so these lines use
 thread_local to mimic that syntax.  If your compiler provides thread local
 storage but using different syntax besides "thread_local", you may want to
 modify these lines.  If your compiler does not support thread local storage,
 you can't use LevelMutex.
 */
#ifndef LOKI_THREAD_LOCAL
    #if defined( _MSC_VER )
        #if ( _MSC_VER >= 1300 )
            #define LOKI_THREAD_LOCAL __declspec( thread )
        #else
            #error "Only Visual Studio versions 7.0 and after supported."
        #endif

    #elif ( __GNUC__ )
        #define LOKI_THREAD_LOCAL __thread

    #else
        #warning "Check if your compiler provides thread local storage."
        #define LOKI_THREAD_LOCAL thread_local
    #endif
#endif

#if defined( DEBUG ) || defined( _DEBUG )
    #define LOKI_MUTEX_DEBUG_CODE( x ) x
#else
    #define LOKI_MUTEX_DEBUG_CODE( x )
#endif


namespace Loki
{


// ----------------------------------------------------------------------------

class MutexErrors
{
public:

    /// @enum Type Possible error conditions detected by LevelMutex functions.
    enum Type
    {
        Success = 0,        ///< Operation occurred correctly.
        NoProblem,          ///< Pre-lock and pre-unlock checks passed.
        WrongLevel,         ///< All mutexes in container must have same level.
        LevelTooLow,        ///< Trying to unlock a mutex lower than current level.
        LevelTooHigh,       ///< Trying to lock a mutex higher than current level.
        TryFailed,          ///< TryLock call failed to lock mutex.
        NullMutexPointer,   ///< Container has a NULL pointer in it.
        DuplicateMutex,     ///< Container must have unique pointers - no duplicates.
        EmptyContainer,     ///< Container must have at least 1 pointer in it.
        AlreadyLocked,      ///< TryLock call failed because mutex already locked.
        WasntLocked,        ///< Unlock failed because mutex was not even locked.
        NotRecentLock,      ///< Mutex in container was not recently locked by this thread.
        NotLockedByThread,  ///< Can't unlock a mutex not locked by this thread.
        MultiUnlockFailed,  ///< MultiUnlock can't unlock at least 1 mutex in container.
        TimedOut,           ///< Wait time elapsed without locking mutex.
        TooMuchRecursion,   ///< Tried to relock a PThread mutex which is not re-entrant.
        NotInitialized,     ///< Tried to lock a PThread mutex which did not get setup.
        AlreadyInitialized, ///< PThread mutex initialized before ctor called.
        InvalidAttribute,   ///< PThread mutex improperly initialized.
        InvalidAddress,     ///< Bad pointer used to initialize a PThread mutex.
        ExceptionThrown,    ///< Exception caught in mutex operation.
        MayDeadlock,        ///< Locking this mutex may cause a deadlock.
        OtherError          ///< Unknown error occurred.
    };
};

// ----------------------------------------------------------------------------

/** @class LevelMutexInfo
 This monolithic base class stores common info for a template class used to
 control mutexes.  The template class, LevelMutex, is policy-based class.

 @par Implementation
 Each thread has a list of mutexes it locked.  When a mutex first gets locked, it
 gets added to the head of the list.  If locked again, LevelMutex merely increments
 a count.  When unlocked, the count gets decremented until it reaches zero, and
 then it gets removed from the list.  Each mutex has a pointer to the mutex most
 recently locked by the current thread.  The current level of a thread is always
 the level of the most recently locked mutex, or UnlockedLevel if the thread does
 not have any mutexes locked now.  A mutex is considered "recently" locked if it is at
 the head of the list, or the same level as the current mutex and also locked by the
 current thread.

 @par Class Invariants
 This class maintains invariants for each LevelMutexInfo so that no function
 calls corrupt a mutex.  Each function makes a call to IsValid at the start so
 that LevelMutex knows it acts on valid internal data.  Many functions call
 IsValid again when they return to insure the function did not leave any data in
 an invalid state.  The exit call to IsValid occurs through a tiny helper class
 called Checker to insure all data remain valid even when exceptions occur.
 Another helper class, MutexUndoer, unlocks mutexes in a container if an
 exception occurs during calls to MultiLock.

 @par Error Results
 Many functions return an enum value to indicate an error status.  Many enum values
 indicate errors detected within LevelMutex, but some indicate errors found in policy
 classes, SpinLevelMutex and SleepLevelMutex.
 */

class LevelMutexInfo
{
public:

    /** Level for thread that has not locked any mutex. Maximum possible level
     for a mutex is UnlockedLevel-1;  No mutex may have a level of UnlockedLevel.
     */
    static const unsigned int UnlockedLevel = 0xFFFFFFFF;

    /// Container for locking multiple mutexes at once.
    typedef ::std::vector< volatile LevelMutexInfo * > MutexContainer;
    typedef MutexContainer::iterator LevelMutexContainerIter;
    typedef MutexContainer::const_iterator LevelMutexContainerCIter;
    typedef MutexContainer::reverse_iterator LevelMutexContainerRIter;
    typedef MutexContainer::const_reverse_iterator LevelMutexContainerCRIter;

    /** Locks several mutexes at once.  Requires O(m + n*n) actions where m is the
     number of mutexes currently locked by the thread and n is the number of mutexes
     in the container. This provides strong exception safety. If an exception occurs,
     any mutexes that were locked during this call will get unlocked.
     @param mutexes Container of pointers to mutexes.  Container must have at
      least 1 mutex, all mutexes must have the same level, no NULL pointers, and all
      mutexes must not exceed the thread's current level.  This sorts the container
      by address order.
     @return Enum value indicating success or error.
     */
    static MutexErrors::Type MultiLock( MutexContainer & mutexes );

    /** Locks several mutexes at once.  Requires O(m + n*n + n*t) actions where m is
     the number of mutexes currently locked by the thread, n is the number of mutexes
     in the container, and t is the wait time for each mutex. This provides strong
     exception safety.  If an exception occurs, any mutexes that were locked during
     this call will ge unlocked.
     @param mutexes Container of pointers to mutexes.  Container must have at
      least 1 mutex, all mutexes must have the same level, no NULL pointers, and all
      mutexes must not exceed the thread's current level.  This sorts the container
      by address order.
     @param milliSeconds Amount of time to wait for each mutex.
     @return Enum value indicating success or error.
     */
    static MutexErrors::Type MultiLock( MutexContainer & mutexes,
        unsigned int milliSeconds );

    /** Unlocks several mutexes at once.  Requires O(m) actions where m is the number of
     mutexes in the container. This provides strong exception safety. If an exception
     occurs when unlocking one mutex, other mutexes in the container get unlocked anyway.
     @param mutexes Container of pointers to mutexes.  Container must have at least 1
      mutex, all mutexes must have the same level, no NULL pointers, and all mutexes must
      be locked by the current thread.  This sorts the container dby address order.
     @return Enum value indicating success or error.
     */
    static MutexErrors::Type MultiUnlock( MutexContainer & mutexes );

    /** Gives pointer to most recently locked mutex, or NULL if nothing locked.
     The pointer is for a const mutex so the mutex can't be modified inappropriately.
     The pointer is for a volatile mutex so callers can call volatile member
     functions to get info about the mutex.
     */
    static const volatile LevelMutexInfo * GetCurrentMutex( void );

    /// Returns the level of this mutex.
    inline unsigned int GetLevel( void ) const volatile { return m_level; }

    /// Returns true if this mutex was locked at least once.
    inline bool IsLocked( void ) const volatile { return ( 0 < m_count ); }

    /// Returns count of how many times this mutex got locked.
    inline unsigned int GetLockCount( void ) const volatile { return m_count; }

    /// Returns pointer to mutex previously locked by the thread which locked this.
    inline const volatile LevelMutexInfo * GetPrevious( void ) const volatile
    {
        return m_previous;
    }

    /** Tries to lock mutex, and returns immediately if mutex already locked by
     another thread.  It will return immediately with a value of AlreadyLocked
     if the mutex was locked by a different thread.  It may throw an exception
     or assert when errors occur if the ErrorPolicy class implements that behavior.
     @return An error condition if any occurred, else Success.
     */
    virtual MutexErrors::Type TryLock( void ) volatile = 0;

    /** Blocking call will attempt to lock mutex and wait until it can lock.
     This may throw an exception if the lock failed or an error occurred - if
     that is what the error policy specifies.
     @return An error condition if any occurred, else Success.
     */
    virtual MutexErrors::Type Lock( void ) volatile = 0;

    /** Attempts to lock mutex, but only waits for a limited amount of time
     before it gives up.  Will return quickly if an error occurs before any
     attempt to lock.  This may throw an exception if the lock failed or an
     error occurred - if that is what the error policy specifies.
     @param milliSeconds How long to wait.
     @return An error condition if any occurred, else Success.
     */
    virtual MutexErrors::Type Lock( unsigned int milliSeconds ) volatile = 0;

    /** Unlocks the mutex, or returns an error condition.  This may throw an
     exception if the lock failed or an error occurred - if that is what the
     error policy specifies.
     @return An error condition if any occurred, else Success.
     */
    virtual MutexErrors::Type Unlock( void ) volatile = 0;

    /** Returns true if this mutex was locked by current thread, and level is the same
     as the current thread's level.  Which means this was the most recently locked
     mutex, or it was locked along with several others of the same level recently.
     */
    bool IsRecentLock( void ) const volatile;

    /** Returns true if this mutex was locked within the last count mutexes.
     @param count How many recent mutexes to look through to find this mutex.
     */
    bool IsRecentLock( unsigned int count ) const volatile;

    /// Returns true if this was locked by current thread.
    bool IsLockedByCurrentThread( void ) const volatile;

    /// Returns true if this was locked by another thread.
    bool IsLockedByAnotherThread( void ) const volatile;

protected:

    /** @class Checker Performs validity check on mutex to insure no class invariants
     were violated inside any member function.  This class only gets used in debug
     builds, and any instance of it gets optimized away in release builds.  A checker
     is created inside many of member functions so that it's destructor gets called
     when the function exits.  It determines if any class invariants were violated
     during the function call.
     */
    class Checker
    {
    public:
        inline explicit Checker( const volatile LevelMutexInfo * mutex ) :
            m_mutex( mutex ) {}
        inline ~Checker( void ) { m_mutex->IsValid(); }
    private:
        Checker( void );
        Checker( const Checker & );
        Checker & operator = ( const Checker & );
        const volatile LevelMutexInfo * m_mutex;
    };

    /** @class MutexUndoer
     Undoes actions by MultiLock if an exception occurs.  It keeps track of
     which mutexes in a container got locked, and if an exception occurs, then
     the destructor unlocks them.  If MultiLock succeeds, then it cancels the
     undoer so nothing gets unlocked inadvertently.
     */
    class MutexUndoer
    {
    public:

        explicit MutexUndoer( MutexContainer & mutexes );
        ~MutexUndoer( void );
        void SetPlace( LevelMutexContainerIter & here );
        void Cancel( void );

    private:

        MutexUndoer( void );
        MutexUndoer( const MutexUndoer & );
        MutexUndoer & operator = ( const MutexUndoer & );

        MutexContainer & m_mutexes;
        LevelMutexContainerIter m_here;
    };

    /** Returns true if linked-list of locked mutexes in this thread is valid.
     Which means the list has no loops, and each previous mutex on the list has a
     higher or same level as the current mutex.  Called by IsValid.
     */
    static bool IsValidList( void );

    /** This is the only available constructor, and it forces any derived class to set
     a level for each mutex.
     */
    explicit LevelMutexInfo( unsigned int level );

    /// The destructor only gets called by the derived class.
    virtual ~LevelMutexInfo( void );

    MutexErrors::Type PreLockCheck( bool forTryLock ) volatile;

    MutexErrors::Type PreUnlockCheck( void ) volatile;

    /** This gets called after each call to DoLock and DoTryLock to make sure the data
     members in this object get set correctly.
     */
    void PostLock( void ) volatile;

    /// Gets called just before an attempt to unlock a mutex.
    void PreUnlock( void ) volatile;

    /// Called to relock a mutex already locked by the current thread.
    void IncrementCount( void ) volatile;

    /// Called to unlock a mutex locked multiple times by the current thread.
    void DecrementCount( void ) volatile;

    /** Returns true if no class invariant broken, otherwise asserts.  This function
    only gets called in debug builds.
     */
    bool IsValid( void ) const volatile;

private:

    /// Copy constructor is not implemented.
    LevelMutexInfo( const LevelMutexInfo & );
    /// Copy-assignment operator is not implemented.
    LevelMutexInfo & operator = ( const LevelMutexInfo & );

    /** Called only by MultiLock & MultiUnlock to pass a result through an
     error checking policy.
     @param result What error condition to check.
     @return Result or assertion or an exception - depending on error policy.
     */
    virtual MutexErrors::Type DoErrorCheck( MutexErrors::Type result ) const volatile = 0;

    /// Called only by MultiLock to Lock each particular mutex within a container.
    virtual MutexErrors::Type LockThis( void ) volatile = 0;

    /** Called only by MultiLock to lock each particular mutex within a container.
     @param milliSeconds How much time to wait before giving up on locking a mutex.
     */
    virtual MutexErrors::Type LockThis( unsigned int milliSeconds ) volatile = 0;

    /// Called only by MultiUnlock to unlock each particular mutex within a container. 
    virtual MutexErrors::Type UnlockThis( void ) volatile = 0;

    /// Pointer to singly-linked list of mutexes locked by the current thread.
    static LOKI_THREAD_LOCAL volatile LevelMutexInfo * s_currentMutex;

    /// Level of this mutex.
    const unsigned int m_level;

    /// How many times this mutex got locked.
    unsigned int m_count;

    /// Pointer to mutex locked before this one.
    volatile LevelMutexInfo * m_previous;

};

// ----------------------------------------------------------------------------

/** @class ThrowOnAnyMutexError
 Implements the ErrorPolicy for LevelMutex and throws an exception for any
 error condition.  Only allows MutexErrors::Success and MutexErrors::NoProblem
 to get through.  Useful for release builds.
 */
class ThrowOnAnyMutexError
{
public:
    static MutexErrors::Type CheckError( MutexErrors::Type error,
        unsigned int level );
};

// ----------------------------------------------------------------------------

/** @class ThrowOnBadDesignMutexError
 Implements the ErrorPolicy for LevelMutex and throws an exception if the error
 indicates the programmer did not levelize the calls to mutexes.  Otherwise
 returns the error result.  Useful for release builds.
 */
class ThrowOnBadDesignMutexError
{
public:
    static MutexErrors::Type CheckError( MutexErrors::Type error,
        unsigned int level );
};

// ----------------------------------------------------------------------------

/** @class AssertAnyMutexError
 Implements the ErrorPolicy for LevelMutex and asserts for any error condition.
 Only allows MutexErrors::Success and MutexErrors::NoProblem to get through.
 Useful for testing mutexes in debug builds.
 */
class AssertAnyMutexError
{
public:
    static inline MutexErrors::Type CheckError( MutexErrors::Type error,
        unsigned int level )
    {
        (void)level;
        assert( ( error == MutexErrors::Success )
             || ( error == MutexErrors::NoProblem ) );
        return error;
    }
};

// ----------------------------------------------------------------------------

/** @class AssertBadDesignMutexError
 Implements the ErrorPolicy for LevelMutex and asserts if the error
 indicates the programmer did not levelize the calls to mutexes.  Otherwise
 returns the error result.  Useful for testing mutexes in debug builds.
 */
class AssertBadDesignMutexError
{
public:
    static inline MutexErrors::Type CheckError( MutexErrors::Type error,
        unsigned int level )
    {
        (void)level;
        assert( ( error != MutexErrors::LevelTooHigh )
             && ( error != MutexErrors::LevelTooLow  ) );
        return error;
    }
};

// ----------------------------------------------------------------------------

/** @class JustReturnMutexError
 Implements the ErrorPolicy for LevelMutex and does nothing no matter how bad
 the error condition.  Only recommended use is for automated unit-testing of
 mutex policies.
 */
class JustReturnMutexError
{
public:
    static inline MutexErrors::Type CheckError( MutexErrors::Type error,
        unsigned int level )
    {
        (void)level;
        return error;
    }
};

// ----------------------------------------------------------------------------

/** @class NoMutexWait
 Implements the WaitPolicy for LevelMutex.  Does nothing at all so it turns
 all wait loops into spin loops.  Useful for low-level mutexes.
 */
class NoMutexWait
{
public:
    static inline void Wait( void ) {}
};

// ----------------------------------------------------------------------------

/** @class MutexSleepWaits
 Implements the WaitPolicy for LevelMutex.  Sleeps for a moment so thread won't
 consume idle CPU cycles.  Useful for high-level mutexes.
 */
class MutexSleepWaits
{
public:
    static void Wait( void );
    static unsigned int sleepTime;
};

// ----------------------------------------------------------------------------

/** @class SpinLevelMutex
 Implements a spin-loop to wait for the mutex to unlock.  Since this class makes
 the thread wait in a tight spin-loop, it can cause the thread to remain busy
 while waiting and thus consume CPU cycles.  For that reason, this mutex is best
 used only for very low-level resources - especially resources which do not
 require much CPU time to exercise.  Rule of thumb: Use this only if all actions
 on the resource consume a very small number of CPU cycles.  Otherwise, use the
 SleepLevelMutex instead.
 */
class SpinLevelMutex
{
public:

    /// Constructs a spin-level mutex.
    explicit SpinLevelMutex( unsigned int level );

    /// Destructs the mutex.
    virtual ~SpinLevelMutex( void );

    virtual MutexErrors::Type Lock( void ) volatile;

    virtual MutexErrors::Type TryLock( void ) volatile;

    virtual MutexErrors::Type Unlock( void ) volatile;

    inline unsigned int GetLevel( void ) const volatile { return m_level; }

private:

    /// Copy constructor is not implemented.
    SpinLevelMutex( const SpinLevelMutex & );
    /// Copy-assignment operator is not implemented.
    SpinLevelMutex & operator = ( const SpinLevelMutex & );

#if defined( _MSC_VER )
    #if ( _MSC_VER >= 1300 )
        /// The actual mutex.
        CRITICAL_SECTION m_mutex;
    #else
        #error "Only Visual Studio versions 7.0 and after supported."
    #endif

#elif ( __GNUC__ )
    /// The actual mutex.
    pthread_mutex_t m_mutex;

#else
    #error "Check if any mutex libraries are compatible with your compiler."
#endif

    /// Keep a copy of the mutex level around for error reporting.
    const unsigned int m_level;

}; // end class SpinLevelMutex

// ----------------------------------------------------------------------------

/** @class SleepLevelMutex
 Implements a sleeping loop to wait for the mutex to unlock.

 @par Purpose
 Since this class puts the thread to sleep for short intervals, you can use this 
 class for most of your mutexes. Especially for locking any high level resources
 where any one operation on the resouce consumes many CPU cycles.  The purpose of
 this mutex is to reduce the number of CPU cycles spent in idle loops.  All
 SleepLevelMutex's should have higher levels than all your SpinLevelMutex's.

 @par Dependence on SpinLevelMutex
 This utilizes SpinLevelMutex so it does not have to re-implement the DoTryLock
 and DoUnlock functions the same way.  All it really needs is a DoLock function
 and the amount of time it should sleep if an attempt to lock a function fails.
 */
class SleepLevelMutex : public SpinLevelMutex
{
public:

    /** Constructs a levelized mutex that puts threads to sleep while they wait
     for another thread to unlock the mutex.
     @param level Level of this mutex.
     */
    explicit SleepLevelMutex( unsigned int level );

    SleepLevelMutex( unsigned int level, unsigned int sleepTime );

    /// Destructs the mutex.
    virtual ~SleepLevelMutex( void );

    inline unsigned int GetSleepTime( void ) const volatile { return m_sleepTime; }

    inline void SetSleepTime( unsigned int sleepTime ) volatile
    {
        if ( 0 != sleepTime )
            m_sleepTime = sleepTime;
    }

#if defined( _MSC_VER )
    inline bool GetWakable( void ) const volatile { return m_wakable; }
    inline void SetWakable( bool wakable ) volatile { m_wakable = wakable; }
#endif

    /** Attempts to lock a mutex, and if it fails, then sleeps for a while
     before attempting again.
     */
    virtual MutexErrors::Type Lock( void ) volatile;

private:

    /// Default constructor is not implemented.
    SleepLevelMutex( void );
    /// Copy constructor is not implemented.
    SleepLevelMutex( const SleepLevelMutex & );
    /// Copy-assignment operator is not implemented.
    SleepLevelMutex & operator = ( const SleepLevelMutex & );

#if defined( _MSC_VER )
    #if ( _MSC_VER >= 1300 )
        /// True if operating system may wake thread to respond to events.
        bool m_wakable;
    #else
        #error "Only Visual Studio versions 7.0 and after supported."
    #endif
#endif

    /// How many milli-seconds to sleep before trying to lock mutex again.
    unsigned int m_sleepTime;

}; // end class SleepLevelMutex

// ----------------------------------------------------------------------------

/** @class LevelMutex
 Levelized mutex class prevents deadlocks by requiring programs to lock mutexes in
 the same order, and unlock them in reverse order.  This is accomplished by forcing
 each mutex to have a level and forcing code to lock mutexes with higher levels
 before locking mutexes at lower levels.  If you want to lock several mutexes, they
 must be locked in decreasing order by level, or if they are all of the same level,
 then locked by LevelMutex::MultiLock.

 @par Features
 - Immune: Very unlikely to deadlock since all mutexes are locked in the same
   order and unlocked in reverse order.
 - Scalable: Can handle any number of mutexes.
 - Efficient: Many operations occur in constant time, and most operations require
   no more than O(m) steps.
 - Exception safe: All operations provide strong safety or don't throw.
 - Extendable: Can work with existing mutexes through policy-based design.
 - Easily Extended: Derived classes only need to implement 5 functions and a mutex
   to get all the features of this class.
 - Re-Entrant: Allows for re-entrancy even if mutexes in policy classes don't.
 - Cost-Free: No resource allocations occur in LevelMutex - although user-defined
   policy classes may allocate resources.
 - Compact: Each LevelMutex object is small.
 - Portable: As long as your compiler and libraries can meet the requirements.
 - Robust: Maintains data integrity even if exceptions occur in policy classes.
 - Affording: Several functions provide information about a mutex which allows
   client code to easily choose correct actions.

 @par Requirements
 - Your compiler must allow for thread-specific data.
 - You must have a threading or mutex library.

 @par Policy-Based Design
 This class hosts 3 policies and a default level.  The policy-based design allows
 users to write their own policies to extend the behaviors of LevelMutex.  The
 paragraphs below say how to design a class for each policy.
 - MutexPolicy The mutex policy class.
 - defaultLevel A level for existing client code that calls a default constructor.
 - ErrorPolicy How the mutex should handle error conditions.
 - WaitPolicy Whether a thread should wait, and how long in some internal loops.

 @par MutexPolicy
 A policy class that wraps a low-level mutex. Loki provides two policy classes
 for the actual mutex (SpinLevelMutex and SleepLevelMutex), both of which wrap
 either pthreads or the Windows CRITICAL_SECTION. If you want to use a mutex
 mechanism besides one of those, then all you have to do is provide a class
 which wraps the mutex and implements these functions.
    explicit SpinLevelMutex( unsigned int level );
    virtual ~SpinLevelMutex( void );
    virtual MutexErrors::Type Lock( void ) volatile;
    virtual MutexErrors::Type TryLock( void ) volatile;
    virtual MutexErrors::Type Unlock( void ) volatile;
 Indeed, since the base class does most of the work, and provides all the interace
 and functionality to client classes, a derived class has very few requirements.
 It only needs to implement a single constructor, the destructor, some virtual
 functions, and whatever data members it requires.  You don't actually need to
 declare those functions as virtual if the policy class is not a base or child
 class.  In the parlance of design patterns, LevelMutex is a Template, and the
 MutexPolicy is a Strategy.

 @par DefaultLevel
 The template class requires a default level to use inside the default constructor.
 Some existing code calls instantiates mutexes with a default constructor, so the
 mutex must know what level to use there.  Please do not use zero or UnlockedLevel
 as the default level.

 @par ErrorPolicy
 This policy specifies how to handle error conditions.  The mutexes can return
 errors, assert, or throw exceptions.  I recommend that debug code use asserts,
 release code use exceptions, and unit-testing code just return errors.  The
 error policy class only needs to implement one function:
   static MutexErrors::Type CheckError( MutexErrors::Type error, unsigned int level );

 @par WaitPolicy
 This states whether the mutex should wait within some tight internal loops,
 how the waiting is done, and for how long.  A wait policy class could sleep,
 do nothing, check if other objects need attention, or check if the program
 received events or notices from the operating system.  It only needs to
 implement one function:
   static void Wait( void );

 @par Per-Function Usage
 If you implement a function with a static local mutex, then you have to insure
 the function is not called from a lower level via call-backs, virtual functions in
 interface classes.  If the function does get called from a lower level, you are
 setting up a potential deadlock.  LevelMutex will detect that by checking the
 current level and the local mutex's level, so it will refuse to lock the local mutex.

 @par Per-Object Usage
 If you use a mutex as a data member of an object to protect that object, then I
 recommend specifying which functions are volatile and which are not, and then only
 use the mutex within the volatile functions.  You may also want to provide accessor
 functions so that client code can lock and unlock the mutex either to allow for
 calling multiple operations without having to lock and unlock before and after each
 operation, or so they can lock it along with several other objects at the same
 level.

 @par Per-Class Usage
 If you make a static data member within a class, you can use that to lock any
 resources shared by those objects, or to require threads to act on only one object
 at a time.  You may also want to provide static accessor functions so that client
 code can lock several other resources at the same level.
 */

template
<
    class MutexPolicy,
    unsigned int DefaultLevel,
    class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError,
    class WaitPolicy  = ::Loki::NoMutexWait
>
class LevelMutex : public LevelMutexInfo
{
public:

    typedef ErrorPolicy EP;
    typedef WaitPolicy  WP;
    typedef MutexPolicy MP;

    /** This constructor allows callers to replace the default level with another
     value.  It also acts as the default constructor for existing code which uses
     default construction for mutexes.  This is the only time the DefaultLevel
     template parameter gets used.
     */
    explicit LevelMutex( unsigned int level = DefaultLevel ) :
        LevelMutexInfo( level ),
        m_mutex( level )
    {
        assert( IsValid() );
    }

    /// The destructor.
    ~LevelMutex( void )
    {
        assert( IsValid() );
    }

    /** These functions allow callers to access the mutex in case they need to
     modify specific values in the MutexPolicy (e.g. - sleep time, functors to
     call as tasks, etc...)  There is one function for every combination of
     const and volatile qualifiers so callers get a reference to a MutexPolicy
     with the proper qualifiers.
     */
    inline const volatile MutexPolicy & GetMutexPolicy( void ) const volatile { return m_mutex; }
    inline       volatile MutexPolicy & GetMutexPolicy( void )       volatile { return m_mutex; }
    inline const          MutexPolicy & GetMutexPolicy( void ) const          { return m_mutex; }
    inline                MutexPolicy & GetMutexPolicy( void )                { return m_mutex; }

    virtual MutexErrors::Type TryLock( void ) volatile
    {
        assert( IsValid() );
        LOKI_MUTEX_DEBUG_CODE( Checker checker( this ); (void)checker; )

        MutexErrors::Type result = LevelMutexInfo::PreLockCheck( true );
        if ( MutexErrors::Success == result )
            return MutexErrors::Success;
        else if ( MutexErrors::AlreadyLocked == result )
            return result;
        else if ( MutexErrors::NoProblem != result )
            return EP::CheckError( result, GetLevel() );

        assert( 0 == LevelMutexInfo::GetLockCount() );
        result = m_mutex.TryLock();
        if ( MutexErrors::Success != result )
            return EP::CheckError( result, GetLevel() );
        LevelMutexInfo::PostLock();

        return MutexErrors::Success;
    }

    virtual MutexErrors::Type Lock( void ) volatile
    {
        assert( IsValid() );
        LOKI_MUTEX_DEBUG_CODE( Checker checker( this ); (void)checker; )

        MutexErrors::Type result = LevelMutexInfo::PreLockCheck( false );
        if ( MutexErrors::Success == result )
            return MutexErrors::Success;
        else if ( MutexErrors::NoProblem != result )
            return EP::CheckError( result, GetLevel() );

        assert( !LevelMutexInfo::IsLockedByCurrentThread() );
        result = m_mutex.Lock();
        if ( MutexErrors::Success != result )
            return EP::CheckError( result, GetLevel() );
        PostLock();

        return MutexErrors::Success;
    }

    virtual MutexErrors::Type Lock( unsigned int milliSeconds ) volatile
    {
        assert( IsValid() );
        LOKI_MUTEX_DEBUG_CODE( Checker checker( this ); (void)checker; )

        MutexErrors::Type result = LevelMutexInfo::PreLockCheck( false );
        if ( MutexErrors::Success == result )
            return MutexErrors::Success;
        else if ( MutexErrors::NoProblem != result )
            return EP::CheckError( result, GetLevel() );

        assert( !LevelMutexInfo::IsLockedByCurrentThread() );
        clock_t timeOut = clock() + milliSeconds;
        while ( clock() < timeOut )
        {
            WP::Wait();
            result = m_mutex.TryLock();
            switch ( result )
            {
                case MutexErrors::Success:
                {
                    PostLock();
                    return MutexErrors::Success;
                }
                case MutexErrors::AlreadyLocked:
                    return MutexErrors::AlreadyLocked;
                case MutexErrors::TryFailed:
                    break;
                default:
                    return EP::CheckError( result, GetLevel() );
            }
        }

        return MutexErrors::TimedOut;
    }

    virtual MutexErrors::Type Unlock( void ) volatile
    {
        assert( IsValid() );
        LOKI_MUTEX_DEBUG_CODE( Checker checker( this ); (void)checker; )

        MutexErrors::Type result = LevelMutexInfo::PreUnlockCheck();
        if ( MutexErrors::Success == result )
            return MutexErrors::Success;
        else if ( MutexErrors::NoProblem != result )
            return EP::CheckError( result, GetLevel() );

        LevelMutexInfo::PreUnlock();
        result = MutexErrors::OtherError;
        try
        {
            result = m_mutex.Unlock();
            if ( MutexErrors::Success != result )
                PostLock();
        }
        catch ( ... )
        {
            PostLock();
            result = MutexErrors::ExceptionThrown;
        }

        return result;
    }

private:

    /// Copy constructor is not implemented since mutexes don't get copied.
    LevelMutex( const LevelMutex & );
    /// Copy-assignment operator is not implemented since mutexes don't get copied.
    LevelMutex & operator = ( const LevelMutex & );

    virtual MutexErrors::Type DoErrorCheck( MutexErrors::Type result ) const volatile
    {
        return EP::CheckError( result, GetLevel() );
    }

    /** Called only by MultiLock to lock each particular mutex within a container.
     This does not do pre-lock error checking since MultiLock does that.  Since
     this skips the error checking, that means that callers of LevelMutex should
     not call this function directly, and so this will not be publicly available.
     @return Error status indicating success or reason for failure.
     */
    virtual MutexErrors::Type LockThis( void ) volatile
    {
        assert( IsValid() );
        LOKI_MUTEX_DEBUG_CODE( Checker checker( this ); (void)checker; )
        assert( this != LevelMutexInfo::GetCurrentMutex() );

        const MutexErrors::Type result = m_mutex.Lock();
        if ( MutexErrors::Success != result )
            return result;
        PostLock();

        return MutexErrors::Success;
    }

    /** Called only by MultiLock to lock each particular mutex within a container.
     This does not do pre-lock error checking since MultiLock does that.  Since
     this skips the error checking, callers of LevelMutex should not call this
     function directly, and so this will not be publicly available.
     @param milliSeconds How much time to wait before giving up on locking a mutex.
     @return Error status indicating success or reason for failure.
     */
    virtual MutexErrors::Type LockThis( unsigned int milliSeconds ) volatile
    {
        assert( IsValid() );
        LOKI_MUTEX_DEBUG_CODE( Checker checker( this ); (void)checker; )

        clock_t timeOut = clock() + milliSeconds;
        while ( clock() < timeOut )
        {
            WP::Wait();
            const bool locked = ( MutexErrors::Success == m_mutex.TryLock() );
            if ( locked )
            {
                PostLock();
                return MutexErrors::Success;
            }
        }

        return MutexErrors::TimedOut;
    }

    /** Called only by MultiUnlock to unlock each mutex within a container.
     This does not do pre-unlock error checking since MultiLock does that.  Since
     this skips the error checking, callers of LevelMutex should not call this
     function directly, and so this will not be publicly available.
     @return Error status indicating success or reason for failure.
     */
    virtual MutexErrors::Type UnlockThis( void ) volatile
    {
        assert( IsValid() );
        assert( NULL != LevelMutexInfo::GetCurrentMutex() );
        LOKI_MUTEX_DEBUG_CODE( Checker checker( this ); (void)checker; )

        if ( 1 < LevelMutexInfo::GetLockCount() )
        {
            LevelMutexInfo::DecrementCount();
            return MutexErrors::Success;
        }

        LevelMutexInfo::PreUnlock();
        MutexErrors::Type result = m_mutex.Unlock();

        return result;
    }

    /// An instance of an unleveled mutex wrapped to match LevelMutex's needs.
    MutexPolicy m_mutex;

}; // end class LevelMutex

// ----------------------------------------------------------------------------

/** Returns level of most recently locked mutex by this thread, or UnlockedLevel
 if no mutexes are locked.  Runs in constant time, and never throws exceptions.
 */
unsigned int GetCurrentThreadsLevel( void );

/** Returns count of how mutexes the current thread locked.  Requires O(m)
 actions where m is the number of mutexes in the thread.  Never throws exceptions.
 */
unsigned int CountMutexesInCurrentThread( void );

/** Returns count of how mutexes the current thread locked.  The lock count
 exceeds the number of mutexes locked by current thread if any mutex got locked
 more than once.  Requires O(m) actions where m is the number of mutexes in the
 thread.  Never throws exceptions.
 */
unsigned int CountLocksInCurrentThread( void );

/** Returns count of mutexes locked by current thread which have the same level
 as GetCurrentThreadsLevel.  Requires O(m) actions where m is the number of
 mutexes in the thread at current level.  Never throws exceptions.
 */
unsigned int CountMutexesAtCurrentLevel( void );

/** Determines if container of mutexes matches the recently locked mutexes.
 If they do match, it returns success, otherwise an error condition.
 */
MutexErrors::Type DoMutexesMatchContainer( const LevelMutexInfo::MutexContainer & mutexes );

// ----------------------------------------------------------------------------

/** @class MutexException
 Exception class used to throw error statuses about LevelMutex's up to code that
 can respond to mutex problems.  This class exists because it conveys more info
 about the error condition than just ::std::exception.
 */
class MutexException : public ::std::exception
{
public:

    /** Constructs an exception which stores information about a mutex and the
     reason an attempt to use a mutex failed.
     */
    MutexException( const char * message, unsigned int level, MutexErrors::Type reason );

    /// Copy constructor performs a member-by-member copy of an exception.
    MutexException( const MutexException & that ) throw ();

    /// Copy-assignment operator performs a member-by-member copy of an exception.
    MutexException & operator = ( const MutexException & that ) throw ();

    /// Destroys the exception.
    virtual ~MutexException( void ) throw();

    /// Returns a simple message about which operation failed.
    virtual const char * what( void ) const throw();

    /// Returns level of mutex(es) used when problem occurred.
    unsigned int GetLevel( void ) const { return m_level; }

    /// Returns an error status for why operation failed.
    MutexErrors::Type GetReason( void ) const { return m_reason; }

private:

    /// Default constructor is not implemented.
    MutexException( void ) throw ();

    /// Simple message about operation that failed.
    const char * m_message;
    /// Level of mutex(es) used when problem occurred.
    unsigned int m_level;
    /// Error status for why operation failed.
    MutexErrors::Type m_reason;

}; // end class MutexException

// ----------------------------------------------------------------------------

/** @class MutexLocker
 You can place an instance of this as a local variable inside a function to lock
 a single mutex.  It will lock the mutex if no error occurs, or throw if one
 does happen.  When the function ends, the destructor will determine if it needs
 to unlock the mutex.  This RAII technique insures the mutex gets unlocked even
 when exceptions occur.
 */
class MutexLocker
{
public:

    /** Creates an object to lock an unlock a mutex for a function.  This
     will throw if an attempt to lock the mutex fails.
     @param mutex Reference to the mutex.
     @param lock True if function wants to lock the mutex as this gets
      constructed.
     */
    explicit MutexLocker( volatile LevelMutexInfo & mutex, bool lock = true );

    /** Creates an object to lock an unlock a mutex for a function.  This waits
     a specified amount of time for another thread to unlock the mutex if it is
     locked.  This will throw if an attempt to lock the mutex fails.
     @param mutex Reference to the mutex.
     @param milliSeconds Amount of time to wait for another thread to unlock
      the mutex.
     @param lock True if function wants to lock the mutex as this gets
      constructed.
     */
    MutexLocker( volatile LevelMutexInfo & mutex, unsigned int milliSeconds,
        bool lock = true );

    /// Destructs the locker, and determines if it needs to unlock the mutex.
    ~MutexLocker( void );

    /** You can call this to lock (or relock) a mutex.  In theory, you can lock
     and unlock a mutex several times within a function in order to give other
     threads access to a resource while this function does not need it.
     @return True if mutex is locked by this, else false if not locked.
     */
    bool Lock( void );

    /** You can call this to unlock a mutex before the destructor does it.
     By unlocking the mutexes before returning, the function can do other
     operations without making other threads wait too long.
     @return True if unlocked by this, else false if not unlocked by this.
     (Which is not the same as whether the mutex itself is locked or not by
     another thread.)
     */
    bool Unlock( void );

    /// Returns true if the mutex is locked by this object.
    inline bool IsLocked( void ) const { return m_locked; }

    /// Provides access to mutex controlled by this. 
    const volatile LevelMutexInfo & GetMutex( void ) const { return m_mutex; }

private:

    /// Default constructor is not implemented.
    MutexLocker( void );
    /// Copy constructor is not implemented.
    MutexLocker( const MutexLocker & );
    /// Copy-assignment operator is not implemented.
    MutexLocker & operator = ( const MutexLocker & );

    /// True if mutex got locked.
    bool m_locked;

    /// Reference to mutex.
    volatile LevelMutexInfo & m_mutex;
};

// ----------------------------------------------------------------------------

/** @class MultiMutexLocker
 You can place an instance of this as a local variable inside a function to lock
 a collection of mutexes.  It locks them if no error occurs, or throws an
 exception if one does happen.  When the function ends, the destructor determines
 if it needs to unlock the mutexes.  This RAII technique insures the mutexes get
 unlocked even when exceptions occur.  You will also have to construct a
 MutexContainer as a local object within the same function.
 */
class MultiMutexLocker
{
public:

    /** Creates an object to lock and unlock a collection of mutexes for a function.
     This will throw if an attempt to lock any mutex fails. If an exception occurs,
     it unlocks mutexes it previously locked.
     @param mutex Reference to a collection of mutexes.
     @param lock True if function wants to lock the mutex as this gets
      constructed.
     */
    explicit MultiMutexLocker( LevelMutexInfo::MutexContainer & mutexes,
        bool lock = true );

    /** Creates an object to lock and unlock a collection of mutexes for a function.
     This waits a specified amount of time for other threads to unlock each mutex
     that is locked.  This will throw if an attempt to lock any mutex fails. If an
     exception occurs, it unlocks mutexes it previously locked.
     @param mutexes Reference to a collection of mutexes.
     @param milliSeconds Amount of time to wait for another thread to unlock
      the mutex.
     @param lock True if function wants to lock the mutexes as this gets
      constructed.
     */
    MultiMutexLocker( LevelMutexInfo::MutexContainer & mutexes,
        unsigned int milliSeconds, bool lock = true );

    /// Destructs the locker, and determines if it needs to unlock the mutexes.
    ~MultiMutexLocker( void );

    /** You can call this to lock (or relock) the mutexes.  In theory, you can lock
     and unlock mutexes several times within a function in order to give other
     threads access to resources while this function does not need them.
     @return True if mutex is locked by this, else false if not locked.
     */
    bool Lock( void );

    /** You can call this to unlock the mutexes before the destructor does it.
     By unlocking the mutexes before returning, the function can do other
     operations without making other threads wait too long.
     @return True if unlocked by this, else false if not unlocked by this.
     (Which is not the same as whether the mutex itself is locked or not by
     another thread.)
     */
    bool Unlock( void );

    /// Returns true if the mutexes are locked by this object.
    inline bool IsLocked( void ) const { return m_locked; }

    /// Provides access to the collection of mutexes controlled by this. 
    const LevelMutexInfo::MutexContainer & GetMutexes( void ) const { return m_mutexes; }

private:

    /// Default constructor is not implemented.
    MultiMutexLocker( void );
    /// Copy constructor is not implemented.
    MultiMutexLocker( const MultiMutexLocker & );
    /// Copy-assignment operator is not implemented.
    MultiMutexLocker & operator = ( const MultiMutexLocker & );

    /// True if mutexes got locked.
    bool m_locked;

    /// Reference to external container of mutexes;
    LevelMutexInfo::MutexContainer & m_mutexes;
};

// ----------------------------------------------------------------------------

} // end namespace Loki

#endif  // end file guardian