Lunchbox  1.14.0
Multi-threaded C++ toolbox library for all application developers creating high-performance multi-threaded programs.
Public Member Functions | List of all members
lunchbox::LFQueue< T > Class Template Reference

A thread-safe, lock-free queue with non-blocking access. More...

#include <lfQueue.h>

+ Inheritance diagram for lunchbox::LFQueue< T >:
+ Collaboration diagram for lunchbox::LFQueue< T >:

Public Member Functions

 LFQueue (const int32_t size)
 Construct a new queue. More...
 
 ~LFQueue ()
 Destruct this queue. More...
 
bool isEmpty () const
 
void clear ()
 Reset (empty) the queue. More...
 
void resize (const int32_t size)
 Resize and reset the queue. More...
 
bool pop (T &result)
 Retrieve and pop the front element from the queue. More...
 
bool getFront (T &result)
 Retrieve the front element from the queue. More...
 
bool push (const T &element)
 Push a new element to the back of the queue. More...
 
size_t getCapacity () const
 

Detailed Description

template<typename T>
class lunchbox::LFQueue< T >

A thread-safe, lock-free queue with non-blocking access.

Typically used for caches and non-blocking communication between two threads.

Current implementation constraints:

  • One reader thread
  • One writer thread
  • Fixed maximum size (writes may fail)
  • Not copyable

Example:

/* Copyright (c) 2010-2011, Stefan Eilemann <eile@equalizergraphics.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 <lunchbox/test.h>
#include <lunchbox/clock.h>
#include <lunchbox/lfQueue.h>
#include <lunchbox/thread.h>
#include <iostream>
#define RUNTIME 1000 /*ms*/
lunchbox::LFQueue< uint64_t > queue(1024);
class ReadThread : public lunchbox::Thread
{
public:
virtual ~ReadThread() {}
virtual void run()
{
uint64_t nOps = 0;
uint64_t nEmpty = 0;
uint64_t item = 0xffffffffffffffffull;
lunchbox::Clock clock;
while( clock.getTime64() < RUNTIME )
{
if( queue.getFront( item ))
{
TEST( item == nOps );
uint64_t item2 = 0xffffffffffffffffull;
TEST( queue.pop( item2 ));
TEST( item2 == item );
++nOps;
}
TEST( item + 1 == nOps );
++nEmpty;
}
const float time = clock.getTimef();
std::cout << 2*nOps/time << " reads/ms, " << nEmpty/time
<< " empty/ms" << std::endl;
}
};
int main( int, char** )
{
ReadThread reader;
uint64_t nOps = 0;
uint64_t nEmpty = 0;
TEST( reader.start( ));
lunchbox::Clock clock;
while( clock.getTime64() < RUNTIME )
{
while( queue.push( nOps ))
++nOps;
++nEmpty;
}
const float time = clock.getTimef();
TEST( reader.join( ));
std::cout << nOps/time << " writes/ms, " << nEmpty/time << " full/ms"
<< std::endl;
return EXIT_SUCCESS;
}

Definition at line 42 of file lfQueue.h.

Constructor & Destructor Documentation

template<typename T>
lunchbox::LFQueue< T >::LFQueue ( const int32_t  size)
inlineexplicit

Construct a new queue.

Version
1.0

Definition at line 46 of file lfQueue.h.

template<typename T>
lunchbox::LFQueue< T >::~LFQueue ( )
inline

Destruct this queue.

Version
1.0

Definition at line 50 of file lfQueue.h.

Member Function Documentation

template<typename T >
void lunchbox::LFQueue< T >::clear ( )

Reset (empty) the queue.

Version
1.0

Definition at line 20 of file lfQueue.ipp.

Referenced by lunchbox::LFQueue< T >::isEmpty().

+ Here is the caller graph for this function:

template<typename T>
size_t lunchbox::LFQueue< T >::getCapacity ( ) const
inline
Returns
the maximum number of elements held by the queue.
Version
1.0

Definition at line 99 of file lfQueue.h.

template<typename T >
bool lunchbox::LFQueue< T >::getFront ( T &  result)

Retrieve the front element from the queue.

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 46 of file lfQueue.ipp.

Referenced by lunchbox::LFQueue< T >::isEmpty().

+ Here is the caller graph for this function:

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

Definition at line 53 of file lfQueue.h.

References lunchbox::LFQueue< T >::clear(), lunchbox::LFQueue< T >::getFront(), lunchbox::LFQueue< T >::pop(), lunchbox::LFQueue< T >::push(), and lunchbox::LFQueue< T >::resize().

+ Here is the call graph for this function:

template<typename T >
bool lunchbox::LFQueue< T >::pop ( T &  result)

Retrieve and pop the front element from the queue.

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 35 of file lfQueue.ipp.

Referenced by lunchbox::LFQueue< T >::isEmpty().

+ Here is the caller graph for this function:

template<typename T >
bool lunchbox::LFQueue< T >::push ( const T &  element)

Push a new element to the back of the queue.

Parameters
elementthe element to add.
Returns
true if the element was placed, false if the queue is full
Version
1.0

Definition at line 56 of file lfQueue.ipp.

Referenced by lunchbox::LFQueue< T >::isEmpty().

+ Here is the caller graph for this function:

template<typename T >
void lunchbox::LFQueue< T >::resize ( const int32_t  size)

Resize and reset the queue.

This method is not thread-safe. The queue has to be empty.

Version
1.0

Definition at line 27 of file lfQueue.ipp.

Referenced by lunchbox::LFQueue< T >::isEmpty().

+ Here is the caller graph for this function:

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