Component bdlcc_singleconsumerqueueimpl [Package bdlcc]

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

Namespaces
namespace	bdlcc

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Allocator Requirements
  • Exception Safety
  • Move Semantics in C++03
  • Memory Usage
  • WARNING: Synchronization Required on Destruction
  • Usage

Purpose:

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

Classes:

bdlcc::SingleConsumerQueueImpl

thread-aware single consumer TYPE queue

Description:

This component defines a type, bdlcc::SingleConsumerQueueImpl, that provides an efficient, thread-aware queue of values assuming a single consumer (the use of popFront, tryPopFront, and removeAll is done by one thread or a group of threads using external synchronization). The behavior of the methods popFront, tryPopFront, and removeAll is undefined unless the use is by a single consumer. This class is ideal for synchronization and communication between threads in a producer-consumer model when there is only one consumer thread.

The queue provides pushBack and popFront methods for pushing data into the queue and popping data from the queue. The queue will allocate memory as necessary to accommodate pushBack invocations (pushBack will never block and is provided for consistency with other containers). When the queue is empty, the popFront methods block until data appears in the queue. Non-blocking methods tryPushBack and tryPopFront are also provided. The tryPopFront method fails immediately, returning a non-zero value, if the queue is empty.

The queue may be placed into a "enqueue disabled" state using the disablePushBack method. When disabled, pushBack and tryPushBack fail immediately and return an error code. The queue may be restored to normal operation with the enablePushBack method.

The queue may be placed into a "dequeue disabled" state using the disablePopFront method. When dequeue disabled, popFront and tryPopFront fail immediately and return an error code. Any threads blocked in popFront when the queue is dequeue disabled return from popFront immediately and return an error code.

Allocator Requirements:

Access to the allocator supplied to the constructor is internally synchronized by this component. If allocations performed by this component must be synchronized with external allocations (performed outside of this component), that synchronization must be guaranteed by the user. Using a thread-safe allocator is the common way to satisfy this requirement.

Exception Safety:

A bdlcc::SingleConsumerQueueImpl is exception neutral, and all of the methods of bdlcc::SingleConsumerQueueImpl provide the basic exception safety guarantee (see bsldoc_glossary).

Move Semantics in C++03:

Move-only types are supported by bdlcc::SingleConsumerQueueImpl on C++11 platforms only (where BSLMF_MOVABLEREF_USES_RVALUE_REFERENCES is defined), and are not supported on C++03 platforms. Unfortunately, in C++03, there are user types where a bslmf::MovableRef will not safely degrade to a lvalue reference when a move constructor is not available (types providing a constructor template taking any type), so bslmf::MovableRefUtil::move cannot be used directly on a user supplied template type. See internal bug report 99039150 for more information.

Memory Usage:

bdlcc::SingleConsumerQueueImpl is most efficient when dealing with small objects or fundamental types (as a thread-safe container, its methods pass objects by value). We recommend large objects be stored as shared-pointers (or possibly raw pointers).

WARNING: Synchronization Required on Destruction:

The behavior for the destructor 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 the precondition on the destructor is met. For example, if two (or more) threads are manipulating a queue, it is not safe to anticipate the number of elements added to the queue, and destroy that queue immediately after the last element is popped (without additional synchronization) because one of the corresponding push functions may not have completed (push may, for instance, signal waiting threads after the element is considered added to the container).

Usage:

There is no usage example for this component since it is not meant for direct client use.