Component bdlcc_singleproducerqueue [Package bdlcc]

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

Namespaces
namespace	bdlcc

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Template Requirements
  • Exception safety
  • Move Semantics in C++03
  • Usage
    • Example 1: A Simple Thread Pool

Purpose:

Provide a thread-aware single producer queue of values.

Classes:

bdlcc::SingleProducerQueue

thread-aware single producer queue of TYPE

Description:

This component defines a type, bdlcc::SingleProducerQueue, 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.

Template Requirements:

bdlcc::SingleProducerQueue is a template that is parameterized on the type of element contained within the queue. The supplied template argument, TYPE, must provide both a default constructor and a copy constructor, as well as an assignment operator. If the default constructor accepts a bslma::Allocator *, TYPE must declare the uses bslma::Allocator trait (see bslma_usesbslmaallocator) so that the allocator of the queue is propagated to the elements contained in the queue.

Exception safety:

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

Move Semantics in C++03:

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

Usage:

This section illustrates intended use of this component.

Example 1: A Simple Thread Pool:

In the following example a bdlcc::SingleProducerQueue is used to communicate between a single "producer" thread and multiple "consumer" threads. The "producer" will push work requests onto the queue, and each "consumer" will iteratively take a work request from the queue and service the request. This example shows a partial, simplified implementation of the bdlmt::FixedThreadPool class. See component bdlmt_fixedthreadpool for more information.

First, we define a utility classes that handles a simple "work item":

  struct my_WorkData {
      // Work data...
  };

  struct my_WorkRequest {
      enum RequestType {
          e_WORK = 1,
          e_STOP = 2
      };

      RequestType d_type;
      my_WorkData d_data;
      // Work data...
  };

Next, we provide a simple function to service an individual work item. The details are unimportant for this example:

  void myDoWork(my_WorkData& data)
  {
      // do some stuff...
      (void)data;
  }

Then, we define a myConsumer function that will pop elements off the queue and process them. Note that the call to queue->popFront(&item) will block until there is an element available on the queue. This function will be executed in multiple threads, so that each thread waits in queue->popFront(&item), and bdlcc::SingleProducerQueue guarantees that each thread gets a unique element from the queue:

  void myConsumer(bdlcc::SingleProducerQueue<my_WorkRequest> *queue)
  {
      while (1) {
          // 'popFront()' will wait for a 'my_WorkRequest' until available.

          my_WorkRequest item;
          queue->popFront(&item);
          if (item.d_type == my_WorkRequest::e_STOP) { break; }
          myDoWork(item.d_data);
      }
  }

Finally, we define a myProducer function that serves multiple roles: it creates the bdlcc::SingleProducerQueue, starts the consumer threads, and then produces and enqueues work items. When work requests are exhausted, this function enqueues one e_STOP item for each consumer queue. This e_STOP item indicates to the consumer thread to terminate its thread-handling function.

Note that, although the producer cannot control which thread pops a particular work item, it can rely on the knowledge that each consumer thread will read a single e_STOP item and then terminate.

  void myProducer(int numThreads)
  {
      enum {
          k_NUM_WORK_ITEMS = 1000
      };

      bdlcc::SingleProducerQueue<my_WorkRequest> queue;

      bslmt::ThreadGroup consumerThreads;
      consumerThreads.addThreads(bdlf::BindUtil::bind(&myConsumer, &queue),
                                 numThreads);

      for (int i = 0; i < k_NUM_WORK_ITEMS; ++i) {
          my_WorkRequest item;
          item.d_type = my_WorkRequest::e_WORK;
          item.d_data = my_WorkData(); // some stuff to do
          queue.pushBack(item);
      }

      for (int i = 0; i < numThreads; ++i) {
          my_WorkRequest item;
          item.d_type = my_WorkRequest::e_STOP;
          queue.pushBack(item);
      }

      consumerThreads.joinAll();
  }