LCOV - code coverage report
Current view: top level - lunchbox - mtQueue.h (source / functions) Hit Total Coverage
Test: lcov2.info Lines: 2 3 66.7 %
Date: 2014-10-01 Functions: 3 5 60.0 %

          Line data    Source code
       1             : 
       2             : /* Copyright (c) 2005-2013, Stefan Eilemann <eile@equalizergraphics.com>
       3             :  *                    2012, Daniel Nachbaur <danielnachbaur@gmail.com>
       4             :  *
       5             :  * This library is free software; you can redistribute it and/or modify it under
       6             :  * the terms of the GNU Lesser General Public License version 2.1 as published
       7             :  * by the Free Software Foundation.
       8             :  *
       9             :  * This library is distributed in the hope that it will be useful, but WITHOUT
      10             :  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
      11             :  * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
      12             :  * details.
      13             :  *
      14             :  * You should have received a copy of the GNU Lesser General Public License
      15             :  * along with this library; if not, write to the Free Software Foundation, Inc.,
      16             :  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
      17             :  */
      18             : 
      19             : #ifndef LUNCHBOX_MTQUEUE_H
      20             : #define LUNCHBOX_MTQUEUE_H
      21             : 
      22             : #include <lunchbox/condition.h>
      23             : #include <lunchbox/debug.h>
      24             : 
      25             : #include <algorithm>
      26             : #include <limits.h>
      27             : #include <queue>
      28             : #include <string.h>
      29             : 
      30             : namespace lunchbox
      31             : {
      32             : /**
      33             :  * A thread-safe queue with a blocking read access.
      34             :  *
      35             :  * Typically used to communicate between two execution threads.
      36             :  *
      37             :  * S is deprecated by the ctor param maxSize, and defines the initial maximum
      38             :  * capacity of the Queue<T>.  When the capacity is reached, pushing new values
      39             :  * blocks until items have been consumed.
      40             :  *
      41             :  * Example: @include tests/mtQueue.cpp
      42             :  */
      43             : template< typename T, size_t S = ULONG_MAX > class MTQueue
      44             : // S = std::numeric_limits< size_t >::max() does not work:
      45             : //   http://gcc.gnu.org/bugzilla/show_bug.cgi?id=6424
      46             : {
      47             : public:
      48             :     class Group;
      49             :     typedef T value_type;
      50             : 
      51             :     /** Construct a new queue. @version 1.0 */
      52           2 :     explicit MTQueue( const size_t maxSize = S ) : _maxSize( maxSize ) {}
      53             : 
      54             :     /** Construct a copy of a queue. @version 1.0 */
      55             :     MTQueue( const MTQueue< T, S >& from )  { *this = from; }
      56             : 
      57             :     /** Destruct this Queue. @version 1.0 */
      58           0 :     ~MTQueue() {}
      59             : 
      60             :     /** Assign the values of another queue. @version 1.0 */
      61             :     MTQueue< T, S >& operator = ( const MTQueue< T, S >& from );
      62             : 
      63             :     /**
      64             :      * Retrieve the requested element from the queue, may block.
      65             :      * @version 1.3.2
      66             :      */
      67             :     const T& operator[]( const size_t index ) const;
      68             : 
      69             :     /** @return true if the queue is empty, false otherwise. @version 1.0 */
      70           5 :     bool isEmpty() const { return _queue.empty(); }
      71             : 
      72             :     /** @return the number of items currently in the queue. @version 1.0 */
      73             :     size_t getSize() const { return _queue.size(); }
      74             : 
      75             :     /**
      76             :      * Set the new maximum size of the queue.
      77             :      *
      78             :      * If the new maximum size is less the current size of the queue, this
      79             :      * call will block until the queue reaches the new maximum size.
      80             :      *
      81             :      * @version 1.3.2
      82             :      */
      83             :     void setMaxSize( const size_t maxSize );
      84             : 
      85             :     /** @return the current maximum size of the queue. @version 1.3.2 */
      86             :     size_t getMaxSize() const { return _maxSize; }
      87             : 
      88             :     /**
      89             :      * Wait for the size to be at least the number of given elements.
      90             :      *
      91             :      * @return the current size when the condition was fulfilled.
      92             :      * @version 1.0
      93             :      */
      94             :     size_t waitSize( const size_t minSize ) const;
      95             : 
      96             :     /** Reset (empty) the queue. @version 1.0 */
      97             :     void clear();
      98             : 
      99             :     /**
     100             :      * Retrieve and pop the front element from the queue, may block.
     101             :      * @version 1.0
     102             :      */
     103             :     T pop();
     104             : 
     105             :     /**
     106             :      * Retrieve and pop the front element from the queue.
     107             :      *
     108             :      * @param timeout the timeout
     109             :      * @param element the element returned
     110             :      * @return true if an element was popped
     111             :      * @version 1.1
     112             :      */
     113             :     bool timedPop( const unsigned timeout, T& element );
     114             : 
     115             :     /**
     116             :      * Retrieve a number of items from the front of the queue.
     117             :      *
     118             :      * Between minimum and maximum number of items are returned in a vector. If
     119             :      * the queue has less than minimum number of elements on timeout, the result
     120             :      * vector is empty. The method returns as soon as there are at least minimum
     121             :      * elements available, i.e., it does not wait for the maximum to be reached.
     122             :      *
     123             :      * Note that this method might block up to 'minimum * timeout' milliseconds,
     124             :      * that is, the timeout defines the time to wait for an update on the queue.
     125             :      *
     126             :      * @param timeout the timeout to wait for an update
     127             :      * @param minimum the minimum number of items to retrieve
     128             :      * @param maximum the maximum number of items to retrieve
     129             :      * @return an empty vector on timeout, otherwise the result vector
     130             :      *         containing between minimum and maximum elements.
     131             :      * @version 1.7.0
     132             :      */
     133             :     std::vector< T > timedPopRange( const unsigned timeout,
     134             :                                     const size_t minimum = 1,
     135             :                                     const size_t maximum = S );
     136             : 
     137             :     /**
     138             :      * Retrieve and pop the front element from the queue if it is not empty.
     139             :      *
     140             :      * @param result the front value or unmodified.
     141             :      * @return true if an element was placed in result, false if the queue
     142             :      *         is empty.
     143             :      * @version 1.0
     144             :      */
     145             :     bool tryPop( T& result );
     146             : 
     147             :     /**
     148             :      * Try to retrieve a number of items from the front of the queue.
     149             :      *
     150             :      * Between zero and the given number of items are appended to the vector.
     151             :      *
     152             :      * @param num the maximum number of items to retrieve
     153             :      * @param result the front value or unmodified.
     154             :      * @return true if an element was placed in result, false if the queue
     155             :      *         is empty.
     156             :      * @version 1.1.6
     157             :      */
     158             :     void tryPop( const size_t num, std::vector< T >& result );
     159             : 
     160             :     /**
     161             :      * Retrieve the front element, or abort if the barrier is reached
     162             :      *
     163             :      * Used for worker threads recursively processing data, pushing it back the
     164             :      * queue. Either returns an item from the queue, or aborts if num
     165             :      * participants are waiting in the queue.
     166             :      *
     167             :      * @param result the result element, unmodified on false return value.
     168             :      * @param barrier the group's barrier handle.
     169             :      * @return true if an element was retrieved, false if the barrier height
     170             :      *         was reached.
     171             :      * @version 1.7.1
     172             :      */
     173             :     bool popBarrier( T& result, Group& barrier );
     174             : 
     175             :     /**
     176             :      * @param result the front value or unmodified.
     177             :      * @return true if an element was placed in result, false if the queue
     178             :      *         is empty.
     179             :      * @version 1.0
     180             :      */
     181             :     bool getFront( T& result ) const;
     182             : 
     183             :     /**
     184             :      * @param result the last value or unmodified.
     185             :      * @return true if an element was placed in result, false if the queue
     186             :      *         is empty.
     187             :      * @version 1.0
     188             :      */
     189             :     bool getBack( T& result ) const;
     190             : 
     191             :     /** Push a new element to the back of the queue. @version 1.0 */
     192             :     void push( const T& element );
     193             : 
     194             :     /** Push a vector of elements to the back of the queue. @version 1.0 */
     195             :     void push( const std::vector< T >& elements );
     196             : 
     197             :     /** Push a new element to the front of the queue. @version 1.0 */
     198             :     void pushFront( const T& element );
     199             : 
     200             :     /** Push a vector of elements to the front of the queue. @version 1.0 */
     201             :     void pushFront( const std::vector< T >& elements );
     202             : 
     203             :     /** @name STL compatibility. @version 1.7.1 */
     204             :     //@{
     205             :     void push_back( const T& element ) { push( element ); }
     206             :     bool empty() const { return isEmpty(); }
     207             :     //@}
     208             : 
     209             : private:
     210             :     std::deque< T > _queue;
     211             :     mutable Condition _cond;
     212             :     size_t _maxSize;
     213             : };
     214             : }
     215             : 
     216             : #include "mtQueue.ipp" // template implementation
     217             : 
     218             : #endif //LUNCHBOX_MTQUEUE_H

Generated by: LCOV version 1.10