The cl-flow Reference Manual

Table of Contents

The cl-flow Reference Manual

This is the cl-flow Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:16:58 2020 GMT+0.

1 Introduction

CL-FLOW

Library for asynchonous non-blocking concurrency in Common Lisp.

Documentation

Documentation at borodust.org

You can hear my lengthy-bad-english explanation of cl-flow operation in Common Lisp Study Group: Concurrency in Common Lisp Part 2 video from Atlanta Functional Programming group.

Tests

(ql:quickload :cl-flow/tests)
(5am:run! :cl-flow-suite)

2 Systems

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

2.1 cl-flow

Author

Pavel Korolev

Contact

dev@borodust.org

License

MIT

Description

Data-flow driven concurrency model for Common Lisp

Version

1.0.0

Dependencies

• alexandria
• cl-muth

Source

cl-flow.asd (file)

Components

• packages.lisp (file)
• utils.lisp (file)
• context.lisp (file)
• flow.lisp (file)
• atomically.lisp (file)
• serially.lisp (file)
• concurrently.lisp (file)
• dynamically.lisp (file)
• asynchronously.lisp (file)
• repeatedly.lisp (file)
• run.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 cl-flow.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/cl-flow-stable-git/cl-flow.asd

Systems

cl-flow (system)

3.1.2 cl-flow/packages.lisp

Parent

cl-flow (system)

Location

packages.lisp

Packages

cl-flow

3.1.3 cl-flow/utils.lisp

Dependency

packages.lisp (file)

Parent

cl-flow (system)

Location

utils.lisp

Internal Definitions

+optimize-form+ (constant)

3.1.4 cl-flow/context.lisp

Dependency

utils.lisp (file)

Parent

cl-flow (system)

Location

context.lisp

Exported Definitions

• inject-flow (function)
• rerun-flow-block (function)
• skip-flow-block (function)
• use-flow-block-value (function)

Internal Definitions

• %%inject-invoke (function)
• %%inject-invoke-text (function)
• %%rerun-invoke (function)
• %%rerun-invoke-text (function)
• %%skip-invoke (function)
• %%skip-invoke-text (function)
• %%use-invoke (function)
• %%use-invoke-text (function)
• %dispatch-rest (function)
• %invoke-with-restarts (function)
• *continue* (special variable)
• *current-context* (special variable)
• *parent-context* (special variable)
• +min-stack-extension+ (constant)
• capture-flow-value (function)
• chop-head (function)
• copy-flow-context (function)
• dispatch (function)
• dispatch-rest (function)
• flow-context (structure)
• flow-context-dispatcher (function)
• (setf flow-context-dispatcher) (function)
• flow-context-function (function)
• (setf flow-context-function) (function)
• flow-context-native-dispatcher (function)
• flow-context-p (function)
• flow-context-parent (function)
• flow-context-stack (function)
• flow-context-value (function)
• (setf flow-context-value) (function)
• init-context-dispatcher (function)
• invoke-flow-function (function)
• invoke-with-restarts (function)
• make-child-flow-context (function)
• make-flow-context (function)
• push-flow-stack (function)
• try-restart (function)

3.1.5 cl-flow/flow.lisp

Dependency

context.lisp (file)

Parent

cl-flow (system)

Location

flow.lisp

Internal Definitions

• %flow-lambda (macro)
• %with-flow-function (macro)
• flow-lambda-macro (macro)
• parse-atomic-block-args (function)
• with-flow-function-macro (macro)
• with-flow-let-macro (macro)

3.1.6 cl-flow/atomically.lisp

Dependency

flow.lisp (file)

Parent

cl-flow (system)

Location

atomically.lisp

Exported Definitions

• -> (macro)
• atomically (macro)

Internal Definitions

dispatch-atomically (function)

3.1.7 cl-flow/serially.lisp

Dependency

atomically.lisp (file)

Parent

cl-flow (system)

Location

serially.lisp

Exported Definitions

• >> (macro)
• serially (macro)

Internal Definitions

dispatch-serially (function)

3.1.8 cl-flow/concurrently.lisp

Dependency

serially.lisp (file)

Parent

cl-flow (system)

Location

concurrently.lisp

Exported Definitions

• concurrently (macro)
• ~> (macro)

Internal Definitions

• %dispatch-concurrently (function)
• dispatch-concurrently (function)

3.1.9 cl-flow/dynamically.lisp

Dependency

concurrently.lisp (file)

Parent

cl-flow (system)

Location

dynamically.lisp

Exported Definitions

• ->> (macro)
• dynamically (macro)

Internal Definitions

dispatch-dynamically (function)

3.1.10 cl-flow/asynchronously.lisp

Dependency

dynamically.lisp (file)

Parent

cl-flow (system)

Location

asynchronously.lisp

Exported Definitions

• %> (macro)
• asynchronously (macro)
• continue-flow (function)
• interrupt-flow (function)

Internal Definitions

dispatch-asynchronously (function)

3.1.11 cl-flow/repeatedly.lisp

Dependency

asynchronously.lisp (file)

Parent

cl-flow (system)

Location

repeatedly.lisp

Exported Definitions

• o> (macro)
• repeatedly (macro)

Internal Definitions

dispatch-repeatedly (function)

3.1.12 cl-flow/run.lisp

Dependency

repeatedly.lisp (file)

Parent

cl-flow (system)

Location

run.lisp

Exported Definitions

run (function)

4 Packages

Packages are listed by definition order.

4.1 cl-flow

Source

packages.lisp (file)

Nickname

flow

Use List

• alexandria
• common-lisp

Exported Definitions

• %> (macro)
• *flow-value* (special variable)
• -> (macro)
• ->> (macro)
• >> (macro)
• asynchronously (macro)
• atomically (macro)
• concurrently (macro)
• continue-flow (function)
• dynamically (macro)
• inject-flow (function)
• interrupt-flow (function)
• o> (macro)
• repeatedly (macro)
• rerun-flow-block (function)
• run (function)
• serially (macro)
• skip-flow-block (function)
• use-flow-block-value (function)
• ~> (macro)

Internal Definitions

• %%inject-invoke (function)
• %%inject-invoke-text (function)
• %%rerun-invoke (function)
• %%rerun-invoke-text (function)
• %%skip-invoke (function)
• %%skip-invoke-text (function)
• %%use-invoke (function)
• %%use-invoke-text (function)
• %dispatch-concurrently (function)
• %dispatch-rest (function)
• %flow-lambda (macro)
• %invoke-with-restarts (function)
• %with-flow-function (macro)
• *continue* (special variable)
• *current-context* (special variable)
• *parent-context* (special variable)
• +min-stack-extension+ (constant)
• +optimize-form+ (constant)
• capture-flow-value (function)
• chop-head (function)
• copy-flow-context (function)
• dispatch (function)
• dispatch-asynchronously (function)
• dispatch-atomically (function)
• dispatch-concurrently (function)
• dispatch-dynamically (function)
• dispatch-repeatedly (function)
• dispatch-rest (function)
• dispatch-serially (function)
• flow-context (structure)
• flow-context-dispatcher (function)
• (setf flow-context-dispatcher) (function)
• flow-context-function (function)
• (setf flow-context-function) (function)
• flow-context-native-dispatcher (function)
• flow-context-p (function)
• flow-context-parent (function)
• flow-context-stack (function)
• flow-context-value (function)
• (setf flow-context-value) (function)
• flow-lambda-macro (macro)
• init-context-dispatcher (function)
• invoke-flow-function (function)
• invoke-with-restarts (function)
• make-child-flow-context (function)
• make-flow-context (function)
• parse-atomic-block-args (function)
• push-flow-stack (function)
• try-restart (function)
• with-flow-function-macro (macro)
• with-flow-let-macro (macro)

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: *flow-value*

Package

cl-flow

5.1.2 Macros

Macro: %> LAMBDA-LIST &body BODY

See flow:asynchronously

Package

cl-flow

Source

asynchronously.lisp (file)

Macro: -> INVARIANT &body ARGS

See flow:atomically

Package

cl-flow

Source

atomically.lisp (file)

Macro: ->> LAMBDA-LIST &body BODY

See flow:dynamically

Package

cl-flow

Source

dynamically.lisp (file)

Macro: >> &rest FLOW

See flow:serially

Package

cl-flow

Source

serially.lisp (file)

Macro: asynchronously LAMBDA-LIST &body BODY

Splits current flow allowing manually managing its execution via #’continue-flow and #’interrupt-flow functions. Consing: ~32 bytes per invocation

Package

cl-flow

Source

asynchronously.lisp (file)

Macro: atomically INVARIANT &body ARGS

Encloses atomic flow block of code that can be dispatched concurrently. Non-consing.

Package

cl-flow

Source

atomically.lisp (file)

Macro: concurrently &body FLOW

Executes child elements in parallel, returning a list of results for child blocks or flows in the same order they were specified. Heavy consing.

Package

cl-flow

Source

concurrently.lisp (file)

Macro: dynamically LAMBDA-LIST &body BODY

Generates new flow dynamically during parent flow execution. In other words, injects new dynamically created flow into a current one. Non-consing.

Package

cl-flow

Source

dynamically.lisp (file)

Macro: o> CONDITION &body BODY

See flow:repeatedly

Package

cl-flow

Source

repeatedly.lisp (file)

Macro: repeatedly LIVE-TEST-FORM &body FLOW

Short-circuit the flow specified inside the block and executes it repeatedly in loop until LIVE-TEST-FORM evaluates to NIL. Result from the last iteration will be passed to the next block. Non-consing.

Package

cl-flow

Source

repeatedly.lisp (file)

Macro: serially &body FLOW

Executes child elements serially (but possibly in different threads) returning a value of the last atomic block or flow. Non-consing.

Package

cl-flow

Source

serially.lisp (file)

Macro: ~> &rest BODY

See flow:concurrently

Package

cl-flow

Source

concurrently.lisp (file)

5.1.3 Functions

Function: continue-flow &optional VALUE

Invokes next flow block with provided value as an argument

Package

cl-flow

Source

asynchronously.lisp (file)

Function: inject-flow FLOW

Package

cl-flow

Source

context.lisp (file)

Function: interrupt-flow &optional CONDITION

Interrupts flow with provided condition

Package

cl-flow

Source

asynchronously.lisp (file)

Function: rerun-flow-block ()

Package

cl-flow

Source

context.lisp (file)

Function: run DISPATCHER FLOW

Dispatcher must be a function with lambda-list congruent to (task arg invariant &key &allow-other-keys)

Package

cl-flow

Source

run.lisp (file)

Function: skip-flow-block ()

Package

cl-flow

Source

context.lisp (file)

Function: use-flow-block-value VALUE

Package

cl-flow

Source

context.lisp (file)

5.2 Internal definitions

5.2.1 Constants

Constant: +min-stack-extension+

Package

cl-flow

Source

context.lisp (file)

Constant: +optimize-form+

Package

cl-flow

Source

utils.lisp (file)

5.2.2 Special variables

Special Variable: *continue*

Package

cl-flow

Source

context.lisp (file)

Special Variable: *current-context*

Package

cl-flow

Source

context.lisp (file)

Special Variable: *parent-context*

Package

cl-flow

Source

context.lisp (file)

5.2.3 Macros

Macro: %flow-lambda (FLOW-CONTEXT) &body BODY

Package

cl-flow

Source

flow.lisp (file)

Macro: %with-flow-function (FU-NAME FU-LAMBDA-LIST &body FU-BODY) &body BODY

Package

cl-flow

Source

flow.lisp (file)

Macro: flow-lambda-macro (FLOW-CONTEXT) &body BODY

Package

cl-flow

Source

flow.lisp (file)

Macro: with-flow-function-macro (FU-NAME FU-LAMBDA-LIST FU-BODY) &body BODY

Package

cl-flow

Source

flow.lisp (file)

Macro: with-flow-let-macro (VAR FLOW) &body BODY

Package

cl-flow

Source

flow.lisp (file)

5.2.4 Functions

Function: %%inject-invoke FLOW

Package

cl-flow

Source

context.lisp (file)

Function: %%inject-invoke-text STREAM

Package

cl-flow

Source

context.lisp (file)

Function: %%rerun-invoke ()

Package

cl-flow

Source

context.lisp (file)

Function: %%rerun-invoke-text STREAM

Package

cl-flow

Source

context.lisp (file)

Function: %%skip-invoke ()

Package

cl-flow

Source

context.lisp (file)

Function: %%skip-invoke-text STREAM

Package

cl-flow

Source

context.lisp (file)

Function: %%use-invoke VALUE

Package

cl-flow

Source

context.lisp (file)

Function: %%use-invoke-text STREAM

Package

cl-flow

Source

context.lisp (file)

Function: %dispatch-concurrently PARENT-CONTEXT FLOW

Package

cl-flow

Source

concurrently.lisp (file)

Function: %dispatch-rest FLOW-CONTEXT

Package

cl-flow

Source

context.lisp (file)

Function: %invoke-with-restarts FU ARG

Package

cl-flow

Source

context.lisp (file)

Function: capture-flow-value CONTEXT VALUE

Package

cl-flow

Source

context.lisp (file)

Function: chop-head CONTEXT

Package

cl-flow

Source

context.lisp (file)

Function: copy-flow-context INSTANCE

Package

cl-flow

Source

context.lisp (file)

Function: dispatch CONTEXT TASK INVARIANT &rest ARGS &key &allow-other-keys

Package

cl-flow

Source

context.lisp (file)

Function: dispatch-asynchronously FLOW-CONTEXT BODY-FU

Package

cl-flow

Source

asynchronously.lisp (file)

Function: dispatch-atomically CONTEXT FU INVARIANT &rest OPTS &key &allow-other-keys

Package

cl-flow

Source

atomically.lisp (file)

Function: dispatch-concurrently PARENT-CONTEXT FLOW

Package

cl-flow

Source

concurrently.lisp (file)

Function: dispatch-dynamically FLOW-CONTEXT BODY-FU

Package

cl-flow

Source

dynamically.lisp (file)

Function: dispatch-repeatedly FLOW-CONTEXT TEST-FU FLOW

Package

cl-flow

Source

repeatedly.lisp (file)

Function: dispatch-rest CONTEXT

Package

cl-flow

Source

context.lisp (file)

Function: dispatch-serially FLOW-CONTEXT FLOW

Package

cl-flow

Source

serially.lisp (file)

Function: flow-context-dispatcher INSTANCE

Function: (setf flow-context-dispatcher) VALUE INSTANCE

Package

cl-flow

Source

context.lisp (file)

Function: flow-context-function INSTANCE

Function: (setf flow-context-function) VALUE INSTANCE

Package

cl-flow

Source

context.lisp (file)

Function: flow-context-native-dispatcher INSTANCE

Package

cl-flow

Source

context.lisp (file)

Function: flow-context-p OBJECT

Package

cl-flow

Source

context.lisp (file)

Function: flow-context-parent INSTANCE

Package

cl-flow

Source

context.lisp (file)

Function: flow-context-stack INSTANCE

Package

cl-flow

Source

context.lisp (file)

Function: flow-context-value INSTANCE

Function: (setf flow-context-value) VALUE INSTANCE

Package

cl-flow

Source

context.lisp (file)

Function: init-context-dispatcher CONTEXT

Package

cl-flow

Source

context.lisp (file)

Function: invoke-flow-function CONTEXT

Package

cl-flow

Source

context.lisp (file)

Function: invoke-with-restarts FLOW-CONTEXT FU ARG

Package

cl-flow

Source

context.lisp (file)

Function: make-child-flow-context PARENT-CONTEXT

Package

cl-flow

Source

context.lisp (file)

Function: make-flow-context &key (NATIVE-DISPATCHER NATIVE-DISPATCHER) (DISPATCHER DISPATCHER) (VALUE VALUE) (FUNCTION FUNCTION) (STACK STACK) (PARENT PARENT)

Package

cl-flow

Source

context.lisp (file)

Function: parse-atomic-block-args ARGS

Package

cl-flow

Source

flow.lisp (file)

Function: push-flow-stack CONTEXT FLOW

Package

cl-flow

Source

context.lisp (file)

Function: try-restart RESTART-NAME &optional ARG

Package

cl-flow

Source

context.lisp (file)

5.2.5 Structures

Structure: flow-context ()

Package

cl-flow

Source

context.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: native-dispatcher

Type

(or null function)

Readers

flow-context-native-dispatcher (function)

Writers

(setf flow-context-native-dispatcher) (function)

Slot: dispatcher

Type

(or null function)

Readers

flow-context-dispatcher (function)

Writers

(setf flow-context-dispatcher) (function)

Slot: value

Readers

flow-context-value (function)

Writers

(setf flow-context-value) (function)

Slot: function

Type

(or null function)

Readers

flow-context-function (function)

Writers

(setf flow-context-function) (function)

Slot: stack

Type

array

Initform

(make-array cl-flow::+min-stack-extension+ :element-type (quote list) :initial-element nil :fill-pointer 0 :adjustable t)

Readers

flow-context-stack (function)

Writers

(setf flow-context-stack) (function)

Slot: parent

Type

(or null cl-flow::flow-context)

Readers

flow-context-parent (function)

Writers

(setf flow-context-parent) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types