bslmt Package

Support for multi-threading and thread-safe processes. More...

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

Detailed Description

Outline

Purpose
MNEMONIC: Basic Standard Library Multi-Threading (bslmt)
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 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 locked 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.

Package bslmt [Package Group bsl]

Components

Detailed Description

Package bslmt
[Package Group bsl]