Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the simple-tasks Reference Manual, version 1.3.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 05:49:20 2022 GMT+0.
Next: Systems, Previous: The simple-tasks Reference Manual, Up: The simple-tasks Reference Manual [Contents][Index]
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.
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*)
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.
Next: Files, Previous: Introduction, Up: The simple-tasks Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
A very simple task scheduling framework.
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(GIT https://github.com/Shinmera/simple-tasks.git)
zlib
1.3.0
Next: Packages, Previous: Systems, Up: The simple-tasks Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: simple-tasks/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
simple-tasks (system).
Next: simple-tasks/toolkit.lisp, Previous: simple-tasks/simple-tasks.asd, Up: Lisp [Contents][Index]
simple-tasks (system).
Next: simple-tasks/status.lisp, Previous: simple-tasks/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
simple-tasks (system).
Next: simple-tasks/runner.lisp, Previous: simple-tasks/toolkit.lisp, Up: Lisp [Contents][Index]
toolkit.lisp (file).
simple-tasks (system).
status-list-p (function).
Next: simple-tasks/task.lisp, Previous: simple-tasks/status.lisp, Up: Lisp [Contents][Index]
status.lisp (file).
simple-tasks (system).
Next: simple-tasks/documentation.lisp, Previous: simple-tasks/runner.lisp, Up: Lisp [Contents][Index]
runner.lisp (file).
simple-tasks (system).
Previous: simple-tasks/task.lisp, Up: Lisp [Contents][Index]
task.lisp (file).
simple-tasks (system).
Next: Definitions, Previous: Files, Up: The simple-tasks Reference Manual [Contents][Index]
Packages are listed by definition order.
org.shirakumo.simple-tasks
common-lisp.
Next: Indexes, Previous: Packages, Up: The simple-tasks Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
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.
Constant to hold an instance of NO-THREADING-STUMP.
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.
Constant matching a running status.
:RUNNING Object is currently executing.
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.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Evaluate BODY within a task, usually a BLOCKING-CALL-TASK.
See CALL-AS-TASK
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
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
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
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Wait for the TASK to match a certain STATUS.
On systems without thread support this does nothing.
See STATUS=
The current back-queue of the runner.
Used to swap with QUEUE when events are handled.
See QUEUE
automatically generated reader method
The function to call upon completion of the task.
See CALLBACK-TASK
automatically generated reader method
automatically generated writer method
The condition variable used to exchange signals.
See QUEUED-RUNNER
See BLOCKING-CALL-TASK
automatically generated reader method
automatically generated reader method
cvar.
automatically generated writer method
An environment object that is stored in case the task fails to run properly.
See DISSECT:ENVIRONMENT
The function the call-task calls once it is run.
See CALL-TASK
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.
The lock used to coordinate task scheduling with the runner.
See QUEUED-RUNNER
automatically generated reader method
automatically generated reader method
lock.
automatically generated writer method
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.
automatically generated reader method
Returns the values that the call returned.
See CALL-TASK
Run the given task object directly.
One restart is established:
STOP to forcibly stop (interrupt) the task. Assigns the :STOPPED status.
The runner the task is scheduled on.
See TASK
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
Start the the runner.
Current status indicator of the status-object.
automatically generated reader method
automatically generated writer method
Compare two statuses with each other (commutative).
Stop the the runner.
The task related to the condition.
task.
Returns T if the task is ready to be run.
Returns the current thread associated with the queued-runner if any.
See QUEUED-RUNNER
automatically generated reader method
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
Condition superclass for conditions related to runner operations.
condition.
| Initarg | Value |
|---|---|
| :runner | (error runner required.) |
:runner
Condition signalled when the runner is not yet started, but has to be.
Condition signalled when the runner did not stop properly.
Condition signalled when attempting to reschedule an already scheduled task.
Condition superclass for task operation related conditions.
Condition signalled when a task failed to run properly.
Next: Types, Previous: Conditions, Up: Public Interface [Contents][Index]
Task class to perform a function call once run. Blocks the scheduling thread until it is done.
See CALL-TASK
See 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
Task class to perform a function call once run. Stores the return values.
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
| Initarg | Value |
|---|---|
| :callback | (error callback required.) |
:callback
Stump class to stand in place of a value on systems without threading support.
A task that will notify a condition upon completion.
This is particularly useful in conjunction with AWAIT.
task.
| Initarg | Value |
|---|---|
| :lock | (make-lock notifying-task) |
| :cvar | (make-condition-variable name notifying-task) |
Queued runner. Runs tasks in a thread if threading is available. Noe that START-RUNNER for this runner will block the current thread.
| Initarg | Value |
|---|---|
| :queue | (make-array 100 adjustable t fill-pointer 0) |
| :back-queue | (make-array 100 adjustable t fill-pointer 0) |
| :lock | (make-lock task-runner-queue-lock) |
| :cvar | (make-condition-variable name task-runner-condition) |
| :thread | nil |
:queue
:back-queue
:thread
Basic runner. Runs task as soon as scheduled.
A class that has a status.
:created
Basic task class.
Previous: Classes, Up: Public Interface [Contents][Index]
A status can be a SYMBOL, a STATUS-OBJECT, or a LIST composed of SYMBOLs.
Previous: Public Interface, Up: Definitions [Contents][Index]
Bound to either NIL or the current queue being processed by the queued-runner.
See QUEUED-RUNNER
Bound to either NIL or the current task being processed by the queued-runner.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Easily set the documentation.
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Check that all functions, classes, and variables have docstrings.
Returns true if every element in the list is a symbol and the list thus qualifies as a STATUS.
Previous: Ordinary functions, Up: Internals [Contents][Index]
automatically generated writer method
automatically generated writer method
automatically generated writer method
Previous: Definitions, Up: The simple-tasks Reference Manual [Contents][Index]
| Jump to: | %
(
A B C E F G I L M P Q R S T W |
|---|
| Jump to: | %
(
A B C E F G I L M P Q R S T W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
+
B C E F L Q R S T |
|---|
| Jump to: | *
+
B C E F L Q R S T |
|---|
| Jump to: | B C D F N P Q R S T |
|---|
| Jump to: | B C D F N P Q R S T |
|---|