LockFreeCallQueue Class Reference

Allows a function call to be executed on a different thread, in a fast lock-safe and thread-safe manner. More...

#include <nonblocking_call_queue.h>

Public Member Functions
	LockFreeCallQueue (int RingBufferSize)
bool	isEmpty ()
	return true if the queue is empty.
int	getFreeSpace ()
	Return the amount of free space in the queue. More...
template<class Functor >
bool	callf (Functor const &f)
	Calls a function, via the queue, on a different thread. More...
bool	synchronize ()
	Execute all the calls in the queue. More...
void	stop ()

Detailed Description

Allows a function call to be executed on a different thread, in a fast lock-safe and thread-safe manner.

A function call queue which enables functions to be called asychronously on another thread. This is a one-reader, one-writer FIFO. You should be using callf() from a single thread, and calling synchronize on a different single thread. If you need two threads to communicate in both directions in a lock free fashion then use two LockFreeCallQueue objects.

It has the following special features:

• No locking
• Avoids using the system allocator except during the constructor.

Watch out for:

• Objects you pass as function arguments, which are passed by value, doing memory allocation, which may result in a lock.

Unit Tests

A unit-test is provided in the _tests directory which be useful reference.

Member Function Documentation

template<class Functor >

bool LockFreeCallQueue::callf ( Functor const &  f )

inline

Calls a function, via the queue, on a different thread.

Add a function to the queue. Use std::bind to call the function like this:

class MyClass {
public:
    void queueUpdateJob() {
        queue.callf(std::bind(&MyClass::doSomething, this, i, j);
    }
private:
    void update(int i, int j) {
        // stuff happens.
    }
    LockFreeCallQueue queue;
};

int LockFreeCallQueue::getFreeSpace ( )

inline

Return the amount of free space in the queue.

If the queue does not have enough free space your callf() call will be dropped which may be a problem. You may want to check the result of this function call during debugging. And bear in mind there are no guarantees of it not filling up during operation - so if something is critical and your application will fail if it doesn't get through you may need to think about some signalling back.

void LockFreeCallQueue::stop ( )

inline

Disables the this LockFreeCallQueue. You may need to use this during shutdown to avoid threads continuing to put work, and objects, into a queue that no longer has anyone executing it. It's probably not a big deal in an application, but in a plugin you could end up with memory leaks or or stuff if resources are being held by objects in the queue.

Todo:

: put in a proper example of when this might be important.

bool LockFreeCallQueue::synchronize ( )

inline

Execute all the calls in the queue.

Call this function in the target thread. When this function is called all the calls added with callf will be executed.

Returns

true if there was anything in the queue, false if the queue was empty.

---

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

• source/nonblocking_call_queue.h