Lunchbox  1.15.0
Multi-threaded C++ toolbox library for all application developers creating high-performance multi-threaded programs.
lunchbox::MTQueue< T, S > Class Template Reference

A thread-safe queue with a blocking read access. More...

#include <mtQueue.h>

+ Collaboration diagram for lunchbox::MTQueue< T, S >:

Classes

class  Group
 Group descriptor for popBarrier(). More...
 

Public Types

typedef T value_type
 

Public Member Functions

 MTQueue (const size_t maxSize=S)
 Construct a new queue. More...
 
 MTQueue (const MTQueue< T, S > &from)
 Construct a copy of a queue. More...
 
 ~MTQueue ()
 Destruct this Queue. More...
 
MTQueue< T, S > & operator= (const MTQueue< T, S > &from)
 Assign the values of another queue. More...
 
const T & operator[] (const size_t index) const
 Retrieve the requested element from the queue, may block. More...
 
bool isEmpty () const
 
size_t getSize () const
 
void setMaxSize (const size_t maxSize)
 Set the new maximum size of the queue. More...
 
size_t getMaxSize () const
 
size_t waitSize (const size_t minSize) const
 Wait for the size to be at least the number of given elements. More...
 
void clear ()
 Reset (empty) the queue. More...
 
pop ()
 Retrieve and pop the front element from the queue, may block. More...
 
bool timedPop (const unsigned timeout, T &element)
 Retrieve and pop the front element from the queue. More...
 
std::vector< T > timedPopRange (const unsigned timeout, const size_t minimum=1, const size_t maximum=S)
 Retrieve a number of items from the front of the queue. More...
 
bool tryPop (T &result)
 Retrieve and pop the front element from the queue if it is not empty. More...
 
void tryPop (const size_t num, std::vector< T > &result)
 Try to retrieve a number of items from the front of the queue. More...
 
bool popBarrier (T &result, Group &barrier)
 Retrieve the front element, or abort if the barrier is reached. More...
 
bool getFront (T &result) const
 
bool getBack (T &result) const
 
void push (const T &element)
 Push a new element to the back of the queue. More...
 
void push (const std::vector< T > &elements)
 Push a vector of elements to the back of the queue. More...
 
void pushFront (const T &element)
 Push a new element to the front of the queue. More...
 
void pushFront (const std::vector< T > &elements)
 Push a vector of elements to the front of the queue. More...
 
STL compatibility. @version 1.7.1
void push_back (const T &element)
 
bool empty () const
 

Detailed Description

template<typename T, size_t S = ULONG_MAX>
class lunchbox::MTQueue< T, S >

A thread-safe queue with a blocking read access.

Typically used to communicate between two execution threads.

S is deprecated by the ctor param maxSize, and defines the initial maximum capacity of the Queue<T>. When the capacity is reached, pushing new values blocks until items have been consumed.

Example:

/* Copyright (c) 2010-2013, Stefan Eilemann <eile@equalizergraphics.com>
* 2012, Daniel Nachbaur <danielnachbaur@gmail.com>
*
* This library is free software; you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License version 2.1 as published
* by the Free Software Foundation.
*
* This library 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 Lesser General Public License for more
* details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this library; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
#include <pthread.h>
#include <lunchbox/test.h>
#include <lunchbox/clock.h>
#include <lunchbox/compiler.h>
#include <lunchbox/mtQueue.h>
#include <lunchbox/thread.h>
#include <iostream>
#define NOPS 100000
#define NTHREADS 4
#ifdef LB_GCC_4_6_OR_LATER
# pragma GCC diagnostic ignored "-Wunused-but-set-variable"
#endif
class ReadThread : public lunchbox::Thread
{
public:
virtual ~ReadThread() {}
virtual void run() { run_(); }
static void run_()
{
uint64_t item = 0xffffffffffffffffull;
#ifndef NDEBUG
uint64_t last = 0;
#endif
while( queue.popBarrier( item, group ))
{
#ifndef NDEBUG
TESTINFO( last < item, last << " >= " << item );
last = item;
#endif
}
TEST( queue.isEmpty( ));
}
};
int main( int, char** )
{
ReadThread reader[ NTHREADS ];
for( size_t i = 0; i < NTHREADS; ++i )
TEST( reader[i].start( ));
for( size_t i = 1 ; i < NOPS; ++i )
queue.push( i );
const float time = clock.getTimef();
ReadThread::run_();
for( size_t i = 0; i < NTHREADS; ++i )
TEST( reader[i].join( ));
std::cout << NOPS/time << " writes/ms" << std::endl;
return EXIT_SUCCESS;
}

Definition at line 43 of file mtQueue.h.

Constructor & Destructor Documentation

template<typename T, size_t S = ULONG_MAX>
lunchbox::MTQueue< T, S >::MTQueue ( const size_t  maxSize = S)
inlineexplicit

Construct a new queue.

Version
1.0

Definition at line 52 of file mtQueue.h.

template<typename T, size_t S = ULONG_MAX>
lunchbox::MTQueue< T, S >::MTQueue ( const MTQueue< T, S > &  from)
inline

Construct a copy of a queue.

Version
1.0

Definition at line 55 of file mtQueue.h.

template<typename T, size_t S = ULONG_MAX>
lunchbox::MTQueue< T, S >::~MTQueue ( )
inline

Destruct this Queue.

Version
1.0

Definition at line 58 of file mtQueue.h.

References lunchbox::MTQueue< T, S >::operator=(), and lunchbox::MTQueue< T, S >::operator[]().

+ Here is the call graph for this function:

Member Function Documentation

template<typename T , size_t S>
void lunchbox::MTQueue< T, S >::clear ( )

Reset (empty) the queue.

Version
1.0

Definition at line 77 of file mtQueue.ipp.

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the caller graph for this function:

template<typename T , size_t S>
bool lunchbox::MTQueue< T, S >::getBack ( T &  result) const
Parameters
resultthe last value or unmodified.
Returns
true if an element was placed in result, false if the queue is empty.
Version
1.0

Definition at line 242 of file mtQueue.ipp.

References lunchbox::Condition::lock(), and lunchbox::Condition::unlock().

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename T , size_t S>
bool lunchbox::MTQueue< T, S >::getFront ( T &  result) const
Parameters
resultthe front value or unmodified.
Returns
true if an element was placed in result, false if the queue is empty.
Version
1.0

Definition at line 227 of file mtQueue.ipp.

References lunchbox::Condition::lock(), and lunchbox::Condition::unlock().

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename T, size_t S = ULONG_MAX>
size_t lunchbox::MTQueue< T, S >::getSize ( ) const
inline
Returns
the number of items currently in the queue.
Version
1.0

Definition at line 73 of file mtQueue.h.

References lunchbox::MTQueue< T, S >::setMaxSize().

+ Here is the call graph for this function:

template<typename T, size_t S = ULONG_MAX>
bool lunchbox::MTQueue< T, S >::isEmpty ( ) const
inline
Returns
true if the queue is empty, false otherwise.
Version
1.0

Definition at line 70 of file mtQueue.h.

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the caller graph for this function:

template<typename T , size_t S>
MTQueue< T, S > & lunchbox::MTQueue< T, S >::operator= ( const MTQueue< T, S > &  from)

Assign the values of another queue.

Version
1.0

Definition at line 22 of file mtQueue.ipp.

References lunchbox::Condition::lock(), and lunchbox::Condition::unlock().

Referenced by lunchbox::MTQueue< T, S >::~MTQueue().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename T , size_t S>
const T & lunchbox::MTQueue< T, S >::operator[] ( const size_t  index) const

Retrieve the requested element from the queue, may block.

Version
1.3.2

Definition at line 41 of file mtQueue.ipp.

Referenced by lunchbox::MTQueue< T, S >::~MTQueue().

+ Here is the caller graph for this function:

template<typename T , size_t S>
T lunchbox::MTQueue< T, S >::pop ( )

Retrieve and pop the front element from the queue, may block.

Version
1.0

Definition at line 86 of file mtQueue.ipp.

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the caller graph for this function:

template<typename T , size_t S>
bool lunchbox::MTQueue< T, S >::popBarrier ( T &  result,
Group barrier 
)

Retrieve the front element, or abort if the barrier is reached.

Used for worker threads recursively processing data, pushing it back the queue. Either returns an item from the queue, or aborts if num participants are waiting in the queue.

Parameters
resultthe result element, unmodified on false return value.
barrierthe group's barrier handle.
Returns
true if an element was retrieved, false if the barrier height was reached.
Version
1.7.1

Definition at line 200 of file mtQueue.ipp.

References lunchbox::Condition::broadcast(), lunchbox::Condition::lock(), lunchbox::Condition::signal(), lunchbox::Condition::unlock(), and lunchbox::Condition::wait().

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename T , size_t S>
void lunchbox::MTQueue< T, S >::push ( const T &  element)

Push a new element to the back of the queue.

Version
1.0

Definition at line 257 of file mtQueue.ipp.

References lunchbox::Condition::lock(), lunchbox::Condition::signal(), lunchbox::Condition::unlock(), and lunchbox::Condition::wait().

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename T , size_t S>
void lunchbox::MTQueue< T, S >::push ( const std::vector< T > &  elements)

Push a vector of elements to the back of the queue.

Version
1.0

Definition at line 268 of file mtQueue.ipp.

References lunchbox::Condition::lock(), lunchbox::Condition::signal(), lunchbox::Condition::unlock(), and lunchbox::Condition::wait().

+ Here is the call graph for this function:

template<typename T , size_t S>
void lunchbox::MTQueue< T, S >::pushFront ( const T &  element)

Push a new element to the front of the queue.

Version
1.0

Definition at line 280 of file mtQueue.ipp.

References lunchbox::Condition::lock(), lunchbox::Condition::signal(), lunchbox::Condition::unlock(), and lunchbox::Condition::wait().

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename T , size_t S>
void lunchbox::MTQueue< T, S >::pushFront ( const std::vector< T > &  elements)

Push a vector of elements to the front of the queue.

Version
1.0

Definition at line 291 of file mtQueue.ipp.

References lunchbox::Condition::lock(), lunchbox::Condition::signal(), lunchbox::Condition::unlock(), and lunchbox::Condition::wait().

+ Here is the call graph for this function:

template<typename T , size_t S>
void lunchbox::MTQueue< T, S >::setMaxSize ( const size_t  maxSize)

Set the new maximum size of the queue.

If the new maximum size is less the current size of the queue, this call will block until the queue reaches the new maximum size.

Version
1.3.2

Definition at line 54 of file mtQueue.ipp.

Referenced by lunchbox::MTQueue< T, S >::getSize().

+ Here is the caller graph for this function:

template<typename T , size_t S>
bool lunchbox::MTQueue< T, S >::timedPop ( const unsigned  timeout,
T &  element 
)

Retrieve and pop the front element from the queue.

Parameters
timeoutthe timeout
elementthe element returned
Returns
true if an element was popped
Version
1.1

Definition at line 101 of file mtQueue.ipp.

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the caller graph for this function:

template<typename T , size_t S>
std::vector< T > lunchbox::MTQueue< T, S >::timedPopRange ( const unsigned  timeout,
const size_t  minimum = 1,
const size_t  maximum = S 
)

Retrieve a number of items from the front of the queue.

Between minimum and maximum number of items are returned in a vector. If the queue has less than minimum number of elements on timeout, the result vector is empty. The method returns as soon as there are at least minimum elements available, i.e., it does not wait for the maximum to be reached.

Note that this method might block up to 'minimum * timeout' milliseconds, that is, the timeout defines the time to wait for an update on the queue.

Parameters
timeoutthe timeout to wait for an update
minimumthe minimum number of items to retrieve
maximumthe maximum number of items to retrieve
Returns
an empty vector on timeout, otherwise the result vector containing between minimum and maximum elements.
Version
1.7.0

Definition at line 121 of file mtQueue.ipp.

References LB_MIN.

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the caller graph for this function:

template<typename T , size_t S>
bool lunchbox::MTQueue< T, S >::tryPop ( T &  result)

Retrieve and pop the front element from the queue if it is not empty.

Parameters
resultthe front value or unmodified.
Returns
true if an element was placed in result, false if the queue is empty.
Version
1.0

Definition at line 147 of file mtQueue.ipp.

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the caller graph for this function:

template<typename T , size_t S>
void lunchbox::MTQueue< T, S >::tryPop ( const size_t  num,
std::vector< T > &  result 
)

Try to retrieve a number of items from the front of the queue.

Between zero and the given number of items are appended to the vector.

Parameters
numthe maximum number of items to retrieve
resultthe front value or unmodified.
Returns
true if an element was placed in result, false if the queue is empty.
Version
1.1.6

Definition at line 164 of file mtQueue.ipp.

References LB_MIN.

template<typename T , size_t S>
size_t lunchbox::MTQueue< T, S >::waitSize ( const size_t  minSize) const

Wait for the size to be at least the number of given elements.

Returns
the current size when the condition was fulfilled.
Version
1.0

Definition at line 65 of file mtQueue.ipp.

Referenced by lunchbox::MTQueue< T, S >::getMaxSize().

+ Here is the caller graph for this function:


The documentation for this class was generated from the following files: