bdlcc.h

Go to the documentation of this file.

/// @file bdlcc.h
///
///
/// @defgroup bdlcc Package bdlcc
/// @brief  Basic Development Library Concurrency Containers (bdlcc)
/// @addtogroup bdl
/// @{
/// @addtogroup bdlcc
/// [bdlcc]: group__bdlcc.html
/// @{
///
/// # Purpose {#bdlcc-purpose}
/// Provide containers that support concurrent (multi-thread) access.
///
/// # Mnemonic {#bdlcc-mnemonic}
/// Basic Development Library Concurrency Containers (bdlcc)
///
/// @see  bdlc, bdlmt
///
/// # Description {#bdlcc-description}
/// The 'bdlcc' package provides a set of containers that allow
/// concurrent access and manipulation.  Components in this package are similar in
/// *intent* to the corresponding 'bdlc' components, except that all operations
/// which change the internal state of the containers are guaranteed to be atomic
/// in the presence of multiple threads.
///
/// Support for true multi-threading causes some significant interface changes
/// when compared to the analogous 'bdlc' components.  A thread-safe collection
/// cannot, in general, guarantee thread safety for its contained objects while
/// still allowing access to those objects.  So, for instance, a canonical
/// implementation of 'operator[]', yielding a reference to the contained object,
/// would violate thread safety.  Therefore, thread-safe collections will, in
/// general, return items *by* *value* rather than *by* *reference*.
///
/// In addition, thread-aware collection components must make policy decisions
/// regarding behavior of manipulators at the "edge conditions" when a collection
/// is empty or full.  In a multi-threading context, it is often reasonable for a
/// manipulator to block if it cannot complete a requested operation, and to wait
/// for the collection state to change.  For instance, when called for an empty
/// collection, 'bdlcc_Queue<T>::popFront()' will block and then wait until an
/// element is available to satisfy the request.
///
/// In general, components in 'bdlcc' support this blocking behavior where it
/// makes sense.  Refer to the individual component documentation to understand
/// how this general principle is carried out in specific components.
///
/// Unless otherwise stated, the behavior of the destructors of components in the
/// 'bdlcc' package is undefined unless all access or modification of the object
/// is completed prior to its destruction.  Some form of synchronization, external
/// to the component, is required to ensure this precondition on the destructor is
/// met.  For example, if two (or more) threads are manipulating a container, it
/// is *not* safe to anticipate the number of elements added to the container, and
/// destroy that container immediately after the last element is removed (without
/// additional synchronization) because one of the corresponding insert functions
/// may not have completed (the insert may, for instance, signal waiting threads
/// after the element is considered added to the container).
///
/// ## Hierarchical Synopsis
///
/// The 'bdlcc' package currently has 20 components having 4 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
///  4. bdlcc_sharedobjectpool
///
///  3. bdlcc_objectpool
///
///  2. bdlcc_fixedqueue
///     bdlcc_singleconsumerqueue
///     bdlcc_singleproducerqueue
///     bdlcc_stripedunorderedmap
///     bdlcc_stripedunorderedmultimap
///
///  1. bdlcc_boundedqueue
///     bdlcc_cache
///     bdlcc_deque
///     bdlcc_fixedqueueindexmanager
///     bdlcc_multipriorityqueue
///     bdlcc_objectcatalog
///     bdlcc_queue                                         !DEPRECATED!
///     bdlcc_singleconsumerqueueimpl
///     bdlcc_singleproducerqueueimpl
///     bdlcc_singleproducersingleconsumerboundedqueue
///     bdlcc_skiplist
///     bdlcc_stripedunorderedcontainerimpl
///     bdlcc_timequeue
/// @endcode
///
/// ## Component Synopsis
///
///  @ref bdlcc_boundedqueue :
///       Provide a thread-aware bounded queue of values.
/// 
///  @ref bdlcc_cache :
///       Provide a in-process cache with configurable eviction policy.
/// 
///  @ref bdlcc_deque :
///       Provide a fully thread-safe deque container.
/// 
///  @ref bdlcc_fixedqueue :
///       Provide a thread-aware fixed-size queue of values.
/// 
///  @ref bdlcc_fixedqueueindexmanager :
///       Provide thread-enabled state management for a fixed-size queue.
/// 
///  @ref bdlcc_multipriorityqueue :
///       Provide a thread-enabled parameterized multi-priority queue.
/// 
///  @ref bdlcc_objectcatalog :
///       Provide an efficient indexed, thread-safe object container.
/// 
///  @ref bdlcc_objectpool :
///       Provide a thread-safe object pool.
/// 
///  @ref bdlcc_queue :                                         !DEPRECATED!
///       Provide a thread-enabled queue of items of parameterized `TYPE`.
/// 
///  @ref bdlcc_sharedobjectpool :
///       Provide a thread-safe pool of shared objects.
/// 
///  @ref bdlcc_singleconsumerqueue :
///       Provide a thread-aware single consumer queue of values.
/// 
///  @ref bdlcc_singleconsumerqueueimpl :
///       Provide a testable thread-aware single consumer queue of values.
/// 
///  @ref bdlcc_singleproducerqueue :
///       Provide a thread-aware single producer queue of values.
/// 
///  @ref bdlcc_singleproducerqueueimpl :
///       Provide a testable thread-aware single producer queue of values.
/// 
///  @ref bdlcc_singleproducersingleconsumerboundedqueue :
///       Provide a thread-aware SPSC bounded queue of values.
/// 
///  @ref bdlcc_skiplist :
///       Provide a generic thread-safe Skip List.
/// 
///  @ref bdlcc_stripedunorderedcontainerimpl :
///       Provide common implementation of *striped* un-ordered map/multimap.
/// 
///  @ref bdlcc_stripedunorderedmap :
///       Provide a bucket-group locking (i.e., *striped*) unordered map.
/// 
///  @ref bdlcc_stripedunorderedmultimap :
///       Provide a bucket-group locking (*striped*) unordered multimap.
/// 
///  @ref bdlcc_timequeue :
///       Provide an efficient queue for time events.
///
/// ## Component Overview
///
/// This section provides a brief introduction to some of the components of the
/// 'bdlcc' package.  Full details are available in the documentation of each
/// component.
///
/// ### @ref bdlcc_objectcatalog 
///
/// The {@ref bdlcc_objectcatalog } component provides a thread-safe, indexable
/// catalog of object.  Clients instantiate a template class,
/// 'bdlcc_ObjectCatalog<T>', where type 'T' is the data type of elements that the
/// catalog will hold.  Type 'T' must be defined to be copyable either by a copy
/// constructor or by 'T::operator=()'; class 'bdlcc_ObjectCatalog' places no
/// additional requirements on 'T'.
///
/// When clients add elements to a 'bdlcc_ObjectCatalog', the 'add' method returns
/// a handle which can be used to refer to the element until the element is
/// 'remove'd.  Addition is not guaranteed to succeed and the return vaslue must
/// be checked.  An element can be accessed through its handle by using the 'find'
/// function and passing a buffer for holding the value.  Passing a null buffer
/// can be used for testing whether the handle is still valid (i.e., refers to an
/// element that has not yet been removed from the catalog).
///
/// The 'bdlcc_ObjectCatalog' is designed to support direct access to individual
/// queued elements based upon their 'Handle'.  This means that 'bdlcc_Catalog'
/// can support frequent additions and removals more efficiently than traditional
/// queue structures designed for sequential access.
///
/// ### @ref bdlcc_pool 
///
/// The {@ref bdlcc_pool } component provides a thread-safe memory pool of objects
/// from a parameterized type 'T'.  Clients instantiate a 'bdlcc_ObjectPool<T>'
/// where the type 'T' has no requirements.  The pool owns the memory and objects
/// it contains.  An object pool manages creation of its objects via a
/// user-installed functor (given to the pool constructor), and provides automatic
/// destruction of its objects either upon the 'destroyObject' method, or upon the
/// pool destruction.  An object can be obtained from the pool by calling the
/// 'getObject' method, and can be released back to the pool for further use
/// within 'getObject' by calling the 'releaseObject' method.
///
/// An object pool is most useful when the objects are equivalent (i.e., any
/// object in the pool can be used to satisfy an object request) and object
/// creation is potentially expensive.  Pooling enables the object to be reused at
/// a later time without going through destruction and re-creation.  For instance,
/// the object constructor may get access to some resource (e.g., a connection)
/// and the resource may remain valid after several uses and thus can be reused.
///
/// ### @ref bdlcc_queue 
///
/// The {@ref bdlcc_queue } component provides an in-place, indexable, double-ended
/// queue.  Clients instantiate a template class, 'bdlcc_Queue<T>', where type 'T'
/// is the data type of elements that the queue will hold.  Type 'T' must be
/// defined to be copyable either by a copy constructor or by 'T::operator=()';
/// class 'bdlcc_Queue' Places no additional requirements on 'T'.
///
/// ### @ref bdlcc_timequeue 
///
/// The {@ref bdlcc_timequeue } component provides an in-place, indexable queue,
/// managed in time order.  Clients instantiate a template class,
/// 'bdlcc_TimeQueue<T>', where type 'T' is the data type of elements that the
/// queue will hold.  Type 'T' must be defined to be copyable either by a copy
/// constructor or by 'T::operator=()'; class 'bdlcc_TimeQueue' places no
/// additional requirements on 'T'.
///
/// When clients add elements to a 'bdlcc_TimeQueue', they provide both the
/// element 'T' to be added and a time value, of type 'bsls::TimeInterval'.
/// Elements can be extracted individually in time order using the overloaded
/// 'popFront()' member functions; a block of elements can also be popped in a
/// single operation, 'popLE()', which pops all elements before a given time
/// value.
///
/// The 'bdlcc_TimeQueue' class template supports direct access to individual
/// queued elements based upon their 'Handle'.  This means that 'bdlcc_TimeQueue'
/// can support frequent additions and removals more efficiently than traditional
/// queue structures designed for sequential access.
///
/// @}
/** @} */