bslmt.txt
@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 18 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.
..
18. bslmt_testutil
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_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.
: o '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.
:
: o '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.
:
: o '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.