The simple-tasks Reference Manual

Table of Contents

The simple-tasks Reference Manual

This is the simple-tasks Reference Manual, version 1.3.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 12:32:22 2021 GMT+0.

1 Introduction

About simple-tasks

Recently I noticed that I seem to write a similar pattern way too often: Some form of scheduling or task management part. Usually this is due to the need of executing some task in a specific thread, or simply wanting to schedule something for processing in the background.

Basic Usage

Load it through ASDF or Quicklisp:

(ql:quickload :simple-tasks)

Before we can do anything, we need to have a manager to run tasks with. These are called runners. Usually you will want a queued-runner which will use threading capabilities if the system provides them, and thus can process tasks in the background.

(defvar *runner* (make-instance 'simple-tasks:queued-runner))

Next we'll want to start the runner, if possible in a separate thread. The standard start-runner function does not do this, as you might want to set up the thread scenario yourself, or perhaps even inject the runner into a different thread. However, for the common scenario, there's make-runner-thread.

(defvar *thread* (simple-tasks:make-runner-thread *runner*))

Now we can finally create tasks and send them off for processing! Out of the box, simple-tasks provides three classes to do remote evaluation with: call-task, blocking-call-task, and callback-task. However, adding your own is very easy. Just subclass task and implement run-task.

(defvar *task* (make-instance 'simple-tasks:call-task :func (lambda () (print "hi"))))

Finally we need to send off the task for processing.

(simple-tasks:schedule-task *task* *runner*)

All call-tasks also save the return-values of the function they're calling, so you can read that out later. Usually if you want to do so, you'll want to either block until the task is done, or delegate to a callback function. The former is made convenient through with-body-as-task.

(simple-tasks:with-body-as-task (*runner*)
  (sleep 1)
  (expt 2 12))

In the case that a task encounters a failure during a run, it sets its status to :errored and saves the current environment. You can inspect this environment at any later point by fetching it with error-environment and looking at its contents with the various functions Dissect provides. This is mostly useful in a scenario where you cannot use a debugger and thus just automatically invoke the skip restart in the runner thread. With the environment saved, the error can still be inspected elsewhere or at a later date.

(dissect:present
  (simple-tasks:error-environment
    (simple-tasks:schedule-task 
      (make-instance 'simple-tasks:blocking-call-task :func (lambda () (error "Hi"))) *runner*)))

And that's pretty much it.

(simple-tasks:stop-runner *runner*)

Extending simple-tasks

If you want to add flexibility by creating your own specialised task classes, you should look at task, run-task, and schedule-task. Usually you can get away by just subclassing task, and adding a run-task method to do your calculations in. If you also need to modify the behaviour of the scheduling, adding :after methods to schedule-task can also be useful.

In case that the existing runners aren't suited to your needs, adding one should also not be much of a problem. Simply subclass runner, and implement appropriate methods for start-runner, stop-runner, and schedule-task. The existing methods on runner will take care of keeping the status in sync and making sure no invalid calls can be made.

Also See

• Dissect for error environment capture and inspection.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 simple-tasks

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://Shinmera.github.io/simple-tasks/

Source Control

(:git "https://github.com/shinmera/simple-tasks.git")

Bug Tracker

https://github.com/Shinmera/simple-tasks/issues

License

zlib

Description

A very simple task scheduling framework.

Version

1.3.0

Dependencies

• bordeaux-threads
• array-utils
• dissect

Source

simple-tasks.asd (file)

Components

• package.lisp (file)
• toolkit.lisp (file)
• status.lisp (file)
• runner.lisp (file)
• task.lisp (file)
• documentation.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 simple-tasks.asd

Location

simple-tasks.asd

Systems

simple-tasks (system)

3.1.2 simple-tasks/package.lisp

Parent

simple-tasks (system)

Location

package.lisp

Packages

simple-tasks

3.1.3 simple-tasks/toolkit.lisp

Dependency

package.lisp (file)

Parent

simple-tasks (system)

Location

toolkit.lisp

Exported Definitions

• +no-threading-stump+ (special variable)
• no-threading-stump (class)

3.1.4 simple-tasks/status.lisp

Dependency

toolkit.lisp (file)

Parent

simple-tasks (system)

Location

status.lisp

Exported Definitions

• +status-ended+ (special variable)
• +status-running+ (special variable)
• +status-started+ (special variable)
• status (generic function)
• status (method)
• (setf status) (method)
• status (type)
• status-object (class)
• status= (generic function)
• status= (method)
• status= (method)
• status= (method)
• status= (method)
• status= (method)
• status= (method)

Internal Definitions

status-list-p (function)

3.1.5 simple-tasks/runner.lisp

Dependency

status.lisp (file)

Parent

simple-tasks (system)

Location

runner.lisp

Exported Definitions

• *runner* (special variable)
• back-queue (generic function)
• back-queue (method)
• cvar (generic function)
• cvar (method)
• interrupt-task (generic function)
• interrupt-task (method)
• interrupt-task (method)
• lock (generic function)
• lock (method)
• make-runner-thread (function)
• queue (generic function)
• queue (method)
• queued-runner (class)
• run-task (generic function)
• runner (method)
• (setf runner) (method)
• runner (class)
• runner-condition (condition)
• runner-not-started (condition)
• runner-not-stopped (condition)
• schedule-task (generic function)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• start-runner (generic function)
• start-runner (method)
• start-runner (method)
• start-runner (method)
• start-runner (method)
• stop-runner (generic function)
• stop-runner (method)
• stop-runner (method)
• stop-runner (method)
• thread (generic function)
• thread (method)

Internal Definitions

• %set-back-queue (method)
• %set-queue (method)
• %set-thread (method)
• *current-queue* (special variable)
• *current-task* (special variable)

3.1.6 simple-tasks/task.lisp

Dependency

runner.lisp (file)

Parent

simple-tasks (system)

Location

task.lisp

Exported Definitions

• await (generic function)
• await (method)
• await (method)
• blocking-call-task (class)
• blocking-task (class)
• call-as-task (function)
• call-task (class)
• callback (generic function)
• callback (method)
• (setf callback) (method)
• callback-task (class)
• cvar (method)
• (setf cvar) (method)
• error-environment (generic function)
• error-environment (method)
• (setf error-environment) (method)
• func (generic function)
• func (method)
• (setf func) (method)
• interrupt-task (method)
• interrupt-task (method)
• lock (method)
• (setf lock) (method)
• notifying-task (class)
• return-values (generic function)
• return-values (method)
• return-values (method)
• (setf return-values) (method)
• run-task (method)
• run-task (method)
• run-task (method)
• run-task (method)
• runner (generic function)
• runner (method)
• (setf runner) (method)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• task (generic function)
• task (method)
• (setf task) (method)
• task (class)
• task-already-scheduled (condition)
• task-condition (condition)
• task-errored (condition)
• task-ready-p (generic function)
• task-ready-p (method)
• with-body-as-task (macro)

3.1.7 simple-tasks/documentation.lisp

Dependency

task.lisp (file)

Parent

simple-tasks (system)

Location

documentation.lisp

Internal Definitions

• checkdocs (function)
• setdocs (macro)

4 Packages

Packages are listed by definition order.

4.1 simple-tasks

Source

package.lisp (file)

Nickname

org.shirakumo.simple-tasks

Use List

common-lisp

Exported Definitions

• *runner* (special variable)
• +no-threading-stump+ (special variable)
• +status-ended+ (special variable)
• +status-running+ (special variable)
• +status-started+ (special variable)
• await (generic function)
• await (method)
• await (method)
• back-queue (generic function)
• back-queue (method)
• blocking-call-task (class)
• blocking-task (class)
• call-as-task (function)
• call-task (class)
• callback (generic function)
• callback (method)
• (setf callback) (generic function)
• (setf callback) (method)
• callback-task (class)
• cvar (generic function)
• cvar (method)
• cvar (method)
• (setf cvar) (generic function)
• (setf cvar) (method)
• error-environment (generic function)
• error-environment (method)
• (setf error-environment) (generic function)
• (setf error-environment) (method)
• func (generic function)
• func (method)
• (setf func) (generic function)
• (setf func) (method)
• interrupt-task (generic function)
• interrupt-task (method)
• interrupt-task (method)
• interrupt-task (method)
• interrupt-task (method)
• lock (generic function)
• lock (method)
• lock (method)
• (setf lock) (generic function)
• (setf lock) (method)
• make-runner-thread (function)
• no-threading-stump (class)
• notifying-task (class)
• queue (generic function)
• queue (method)
• queued-runner (class)
• return-values (generic function)
• return-values (method)
• return-values (method)
• (setf return-values) (generic function)
• (setf return-values) (method)
• run-task (generic function)
• run-task (method)
• run-task (method)
• run-task (method)
• run-task (method)
• runner (generic function)
• runner (method)
• runner (method)
• (setf runner) (generic function)
• (setf runner) (method)
• (setf runner) (method)
• runner (class)
• runner-condition (condition)
• runner-not-started (condition)
• runner-not-stopped (condition)
• schedule-task (generic function)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• schedule-task (method)
• start-runner (generic function)
• start-runner (method)
• start-runner (method)
• start-runner (method)
• start-runner (method)
• status (generic function)
• status (method)
• (setf status) (generic function)
• (setf status) (method)
• status (type)
• status-object (class)
• status= (generic function)
• status= (method)
• status= (method)
• status= (method)
• status= (method)
• status= (method)
• status= (method)
• stop-runner (generic function)
• stop-runner (method)
• stop-runner (method)
• stop-runner (method)
• task (generic function)
• task (method)
• (setf task) (generic function)
• (setf task) (method)
• task (class)
• task-already-scheduled (condition)
• task-condition (condition)
• task-errored (condition)
• task-ready-p (generic function)
• task-ready-p (method)
• thread (generic function)
• thread (method)
• with-body-as-task (macro)

Internal Definitions

• %set-back-queue (generic function)
• %set-back-queue (method)
• %set-queue (generic function)
• %set-queue (method)
• %set-thread (generic function)
• %set-thread (method)
• *current-queue* (special variable)
• *current-task* (special variable)
• checkdocs (function)
• setdocs (macro)
• status-list-p (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *runner*

Bound to the current runner if within a runner context. Otherwise, set to NIL. Useful to detect if a task is run in a particular runner to avoid conflicts.

Package

simple-tasks

Source

runner.lisp (file)

Special Variable: +no-threading-stump+

Constant to hold an instance of NO-THREADING-STUMP.

Package

simple-tasks

Source

toolkit.lisp (file)

Special Variable: +status-ended+

Constant matching any ended (not necessarily successful) status.

:STOPPING Object is in the process of being stopped. :STOPPED Object has been stopped.
:COMPLETED Object successfully completed execution. :ERRORED Object ended execution with an error.

Package

simple-tasks

Source

status.lisp (file)

Special Variable: +status-running+

Constant matching a running status.

:RUNNING Object is currently executing.

Package

simple-tasks

Source

status.lisp (file)

Special Variable: +status-started+

Constant matching any started (not necessarily running) status.

:CREATED Object has been initialized, but not started. :SCHEDULED Object has been scheduled for execution. :RUNNING Object is currently executing.

Package

simple-tasks

Source

status.lisp (file)

5.1.2 Macros

Macro: with-body-as-task (RUNNER &optional TASK-CLASS) &body BODY

Evaluate BODY within a task, usually a BLOCKING-CALL-TASK.

See CALL-AS-TASK

Package

simple-tasks

Source

task.lisp (file)

5.1.3 Functions

Function: call-as-task FUNCTION RUNNER &optional TASK-CLASS

Call function within a task, usually a BLOCKING-CALL-TASK.
Depending on the task’s STATUS after SCHEDULE-TASK returns, the following happens. :COMPLETED The task’s return values are returned.
:ERRORED A condition of type TASK-ERRORED is signalled.
T The task is returned.

See SCHEDULE-TASK
See BLOCKING-CALL-TASK

Package

simple-tasks

Source

task.lisp (file)

Function: make-runner-thread RUNNER

Make a thread to call START-RUNNER on RUNNER in.

On platforms with thread support, this returns the new thread.
On platforms without, this simply calls START-RUNNER and returns NIL.

See START-RUNNER

Package

simple-tasks

Source

runner.lisp (file)

5.1.4 Generic functions

Generic Function: await TASK STATUS

Wait for the TASK to match a certain STATUS.

On systems without thread support this does nothing.

See STATUS=

Package

simple-tasks

Source

task.lisp (file)

Methods

Method: await (TASK notifying-task) STATUS

Method: await (TASK task) STATUS

Generic Function: back-queue RUNNER

The current back-queue of the runner.

Used to swap with QUEUE when events are handled.

See QUEUE

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: back-queue (QUEUED-RUNNER queued-runner)

automatically generated reader method

Generic Function: callback CALLBACK-TASK

The function to call upon completion of the task.

See CALLBACK-TASK

Package

simple-tasks

Source

task.lisp (file)

Writer

(setf callback) (generic function)

Methods

Method: callback (CALLBACK-TASK callback-task)

automatically generated reader method

Generic Function: (setf callback) NEW-VALUE OBJECT

Package

simple-tasks

Reader

callback (generic function)

Methods

Method: (setf callback) NEW-VALUE (CALLBACK-TASK callback-task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: cvar OBJECT

The condition variable used to exchange signals.

See QUEUED-RUNNER
See BLOCKING-CALL-TASK

Package

simple-tasks

Source

runner.lisp (file)

Writer

(setf cvar) (generic function)

Methods

Method: cvar (NOTIFYING-TASK notifying-task)

automatically generated reader method

Source

task.lisp (file)

Method: cvar (QUEUED-RUNNER queued-runner)

automatically generated reader method

Generic Function: (setf cvar) NEW-VALUE OBJECT

Package

simple-tasks

Reader

cvar (generic function)

Methods

Method: (setf cvar) NEW-VALUE (NOTIFYING-TASK notifying-task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: error-environment TASK

An environment object that is stored in case the task fails to run properly.

See DISSECT:ENVIRONMENT

Package

simple-tasks

Source

task.lisp (file)

Writer

(setf error-environment) (generic function)

Methods

Method: error-environment (TASK task)

automatically generated reader method

Generic Function: (setf error-environment) NEW-VALUE OBJECT

Package

simple-tasks

Reader

error-environment (generic function)

Methods

Method: (setf error-environment) NEW-VALUE (TASK task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: func CALL-TASK

The function the call-task calls once it is run.

See CALL-TASK

Package

simple-tasks

Source

task.lisp (file)

Writer

(setf func) (generic function)

Methods

Method: func (CALL-TASK call-task)

automatically generated reader method

Generic Function: (setf func) NEW-VALUE OBJECT

Package

simple-tasks

Reader

func (generic function)

Methods

Method: (setf func) NEW-VALUE (CALL-TASK call-task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: interrupt-task TASK RUNNER

Interrupt the TASK to stop it from execution on RUNNER.

If the task is currently on the RUNNER’s queue to be executed (:SCHEDULED), it is removed from the queue. If the task is currently running, it is forcibly aborted. In either case, the task’s status is changed to :STOPPED and it will not execute further. On systems without thread support this does nothing.

If this is called with the RUNNER being T, the current runner of the TASK is used, if possible. If this is called with the RUNNER being NIL, the actual termination mechanism for the task is performed, leading it to be terminated.

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: interrupt-task (TASK task) (TRUE (eql t))

Source

task.lisp (file)

Method: interrupt-task (TASK task) (NULL null)

Source

task.lisp (file)

Method: interrupt-task TASK (RUNNER queued-runner)

Method: interrupt-task TASK (RUNNER runner)

Generic Function: lock OBJECT

The lock used to coordinate task scheduling with the runner.

See QUEUED-RUNNER

Package

simple-tasks

Source

runner.lisp (file)

Writer

(setf lock) (generic function)

Methods

Method: lock (NOTIFYING-TASK notifying-task)

automatically generated reader method

Source

task.lisp (file)

Method: lock (QUEUED-RUNNER queued-runner)

automatically generated reader method

Generic Function: (setf lock) NEW-VALUE OBJECT

Package

simple-tasks

Reader

lock (generic function)

Methods

Method: (setf lock) NEW-VALUE (NOTIFYING-TASK notifying-task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: queue RUNNER

The current task queue of the runner.

Do not directly push tasks to this! Use SCHEDULE-TASK instead.
This queue is also NOT indicative of which tasks have yet to be run, or which ones have. When the queued runner runs, it retains the current queue for processing and sets a new, empty queue on the runner. As such, when you look at the queue at any particular moment, tasks that are not in it might not have run yet.

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: queue (QUEUED-RUNNER queued-runner)

automatically generated reader method

Generic Function: return-values CALL-TASK

Returns the values that the call returned.

See CALL-TASK

Package

simple-tasks

Source

task.lisp (file)

Writer

(setf return-values) (generic function)

Methods

Method: return-values (TASK call-task) around

Method: return-values (CALL-TASK call-task)

automatically generated reader method

Generic Function: (setf return-values) NEW-VALUE OBJECT

Package

simple-tasks

Reader

return-values (generic function)

Methods

Method: (setf return-values) NEW-VALUE (CALL-TASK call-task)

automatically generated writer method

Source

task.lisp (file)

Generic Function: run-task TASK

Run the given task object directly.

One restart is established:
STOP to forcibly stop (interrupt) the task. Assigns the :STOPPED status.

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: run-task (TASK callback-task) after

Source

task.lisp (file)

Method: run-task (TASK notifying-task) around

Source

task.lisp (file)

Method: run-task (TASK call-task)

Source

task.lisp (file)

Method: run-task (TASK task) around

Source

task.lisp (file)

Generic Function: runner TASK

The runner the task is scheduled on.

See TASK

Package

simple-tasks

Source

task.lisp (file)

Writer

(setf runner) (generic function)

Methods

Method: runner (TASK task)

automatically generated reader method

Method: runner (CONDITION runner-condition)

Source

runner.lisp (file)

Generic Function: (setf runner) NEW-VALUE CONDITION

Package

simple-tasks

Reader

runner (generic function)

Methods

Method: (setf runner) NEW-VALUE (TASK task)

automatically generated writer method

Source

task.lisp (file)

Method: (setf runner) NEW-VALUE (CONDITION runner-condition)

Source

runner.lisp (file)

Generic Function: schedule-task TASK RUNNER

Schedule the task object for running.
The task may or may not be run immediately, depending on the runner and given system support. Tasks are guaranteed to be run in the same order as they are scheduled.

See RUN-TASK

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: schedule-task (TASK blocking-task) RUNNER after

Source

task.lisp (file)

Method: schedule-task (TASK blocking-task) RUNNER

Source

task.lisp (file)

Method: schedule-task (TASK blocking-task) RUNNER around

Source

task.lisp (file)

Method: schedule-task (TASK task) RUNNER before

Source

task.lisp (file)

Method: schedule-task TASK (RUNNER queued-runner)

Method: schedule-task TASK (RUNNER runner)

Method: schedule-task TASK (RUNNER runner) before

Generic Function: start-runner RUNNER

Start the the runner.

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: start-runner (RUNNER queued-runner)

Method: start-runner (RUNNER runner)

Method: start-runner (RUNNER runner) around

Method: start-runner (RUNNER runner) before

Generic Function: status STATUS-OBJECT

Current status indicator of the status-object.

Package

simple-tasks

Source

status.lisp (file)

Writer

(setf status) (generic function)

Methods

Method: status (STATUS-OBJECT status-object)

automatically generated reader method

Generic Function: (setf status) NEW-VALUE OBJECT

Package

simple-tasks

Reader

status (generic function)

Methods

Method: (setf status) NEW-VALUE (STATUS-OBJECT status-object)

automatically generated writer method

Source

status.lisp (file)

Generic Function: status= A B

Compare two statuses with each other (commutative).

Package

simple-tasks

Source

status.lisp (file)

Methods

Method: status= (A list) (B list)

Method: status= B (A status-object)

Method: status= (B list) (A status-object)

Method: status= (A status-object) B

Method: status= (A status-object) (B list)

Method: status= (A status-object) (B status-object)

Generic Function: stop-runner RUNNER

Stop the the runner.

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: stop-runner (RUNNER queued-runner)

Method: stop-runner (RUNNER runner)

Method: stop-runner (RUNNER runner) before

Generic Function: task TASK-CONDITION

The task related to the condition.

Package

simple-tasks

Source

task.lisp (file)

Writer

(setf task) (generic function)

Methods

Method: task (CONDITION task-condition)

Generic Function: (setf task) NEW-VALUE CONDITION

Package

simple-tasks

Reader

task (generic function)

Methods

Method: (setf task) NEW-VALUE (CONDITION task-condition)

Source

task.lisp (file)

Generic Function: task-ready-p TASK

Returns T if the task is ready to be run.

Package

simple-tasks

Source

task.lisp (file)

Methods

Method: task-ready-p (TASK task)

Generic Function: thread OBJECT

Returns the current thread associated with the queued-runner if any.

See QUEUED-RUNNER

Package

simple-tasks

Source

runner.lisp (file)

Methods

Method: thread (QUEUED-RUNNER queued-runner)

automatically generated reader method

5.1.5 Conditions

Condition: runner-condition ()

Condition superclass for conditions related to runner operations.

Package

simple-tasks

Source

runner.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses

• runner-not-started (condition)
• runner-not-stopped (condition)

Direct methods

• (setf runner) (method)
• runner (method)

Direct slots

Slot: runner

Initargs

:runner

Readers

runner (generic function)

Writers

(setf runner) (generic function)

Direct Default Initargs

Initarg	Value
:runner	(error "runner required.")

Condition: runner-not-started ()

Condition signalled when the runner is not yet started, but has to be.

Package

simple-tasks

Source

runner.lisp (file)

Direct superclasses

• error (condition)
• runner-condition (condition)

Condition: runner-not-stopped ()

Condition signalled when the runner did not stop properly.

Package

simple-tasks

Source

runner.lisp (file)

Direct superclasses

• warning (condition)
• runner-condition (condition)

Condition: task-already-scheduled ()

Condition signalled when attempting to reschedule an already scheduled task.

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

• error (condition)
• task-condition (condition)

Condition: task-condition ()

Condition superclass for task operation related conditions.

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses

• task-already-scheduled (condition)
• task-errored (condition)

Direct methods

• (setf task) (method)
• task (method)

Direct slots

Slot: task

Initargs

:task

Readers

task (generic function)

Writers

(setf task) (generic function)

Direct Default Initargs

Initarg	Value
:task	(error "task required.")

Condition: task-errored ()

Condition signalled when a task failed to run properly.

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

• warning (condition)
• task-condition (condition)

5.1.6 Classes

Class: blocking-call-task ()

Task class to perform a function call once run. Blocks the scheduling thread until it is done.

See CALL-TASK
See BLOCKING-TASK

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

• blocking-task (class)
• call-task (class)

Class: blocking-task ()

A task that will block after being scheduled until it is done or interrupted.

When SCHEDULE-TASK is called on this, it establishes two restarts:
ABORT to forcibly abort (interrupt) the task.
UNBLOCK to resume execution in the current thread and leave the task running.

If a restart or similar exit functionality is invoked that leaves the scope of SCHEDULE-TASK, the task is interrupted.

Note that the restarts are not useful on systems without thread support. In such a case the task will be interrupted either way, due to the very nature of running in the current thread.

See AWAIT
See INTERRUPT-TASK
See NOTIFYING-TASK

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

notifying-task (class)

Direct subclasses

blocking-call-task (class)

Direct methods

• schedule-task (method)
• schedule-task (method)
• schedule-task (method)

Class: call-task ()

Task class to perform a function call once run. Stores the return values.

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

task (class)

Direct subclasses

• blocking-call-task (class)
• callback-task (class)

Direct methods

• run-task (method)
• print-object (method)
• return-values (method)
• (setf return-values) (method)
• return-values (method)
• (setf func) (method)
• func (method)

Direct slots

Slot: func

Initargs

:func

Readers

func (generic function)

Writers

(setf func) (generic function)

Slot: return-values

Readers

return-values (generic function)

Writers

(setf return-values) (generic function)

Direct Default Initargs

Initarg	Value
:func	(error "func required.")

Class: callback-task ()

Task class to perform a function call once run and call a callback upon completion.

If the task completes successfully, the callback function is called with each return value as an argument. Note that the callback function is called within the runner environment which may be different from the scheduler environment.

See CALL-TASK

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

call-task (class)

Direct methods

• run-task (method)
• (setf callback) (method)
• callback (method)

Direct slots

Slot: callback

Initargs

:callback

Readers

callback (generic function)

Writers

(setf callback) (generic function)

Direct Default Initargs

Initarg	Value
:callback	(error "callback required.")

Class: no-threading-stump ()

Stump class to stand in place of a value on systems without threading support.

Package

simple-tasks

Source

toolkit.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

print-object (method)

Class: notifying-task ()

A task that will notify a condition upon completion.

This is particularly useful in conjunction with AWAIT.

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

task (class)

Direct subclasses

blocking-task (class)

Direct methods

• await (method)
• run-task (method)
• (setf cvar) (method)
• cvar (method)
• (setf lock) (method)
• lock (method)

Direct slots

Slot: lock

Initargs

:lock

Readers

lock (generic function)

Writers

(setf lock) (generic function)

Slot: cvar

Initargs

:cvar

Readers

cvar (generic function)

Writers

(setf cvar) (generic function)

Direct Default Initargs

Initarg	Value
:lock	(bordeaux-threads:make-lock "notifying-task")
:cvar	(bordeaux-threads:make-condition-variable :name "notifying-task")

Class: queued-runner ()

Queued runner. Runs tasks in a thread if threading is available. Noe that START-RUNNER for this runner will block the current thread.

Package

simple-tasks

Source

runner.lisp (file)

Direct superclasses

runner (class)

Direct methods

• interrupt-task (method)
• schedule-task (method)
• stop-runner (method)
• start-runner (method)
• %set-thread (method)
• thread (method)
• cvar (method)
• lock (method)
• %set-back-queue (method)
• back-queue (method)
• %set-queue (method)
• queue (method)

Direct slots

Slot: queue

Initargs

:queue

Readers

queue (generic function)

Writers

%set-queue (generic function)

Slot: back-queue

Initargs

:back-queue

Readers

back-queue (generic function)

Writers

%set-back-queue (generic function)

Slot: lock

Initargs

:lock

Readers

lock (generic function)

Slot: cvar

Initargs

:cvar

Readers

cvar (generic function)

Slot: thread

Initargs

:thread

Readers

thread (generic function)

Writers

%set-thread (generic function)

Direct Default Initargs

Initarg	Value
:queue	(make-array 100 :adjustable t :fill-pointer 0)
:back-queue	(make-array 100 :adjustable t :fill-pointer 0)
:lock	(bordeaux-threads:make-lock "task-runner-queue-lock")
:cvar	(bordeaux-threads:make-condition-variable :name "task-runner-condition")
:thread	nil

Class: runner ()

Basic runner. Runs task as soon as scheduled.

Package

simple-tasks

Source

runner.lisp (file)

Direct superclasses

status-object (class)

Direct subclasses

queued-runner (class)

Direct methods

• interrupt-task (method)
• schedule-task (method)
• schedule-task (method)
• stop-runner (method)
• stop-runner (method)
• start-runner (method)
• start-runner (method)
• start-runner (method)
• print-object (method)

Class: status-object ()

A class that has a status.

Package

simple-tasks

Source

status.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• runner (class)
• task (class)

Direct methods

• status= (method)
• status= (method)
• status= (method)
• status= (method)
• status= (method)
• (setf status) (method)
• status (method)

Direct slots

Slot: status

Initform

:created

Readers

status (generic function)

Writers

(setf status) (generic function)

Class: task ()

Basic task class.

Package

simple-tasks

Source

task.lisp (file)

Direct superclasses

status-object (class)

Direct subclasses

• call-task (class)
• notifying-task (class)

Direct methods

• interrupt-task (method)
• interrupt-task (method)
• await (method)
• run-task (method)
• schedule-task (method)
• print-object (method)
• task-ready-p (method)
• (setf error-environment) (method)
• error-environment (method)
• (setf runner) (method)
• runner (method)

Direct slots

Slot: runner

Readers

runner (generic function)

Writers

(setf runner) (generic function)

Slot: error-environment

Readers

error-environment (generic function)

Writers

(setf error-environment) (generic function)

5.1.7 Types

Type: status ()

A status can be a SYMBOL, a STATUS-OBJECT, or a LIST composed of SYMBOLs.

Package

simple-tasks

Source

status.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *current-queue*

Bound to either NIL or the current queue being processed by the queued-runner.

See QUEUED-RUNNER

Package

simple-tasks

Source

runner.lisp (file)

Special Variable: *current-task*

Bound to either NIL or the current task being processed by the queued-runner.

Package

simple-tasks

Source

runner.lisp (file)

5.2.2 Macros

Macro: setdocs &body PAIRS

Easily set the documentation.

Package

simple-tasks

Source

documentation.lisp (file)

5.2.3 Functions

Function: checkdocs &optional PACKAGE

Check that all functions, classes, and variables have docstrings.

Package

simple-tasks

Source

documentation.lisp (file)

Function: status-list-p LIST

Returns true if every element in the list is a symbol and the list thus qualifies as a STATUS.

Package

simple-tasks

Source

status.lisp (file)

5.2.4 Generic functions

Generic Function: %set-back-queue NEW-VALUE OBJECT

Package

simple-tasks

Methods

Method: %set-back-queue NEW-VALUE (QUEUED-RUNNER queued-runner)

automatically generated writer method

Source

runner.lisp (file)

Generic Function: %set-queue NEW-VALUE OBJECT

Package

simple-tasks

Methods

Method: %set-queue NEW-VALUE (QUEUED-RUNNER queued-runner)

automatically generated writer method

Source

runner.lisp (file)

Generic Function: %set-thread NEW-VALUE OBJECT

Package

simple-tasks

Methods

Method: %set-thread NEW-VALUE (QUEUED-RUNNER queued-runner)

automatically generated writer method

Source

runner.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types