Task Operations

Macros
#define	tqAdd(tq, task)   taskqueueAdd(tq, task)
#define	tqRun(tq, ptask)
#define	tqSchedule(tq, task, delay)   _tqSchedule(tq, ComplexTask(task), delay)
#define	tqDefer(tq, task)   _tqDefer(tq, ComplexTask(task))

Functions
bool	tqCall (TaskQueue *tq, closure cls)
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 127 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 173 of file taskqueue.h.

tqRun

#define tqRun	(		tq,
			ptask
	)

Value:

    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 135 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 156 of file taskqueue.h.

Function Documentation

tqCall()

bool tqCall	(	TaskQueue *	tq,
		closure	cls
	)

Runs a closure on a thread in a task queue's worker pool.

A simplified interface for cases where creating a task class is overkill. The closure is called with the queue it is running on: closureCall(cls, stvar(object, tq)). Returning false from it marks the task failed.

Anything the closure needs is captured when it is created, and released with it, so there is no separate context pointer to clean up:

tqCall(tq, closureCreate(myWork, stvark(path, string, filename)));

Takes ownership of the closure whatever happens: it is destroyed once the task has run, when the task is cancelled or the queue shuts down without running it, and before this returns if the task could not be queued at all. Do not destroy it afterwards.

Parameters

tq	Task queue to run the closure on
cls	Closure to execute; ownership passes to the queue

Returns

true if the 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