The bodge-concurrency Reference Manual
Table of Contents
The bodge-concurrency Reference Manual
This is the bodge-concurrency Reference Manual, version 1.0.0,
generated automatically by Declt version 3.0 "Montgomery Scott"
on Tue Dec 22 11:49:15 2020 GMT+0.
1 Introduction
bodge-concurrency
Core concurrency utilities of bodge
library collection.
2 Systems
The main system appears first, followed by any subsystem dependency.
2.1 bodge-concurrency
- Author
Pavel Korolev
- Contact
dev@borodust.org
- License
MIT
- Description
Concurrency utilities
- Version
1.0.0
- Dependencies
- bodge-utilities
- bodge-memory
- cl-flow
- cl-muth
- trivial-main-thread
- bordeaux-threads
- simple-flow-dispatcher
- bodge-queue
- Source
bodge-concurrency.asd (file)
- Components
-
3 Files
Files are sorted by type and then listed depth-first from the systems
components trees.
3.1 Lisp
3.1.1 bodge-concurrency.asd
- Location
/home/quickref/quicklisp/dists/quicklisp/software/bodge-concurrency-stable-git/bodge-concurrency.asd
- Systems
bodge-concurrency (system)
3.1.2 bodge-concurrency/packages.lisp
- Parent
bodge-concurrency (system)
- Location
packages.lisp
- Packages
bodge-concurrency
3.1.3 bodge-concurrency/dispatch.lisp
- Dependency
packages.lisp (file)
- Parent
bodge-concurrency (system)
- Location
dispatch.lisp
- Exported Definitions
-
3.1.4 bodge-concurrency/execution.lisp
- Dependency
dispatch.lisp (file)
- Parent
bodge-concurrency (system)
- Location
execution.lisp
- Exported Definitions
-
- Internal Definitions
-
3.1.5 bodge-concurrency/task-queue.lisp
- Dependency
execution.lisp (file)
- Parent
bodge-concurrency (system)
- Location
task-queue.lisp
- Exported Definitions
-
- Internal Definitions
-
3.1.6 bodge-concurrency/instance-lock.lisp
- Dependency
task-queue.lisp (file)
- Parent
bodge-concurrency (system)
- Location
instance-lock.lisp
- Exported Definitions
-
- Internal Definitions
instance-lock-of (method)
3.1.7 bodge-concurrency/main-thread.lisp
- Dependency
instance-lock.lisp (file)
- Parent
bodge-concurrency (system)
- Location
main-thread.lisp
- Exported Definitions
-
4 Packages
Packages are listed by definition order.
4.1 bodge-concurrency
- Source
packages.lisp (file)
- Use List
- cl-flow
- cl-muth
- bordeaux-threads
- common-lisp
- bodge-memory
- bodge-util
- Exported Definitions
-
- Internal Definitions
-
5 Definitions
Definitions are sorted by export status, category, package, and then by
lexicographic order.
5.1 Exported definitions
5.1.1 Macros
- Macro: in-new-thread (THREAD-NAME) &body BODY
-
Execute ‘body‘ in the new thread with name ‘thread-name‘ instantly returning execution to the
caller.
- Package
bodge-concurrency
- Source
dispatch.lisp (file)
- Macro: in-new-thread-waiting (THREAD-NAME) &body BODY
-
Execute ‘body‘ in the new thread with name ‘thread-name‘ blocking caller until ‘body‘
returns.
- Package
bodge-concurrency
- Source
dispatch.lisp (file)
- Macro: push-body-into (TASK-QUEUE) &body BODY
-
Push block of code to execute as a task to the end of the queue. Thread-safe.
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Macro: with-body-in-main-thread () &body BODY
-
- Package
bodge-concurrency
- Source
main-thread.lisp (file)
- Macro: with-instance-lock-held (INSTANCE &optional LOCK-VAR) &body BODY
-
Hold instance lock for the duration of the ‘body‘.
- Package
bodge-concurrency
- Source
instance-lock.lisp (file)
5.1.2 Functions
- Function: clearup TASK-QUEUE
-
Remove all tasks from the queue. Thread-safe.
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Function: drain TASK-QUEUE &optional INVOKER
-
Execute tasks in FIFO order once. If ‘invoker‘ function provided, invoke it with task
function as an argument instead. Thread-safe.
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Function: make-pooled-executor &optional SIZE
-
Make executor that run tasks concurrently in the dedicated thread-pool.
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Function: make-single-threaded-executor &key QUEUE-SIZE SPECIAL-VARIABLES INVOKER
-
Make executor that run tasks in the same dedicated thread. Symbols specified in the
‘special-variables‘ would be available to the tasks ran by this executor.
Executor has maximum number of tasks it can take in until it block next call to #’execute if
:important-p key is not specified or set to ’t. If :important-p is set to ’nil when maximum
number of tasks is reached new incoming tasks will be discarded until number of tasks will drop
below maximum allowed.
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Function: make-task-queue ()
-
Make trivial thread-safe task FIFO queue.
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Function: push-task TASK-FU TASK-QUEUE
-
Push task function to the end of the queue. Thread-safe.
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Function: stop-main-runner ()
-
- Package
bodge-concurrency
- Source
main-thread.lisp (file)
5.1.3 Generic functions
- Generic Function: alivep EXECUTOR
-
Checks if executor is alive
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Methods
- Method: alivep (THIS pooled-executor)
-
- Method: alivep (THIS single-threaded-executor)
-
- Method: alivep EXECUTOR
-
- Generic Function: dispatch DISPATCHER TASK INVARIANT &key &allow-other-keys
-
- Package
bodge-concurrency
- Source
dispatch.lisp (file)
- Generic Function: execute EXECUTOR TASK &key INVARIANT PRIORITY IMPORTANT-P PROCESSING-THREAD &allow-other-keys
-
Abstract execution facility: runs ‘task‘ in a way defined by
‘executor‘. Executors must operate in a thread-safe manner.
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Methods
- Method: execute (THIS pooled-executor) (TASK function) &key INVARIANT PRIORITY
-
Run task concurrently in the thread pool.
- Method: execute (THIS single-threaded-executor) (TASK function) &key PRIORITY IMPORTANT-P
-
Execute task in the dedicated thread. Block execution of the #’execute caller if maximum
number of queued tasks is reached and :important-p is set to ’t. Discard task if maximum number
of queued tasks is reached, but :important-p is set to nil or posting thread and processing
thread are the same.
- Method: execute (THIS discarding-executor) (TASK function) &key PRIORITY IMPORTANT-P PROCESSING-THREAD
-
- Method: execute (THIS blocking-executor) (TASK function) &key PRIORITY
-
5.1.4 Classes
- Class: lockable ()
-
Mixin for quick instance locking facility
- Package
bodge-concurrency
- Source
instance-lock.lisp (file)
- Direct superclasses
standard-object (class)
- Direct methods
instance-lock-of (method)
- Direct slots
- Slot: lock
-
- Initform
(bordeaux-threads:make-recursive-lock "instance-lock")
- Readers
instance-lock-of (generic function)
5.2 Internal definitions
5.2.1 Constants
- Constant: +default-pool-size+
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Constant: +default-queue-size+
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
5.2.2 Functions
- Function: %make-task-queue &key (QUEUE QUEUE)
-
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Function: copy-task-queue INSTANCE
-
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Function: ignite EXECUTOR
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Function: invoke-next-task EXECUTOR
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Function: make-blocking-executor &optional QUEUE-SIZE
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Function: make-discarding-executor &optional INVOKER QUEUE-SIZE
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Function: task-queue-p OBJECT
-
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Function: task-queue-queue INSTANCE
-
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
5.2.3 Generic functions
- Generic Function: instance-lock-of OBJECT
-
- Package
bodge-concurrency
- Methods
- Method: instance-lock-of (LOCKABLE lockable)
-
automatically generated reader method
- Source
instance-lock.lisp (file)
- Generic Function: task-queue-of OBJECT
-
- Package
bodge-concurrency
- Methods
- Method: task-queue-of (GENERIC-EXECUTOR generic-executor)
-
automatically generated reader method
- Source
execution.lisp (file)
5.2.4 Structures
- Structure: task-queue ()
-
- Package
bodge-concurrency
- Source
task-queue.lisp (file)
- Direct superclasses
structure-object (structure)
- Direct slots
- Slot: queue
-
- Initform
(cl-muth:make-guarded-reference (bodge-queue:make-queue))
- Readers
task-queue-queue (function)
- Writers
(setf task-queue-queue) (function)
5.2.5 Classes
- Class: blocking-executor ()
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Direct superclasses
generic-executor (class)
- Direct methods
execute (method)
- Class: discarding-executor ()
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Direct superclasses
generic-executor (class)
- Direct methods
execute (method)
- Class: generic-executor ()
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Direct superclasses
disposable (class)
- Direct subclasses
-
- Direct methods
- destructor-of (method)
- initialize-instance (method)
- task-queue-of (method)
- Direct slots
- Slot: queue
-
- Readers
task-queue-of (generic function)
- Slot: invoker
-
- Initargs
nil
- Class: pooled-executor ()
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Direct superclasses
disposable (class)
- Direct methods
- execute (method)
- alivep (method)
- destructor-of (method)
- initialize-instance (method)
- Direct slots
- Slot: dispatching-fu
-
- Slot: dispatching-instance
-
- Class: single-threaded-executor ()
-
- Package
bodge-concurrency
- Source
execution.lisp (file)
- Direct superclasses
disposable (class)
- Direct methods
- execute (method)
- alivep (method)
- destructor-of (method)
- initialize-instance (method)
- Direct slots
- Slot: executor
-
- Initargs
:executor
- Initform
(error ":executor missing")
- Slot: processing-thread
-
Appendix A Indexes
A.1 Concepts
| Index Entry | | Section |
|
B | | |
| bodge-concurrency.asd: | | The bodge-concurrency․asd file |
| bodge-concurrency/dispatch.lisp: | | The bodge-concurrency/dispatch․lisp file |
| bodge-concurrency/execution.lisp: | | The bodge-concurrency/execution․lisp file |
| bodge-concurrency/instance-lock.lisp: | | The bodge-concurrency/instance-lock․lisp file |
| bodge-concurrency/main-thread.lisp: | | The bodge-concurrency/main-thread․lisp file |
| bodge-concurrency/packages.lisp: | | The bodge-concurrency/packages․lisp file |
| bodge-concurrency/task-queue.lisp: | | The bodge-concurrency/task-queue․lisp file |
|
F | | |
| File, Lisp, bodge-concurrency.asd: | | The bodge-concurrency․asd file |
| File, Lisp, bodge-concurrency/dispatch.lisp: | | The bodge-concurrency/dispatch․lisp file |
| File, Lisp, bodge-concurrency/execution.lisp: | | The bodge-concurrency/execution․lisp file |
| File, Lisp, bodge-concurrency/instance-lock.lisp: | | The bodge-concurrency/instance-lock․lisp file |
| File, Lisp, bodge-concurrency/main-thread.lisp: | | The bodge-concurrency/main-thread․lisp file |
| File, Lisp, bodge-concurrency/packages.lisp: | | The bodge-concurrency/packages․lisp file |
| File, Lisp, bodge-concurrency/task-queue.lisp: | | The bodge-concurrency/task-queue․lisp file |
|
L | | |
| Lisp File, bodge-concurrency.asd: | | The bodge-concurrency․asd file |
| Lisp File, bodge-concurrency/dispatch.lisp: | | The bodge-concurrency/dispatch․lisp file |
| Lisp File, bodge-concurrency/execution.lisp: | | The bodge-concurrency/execution․lisp file |
| Lisp File, bodge-concurrency/instance-lock.lisp: | | The bodge-concurrency/instance-lock․lisp file |
| Lisp File, bodge-concurrency/main-thread.lisp: | | The bodge-concurrency/main-thread․lisp file |
| Lisp File, bodge-concurrency/packages.lisp: | | The bodge-concurrency/packages․lisp file |
| Lisp File, bodge-concurrency/task-queue.lisp: | | The bodge-concurrency/task-queue․lisp file |
|
A.2 Functions
| Index Entry | | Section |
|
% | | |
| %make-task-queue : | | Internal functions |
|
A | | |
| alivep : | | Exported generic functions |
| alivep : | | Exported generic functions |
| alivep : | | Exported generic functions |
| alivep : | | Exported generic functions |
|
C | | |
| clearup : | | Exported functions |
| copy-task-queue : | | Internal functions |
|
D | | |
| dispatch : | | Exported generic functions |
| drain : | | Exported functions |
|
E | | |
| execute : | | Exported generic functions |
| execute : | | Exported generic functions |
| execute : | | Exported generic functions |
| execute : | | Exported generic functions |
| execute : | | Exported generic functions |
|
F | | |
| Function, %make-task-queue : | | Internal functions |
| Function, clearup : | | Exported functions |
| Function, copy-task-queue : | | Internal functions |
| Function, drain : | | Exported functions |
| Function, ignite : | | Internal functions |
| Function, invoke-next-task : | | Internal functions |
| Function, make-blocking-executor : | | Internal functions |
| Function, make-discarding-executor : | | Internal functions |
| Function, make-pooled-executor : | | Exported functions |
| Function, make-single-threaded-executor : | | Exported functions |
| Function, make-task-queue : | | Exported functions |
| Function, push-task : | | Exported functions |
| Function, stop-main-runner : | | Exported functions |
| Function, task-queue-p : | | Internal functions |
| Function, task-queue-queue : | | Internal functions |
|
G | | |
| Generic Function, alivep : | | Exported generic functions |
| Generic Function, dispatch : | | Exported generic functions |
| Generic Function, execute : | | Exported generic functions |
| Generic Function, instance-lock-of : | | Internal generic functions |
| Generic Function, task-queue-of : | | Internal generic functions |
|
I | | |
| ignite : | | Internal functions |
| in-new-thread : | | Exported macros |
| in-new-thread-waiting : | | Exported macros |
| instance-lock-of : | | Internal generic functions |
| instance-lock-of : | | Internal generic functions |
| invoke-next-task : | | Internal functions |
|
M | | |
| Macro, in-new-thread : | | Exported macros |
| Macro, in-new-thread-waiting : | | Exported macros |
| Macro, push-body-into : | | Exported macros |
| Macro, with-body-in-main-thread : | | Exported macros |
| Macro, with-instance-lock-held : | | Exported macros |
| make-blocking-executor : | | Internal functions |
| make-discarding-executor : | | Internal functions |
| make-pooled-executor : | | Exported functions |
| make-single-threaded-executor : | | Exported functions |
| make-task-queue : | | Exported functions |
| Method, alivep : | | Exported generic functions |
| Method, alivep : | | Exported generic functions |
| Method, alivep : | | Exported generic functions |
| Method, execute : | | Exported generic functions |
| Method, execute : | | Exported generic functions |
| Method, execute : | | Exported generic functions |
| Method, execute : | | Exported generic functions |
| Method, instance-lock-of : | | Internal generic functions |
| Method, task-queue-of : | | Internal generic functions |
|
P | | |
| push-body-into : | | Exported macros |
| push-task : | | Exported functions |
|
S | | |
| stop-main-runner : | | Exported functions |
|
T | | |
| task-queue-of : | | Internal generic functions |
| task-queue-of : | | Internal generic functions |
| task-queue-p : | | Internal functions |
| task-queue-queue : | | Internal functions |
|
W | | |
| with-body-in-main-thread : | | Exported macros |
| with-instance-lock-held : | | Exported macros |
|
A.3 Variables
| Index Entry | | Section |
|
+ | | |
| +default-pool-size+ : | | Internal constants |
| +default-queue-size+ : | | Internal constants |
|
C | | |
| Constant, +default-pool-size+ : | | Internal constants |
| Constant, +default-queue-size+ : | | Internal constants |
|
D | | |
| dispatching-fu : | | Internal classes |
| dispatching-instance : | | Internal classes |
|
E | | |
| executor : | | Internal classes |
|
I | | |
| invoker : | | Internal classes |
|
L | | |
| lock : | | Exported classes |
|
P | | |
| processing-thread : | | Internal classes |
|
Q | | |
| queue : | | Internal structures |
| queue : | | Internal classes |
|
S | | |
| Slot, dispatching-fu : | | Internal classes |
| Slot, dispatching-instance : | | Internal classes |
| Slot, executor : | | Internal classes |
| Slot, invoker : | | Internal classes |
| Slot, lock : | | Exported classes |
| Slot, processing-thread : | | Internal classes |
| Slot, queue : | | Internal structures |
| Slot, queue : | | Internal classes |
|
A.4 Data types