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 Mon Apr 19 14:13:40 2021 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

• packages.lisp (file)
• dispatch.lisp (file)
• execution.lisp (file)
• task-queue.lisp (file)
• instance-lock.lisp (file)
• main-thread.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 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

• dispatch (generic function)
• in-new-thread (macro)
• in-new-thread-waiting (macro)

3.1.4 bodge-concurrency/execution.lisp

Dependency

dispatch.lisp (file)

Parent

bodge-concurrency (system)

Location

execution.lisp

Exported Definitions

• alivep (generic function)
• alivep (method)
• alivep (method)
• alivep (method)
• execute (generic function)
• execute (method)
• execute (method)
• execute (method)
• execute (method)
• make-pooled-executor (function)
• make-single-threaded-executor (function)

Internal Definitions

• +default-pool-size+ (constant)
• +default-queue-size+ (constant)
• blocking-executor (class)
• discarding-executor (class)
• generic-executor (class)
• ignite (function)
• invoke-next-task (function)
• make-blocking-executor (function)
• make-discarding-executor (function)
• pooled-executor (class)
• single-threaded-executor (class)
• task-queue-of (method)

3.1.5 bodge-concurrency/task-queue.lisp

Dependency

execution.lisp (file)

Parent

bodge-concurrency (system)

Location

task-queue.lisp

Exported Definitions

• clearup (function)
• drain (function)
• make-task-queue (function)
• push-body-into (macro)
• push-task (function)

Internal Definitions

• %make-task-queue (function)
• copy-task-queue (function)
• task-queue (structure)
• task-queue-p (function)
• task-queue-queue (function)

3.1.6 bodge-concurrency/instance-lock.lisp

Dependency

task-queue.lisp (file)

Parent

bodge-concurrency (system)

Location

instance-lock.lisp

Exported Definitions

• lockable (class)
• with-instance-lock-held (macro)

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

• stop-main-runner (function)
• with-body-in-main-thread (macro)

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

• alivep (generic function)
• alivep (method)
• alivep (method)
• alivep (method)
• clearup (function)
• dispatch (generic function)
• drain (function)
• execute (generic function)
• execute (method)
• execute (method)
• execute (method)
• execute (method)
• in-new-thread (macro)
• in-new-thread-waiting (macro)
• lockable (class)
• make-pooled-executor (function)
• make-single-threaded-executor (function)
• make-task-queue (function)
• push-body-into (macro)
• push-task (function)
• stop-main-runner (function)
• with-body-in-main-thread (macro)
• with-instance-lock-held (macro)

Internal Definitions

• %make-task-queue (function)
• +default-pool-size+ (constant)
• +default-queue-size+ (constant)
• blocking-executor (class)
• copy-task-queue (function)
• discarding-executor (class)
• generic-executor (class)
• ignite (function)
• instance-lock-of (generic function)
• instance-lock-of (method)
• invoke-next-task (function)
• make-blocking-executor (function)
• make-discarding-executor (function)
• pooled-executor (class)
• single-threaded-executor (class)
• task-queue (structure)
• task-queue-of (generic function)
• task-queue-of (method)
• task-queue-p (function)
• task-queue-queue (function)

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

• blocking-executor (class)
• discarding-executor (class)

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

A.2 Functions

A.3 Variables

A.4 Data types