Package bdlcc [Package Group bdl]

Provide containers that support concurrent (multi-thread) access. More...

Components
	Component bdlcc_boundedqueue
	Provide a thread-aware bounded queue of values.
	Component bdlcc_cache
	Provide a in-process cache with configurable eviction policy.
	Component bdlcc_deque
	Provide a fully thread-safe deque container.
	Component bdlcc_fixedqueue
	Provide a thread-aware fixed-size queue of values.
	Component bdlcc_fixedqueueindexmanager
	Provide thread-enabled state management for a fixed-size queue.
	Component bdlcc_multipriorityqueue
	Provide a thread-enabled parameterized multi-priority queue.
	Component bdlcc_objectcatalog
	Provide an efficient indexed, thread-safe object container.
	Component bdlcc_objectpool
	Provide a thread-safe object pool.
	Component bdlcc_queue: DEPRECATED
	Provide a thread-enabled queue of items of parameterized TYPE.
	Component bdlcc_sharedobjectpool
	Provide a thread-safe pool of shared objects.
	Component bdlcc_singleconsumerqueue
	Provide a thread-aware single consumer queue of values.
	Component bdlcc_singleconsumerqueueimpl
	Provide a testable thread-aware single consumer queue of values.
	Component bdlcc_singleproducerqueue
	Provide a thread-aware single producer queue of values.
	Component bdlcc_singleproducerqueueimpl
	Provide a testable thread-aware single producer queue of values.
	Component bdlcc_singleproducersingleconsumerboundedqueue
	Provide a thread-aware SPSC bounded queue of values.
	Component bdlcc_skiplist
	Provide a generic thread-safe Skip List.
	Component bdlcc_stripedunorderedcontainerimpl
	Provide common implementation of striped un-ordered map/multimap.
	Component bdlcc_stripedunorderedmap
	Provide a bucket-group locking (i.e., striped) unordered map.
	Component bdlcc_stripedunorderedmultimap
	Provide a bucket-group locking (striped) unordered multimap.
	Component bdlcc_timequeue
	Provide an efficient queue for time events.

---

Detailed Description

Outline

• Purpose
• MNEMONIC: Basic Development Library Concurrency Containers (bdlcc)
• Description
  • Hierarchical Synopsis
  • Component Synopsis
  • Component Overview
    • bdlcc_objectcatalog
    • bdlcc_pool
    • bdlcc_queue
    • bdlcc_timequeue

Purpose:

Provide containers that support concurrent (multi-thread) access.

MNEMONIC: Basic Development Library Concurrency Containers (bdlcc):

See also:

bdlc, bdlmt

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.

  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

Component Synopsis:

bdlcc_boundedqueue:
Provide a thread-aware bounded queue of values.

bdlcc_cache:
Provide a in-process cache with configurable eviction policy.

bdlcc_deque:
Provide a fully thread-safe deque container.

bdlcc_fixedqueue:
Provide a thread-aware fixed-size queue of values.

bdlcc_fixedqueueindexmanager:
Provide thread-enabled state management for a fixed-size queue.

bdlcc_multipriorityqueue:
Provide a thread-enabled parameterized multi-priority queue.

bdlcc_objectcatalog:
Provide an efficient indexed, thread-safe object container.

bdlcc_objectpool:
Provide a thread-safe object pool.

bdlcc_queue: DEPRECATED
Provide a thread-enabled queue of items of parameterized TYPE.

bdlcc_sharedobjectpool:
Provide a thread-safe pool of shared objects.

bdlcc_singleconsumerqueue:
Provide a thread-aware single consumer queue of values.

bdlcc_singleconsumerqueueimpl:
Provide a testable thread-aware single consumer queue of values.

bdlcc_singleproducerqueue:
Provide a thread-aware single producer queue of values.

bdlcc_singleproducerqueueimpl:
Provide a testable thread-aware single producer queue of values.

bdlcc_singleproducersingleconsumerboundedqueue:
Provide a thread-aware SPSC bounded queue of values.

bdlcc_skiplist:
Provide a generic thread-safe Skip List.

bdlcc_stripedunorderedcontainerimpl:
Provide common implementation of striped un-ordered map/multimap.

bdlcc_stripedunorderedmap:
Provide a bucket-group locking (i.e., striped) unordered map.

bdlcc_stripedunorderedmultimap:
Provide a bucket-group locking (striped) unordered multimap.

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.

bdlcc_objectcatalog:

The 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 removed. 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.

bdlcc_pool:

The 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.

bdlcc_queue:

The 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.

bdlcc_timequeue:

The 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.