Package bslmt

Modules
	bslmt_barrier
	Provide a thread barrier component.
	bslmt_chronoutil
	Provide utilities related to threading with C++11-style clocks.
	bslmt_condition
	Provide a portable, efficient condition variable.
	bslmt_conditionimpl_pthread
	Provide a POSIX implementation of bslmt::Condition.
	bslmt_conditionimpl_win32
	Provide a win32 implementation of bslmt::Condition.
	bslmt_configuration
	Provide utilities to allow configuration of values for BCE.
	bslmt_entrypointfunctoradapter
	Provide types and utilities to simplify thread creation.
	bslmt_fastpostsemaphore
	Provide a semaphore class optimizing post.
	bslmt_fastpostsemaphoreimpl
	Provide a testable semaphore class optimizing post.
	bslmt_latch
	Provide a single-use mechanism for synchronizing on an event count.
	bslmt_lockguard
	Provide generic scoped guards for synchronization objects.
	bslmt_meteredmutex
	Provide a mutex capable of keeping track of wait and hold time.
	bslmt_mutex
	Provide a platform-independent mutex.
	bslmt_mutexassert
	Provide an assert macro for verifying that a mutex is locked.
	bslmt_muteximpl_pthread
	Provide a POSIX implementation of bslmt::Mutex.
	bslmt_muteximpl_win32
	Provide a win32 implementation of bslmt::Mutex.
	bslmt_once
	Provide a thread-safe way to execute code once per process.
	bslmt_platform
	Provide platform-dependent thread-related trait definitions.
	bslmt_qlock
	Provide small, statically-initializable mutex lock.
	bslmt_readerwriterlock
	Provide a multi-reader/single-writer lock.
	bslmt_readerwriterlockassert
	Provide an assert macro for verifying reader-writer lock status.
	bslmt_readerwritermutex
	Provide a multi-reader/single-writer lock.
	bslmt_readerwritermuteximpl
	Provide a multi-reader/single-writer lock.
	bslmt_readlockguard
	Provide generic scoped guards for read synchronization objects.
	bslmt_recursivemutex
	Provide a platform-independent recursive mutex.
	bslmt_recursivemuteximpl_pthread
	Provide a POSIX implementation of bslmt::RecursiveMutex.
	bslmt_recursivemuteximpl_win32
	Provide a win32 implementation of bslmt::RecursiveMutex.
	bslmt_rwmutex
	Provide a platform-independent RW mutex class.
	bslmt_saturatedtimeconversionimputil
	Provide special narrowing conversions for time types.
	bslmt_semaphore
	Provide a semaphore class.
	bslmt_semaphoreimpl_counted
	Provide an implementation of bslmt::Semaphore with count.
	bslmt_semaphoreimpl_darwin
	Provide a Darwin implementation of bslmt::Semaphore.
	bslmt_semaphoreimpl_pthread
	Provide a POSIX implementation of bslmt::Semaphore.
	bslmt_semaphoreimpl_win32
	Provide a win32 implementation of bslmt::Semaphore.
	bslmt_sluice
	Provide a "sluice" class.
	bslmt_testutil
	Provide thread-safe test utilities for multithreaded components.
	bslmt_threadattributes
	Provide a description of the attributes of a thread.
	bslmt_threadgroup
	Provide a container for managing a group of threads.
	bslmt_threadlocalvariable
	Provide a macro to declare a thread-local variable.
	bslmt_threadutil
	Provide platform-independent utilities related to threading.
	bslmt_threadutilimpl_pthread
	Provide a POSIX implementation of bslmt::ThreadUtil.
	bslmt_threadutilimpl_win32
	Provide a win32 implementation of bslmt::ThreadUtil.
	bslmt_throughputbenchmark
	Provide a performance test harness for multi-threaded components.
	bslmt_throughputbenchmarkresult
	Provide result repository for throughput performance test harness.
	bslmt_timedsemaphore
	Provide a timed semaphore class.
	bslmt_timedsemaphoreimpl_posixadv
	Provide "advanced" POSIX implementation of bslmt::TimedSemaphore.
	bslmt_timedsemaphoreimpl_pthread
	Provide a POSIX implementation of bslmt::TimedSemaphore.
	bslmt_timedsemaphoreimpl_win32
	Provide a win32 implementation of bslmt::TimedSemaphore.
	bslmt_turnstile
	Provide a mechanism to meter time.
	bslmt_writelockguard
	Provide generic scoped guards for write synchronization objects.

Detailed Description

Purpose

Support for multi-threading and thread-safe processes.

Mnemonic

Basic Standard Library Multi-Threading (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 bslmt_lockguard and 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.

 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

Component Synopsis

bslmt_barrier : Provide a thread barrier component.

bslmt_chronoutil : Provide utilities related to threading with C++11-style clocks.

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.

bslmt_configuration : Provide utilities to allow configuration of values for BCE.

bslmt_entrypointfunctoradapter : Provide types and utilities to simplify thread creation.

bslmt_fastpostsemaphore : Provide a semaphore class optimizing post.

bslmt_fastpostsemaphoreimpl : Provide a testable semaphore class optimizing post.

bslmt_latch : Provide a single-use mechanism for synchronizing on an event count.

bslmt_lockguard : Provide generic scoped guards for synchronization objects.

bslmt_meteredmutex : Provide a mutex capable of keeping track of wait and hold time.

bslmt_mutex : Provide a platform-independent mutex.

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.

bslmt_once : Provide a thread-safe way to execute code once per process.

bslmt_platform : Provide platform-dependent thread-related trait definitions.

bslmt_qlock : Provide small, statically-initializable mutex lock.

bslmt_readerwriterlock : Provide a multi-reader/single-writer lock.

bslmt_readerwriterlockassert : Provide an assert macro for verifying reader-writer lock status.

bslmt_readerwritermutex : Provide a multi-reader/single-writer lock.

bslmt_readerwritermuteximpl : Provide a multi-reader/single-writer lock.

bslmt_readlockguard : Provide generic scoped guards for read synchronization objects.

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.

bslmt_rwmutex : !DEPRECATED! Provide a platform-independent RW mutex class.

bslmt_saturatedtimeconversionimputil : Provide special narrowing conversions for time types.

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.

bslmt_sluice : Provide a "sluice" class.

bslmt_testutil : Provide thread-safe test utilities for multithreaded components.

bslmt_threadattributes : Provide a description of the attributes of a thread.

bslmt_threadgroup : Provide a container for managing a group of threads.

bslmt_threadlocalvariable : Provide a macro to declare a thread-local variable.

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.

bslmt_throughputbenchmark : Provide a performance test harness for multi-threaded components.

bslmt_throughputbenchmarkresult : Provide result repository for throughput performance test harness.

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.

bslmt_turnstile : Provide a mechanism to meter time.

bslmt_writelockguard : Provide generic scoped guards for write synchronization objects.

Thread Management

Thread management is done via the utility class 'bslmt::ThreadUtil' in the 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 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 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 bslmt_recursivemutex .

Inter-thread Condition Variables: bslmt::Condition

The 'bslmt::Condition' class, defined in component 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.

 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()'
 }

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 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 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 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 bslmt_once component. The 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 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:

            Component           |                 Purpose
 +==============================+===========================================+
 | bslmt_threadutilimpl_pthread | Template specialization for POSIX threads |
 | bslmt_threadutilimpl_win32   | Template specialization for MS-Windows    |
 +------------------------------+-------------------------------------------+

These components are visible and documented. However, their intended use is to support component bslmt_threadutil . Clients should not expect to use them directly.