WorkQueue< T > Class Template Reference

A WorkQueue manages the synchronisation around a queue of work items, where a number of client threads queue tasks and a number of worker threads take and execute them. More...

#include <workqueue.h>

Public Member Functions
	WorkQueue (const std::string &name, size_t hi=0, size_t lo=1)
	Create a WorkQueue. More...
void	setTaskFreeFunc (void(*func)(T &))
	Task deleter If put() is called with the flush option, and the tasks allocate memory, you need to set this function, which will be called on each task popped from the queue. More...
bool	start (int nworkers, void *(workproc)(void *), void *arg)
	Start the worker threads. More...
bool	put (T t, bool flushprevious=false)
	Add item to work queue, called from client. More...
bool	waitIdle ()
	Wait until the queue is inactive. More...
void *	setTerminateAndWait ()
	Tell the workers to exit, and wait for them. More...
bool	take (T *tp, size_t *szp=0)
	Take task from queue. More...
bool	waitminsz (size_t sz)
void	workerExit ()
	Advertise exit and abort queue. More...
size_t	qsize ()

Detailed Description

template<class T>
class WorkQueue< T >

A WorkQueue manages the synchronisation around a queue of work items, where a number of client threads queue tasks and a number of worker threads take and execute them.

The goal is to introduce some level of parallelism between the successive steps of a previously single threaded pipeline. For example data extraction / data preparation / index update, but this could have other uses.

There is no individual task status return. In case of fatal error, the client or worker sets an end condition on the queue. A second queue could conceivably be used for returning individual task status.

The strange thread functions argument and return values comes from compatibility with an earlier pthread-based implementation.

Constructor & Destructor Documentation

WorkQueue()

template<class T >

WorkQueue< T >::WorkQueue ( const std::string &  name, size_t  hi = 0, size_t  lo = 1  )

inline

Create a WorkQueue.

Parameters

name	for message printing
hi	number of tasks on queue before clients blocks. Default 0 meaning no limit. hi == -1 means that the queue is disabled.
lo	minimum count of tasks before worker starts. Default 1.

Member Function Documentation

put()

template<class T >

bool WorkQueue< T >::put ( T  t, bool  flushprevious = false  )

inline

Add item to work queue, called from client.

Sleeps if there are already too many.

setTaskFreeFunc()

template<class T >

void WorkQueue< T >::setTaskFreeFunc ( void(*)(T &)  func )

inline

Task deleter If put() is called with the flush option, and the tasks allocate memory, you need to set this function, which will be called on each task popped from the queue.

Tasks which go through normally must be freed by the worker function.

setTerminateAndWait()

template<class T >

void* WorkQueue< T >::setTerminateAndWait ( )

inline

Tell the workers to exit, and wait for them.

Does not bother about tasks possibly remaining on the queue, so should be called after waitIdle() for an orderly shutdown.

start()

template<class T >

bool WorkQueue< T >::start ( int  nworkers, void *  workproc)(void *, void *  arg  )

inline

Start the worker threads.

Parameters

nworkers	number of threads copies to start.
start_routine	thread function. It should loop taking (QueueWorker::take()) and executing tasks.
arg	initial parameter to thread function.

Returns

true if ok.

take()

template<class T >

bool WorkQueue< T >::take ( T *  tp, size_t *  szp = 0  )

inline

Take task from queue.

Called from worker.

Sleeps if there are not enough. Signal if we go to sleep on empty queue: client may be waiting for our going idle.

waitIdle()

template<class T >

bool WorkQueue< T >::waitIdle ( )

inline

Wait until the queue is inactive.

Called from client.

Waits until the task queue is empty and the workers are all back sleeping. Used by the client to wait for all current work to be completed, when it needs to perform work that couldn't be done in parallel with the worker's tasks, or before shutting down. Work can be resumed after calling this. Note that the only thread which can call it safely is the client just above (which can control the task flow), else there could be tasks in the intermediate queues. To rephrase: there is no warranty on return that the queue is actually idle EXCEPT if the caller knows that no jobs are still being created. It would be possible to transform this into a safe call if some kind of suspend condition was set on the queue by waitIdle(), to be reset by some kind of "resume" call. Not currently the case.

workerExit()

template<class T >

void WorkQueue< T >::workerExit ( )

inline

Advertise exit and abort queue.

Called from worker

This would happen after an unrecoverable error, or when the queue is terminated by the client. Workers never exit normally, except when the queue is shut down (at which point m_ok is set to false by the shutdown code anyway). The thread must return/exit immediately after calling this.

---

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

• /home/dockes/projets/mpdupnp/libupnpp/libupnpp/workqueue.h