Component bdlcc_singleproducerqueueimpl [Package bdlcc]

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

Namespaces
namespace	bdlcc

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Exception safety
  • Move Semantics in C++03
  • Memory Usage
  • Usage

Purpose:

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

Classes:

bdlcc::SingleProducerQueueImpl

thread-aware single producer TYPE queue

Description:

This component defines a type, bdlcc::SingleProducerQueueImpl, that provides an efficient, thread-aware queue of values assuming a single producer (the use of pushBack and tryPushBack is done by one thread or a group of threads using external synchronization). The behavior of the methods pushBack and tryPushBack is undefined unless the use is by a single producer. This class is ideal for synchronization and communication between threads in a producer-consumer model when there is only one producer 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.

Exception safety:

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

Move Semantics in C++03:

Move-only types are supported by bdlcc::SingleProducerQueueImpl 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::SingleProducerQueueImpl 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).

Usage:

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