karoo::exeque Class Reference

An exeque is a convenient way to manage things that need to be run in a single thread. More...

#include <queue.h>

Inheritance diagram for karoo::exeque:

List of all members.

Public Member Functions
	exeque (long granularity=0, int time_sample_alloc_size=100)
	Construct a new exeque.
virtual	~exeque ()
	Destroy the queue.
void	setLogger (const log &logger)
	Set the logger object.
bool	start (long granularity=5, bool take_over=false)
	Start the exeque.
void	stop (bool block=false)
	Stop the exeque.
void	join ()
	Wait until the runner thread has actually stopped (times out after 50 seconds).
bool	isStopped (long wait_usec=0) const
	Query the queue to see if it has stopped.
void	refuse ()
	refuse to add any more pebbles to the queue
void	add (pebble *p)
	Add a pebble to the queue, to be run synchronously in first-in, first-out order, as soon as possible.
void	add (const struct timespec &ts, pebble *p)
	Add a pebble to the queue, to be run synchronously after a specified timestamp.
void	add (int after_seconds, pebble *p, long after_nano_seconds=0)
	Add a pebble to the queue, to be run synchronously after a specified delay.
void	run ()
	This method should only ever called by the pthread that runs it.
void	reset (long granularity=0, int time_sample_alloc_size=100)
	This method causes the queue to stop, and it waits until it has really stopped, and then resets everything (except for the inbox).
const qstats &	getStats (qstats &qs, bool reset=false) const
	Get statistics about how this queue is performing.
int	getBusyPercent (bool reset=false)
	Get the percentage that the queue is busy.
int	getRunCount (bool reset=false)
	Get the number of times that pebbles have been run in this queue.
int	getErrorCount (bool reset=false)
	Get the number of exceptions that have been caught from pebbles run in the queue.
int	getTimeoutCount (bool reset=false)
	Get the number of times the runner thread has timed out while waiting for a pebble to become available to execute.
int	getWaitingCount () const
	Get the number of pebbles that are waiting for their timestamp to come up.
int	getQueuedCount () const
	Get the number of pebbles queued.
int	getImminentCount (unsigned usecs=0) const
	Get the number of pebbles that are scheduled and imminent to run.
bool	hasBeenIdleSince (const struct timespec &comp) const
	Find out if the queue has been idle since a specified past-dated timestamp.
pthread_t	getThread ()
	Return the runner thread.
sigjmp_buf &	getSigLongJmpEnv ()
	Get the sigjmp_buf object that the runner queue uses for handling exceptions (such as segfault, div_zero) caught when running a pebble.
Protected Attributes
multimap< const struct timespec, pebble *, exeque_comp >	inbox
	Contains all the pebbles waiting for execution.
karoo_mutex	inbox_sem
	This semaphore is used to lock accesses to the inbox.
karoo_cond	inbox_notifier
	This semaphore is used to notify the runner thread when it is waiting, that a new pebble has been added to the inbox which may be ready for execution now.
log	logger
	This variable will be true only when the runner thread is waiting for a pebble to run.
Friends
class	exepool

---

Detailed Description

An exeque is a convenient way to manage things that need to be run in a single thread.

You can add as many pebbles (task objects) to the exeque as you like, and they will be executed synchronously in the order you added them. You can also add then with a timestamp set in the future. Then they will be executed after that date.

---

Constructor & Destructor Documentation

karoo::exeque::exeque	(	long	granularity = 0,
		int	time_sample_alloc_size = 100
	)

Construct a new exeque.

Parameters:

	granularity	this is a time in seconds that is the maximum time things should ever wait inside this queue. If it is zero, then the queue is not automatically started during construction.
	time_sample_alloc_size	the number of time samples that should be collected for statistical purposes (returned by the getStats method.)

virtual karoo::exeque::~exeque

(

)

[virtual]

Destroy the queue.

Note that it's very important to call exeque::stop(true) before destroying the queue, to avoid race conditions.

---

Member Function Documentation

void karoo::exeque::add	(	int	after_seconds,
		pebble *	p,
		long	after_nano_seconds = 0
	)

Add a pebble to the queue, to be run synchronously after a specified delay.

This is a convenience function that sets up the timestamp for you.

Parameters:

	p	the pebble that must be run.
	after_seconds	the number of seconds after which this pebble should be run.
	after_nano_seconds	the number of nano seconds after which this pebble should be run.

void karoo::exeque::add	(	const struct timespec &	ts,
		pebble *	p
	)

Add a pebble to the queue, to be run synchronously after a specified timestamp.

Parameters:

	p	the pebble that must be run.
	ts	the time when the pebble should be run.

void karoo::exeque::add

(

pebble *

p

)

Add a pebble to the queue, to be run synchronously in first-in, first-out order, as soon as possible.

Parameters:

p

the pebble that must be run.

int karoo::exeque::getBusyPercent

(

bool

reset = false

)

Get the percentage that the queue is busy.

Parameters:

reset

true if you want this statistic to be reset after calling.

int karoo::exeque::getErrorCount

(

bool

reset = false

)

Get the number of exceptions that have been caught from pebbles run in the queue.

Parameters:

reset

true if you want this statistic to be reset after calling.

int karoo::exeque::getImminentCount

(

unsigned

usecs = 0

)

const

Get the number of pebbles that are scheduled and imminent to run.

Parameters:

usecs

the number of microseconds (of waiting pebbles) to consider as "imminent"

int karoo::exeque::getRunCount

(

bool

reset = false

)

Get the number of times that pebbles have been run in this queue.

Parameters:

reset

true if you want this statistic to be reset after calling.

const qstats& karoo::exeque::getStats	(	qstats &	qs,
		bool	reset = false
	)			const

Get statistics about how this queue is performing.

Parameters:

	qs	the object to store the results into.
	reset	true if you want the statistics to be reset to zero after calling.

Returns:

a reference to the same qstats object that was passed in.

This qstats structure holds statistical information about the state of a queue.

You can send objects of this class to stdout, e.g.

 qstats qs;
 ...
 cout << qs << endl;
 

Definition of the structure:

	 typedef struct {
	 double mean;	// average time spent in running each pebble 
	 double sd;		// standard deviation in time spent running pebbles
	 double min;		// minimum time spent running the fastest pebble
	 double max;		// maximum time spent running the slowest pebble

	 double mean_delay;	// average latency when running pebbles that had a timestamp
	 double sd_delay;	// standard deviation in latency when running pebbles that had a timestamp
	 double min_delay;	// minimum latency when running pebbles that had a timestamp
	 double max_delay;	// maximum latency when running pebbles that had a timestamp

	 int busy_percent;	// the busy percentage. Zero means the queue is way under-utilised. 100% is not necesarily a problem, though it likely is... but the latency statistics are more indicative of an overload problem.

	 int num_iterations;	// the number of times this queue has iterated through its run loop

	 int num_errors;	// the number of caught exceptions from pebbles running in this queue.

	 bool is_stopped;	// true if the queue is stopped

	 double min_idle;	// minimum number of seconds spent waiting
	 double max_idle;	// maximum number of seconds spent waiting

	 int queued;		// number of pebbles currently queued
	 int waiting;	// number of pebbles currently waiting for their timestamp to come up
	 int running;	// number of pebbles currently runing (can only be 1 or zero)
	 int timeouts;	// number of times the queue has timed out while waiting for pebbles to run.
	 } qstats;
 

pthread_t karoo::exeque::getThread

(

)

[inline]

Return the runner thread.

Use with caution.

int karoo::exeque::getTimeoutCount

(

bool

reset = false

)

Get the number of times the runner thread has timed out while waiting for a pebble to become available to execute.

Parameters:

reset

true if you want this statistic to be reset after calling.

bool karoo::exeque::hasBeenIdleSince

(

const struct timespec &

comp

)

const

Find out if the queue has been idle since a specified past-dated timestamp.

Parameters:

comp

the past-dated timespec since when this method is querying if the queue has remained idle till now.

Returns:

true if the queue has been idle.

bool karoo::exeque::isStopped

(

long

wait_usec = 0

)

const

Query the queue to see if it has stopped.

If wait_usec is non zero, and it is still running the it will wait until either the timeout expires, or the queue does stop.

Parameters:

wait_usec

the number of micro-seconds to wait if it is still runing.

Returns:

true if the queue is stopped.

void karoo::exeque::reset	(	long	granularity = 0,
		int	time_sample_alloc_size = 100
	)

This method causes the queue to stop, and it waits until it has really stopped, and then resets everything (except for the inbox).

The integrity of the queue's pebbles is maintained, so when it is restarted it carries on executing from where it left off; but the statistical information is all reset. The queue will automatically restart if the granularity is non zero.

Parameters:

	granularity	this is a time in seconds that is the maximum time things should ever wait inside this queue. If it is zero, then the queue is not automatically restarted.
	time_sample_alloc_size	the number of time samples that should be collected for statistical purposes (returned by the getStats method.)

void karoo::exeque::run

(

)

This method should only ever called by the pthread that runs it.

Don't call this.

void karoo::exeque::setLogger

(

const log &

logger

)

[inline]

Set the logger object.

Parameters:

logger

the log object for sending warninfs, errors etc... to

bool karoo::exeque::start	(	long	granularity = 5,
		bool	take_over = false
	)

Start the exeque.

Parameters:

	granularity	this is a time in seconds that is the maximum time things should ever wait inside this queue.
	take_over	if this is true, then it will use the current thread, and this method will only return once the queue is stopped.

void karoo::exeque::stop

(

bool

block = false

)

Stop the exeque.

The default is to schedule the stop and return immediately.

Parameters:

block

if true, don't return from this method until the runner thread has actually stopped.

---

Member Data Documentation

multimap<const struct timespec,pebble*,exeque_comp> karoo::exeque::inbox [protected]

Contains all the pebbles waiting for execution.

The multimap is set up to order them by time. If a pebble does not have a timestamp, then it is inserted just before any with timestamps. A pebble "without a timestamp" is actually a zeroed out timestamp. The insert pair for the multimap is a timespec and a pointer to a pebble.

log karoo::exeque::logger [protected]

This variable will be true only when the runner thread is waiting for a pebble to run.

This will occur when there are no pebbles left in the inbox, or when all the remaining ones are timestamped in the future.

---

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

• queue/queue.h