The bodge-concurrency Reference Manual

This is the bodge-concurrency Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 16:30:13 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 bodge-concurrency

Concurrency utilities

Author

Pavel Korolev

Contact

License

MIT

Version

1.0.0

Dependencies
  • bodge-utilities (system).
  • bodge-memory (system).
  • cl-flow (system).
  • cl-muth (system).
  • trivial-main-thread (system).
  • bordeaux-threads (system).
  • simple-flow-dispatcher (system).
  • bodge-queue (system).
Source

bodge-concurrency.asd.

Child 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/bodge-concurrency.asd

Source

bodge-concurrency.asd.

Parent Component

bodge-concurrency (system).

ASDF Systems

bodge-concurrency.


3.1.2 bodge-concurrency/packages.lisp

Source

bodge-concurrency.asd.

Parent Component

bodge-concurrency (system).

Packages

bodge-concurrency.


3.1.3 bodge-concurrency/dispatch.lisp

Dependency

packages.lisp (file).

Source

bodge-concurrency.asd.

Parent Component

bodge-concurrency (system).

Public Interface

3.1.4 bodge-concurrency/execution.lisp

Dependency

dispatch.lisp (file).

Source

bodge-concurrency.asd.

Parent Component

bodge-concurrency (system).

Public Interface
Internals

3.1.5 bodge-concurrency/task-queue.lisp

Dependency

execution.lisp (file).

Source

bodge-concurrency.asd.

Parent Component

bodge-concurrency (system).

Public Interface
Internals

3.1.6 bodge-concurrency/instance-lock.lisp

Dependency

task-queue.lisp (file).

Source

bodge-concurrency.asd.

Parent Component

bodge-concurrency (system).

Public Interface
Internals

instance-lock-of (reader method).


3.1.7 bodge-concurrency/main-thread.lisp

Dependency

instance-lock.lisp (file).

Source

bodge-concurrency.asd.

Parent Component

bodge-concurrency (system).

Public Interface

4 Packages

Packages are listed by definition order.


4.1 bodge-concurrency

Source

packages.lisp.

Use List
  • bodge-memory.
  • bodge-util.
  • bordeaux-threads.
  • cl-flow.
  • cl-muth.
  • common-lisp.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


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.

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.

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.

Macro: with-body-in-main-thread (() &body body)
Package

bodge-concurrency.

Source

main-thread.lisp.

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.


5.1.2 Ordinary functions

Function: clearup (task-queue)

Remove all tasks from the queue. Thread-safe.

Package

bodge-concurrency.

Source

task-queue.lisp.

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.

Function: make-pooled-executor (&optional size)

Make executor that run tasks concurrently in the dedicated thread-pool.

Package

bodge-concurrency.

Source

execution.lisp.

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.

Function: make-task-queue ()

Make trivial thread-safe task FIFO queue.

Package

bodge-concurrency.

Source

task-queue.lisp.

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.

Function: stop-main-runner ()
Package

bodge-concurrency.

Source

main-thread.lisp.


5.1.3 Generic functions

Generic Function: alivep (executor)

Checks if executor is alive

Package

bodge-concurrency.

Source

execution.lisp.

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.

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.

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 Standalone methods

Method: initialize-instance :after ((this pooled-executor) &key size)
Source

execution.lisp.

Method: initialize-instance :after ((this generic-executor) &key queue-size invoker)
Source

execution.lisp.

Method: initialize-instance :after ((this single-threaded-executor) &key special-variables)
Source

execution.lisp.


5.1.5 Classes

Class: lockable

Mixin for quick instance locking facility

Package

bodge-concurrency.

Source

instance-lock.lisp.

Direct methods

instance-lock-of.

Direct slots
Slot: lock
Package

bordeaux-threads.

Initform

(bordeaux-threads:make-recursive-lock "instance-lock")

Readers

instance-lock-of.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Constants

Constant: +default-pool-size+
Package

bodge-concurrency.

Source

execution.lisp.

Constant: +default-queue-size+
Package

bodge-concurrency.

Source

execution.lisp.


5.2.2 Ordinary functions

Function: %make-task-queue (&key queue)
Package

bodge-concurrency.

Source

task-queue.lisp.

Function: copy-task-queue (instance)
Package

bodge-concurrency.

Source

task-queue.lisp.

Function: ignite (executor)
Package

bodge-concurrency.

Source

execution.lisp.

Function: invoke-next-task (executor)
Package

bodge-concurrency.

Source

execution.lisp.

Function: make-blocking-executor (&optional queue-size)
Package

bodge-concurrency.

Source

execution.lisp.

Function: make-discarding-executor (&optional invoker queue-size)
Package

bodge-concurrency.

Source

execution.lisp.

Function: task-queue-p (object)
Package

bodge-concurrency.

Source

task-queue.lisp.

Reader: task-queue-queue (instance)
Package

bodge-concurrency.

Source

task-queue.lisp.

Target Slot

queue.


5.2.3 Generic functions

Generic Reader: instance-lock-of (object)
Package

bodge-concurrency.

Methods
Reader Method: instance-lock-of ((lockable lockable))

automatically generated reader method

Source

instance-lock.lisp.

Target Slot

lock.

Generic Reader: task-queue-of (object)
Package

bodge-concurrency.

Methods
Reader Method: task-queue-of ((generic-executor generic-executor))

automatically generated reader method

Source

execution.lisp.

Target Slot

queue.


5.2.4 Standalone methods

Method: destructor-of ((this0 pooled-executor))
Package

bodge-memory.

Source

execution.lisp.

Method: destructor-of ((this0 generic-executor))
Package

bodge-memory.

Source

execution.lisp.

Method: destructor-of ((this0 single-threaded-executor))
Package

bodge-memory.

Source

execution.lisp.


5.2.5 Structures

Structure: task-queue
Package

bodge-concurrency.

Source

task-queue.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: queue
Initform

(cl-muth:make-guarded-reference (bodge-queue:make-queue))

Readers

task-queue-queue.

Writers

This slot is read-only.


5.2.6 Classes

Class: blocking-executor
Package

bodge-concurrency.

Source

execution.lisp.

Direct superclasses

generic-executor.

Direct methods

execute.

Class: discarding-executor
Package

bodge-concurrency.

Source

execution.lisp.

Direct superclasses

generic-executor.

Direct methods

execute.

Class: generic-executor
Package

bodge-concurrency.

Source

execution.lisp.

Direct superclasses

disposable.

Direct subclasses
Direct methods
Direct slots
Slot: queue
Readers

task-queue-of.

Writers

This slot is read-only.

Slot: invoker
Initargs

nil

Class: pooled-executor
Package

bodge-concurrency.

Source

execution.lisp.

Direct superclasses

disposable.

Direct methods
Direct slots
Slot: dispatching-fu
Slot: dispatching-instance
Class: single-threaded-executor
Package

bodge-concurrency.

Source

execution.lisp.

Direct superclasses

disposable.

Direct methods
Direct slots
Slot: executor
Initform

(error ":executor missing")

Initargs

:executor

Slot: processing-thread

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %  
A   C   D   E   F   G   I   M   P   S   T   W  
Index Entry  Section

%
%make-task-queue: Private ordinary functions

A
alivep: Public generic functions
alivep: Public generic functions
alivep: Public generic functions
alivep: Public generic functions

C
clearup: Public ordinary functions
copy-task-queue: Private ordinary functions

D
destructor-of: Private standalone methods
destructor-of: Private standalone methods
destructor-of: Private standalone methods
dispatch: Public generic functions
drain: Public ordinary functions

E
execute: Public generic functions
execute: Public generic functions
execute: Public generic functions
execute: Public generic functions
execute: Public generic functions

F
Function, %make-task-queue: Private ordinary functions
Function, clearup: Public ordinary functions
Function, copy-task-queue: Private ordinary functions
Function, drain: Public ordinary functions
Function, ignite: Private ordinary functions
Function, invoke-next-task: Private ordinary functions
Function, make-blocking-executor: Private ordinary functions
Function, make-discarding-executor: Private ordinary functions
Function, make-pooled-executor: Public ordinary functions
Function, make-single-threaded-executor: Public ordinary functions
Function, make-task-queue: Public ordinary functions
Function, push-task: Public ordinary functions
Function, stop-main-runner: Public ordinary functions
Function, task-queue-p: Private ordinary functions
Function, task-queue-queue: Private ordinary functions

G
Generic Function, alivep: Public generic functions
Generic Function, dispatch: Public generic functions
Generic Function, execute: Public generic functions
Generic Function, instance-lock-of: Private generic functions
Generic Function, task-queue-of: Private generic functions

I
ignite: Private ordinary functions
in-new-thread: Public macros
in-new-thread-waiting: Public macros
initialize-instance: Public standalone methods
initialize-instance: Public standalone methods
initialize-instance: Public standalone methods
instance-lock-of: Private generic functions
instance-lock-of: Private generic functions
invoke-next-task: Private ordinary functions

M
Macro, in-new-thread: Public macros
Macro, in-new-thread-waiting: Public macros
Macro, push-body-into: Public macros
Macro, with-body-in-main-thread: Public macros
Macro, with-instance-lock-held: Public macros
make-blocking-executor: Private ordinary functions
make-discarding-executor: Private ordinary functions
make-pooled-executor: Public ordinary functions
make-single-threaded-executor: Public ordinary functions
make-task-queue: Public ordinary functions
Method, alivep: Public generic functions
Method, alivep: Public generic functions
Method, alivep: Public generic functions
Method, destructor-of: Private standalone methods
Method, destructor-of: Private standalone methods
Method, destructor-of: Private standalone methods
Method, execute: Public generic functions
Method, execute: Public generic functions
Method, execute: Public generic functions
Method, execute: Public generic functions
Method, initialize-instance: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, instance-lock-of: Private generic functions
Method, task-queue-of: Private generic functions

P
push-body-into: Public macros
push-task: Public ordinary functions

S
stop-main-runner: Public ordinary functions

T
task-queue-of: Private generic functions
task-queue-of: Private generic functions
task-queue-p: Private ordinary functions
task-queue-queue: Private ordinary functions

W
with-body-in-main-thread: Public macros
with-instance-lock-held: Public macros


A.4 Data types

Jump to:   B   C   D   E   F   G   I   L   M   P   S   T  
Index Entry  Section

B
blocking-executor: Private classes
bodge-concurrency: The bodge-concurrency system
bodge-concurrency: The bodge-concurrency package
bodge-concurrency.asd: The bodge-concurrency/bodge-concurrency․asd file

C
Class, blocking-executor: Private classes
Class, discarding-executor: Private classes
Class, generic-executor: Private classes
Class, lockable: Public classes
Class, pooled-executor: Private classes
Class, single-threaded-executor: Private classes

D
discarding-executor: Private classes
dispatch.lisp: The bodge-concurrency/dispatch․lisp file

E
execution.lisp: The bodge-concurrency/execution․lisp file

F
File, bodge-concurrency.asd: The bodge-concurrency/bodge-concurrency․asd file
File, dispatch.lisp: The bodge-concurrency/dispatch․lisp file
File, execution.lisp: The bodge-concurrency/execution․lisp file
File, instance-lock.lisp: The bodge-concurrency/instance-lock․lisp file
File, main-thread.lisp: The bodge-concurrency/main-thread․lisp file
File, packages.lisp: The bodge-concurrency/packages․lisp file
File, task-queue.lisp: The bodge-concurrency/task-queue․lisp file

G
generic-executor: Private classes

I
instance-lock.lisp: The bodge-concurrency/instance-lock․lisp file

L
lockable: Public classes

M
main-thread.lisp: The bodge-concurrency/main-thread․lisp file

P
Package, bodge-concurrency: The bodge-concurrency package
packages.lisp: The bodge-concurrency/packages․lisp file
pooled-executor: Private classes

S
single-threaded-executor: Private classes
Structure, task-queue: Private structures
System, bodge-concurrency: The bodge-concurrency system

T
task-queue: Private structures
task-queue.lisp: The bodge-concurrency/task-queue․lisp file