Scieneer Common Lisp 1.3.9 online documentation

Task Queue

Introduction

A simple task queue is provided along with the HTTP library. A function may be queued to be executed by a thread from a thread pool. This avoids the cost of creating a thread to execute each task, and can be used to place an upper bound on the number of threads dedicated to processing the tasks. The maximum queue length may also be specified to place an upper bound on the number of tasks queued.

The functions below are generally thread safe. The queue parameters may be safely adjusted, for example changing the number of threads in the pool.


thread:task-queue[Class]

Class precedence list:

thread:task-queue, structure-object, ext:instance, t.

thread:make-task-queue &key maximum-length maximum-threads enabled-p timeout priority-levels[Function]

Create and return a thread:task-queue object. Functional tasks may be queued by thread:queue-task. The queue may have a number of priority-levels which are used to prioritize the tasks, and the default is just one priority level. When a maximum-length is specified, thread:queue-task will refuse to queue more tasks once this limit is reached. When enabled-p the queued tasks are executed by a pool of threads created as needed until and up to the maximum-threads limit if any. Threads created to process the pool will wait for new work up to the given timeout if any. When the queue is disabled tasks are not queued and a new thread is created to execute each task.

thread:queue-task task-queue function &optional priority[Function]

Queue a function to be executed by the given task-queue. The optional priority is a zero based integer priority level and must be within the number of priority levels defined for the queue, see thread:make-task-queue. Tasks with a higher priority are queued to be executed before any lower priority tasks, and the new task is queued to execute after other tasks with the same priority. The default priority level is zero, the lowest priority.

If the task queue is enabled and the maximum task queue length has not been reached then the task is placed in the queue. Once a task has been queued it is generally executed even if the queue is subsequently shutdown or the maximum queue length reduced.

Three values are returned: 1. a success flag which if true if the task was queue otherwise false; 2. the queue length; 3. the number of threads busy executing tasks, which is the total minus the number of threads free to execute tasks.

When the task queue is enabled, a count of the number of calls is increased, see thread:task-queue-count. If the queue has reached its maximum length and the task is not queued then the thread:task-queue-dropped-count is increased. If no threads are available to execute the task, and none can be created because the maximum threads limited has been reached, then the thread:task-queue-deferred-count is increased.

If the task queue is disabled then a new thread is created to execute the task, returning t, 0, and 0. If ext:quit has been called then no further tasks will be queued, returning nil, 0, and 0.

thread:shutdown-task-queue task-queue &key waitp[Function]

Shutdown the task-queue, preventing further tasks being queued or executed and optionally waiting until the queue is empty and the execution of all tasks has completed. The execution of pending tasks will continue until all have been completed.

thread:task-queue-enabled-p task-queue[Function]

Return true if the task-queue is enabled. When enabled, tasks will be queued to be processed by the thread pool.

(setf (thread:task-queue-enabled-p task-queue) state)[Function]

Set the task-queue enabled state. When enabled, thread:queue-task will place the tasks in the queue to be execute by the thread pool.

thread:task-queue-length task-queue[Function]

Return the number of queued tasks waiting to be processed.

thread:task-queue-maximum-length task-queue[Function]

Return the maximum allowed number of queued tasks, or nil if there is no restriction.

(setf (thread:task-queue-maximum-length task-queue) length)[Function]

Set the maximum allowed number of queue tasks. If the length is nil then there is no restriction and all task will be queued. Decreasing the maximum does not removed any pending tasks over the limit, but no new tasks will be queued until enough pending tasks are executed to bring the queue length within the maximum. Setting the maximum to zero will prevent any tasks being queued.

thread:task-queue-threads task-queue[Function]

Return the size of the thread pool.

thread:task-queue-maximum-threads task-queue[Function]

Return the maximum size of the thread pool used to exectute queued tasks, or nil if there is no restriction.

(setf (thread:task-queue-maximum-threads task-queue) size)[Function]

Set the maximum size of the thread pool used to execute queued tasks. If the size is nil then there is no restriction and threads will created as needed. If the size increases then the thread pool will be grown, and if the size decreases then the thread pool with shrink as the threads complete execution of their current tasks.

thread:task-queue-timeout task-queue[Function]

Return the duration of time that a thread will wait for a new task to execute before exiting. When nil the threads in the pool will not timeout and exit.

(setf (thread:task-queue-timeout task-queue) timeout)[Function]

Set the duration of time that a thread will wait for a new task to execute before exiting. When nil the threads in the pool will not timeout and exit.

thread:task-queue-count task-queue[Function]

Return the number of calls to thread:queue-task. This count is only updated then the task queue is enabled.

thread:task-queue-deferred-count task-queue[Function]

Return the number of tasks which could not be executed immediately because the maximum number of threads servicing the queue had been reached.

thread:task-queue-dropped-count task-queue[Function]

Return the number of tasks which could not be queued because the maximum task queue length had been reached.