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...

T	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 <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
lunchbox::MTQueue< uint64_t > queue;
lunchbox::MTQueue< uint64_t >::Group group( NTHREADS + 1 );
#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( ));
    lunchbox::Clock clock;
    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.

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.

template<typename T , size_t S>

bool lunchbox::MTQueue< T, S >::getBack ( T & result ) const

Parameters

result the 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.

template<typename T , size_t S>

bool lunchbox::MTQueue< T, S >::getFront ( T & result ) const

Parameters

result the 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.

template<typename T, size_t S = ULONG_MAX>

size_t lunchbox::MTQueue< T, S >::getMaxSize ( ) const

inline

Returns: the current maximum size of the queue.

Version: 1.3.2

Definition at line 86 of file mtQueue.h.

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.

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.

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().

Here is the call 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.

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.

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

result	the result element, unmodified on false return value.
barrier	the 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.

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.

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.

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.

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.

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.

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

timeout	the timeout
element	the element returned

Returns: true if an element was popped

Version: 1.1

Definition at line 101 of file mtQueue.ipp.

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

timeout	the timeout to wait for an update
minimum	the minimum number of items to retrieve
maximum	the 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.

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

result the 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.

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

num	the maximum number of items to retrieve
result	the 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.

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

Classes

Public Types

Public Member Functions

Detailed Description

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

Constructor & Destructor Documentation

Member Function Documentation

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