source: trunk/yat/utility/Queue.h @ 3060

#ifndef theplu_yat_utility_queue
#define theplu_yat_utility_queue

// $Id: Queue.h 3060 2013-07-02 00:04:54Z peter $
//
// Copyright (C) 2013 Peter Johansson
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.

#include <boost/thread.hpp>

#include <deque>

namespace theplu {
namespace yat {
namespace utility {

  /**
     \brief Multi-thread safe queue

     This class provides a multi-thread safe queue. The Queue is
     typically shared by multiple threads such that some threads push
     elements and some pop elements. The Queue is a "first in first
     out" container and holds the same functionality as the similar
     <a href="http://www.sgi.com/tech/stl/queue.html">std::queue</a>. The
     difference is that Queue is multi-thread safe, in other words,
     when one thread access the Queue, other threads are locked out
     from access so that only one thread touches the Queue at a time
     and its behaviour is well defined. In a single-thread application
     there is no point in using the class as std::queue should be
     prefereble.

     \since New in yat 0.11
   */
  template<typename T>
  class Queue
  {
  public:
    /// Type of object stored in Queue
    typedef T value_type;

    /**
       An unsigned integral type. \see size(void)
    */
    typedef typename std::deque<T>::size_type size_type;

    /**
       \return \c true if container's size is zero
     */
    bool empty(void) const
    {
      boost::unique_lock<boost::mutex> lock(mutex_);
      return q_.empty();
    } // lock is released here


    /**
       \brief access next element is queue

       Access the next element is queue. If container is empty,
       process is waiting until other process is inserting element
       into container.
     */
    void pop(T& value)
    {
      boost::unique_lock<boost::mutex> lock(mutex_);
      while (q_.empty())
        condition_.wait(lock);
      // The obvious choice would be to create a temp copy of front,
      // pop the queue and then return by-value. This is, however,
      // dangerous becasue if the copy constructor throws, the queue
      // has been popped and the element is lost. Instead we choose to
      // pass via passed reference.
      value = q_.front();
      q_.pop_front();
    } // lock is released here


    /**
       \brief insert an element into container
     */
    void push(const T& t)
    {
      boost::unique_lock<boost::mutex> lock(mutex_);
      q_.push_back(t);
      lock.unlock(); // unlock the mutex

      // Notify others that data is ready after we have unlocked
      condition_.notify_one();
    }


    /**
       \return Number of elements stored in container
     */
    size_type size(void) const
    {
      boost::unique_lock<boost::mutex> lock(mutex_);
      return q_.size();
    } // lock is released here


    /**
       If Queue is empty() do nothing and return \c false, else pop
       the element into \a value and return \c true
     */
    bool try_pop(T& value)
    {
      boost::unique_lock<boost::mutex> lock(mutex_);
      if (q_.empty())
        return false;
      value = q_.front();
      q_.pop_front();
      return true;
    } // lock is released here

  private:
    std::deque<T> q_;
    mutable boost::mutex mutex_;
    boost::condition_variable condition_;
  };

}}}
#endif