bslmt.h

Go to the documentation of this file.

/// @file bslmt.h
///
///
/// @defgroup bslmt Package bslmt
/// @brief  Basic Standard Library Multi-Threading (bslmt)
/// @addtogroup bsl
/// @{
/// @addtogroup bslmt
/// [bslmt]: group__bslmt.html
/// @{
///
/// # Purpose {#bslmt-purpose}
/// Support for multi-threading and thread-safe processes.
///
/// # Mnemonic {#bslmt-mnemonic}
/// Basic Standard Library Multi-Threading (bslmt)
///
/// # Description {#bslmt-description}
/// The 'bslmt' package supports primitives that allow creation and
/// management of operating system threads.  Using the components in 'bslmt',
/// clients can write efficient, thread-safe code.
///
/// Thread creation and management of mutually exclusive locks (mutexes) are
/// supported in a way that should be familiar to developers with experience
/// programming in threads on any common computing platform.  In addition,
/// individual components such as @ref bslmt_lockguard  and @ref bslmt_barrier  manage
/// synchronization concerns through simple, idiomatic object interfaces that make
/// client code easy to read and understand.
///
/// ## Hierarchical Synopsis
///
/// The 'bslmt' package currently has 50 components having 17 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  17. bslmt_once
///      bslmt_readerwriterlockassert
///      bslmt_rwmutex                                      !DEPRECATED!
///
///  16. bslmt_latch
///      bslmt_meteredmutex
///      bslmt_qlock
///      bslmt_readerwriterlock
///      bslmt_throughputbenchmark
///
///  15. bslmt_barrier
///      bslmt_fastpostsemaphore
///
///  14. bslmt_condition
///
///  13. bslmt_conditionimpl_win32                                       !PRIVATE!
///
///  12. bslmt_readerwritermutex
///      bslmt_sluice
///
///  11. bslmt_readerwritermuteximpl
///      bslmt_threadgroup
///
///  10. bslmt_semaphore
///
///   9. bslmt_semaphoreimpl_counted                                     !PRIVATE!
///      bslmt_timedsemaphore
///
///   8. bslmt_conditionimpl_pthread                                     !PRIVATE!
///      bslmt_mutexassert
///      bslmt_semaphoreimpl_darwin                                      !PRIVATE!
///      bslmt_semaphoreimpl_pthread                                     !PRIVATE!
///      bslmt_semaphoreimpl_win32                                       !PRIVATE!
///      bslmt_testutil
///      bslmt_timedsemaphoreimpl_win32                                  !PRIVATE!
///
///   7. bslmt_mutex
///      bslmt_recursivemutex
///      bslmt_timedsemaphoreimpl_posixadv                               !PRIVATE!
///      bslmt_timedsemaphoreimpl_pthread                                !PRIVATE!
///      bslmt_turnstile
///
///   6. bslmt_threadutil
///
///   5. bslmt_entrypointfunctoradapter
///
///   4. bslmt_threadutilimpl_pthread                                    !PRIVATE!
///      bslmt_threadutilimpl_win32                                      !PRIVATE!
///
///   3. bslmt_configuration
///      bslmt_recursivemuteximpl_win32                                  !PRIVATE!
///
///   2. bslmt_fastpostsemaphoreimpl
///      bslmt_muteximpl_pthread                                         !PRIVATE!
///      bslmt_muteximpl_win32                                           !PRIVATE!
///      bslmt_recursivemuteximpl_pthread                                !PRIVATE!
///      bslmt_saturatedtimeconversionimputil
///      bslmt_threadattributes
///
///   1. bslmt_chronoutil
///      bslmt_lockguard
///      bslmt_platform
///      bslmt_readlockguard
///      bslmt_threadlocalvariable
///      bslmt_throughputbenchmarkresult
///      bslmt_writelockguard
/// @endcode
///
/// ## Component Synopsis
///
///  @ref bslmt_barrier :
///       Provide a thread barrier component.
/// 
///  @ref bslmt_chronoutil :
///       Provide utilities related to threading with C++11-style clocks.
/// 
///  @ref bslmt_condition :
///       Provide a portable, efficient condition variable.
/// 
///  'bslmt_conditionimpl_pthread':                                      !PRIVATE!
///       Provide a POSIX implementation of `bslmt::Condition`.
/// 
///  'bslmt_conditionimpl_win32':                                        !PRIVATE!
///       Provide a win32 implementation of `bslmt::Condition`.
/// 
///  @ref bslmt_configuration :
///       Provide utilities to allow configuration of values for BCE.
/// 
///  @ref bslmt_entrypointfunctoradapter :
///       Provide types and utilities to simplify thread creation.
/// 
///  @ref bslmt_fastpostsemaphore :
///       Provide a semaphore class optimizing `post`.
/// 
///  @ref bslmt_fastpostsemaphoreimpl :
///       Provide a testable semaphore class optimizing `post`.
/// 
///  @ref bslmt_latch :
///       Provide a single-use mechanism for synchronizing on an event count.
/// 
///  @ref bslmt_lockguard :
///       Provide generic scoped guards for synchronization objects.
/// 
///  @ref bslmt_meteredmutex :
///       Provide a mutex capable of keeping track of wait and hold time.
/// 
///  @ref bslmt_mutex :
///       Provide a platform-independent mutex.
/// 
///  @ref bslmt_mutexassert :
///       Provide an assert macro for verifying that a mutex is locked.
/// 
///  'bslmt_muteximpl_pthread':                                          !PRIVATE!
///       Provide a POSIX implementation of `bslmt::Mutex`.
/// 
///  'bslmt_muteximpl_win32':                                            !PRIVATE!
///       Provide a win32 implementation of `bslmt::Mutex`.
/// 
///  @ref bslmt_once :
///       Provide a thread-safe way to execute code once per process.
/// 
///  @ref bslmt_platform :
///       Provide platform-dependent thread-related trait definitions.
/// 
///  @ref bslmt_qlock :
///       Provide small, statically-initializable mutex lock.
/// 
///  @ref bslmt_readerwriterlock :
///       Provide a multi-reader/single-writer lock.
/// 
///  @ref bslmt_readerwriterlockassert :
///       Provide an assert macro for verifying reader-writer lock status.
/// 
///  @ref bslmt_readerwritermutex :
///       Provide a multi-reader/single-writer lock.
/// 
///  @ref bslmt_readerwritermuteximpl :
///       Provide a multi-reader/single-writer lock.
/// 
///  @ref bslmt_readlockguard :
///       Provide generic scoped guards for read synchronization objects.
/// 
///  @ref bslmt_recursivemutex :
///       Provide a platform-independent recursive mutex.
/// 
///  'bslmt_recursivemuteximpl_pthread':                                 !PRIVATE!
///       Provide a POSIX implementation of `bslmt::RecursiveMutex`.
/// 
///  'bslmt_recursivemuteximpl_win32':                                   !PRIVATE!
///       Provide a win32 implementation of `bslmt::RecursiveMutex`.
/// 
///  @ref bslmt_rwmutex :                                       !DEPRECATED!
///       Provide a platform-independent RW mutex class.
/// 
///  @ref bslmt_saturatedtimeconversionimputil :
///       Provide special narrowing conversions for time types.
/// 
///  @ref bslmt_semaphore :
///       Provide a semaphore class.
/// 
///  'bslmt_semaphoreimpl_counted':                                      !PRIVATE!
///       Provide an implementation of `bslmt::Semaphore` with count.
/// 
///  'bslmt_semaphoreimpl_darwin':                                       !PRIVATE!
///       Provide a Darwin implementation of `bslmt::Semaphore`.
/// 
///  'bslmt_semaphoreimpl_pthread':                                      !PRIVATE!
///       Provide a POSIX implementation of `bslmt::Semaphore`.
/// 
///  'bslmt_semaphoreimpl_win32':                                        !PRIVATE!
///       Provide a win32 implementation of `bslmt::Semaphore`.
/// 
///  @ref bslmt_sluice :
///       Provide a "sluice" class.
/// 
///  @ref bslmt_testutil :
///       Provide thread-safe test utilities for multithreaded components.
/// 
///  @ref bslmt_threadattributes :
///       Provide a description of the attributes of a thread.
/// 
///  @ref bslmt_threadgroup :
///       Provide a container for managing a group of threads.
/// 
///  @ref bslmt_threadlocalvariable :
///       Provide a macro to declare a thread-local variable.
/// 
///  @ref bslmt_threadutil :
///       Provide platform-independent utilities related to threading.
/// 
///  'bslmt_threadutilimpl_pthread':                                     !PRIVATE!
///       Provide a POSIX implementation of `bslmt::ThreadUtil`.
/// 
///  'bslmt_threadutilimpl_win32':                                       !PRIVATE!
///       Provide a win32 implementation of `bslmt::ThreadUtil`.
/// 
///  @ref bslmt_throughputbenchmark :
///       Provide a performance test harness for multi-threaded components.
/// 
///  @ref bslmt_throughputbenchmarkresult :
///       Provide result repository for throughput performance test harness.
/// 
///  @ref bslmt_timedsemaphore :
///       Provide a timed semaphore class.
/// 
///  'bslmt_timedsemaphoreimpl_posixadv':                                !PRIVATE!
///       Provide "advanced" POSIX implementation of `bslmt::TimedSemaphore`.
/// 
///  'bslmt_timedsemaphoreimpl_pthread':                                 !PRIVATE!
///       Provide a POSIX implementation of `bslmt::TimedSemaphore`.
/// 
///  'bslmt_timedsemaphoreimpl_win32':                                   !PRIVATE!
///       Provide a win32 implementation of `bslmt::TimedSemaphore`.
/// 
///  @ref bslmt_turnstile :
///       Provide a mechanism to meter time.
/// 
///  @ref bslmt_writelockguard :
///       Provide generic scoped guards for write synchronization objects.
///
/// ## Thread Management
///
/// Thread management is done via the utility class 'bslmt::ThreadUtil' in the
/// @ref bslmt_threadutil  component.  This component presents a platform-independent
/// protocol whose operations nonetheless correspond closely to native operations
/// on platform-specific threads.  'bslmt::ThreadUtil' presents a procedural
/// interface -- that is, clients do not instantiate 'bslmt::ThreadUtil' objects,
/// and all methods of 'bslmt::ThreadUtil' are declared 'static'.
///
/// Clients create threads with the functions
/// 'bslmt::ThreadUtil::create(Handle*, ...)'.  On success, these functions yield
/// a 'bslmt::ThreadUtil::Handle' object that provides a lightweight handle for an
/// operating systems thread.  Similarly, clients destroy threads for which they
/// have a current 'Handle' with 'bslmt::ThreadUtil::terminate(Handle*)'.
///
/// 'bslmt::ThreadUtil' supports two 'create()' functions.  The first function
/// simply takes a pointer to a 'bslmt::ThreadUtil::Handle'; the second function
/// takes a 'bslmt::ThreadAttributes' object that defines component-specific and
/// platform-specific attributes of the created thread.  Platform-specific
/// attributes include scheduling policy and priority, and thread stack size.  See
/// the @ref bslmt_threadattributes  component documentation for details.
///
/// ## Thread Synchronization
///
/// The 'bslmt' package contains several components and classes that support
/// thread synchronization in a number of ways.
///
/// ### Basic Mutexes: bslmt::Mutex and bslmt::RecursiveMutex
///
/// At the lowest level, synchronization between threads is done with
/// 'bslmt::Mutex', a type defined in component @ref bslmt_mutex .  Locks are
/// acquired with 'bslmt::Mutex::lock()' or 'bslmt::Mutex::tryLock()', and
/// released with 'bslmt::Mutex::unlock()'.  The 'bslmt' package provides several
/// other mechanisms for synchronization and communication, which suit specific
/// synchronization problems and allow more idiomatic C++ coding.
///
/// 'bslmt::RecursiveMutex' is similar to 'bslmt::Mutex', except that it can be
/// 'lock'ed multiple times *in* *a* *single* *thread*.  A corresponding number of
/// calls to 'unlock()' are required to unlock the mutex.  'bslmt::RecursiveMutex'
/// is defined in component @ref bslmt_recursivemutex .
///
/// ### Inter-thread Condition Variables: bslmt::Condition
///
/// The 'bslmt::Condition' class, defined in component @ref bslmt_condition ,
/// implements a "condition variable" that can be used by multiple threads to
/// communicate changes in the condition.  Multiple threads wait on the condition
/// by calling 'myCondition->wait(bslmt::Mutex*)', suspending their execution and
/// waiting.  An individual thread then signals when the condition is met by
/// calling either 'myCondition->signal()' (waking up a single waiting thread) or
/// 'myCondition->broadcast()' (waking up all waiting threads).  Waits with
/// timeouts are supported through 'bslmt::Condition::timedWait()'.
///
/// ### Locking/Unlocking Critical Code
///
/// Code in multiple threads can create a 'bslmt::Mutex' and call 'mutex->lock()'
/// and 'mutex->unlock()' to guarantee exclusive access to critical sections of
/// code.  A more idiomatic usage is provided by 'bslmt::LockGuard' and
/// 'bslmt::LockGuardUnlock'; objects of these types themselves lock and unlock a
/// 'bslmt::Mutex' when they are created or destroyed, allowing clients to manage
/// mutex locks in a way more transparent, safer way, and also making sure the
/// lock is released when an exception is thrown within the critical section.
/// @code
///  static void myThreadsafeFunction(myObject *obj, bslmt::Mutex *mutex)
///  {
///      // creating the 'LockGuard', 'guard', calls 'mutex->lock()'
///      bslmt::LockGuard<bslmt::Mutex> guard(mutex);
///      if (someCondition) {
///          obj->someMethod();
///          return;
///          // 'guard' is destroyed; this calls 'mutex->unlock()'
///      } else if (someOtherCondition) {
///          obj->someOtherMethod();
///          return;
///          // 'guard' is destroyed; this calls 'mutex->unlock()'
///      }
///      obj->defaultMethod();
///      return;
///      // 'guard' is destroyed; this calls 'mutex->unlock()'
///  }
/// @endcode
///
/// ### Thread-Specific Storage
///
/// Thread-specific storage (also known as thread-local storage, or TLS) is a
/// mechanism for referring to a single variable (identified by its 'Key' in
/// 'bslmt::ThreadUtil', provided by the @ref bslmt_threadutil  component) whose
/// content varies according to the thread it is observed in.  This is useful for
/// status variables such as 'errno', which is implemented by the system as a TLS,
/// since otherwise it would be impossible to use 'errno' values in a thread, not
/// knowing if another thread had modified it after the last system call in this
/// thread.
///
/// ### Synchronization of Multiple, Parallel Threads: bslmt::Barrier
///
/// The @ref bslmt_barrier  component provides a single class, 'bslmt::Barrier', that
/// can be used to synchronize processing among multiple threads.  The
/// 'bslmt::Barrier' is created with a single argument specifying the number of
/// threads to synchronize.  Each individual thread then calls 'myBarrier->wait()'
/// when it reaches its synchronization point.  All waiting threads are blocked
/// until the required number of threads have called 'myBarrier->wait()'; once the
/// required number is reached, the threads are released and can continue
/// processing.
///
/// ### bslmt read/write Locking Components
///
/// There are 3 components that provide locking mechanisms that allows multiple
/// threads to simultaneously lock for read, while providing exclusive access to
/// a thread locking for write.
///
///  * 'bslmt::ReaderWriterMutex': Preferred for most use-cases, has been shown to
///    be faster than 'bslmt::ReaderWriterLock': under most conditions and is
///    generally the best choice.
/// 
///  * 'bslmt::ReaderWriterLock': Preferred only when very long hold times are
///    anticipated.  It also provides 'upgrade*' methods from a locked-for-read
///    state to a locked-for-write state, but the use of this feature is
///    discouraged as it has performed poorly on benchmarks.
/// 
///  * 'bslmt::RWMutex': Deprecated.
///
/// Note that for extremely short hold times and very high concurrency, a
/// 'bslmt::Mutex' might outperform all of the above.
///
/// Also note that reader/writer locks also have their own guards, provided by the
/// templated 'bslmt::ReadLockGuard' and 'bslmt::WriteLockGuard' classes, which
/// work on locks of all 3 types.
///
/// Also note that assertions to verify locking are available from
/// @ref bslmt_readerwriterlockassert , which work on locks of type
/// 'bslmt::ReaderWriterMutex' and 'bslmt::ReaderWriterLock', but not
/// 'bslmt::RWMutex'.
///
/// ### Recursive Write Locks: bslmt::RecursiveRWLock
///
/// This component is *DEPRECATED*.  It can be emulated by a wrapper on a
/// 'bslmt::ReaderWriterLock' along with a thread-specific counter used to store
/// the number of recursive locks acquired by the current thread.
///
/// ### Static Initialization
///
/// Initialization of a thread-specific static variable (such as a thread-local
/// singleton) can be achieved by using the @ref bslmt_once  component.  The
/// @ref bslmt_qlock  component ensures thread-safe static initialization of shared
/// resources by providing a light-weight, statically initializable lock.  Note
/// that the classic 'bslmt::Mutex' provided by the @ref bslmt_mutex  component
/// cannot safely be used in static initializations because some platforms (e.g.,
/// Windows XP) do not have a native statically-initializable mutex type.
///
/// ## Implementation Classes and Components
///
/// The 'bslmt' package is supported on all Bloomberg platforms.  In order to
/// accomplish this, 'bslmt' provides platform-specific implementations of thread
/// primitives.  The following components provide platform-specific
/// implementations:
/// @code
///             Component           |                 Purpose
///  +==============================+===========================================+
///  | bslmt_threadutilimpl_pthread | Template specialization for POSIX threads |
///  | bslmt_threadutilimpl_win32   | Template specialization for MS-Windows    |
///  +------------------------------+-------------------------------------------+
/// @endcode
/// These components are visible and documented.  However, their intended use is
/// to support component @ref bslmt_threadutil .  Clients should not expect to use
/// them directly.
///
/// @}
/** @} */