Task Operations

Macros
#define	tqAdd(tq, task)   taskqueueAdd(tq, task)
#define	tqRun(tq, ptask)   do { taskqueueAdd(tq, *ptask); objRelease(ptask); } while(0)
#define	tqSchedule(tq, task, delay)   _tqSchedule(tq, ComplexTask(task), delay)
#define	tqDefer(tq, task)   _tqDefer(tq, ComplexTask(task))

Typedefs
typedef bool(*	UserTaskCB) (TaskQueue *tq, void *data)

Functions
bool	tqCall (TaskQueue *tq, UserTaskCB func, void *userdata)
int32	tqWorkers (TaskQueue *tq)

Detailed Description

Macro Definition Documentation

tqAdd

#define tqAdd	(		tq,
			task
	)		taskqueueAdd(tq, task)

bool tqAdd(TaskQueue *tq, BasicTask *task)

Add a task to the queue to run immediately. The caller retains ownership of the task reference.

Parameters

tq	Task queue to add task to
task	Task to add (any type derived from BasicTask)

Returns

true if task was added successfully

Definition at line 126 of file taskqueue.h.

tqDefer

#define tqDefer	(		tq,
			task
	)		_tqDefer(tq, ComplexTask(task))

bool tqDefer(TaskQueue *tq, ComplexTask *task)

Add a task to the queue but defer it indefinitely. Task will not run until explicitly advanced with taskAdvance() or ctaskAdvance(). Useful for tasks waiting on external events.

Parameters

tq	Task queue (must support complex tasks)
task	Complex task to defer

Returns

true if task was deferred successfully

Definition at line 168 of file taskqueue.h.

tqRun

#define tqRun	(		tq,
			ptask
	)		do { taskqueueAdd(tq, *ptask); objRelease(ptask); } while(0)

void tqRun(TaskQueue *tq, BasicTask **ptask)

Convenience function to add a task to the queue and release it. This is the most common pattern for fire-and-forget tasks.

Parameters

tq	Task queue to run task on
ptask	Pointer to task pointer (task is released after adding)

Definition at line 134 of file taskqueue.h.

tqSchedule

#define tqSchedule	(		tq,
			task,
			delay
	)		_tqSchedule(tq, ComplexTask(task), delay)

bool tqSchedule(TaskQueue *tq, ComplexTask *task, int64 delay)

Add a task to the queue to run after a delay. Requires a ComplexTask-derived task and a ComplexTaskQueue.

Parameters

tq	Task queue (must support complex tasks)
task	Complex task to schedule
delay	Delay in system time units before task should run

Returns

true if task was scheduled successfully

Definition at line 151 of file taskqueue.h.

Typedef Documentation

UserTaskCB

typedef bool(* UserTaskCB) (TaskQueue *tq, void *data)

Generic callback mechanism for basic use that doesn't need to create classes. The callback should return true for success, false for failure.

Parameters

tq	Task queue the callback is running on
data	User-provided data pointer

Returns

true for success, false for failure

Definition at line 175 of file taskqueue.h.

Function Documentation

tqCall()

bool tqCall	(	TaskQueue *	tq,
		UserTaskCB	func,
		void *	userdata
	)

bool tqCall(TaskQueue *tq, UserTaskCB func, void *userdata)

Runs a custom function on a thread in a task queue's worker pool. This is a simplified interface for cases where creating a task class is overkill.

Parameters

tq	Task queue to run callback on
func	Callback function to execute
userdata	Optional data pointer passed to callback

Returns

true if callback task was queued successfully

tqWorkers()

int32 tqWorkers

(

TaskQueue *

tq

)

int32 tqWorkers(TaskQueue *tq)

Returns the current number of worker threads in the queue's pool. For manual queues, returns 0.

Parameters

tq	Task queue to query

Returns

Number of active worker threads