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
/// @{
/// * <a href="#bdlcc-purpose"> Purpose</a>
/// * <a href="#bdlcc-mnemonic"> Mnemonic </a>
/// * <a href="#bdlcc-description"> Description </a>
///   * <a href="#bdlcc-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bdlcc-component-synopsis"> Component Synopsis </a>
///   * <a href="#bdlcc-component-overview"> Component Overview </a>
///     * <a href="#bdlcc-ref-bdlcc_objectcatalog"> @ref bdlcc_objectcatalog  </a>
///     * <a href="#bdlcc-ref-bdlcc_objectpool"> @ref bdlcc_objectpool  </a>
///     * <a href="#bdlcc-ref-bdlcc_queue"> @ref bdlcc_queue  </a>
///     * <a href="#bdlcc-ref-bdlcc_timequeue"> @ref bdlcc_timequeue  </a>
///
/// # 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 {#bdlcc-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 {#bdlcc-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 {#bdlcc-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  {#bdlcc-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::ObjectCatalog' can support frequent additions and removals more
/// efficiently than traditional queue structures designed for sequential access.
///
/// ### @ref bdlcc_objectpool  {#bdlcc-ref-bdlcc_objectpool}
///
/// The @ref bdlcc_objectpool  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  {#bdlcc-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  {#bdlcc-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.
///
/// @}
/** @} */