AutoLock.h revision cdd02359ba9ceffb2e9bd104a572ad1130091f44
/** @file
*
* AutoLock: smart critical section wrapper
*/
/*
* Copyright (C) 2006-2008 innotek GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*/
#ifndef ____H_AUTOLOCK
#define ____H_AUTOLOCK
#include <iprt/critsect.h>
#include <iprt/semaphore.h>
#if defined(DEBUG)
#endif
{
/**
* Abstract lock operations. See LockHandle and AutoLock for details.
*/
{
};
/**
* Read lock operations. See LockHandle and AutoLock for details.
*/
{
/**
* Requests a read (shared) lock.
*/
/**
* Releases a read (shared) lock ackquired by lockRead().
*/
virtual void unlockRead() = 0;
// LockOps interface
void unlock() { unlockRead(); }
};
/**
* Write lock operations. See LockHandle and AutoLock for details.
*/
{
/**
* Requests a write (exclusive) lock.
*/
/**
* Releases a write (exclusive) lock ackquired by lockWrite().
*/
virtual void unlockWrite() = 0;
// LockOps interface
void unlock() { unlockWrite(); }
};
/**
*
* Subclasses must implement all pure virtual methods of this class together
* with pure methods of ReadLockOps and WriteLockOps classes.
*
* See the AutoLock class documentation for the detailed description of read and
* write locks.
*/
{
LockHandle() {}
virtual ~LockHandle() {}
/**
* Returns @c true if the current thread holds a write lock on this
*/
virtual bool isLockedOnCurrentThread() const = 0;
/**
* Returns the current write lock level of this semaphore. The lock level
* determines the number of nested #lock() calls on the given semaphore
* handle.
*
* Note that this call is valid only when the current thread owns a write
* lock on the given semaphore handle and will assert otherwise.
*/
/**
* Returns an interface to read lock operations of this semaphore.
* Used by constructors of AutoMultiLockN classes.
*/
/**
* Returns an interface to write lock operations of this semaphore.
* Used by constructors of AutoMultiLockN classes.
*/
};
/**
*
* This is an auxiliary base class for classes that need full-featured
* Instances of classes inherited from this class can be passed as arguments to
* the AutoLock and AutoReaderLock constructors.
*/
{
RWLockHandle();
virtual ~RWLockHandle();
bool isLockedOnCurrentThread() const;
void lockWrite();
void unlockWrite();
void lockRead();
void unlockRead();
uint32_t writeLockLevel() const;
};
/**
* Write-only semaphore handle implementation.
*
* This is an auxiliary base class for classes that need write-only (exclusive)
* locking and do not need read (shared) locking. This implementation uses a
* cheap and fast critical section for both lockWrite() and lockRead() methods
* which makes a lockRead() call fully equivalent to the lockWrite() call and
* therefore makes it pointless to use instahces of this class with
* AutoReaderLock instances -- shared locking will not be possible anyway and
* any call to lock() will block if there are lock owners on other threads.
*
* Use with care only when absolutely sure that shared locks are not necessary.
*/
{
{
}
{
}
bool isLockedOnCurrentThread() const
{
return RTCritSectIsOwner (&mCritSect);
}
void lockWrite()
{
#if defined(DEBUG)
"WriteLockHandle::lockWrite() return address >>>",
0, (RTUINTPTR) ASMReturnAddress());
#else
#endif
}
void unlockWrite()
{
}
void unlockRead() { unlockWrite(); }
uint32_t writeLockLevel() const
{
return RTCritSectGetRecursion (&mCritSect);
}
};
/**
* Lockable interface.
*
* class data, this class allows subclasses to decide which semaphore handle to
* use.
*/
{
/**
* Returns a pointer to a LockHandle used by AutoLock/AutoReaderLock for
* locking. Subclasses are allowed to return @c NULL -- in this case,
* the AutoLock/AutoReaderLock object constructed using an instance of
* such subclass will simply turn into no-op.
*/
/**
* Equivalent to <tt>#lockHandle()->isLockedOnCurrentThread()</tt>.
* Returns @c false if lockHandle() returns @c NULL.
*/
bool isLockedOnCurrentThread()
{
LockHandle *h = lockHandle();
return h ? h->isLockedOnCurrentThread() : false;
}
/**
* Equivalent to <tt>#lockHandle()->rlock()</tt>.
* Returns @c NULL false if lockHandle() returns @c NULL.
*/
{
LockHandle *h = lockHandle();
}
/**
* Equivalent to <tt>#lockHandle()->wlock()</tt>. Returns @c NULL false if
* lockHandle() returns @c NULL.
*/
{
LockHandle *h = lockHandle();
}
};
/**
*
* can be requested ("locked") in two different modes: for reading and for
* writing. A write lock is exclusive and acts like a mutex: only one thread can
* acquire a write lock on the given semaphore at a time; all other threads
* trying to request a write lock or a read lock (see below) on the same
* semaphore will be indefinitely blocked until the owning thread releases the
* write lock.
*
* A read lock is shared. This means that several threads can acquire a read
* lock on the same semaphore at the same time provided that there is no thread
* that holds a write lock on that semaphore. Note that when there are one or
* more threads holding read locks, a request for a write lock on another thread
* will be indefinitely blocked until all threads holding read locks release
* them.
*
* Note that write locks can be nested -- the same thread can request a write
* lock on the same semaphore several times. In this case, the corresponding
* number of release calls must be done in order to completely release all
* nested write locks and make the semaphore available for locking by other
* threads.
*
* Read locks can be nested too in which case the same rule of the equal number
* of the release calls applies. Read locks can be also nested into write
* locks which means that the same thread can successfully request a read lock
* if it already holds a write lock. However, please note that the opposite is
* <b>not possible</b>: if a thread tries to request a write lock on the same
* semaphore it is already holding a read lock, it will definitely produce a
* <b>deadlock</b> (i.e. it will block forever waiting for itself).
*
* semaphores only. In order to manage read locks, please use the AutoReaderLock
* class.
*
* Safe semaphore management consists of the following:
* <ul>
* <li>When an instance of the AutoLock class is constructed given a valid
* semaphore handle, it will automatically request a write lock on that
* semaphore.
* </li>
* <li>When an instance of the AutoLock class constructed given a valid
* semaphore handle is destroyed (e.g. goes out of scope), it will
* automatically release the write lock that was requested upon construction
* and also all nested write locks requested later using the #lock() call
* (note that the latter is considered to be a program logic error, see the
* #~AutoLock() description for details).
* </li>
* </ul>
*
* Note that the LockHandle class taken by AutoLock constructors is an abstract
* subclasses of this abstract class or create your own subclass that implements
* necessary read and write lock semantics. The most suitable choice is the
* RWLockHandle class which provides full support for both read and write locks
* as describerd above. Alternatively, you can use the WriteLockHandle class if
* you only need write (exclusive) locking (WriteLockHandle requires less system
* resources and works faster).
*
* A typical usage pattern of the AutoLock class is as follows:
* <code>
* struct Struct : public RWLockHandle
* {
* ...
* };
*
* void foo (Struct &aStruct)
* {
* {
* // acquire a write lock of aStruct
* AutoLock alock (aStruct);
*
* // now we can modify aStruct in a thread-safe manner
* aStruct.foo = ...;
*
* // note that the write lock will be automatically released upon
* // execution of the return statement below
* if (!aStruct.bar)
* return;
*
* ...
* }
*
* // note that the write lock is automatically released here
* }
* </code>
*
* <b>Locking policy</b>
*
* When there are multiple threads and multiple objects to lock, there is always
* a potential possibility to produce a deadlock if the lock order is mixed up.
* Here is a classical example of a deadlock when two threads need to lock the
* same two objects in a row but do it in different order:
* <code>
* Thread 1:
* #1: AutoLock (mFoo);
* ...
* #2: AutoLock (mBar);
* ...
* Thread 2:
* #3: AutoLock (mBar);
* ...
* #4: AutoLock (mFoo);
* ...
* </code>
*
* If the threads happen to be scheduled so that #3 completes after #1 has
* completed but before #2 got control, the threads will hit a deadlock: Thread
* 2 will be holding mBar and waiting for mFoo at #4 forever because Thread 1 is
* holding mFoo and won't release it until it acquires mBar at #2 that will
* never happen because mBar is held by Thread 2.
*
* One of ways to avoid the described behavior is to never lock more than one
* obhect in a row. While it is definitely a good and safe practice, it's not
* always possible: the application logic may require several simultaneous locks
* in order to provide data integrity.
*
* One of the possibilities to solve the deadlock problem is to make sure that
* the locking order is always the same across the application. In the above
* example, it would mean that <b>both</b> threads should first requiest a lock
* of mFoo and then mBar (or vice versa). One of the methods to guarantee the
* locking order consistent is to introduce a set of locking rules. The
* advantage of this method is that it doesn't require any special semaphore
* implementation or additional control structures. The disadvantage is that
* it's the programmer who must make sure these rules are obeyed across the
* whole application so the human factor applies. Taking the simplicity of this
* method into account, it is chosen to solve potential deadlock problems when
* using AutoLock and AutoReaderLock classes. Here are the locking rules that
* must be obeyed by <b>all</b> users of these classes. Note that if more than
* one rule matches the given group of objects to lock, all of these rules must
* be met:
* <ol>
* <li>If there is a parent-child (or master-slave) relationship between the
* locked objects, parent (master) objects must be locked before child
* (slave) objects.
* </li>
* <li>When a group of equal objects (in terms of parent-child or
* master-slave relationsip) needs to be locked in a raw, the lock order
* must match the sort order (which must be consistent for the given group).
* </ol>
* Note that if there is no pragrammatically expressed sort order (e.g.
* the objects are not part of the sorted vector or list but instead are
* separate data members of a class), object class names sorted in alphabetical
* order must be used to determine the lock order. If there is more than one
* object of the given class, the object variable names' alphabetical order must
* be used as a lock order. When objects are not represented as individual
* sorted object UUIDs must be used to determine the sort order.
*
* All non-standard locking order must be avoided by all means, but when
* absolutely necessary, it must be clearly documented at relevant places so it
* is well seen by other developers. For example, if a set of instances of some
* class needs to be locked but these instances are not part of the sorted list
* and don't have UUIDs, then the class description must state what to use to
* determine the lock order (maybe some property that returns an unique value
* per every object).
*/
{
/**
* semaphore.
*
* Note that all method calls on a null instance are no-ops. This allows to
* have the code where lock protection can be selected (or omitted) at
* runtime.
*/
/**
* semaphore by requesting a write lock.
*/
{ lock(); }
/**
* semaphore by requesting a write lock.
*/
{ lock(); }
/**
* semaphore by requesting a write lock.
*/
{ lock(); }
/**
* semaphore by requesting a write lock.
*/
, mLockLevel (0), mGlobalLockLevel (0)
{ lock(); }
/**
* Release all write locks acquired by this instance through the #lock()
* call and destroys the instance.
*
* Note that if there there are nested #lock() calls without the
* corresponding number of #unlock() calls when the destructor is called, it
* will assert. This is because having an unbalanced number of nested locks
* is a program logic error which must be fixed.
*/
~AutoLock()
{
if (mHandle)
{
if (mGlobalLockLevel)
{
mLockLevel = 0;
for (; mGlobalLockLevel; -- mGlobalLockLevel)
}
for (; mLockLevel; -- mLockLevel)
mHandle->unlockWrite();
}
}
/**
* Requests a write (exclusive) lock. If a write lock is already owned by
* this thread, increases the lock level (allowing for nested write locks on
* the same thread). Blocks indefinitely if a write lock or a read lock is
* already owned by another thread until that tread releases the locks,
* otherwise returns immediately.
*/
void lock()
{
if (mHandle)
{
++ mLockLevel;
}
}
/**
* Decreases the write lock level increased by #lock(). If the level drops
* to zero (e.g. the number of nested #unlock() calls matches the number of
* nested #lock() calls), releases the lock making the managed semaphore
* available for locking by other threads.
*/
void unlock()
{
if (mHandle)
{
mHandle->unlockWrite();
-- mLockLevel;
}
}
/**
* Causes the current thread to completely release the write lock to make
* the managed semaphore immediately available for locking by other threads.
*
* This implies that all nested write locks on the semaphore will be
* released, even those that were acquired through the calls to #lock()
* methods of all other AutoLock/AutoReaderLock instances managing the
*
* After calling this method, the only method you are allowed to call is
* #enter(). It will acquire the write lock again and restore the same
* level of nesting as it had before calling #leave().
*
* If this instance is destroyed without calling #enter(), the destructor
* will try to restore the write lock level that existed when #leave() was
* called minus the number of nested #lock() calls made on this instance
* itself. This is done to preserve lock levels of other
* AutoLock/AutoReaderLock instances managing the same semaphore (if any).
* Tiis also means that the destructor may indefinitely block if a write or
* a read lock is owned by some other thread by that time.
*/
void leave()
{
if (mHandle)
{
mHandle->unlockWrite();
}
}
/**
* Causes the current thread to restore the write lock level after the
* #leave() call. This call will indefinitely block if another thread has
* successfully acquired a write or a read lock on the same semaphore in
* between.
*/
void enter()
{
if (mHandle)
{
for (; mGlobalLockLevel; -- mGlobalLockLevel)
}
}
/** Returns @c true if this instance manages a null semaphore handle. */
/**
* Returns @c true if the current thread holds a write lock on the managed
* NULL.
*
* @note Intended for debugging only.
*/
bool isLockedOnCurrentThread() const
{
}
/**
* Returns the current write lock level of the managed smaphore. The lock
* level determines the number of nested #lock() calls on the given
* semaphore handle. Returns @c 0 if the managed semaphore is @c
* NULL.
*
* Note that this call is valid only when the current thread owns a write
* lock on the given semaphore handle and will assert otherwise.
*
* @note Intended for debugging only.
*/
uint32_t writeLockLevel() const
{
}
/**
* Returns @c true if this instance manages the given semaphore handle.
*
* @note Intended for debugging only.
*/
/**
* Returns @c true if this instance manages the given semaphore handle.
*
* @note Intended for debugging only.
*/
/**
* Returns @c true if this instance manages the given lockable object.
*
* @note Intended for debugging only.
*/
{
}
/**
* Returns @c true if this instance manages the given lockable object.
*
* @note Intended for debugging only.
*/
{
}
};
////////////////////////////////////////////////////////////////////////////////
/**
*
* This class differs from the AutoLock class is so that it's #lock() and
* #unlock() methods requests and release read (shared) locks on the managed
* class description for more information about read and write locks.
*
* Safe semaphore management consists of the following:
* <ul>
* <li>When an instance of the AutoReaderLock class is constructed given a
* valid semaphore handle, it will automatically request a read lock on that
* semaphore.
* </li>
* <li>When an instance of the AutoReaderLock class constructed given a valid
* semaphore handle is destroyed (e.g. goes out of scope), it will
* automatically release the read lock that was requested upon construction
* and also all nested read locks requested later using the #lock() call (note
* that the latter is considered to be a program logic error, see the
* #~AutoReaderLock() description for details).
* </li>
* </ul>
*
* Note that the LockHandle class taken by AutoReaderLock constructors is an
* existing subclasses of this abstract class or create your own subclass that
* implements necessary read and write lock semantics. The most suitable choice
* is the RWLockHandle class which provides full support for both read and write
* locks as describerd in AutoLock docs. Alternatively, you can use the
* WriteLockHandle class if you only need write (exclusive) locking
* (WriteLockHandle requires less system resources and works faster).
*
* However, please note that it absolutely does not make sense to manage
* WriteLockHandle semaphores with AutoReaderLock instances because
* AutoReaderLock instances will behave like AutoLock instances in this case
* since WriteLockHandle provides only exclusive write locking. You have been
* warned.
* A typical usage pattern of the AutoReaderLock class is as follows:
* <code>
* struct Struct : public RWLockHandle
* {
* ...
* };
*
* void foo (Struct &aStruct)
* {
* {
* // acquire a read lock of aStruct (note that two foo() calls may be
* executed on separate threads simultaneously w/o blocking each other)
* AutoReaderLock alock (aStruct);
*
* // now we can read aStruct in a thread-safe manner
* if (aStruct.foo)
* ...;
*
* // note that the read lock will be automatically released upon
* // execution of the return statement below
* if (!aStruct.bar)
* return;
*
* ...
* }
*
* // note that the read lock is automatically released here
* }
* </code>
*/
{
/**
* semaphore.
*
* Note that all method calls on a null instance are no-ops. This allows to
* have the code where lock protection can be selected (or omitted) at
* runtime.
*/
/**
* semaphore by requesting a read lock.
*/
{ lock(); }
/**
* semaphore by requesting a read lock.
*/
{ lock(); }
/**
* semaphore by requesting a read lock.
*/
{ lock(); }
/**
* semaphore by requesting a read lock.
*/
, mLockLevel (0)
{ lock(); }
/**
* Release all read locks acquired by this instance through the #lock()
* call and destroys the instance.
*
* Note that if there there are nested #lock() calls without the
* corresponding number of #unlock() calls when the destructor is called, it
* will assert. This is because having an unbalanced number of nested locks
* is a program logic error which must be fixed.
*/
{
if (mHandle)
{
for (; mLockLevel; -- mLockLevel)
mHandle->unlockRead();
}
}
/**
* Requests a read (shared) lock. If a read lock is already owned by
* this thread, increases the lock level (allowing for nested read locks on
* the same thread). Blocks indefinitely if a write lock is already owned by
* another thread until that tread releases the write lock, otherwise
* returns immediately.
*
* Note that this method returns immediately even if any number of other
* threads owns read locks on the same semaphore. Also returns immediately
* if a write lock on this semaphore is owned by the current thread which
* allows for read locks nested into write locks on the same thread.
*/
void lock()
{
if (mHandle)
{
++ mLockLevel;
}
}
/**
* Decreases the read lock level increased by #lock(). If the level drops to
* zero (e.g. the number of nested #unlock() calls matches the number of
* nested #lock() calls), releases the lock making the managed semaphore
* available for locking by other threads.
*/
void unlock()
{
if (mHandle)
{
mHandle->unlockRead();
-- mLockLevel;
}
}
/** Returns @c true if this instance manages a null semaphore handle. */
/**
* Returns @c true if this instance manages the given semaphore handle.
*
* @note Intended for debugging only.
*/
/**
* Returns @c true if this instance manages the given semaphore handle.
*
* @note Intended for debugging only.
*/
/**
* Returns @c true if this instance manages the given lockable object.
*
* @note Intended for debugging only.
*/
{
}
/**
* Returns @c true if this instance manages the given lockable object.
*
* @note Intended for debugging only.
*/
{
}
};
////////////////////////////////////////////////////////////////////////////////
/**
* Helper template class for AutoMultiLockN classes.
*
*/
{
/**
* Releases all locks if not yet released by #unlock() and destroys the
* instance.
*/
{
if (mIsLocked)
unlock();
}
/**
* Calls LockOps::lock() methods of all managed semaphore handles
* in order they were passed to the constructor.
*
* Note that as opposed to LockHandle::lock(), this call cannot be nested
* and will assert if so.
*/
void lock()
{
size_t i = 0;
if (mOps [i])
mIsLocked = true;
}
/**
* Calls LockOps::unlock() methods of all managed semaphore handles in
* reverse to the order they were passed to the constructor.
*
* Note that as opposed to LockHandle::unlock(), this call cannot be nested
* and will assert if so.
*/
void unlock()
{
do
if (mOps [-- i])
while (i != 0);
mIsLocked = false;
}
AutoMultiLockBase() : mIsLocked (false) {}
bool mIsLocked;
};
/** AutoMultiLockBase <0> is meaningless and forbidden. */
template<>
/** AutoMultiLockBase <1> is meaningless and forbidden. */
template<>
////////////////////////////////////////////////////////////////////////////////
/* AutoMultiLockN class definitions */
#define A(n) LockOps *l##n
#define B(n) mOps [n] = l##n
/**
* AutoMultiLock for 2 locks.
*
* The AutoMultiLockN family of classes provides a possibility to manage several
* to be locked and unlocked synchronously and will also help to avoid locking
* order errors.
*
* Instances of AutoMultiLockN classes are constructed from a list of LockOps
* arguments. The AutoMultiLockBase::lock() method will make sure that the given
* list of semaphores represented by LockOps pointers will be locked in order
* they are passed to the constructor. The AutoMultiLockBase::unlock() method
* will make sure that they will be unlocked in reverse order.
*
* The type of the lock to request is specified for each semaphore individually
* using the corresponding LockOps getter of a LockHandle or Lockable object:
* LockHandle::wlock() in order to request a write lock or LockHandle::rlock()
* in order to request a read lock.
*
* Here is a typical usage pattern:
* <code>
* ...
* LockHandle data1, data2;
* ...
* {
* AutoMultiLock2 multiLock (data1.wlock(), data2.rlock());
* // both locks are held here:
* // - data1 is locked in write mode (like AutoLock)
* // - data2 is locked in read mode (like AutoReaderLock)
* }
* // both locks are released here
* </code>
*/
{
AutoMultiLock2 (A(0), A(1))
{ B(0); B(1); lock(); }
};
/** AutoMultiLock for 3 locks. See AutoMultiLock2 for more information. */
{
};
/** AutoMultiLock for 4 locks. See AutoMultiLock2 for more information. */
{
};
#undef B
#undef A
////////////////////////////////////////////////////////////////////////////////
/**
* Helper template class for AutoMultiWriteLockN classes.
*
* @param Cnt number of write semaphores to manage.
*/
{
/**
* Calls AutoLock::lock() methods for all managed semaphore handles in order
* they were passed to the constructor.
*/
void lock()
{
size_t i = 0;
}
/**
* Calls AutoLock::unlock() methods for all managed semaphore handles in
* reverse to the order they were passed to the constructor.
*/
void unlock()
{
do
while (i != 0);
}
/**
* Calls AutoLock::leave() methods for all managed semaphore handles in
* reverse to the order they were passed to the constructor.
*/
void leave()
{
do
while (i != 0);
}
/**
* Calls AutoLock::enter() methods for all managed semaphore handles in order
* they were passed to the constructor.
*/
void enter()
{
size_t i = 0;
}
};
/** AutoMultiWriteLockBase <0> is meaningless and forbidden. */
template<>
/** AutoMultiWriteLockBase <1> is meaningless and forbidden. */
template<>
////////////////////////////////////////////////////////////////////////////////
/* AutoMultiLockN class definitions */
#define A(n) LockHandle *l##n
#define B(n) setLockHandle (n, l##n)
#define C(n) Lockable *l##n
/**
* AutoMultiWriteLock for 2 locks.
*
* The AutoMultiWriteLockN family of classes provides a possibility to manage
* semaphores need to be locked and unlocked synchronously and will also help to
* avoid locking order errors.
*
* The functionality of the AutoMultiWriteLockN class family is similar to the
* functionality of the AutoMultiLockN class family (see the AutoMultiLock2
* class for details) with two important differences:
* <ol>
* <li>Instances of AutoMultiWriteLockN classes are constructed from a list
* of LockHandle or Lockable arguments directly instead of getting
* intermediate LockOps interface pointers.
* </li>
* <li>All locks are requested in <b>write</b> mode.
* </li>
* <li>Since all locks are requested in write mode, bulk
* AutoMultiWriteLockBase::leave() and AutoMultiWriteLockBase::enter()
* operations are also available, that will leave and enter all managed
* semaphores at once in the proper order (similarly to
* AutoMultiWriteLockBase::lock() and AutoMultiWriteLockBase::unlock()).
* </li>
* </ol>
*
* Here is a typical usage pattern:
* <code>
* ...
* LockHandle data1, data2;
* ...
* {
* AutoMultiWriteLock2 multiLock (&data1, &data2);
* // both locks are held in write mode here
* }
* // both locks are released here
* </code>
*/
{
AutoMultiWriteLock2 (A(0), A(1))
{ B(0); B(1); lock(); }
AutoMultiWriteLock2 (C(0), C(1))
{ D(0); D(1); lock(); }
};
/** AutoMultiWriteLock for 3 locks. See AutoMultiWriteLock2 for more details. */
{
};
/** AutoMultiWriteLock for 4 locks. See AutoMultiWriteLock2 for more details. */
{
};
#undef D
#undef C
#undef B
#undef A
} /* namespace util */
#endif // ____H_AUTOLOCK