Liking cljdoc? Tell your friends :D

clojure.core.async

Facilities for async programming and communication.

Set Java system property clojure.core.async.go-checking to true to validate go blocks do not invoke core.async blocking operations. Property is read once, at namespace load time. Recommended for use primarily during development. Invalid blocking calls will throw in go block threads - use Thread.setDefaultUncaughtExceptionHandler() to catch and handle.

Use the Java system property clojure.core.async.executor-factory to specify a function that will provide ExecutorServices for application-wide use by core.async in lieu of its defaults. The property value should name a fully qualified var. The function will be passed a keyword indicating the context of use of the executor, and should return either an ExecutorService, or nil to use the default. Results per keyword will be cached and used for the remainder of the application. Possible context arguments are:

:io - used in async/io-thread, for :io workloads in flow/process, and for dispatch handling if no explicit dispatch handler is provided (see below)

:mixed - used by async/thread and for :mixed workloads in flow/process

:compute - used for :compute workloads in flow/process

:core-async-dispatch - used for completion fn handling (e.g. in put! and take!, as well as go block IOC thunk processing) throughout core.async. If not supplied the ExecutorService for :io will be used instead.

The set of contexts may grow in the future so the function should return nil for unexpected contexts.

Use the Java system property clojure.core.async.vthreads to control how core.async uses JDK 21+ virtual threads. The property can be one of the following values:

unset - core.async will opportunistically use vthreads when available (≥ Java 21) and will otherwise use the old IOC impl. io-thread and :io thread pool will run on platform threads if vthreads are not available. If AOT compiling, go blocks will always use IOC so that the resulting bytecode works on all JVMs (so no change in compiled output)

"target" - means that you are targeting virtual threads. At runtime from source, go blocks will throw if vthreads are not available. If AOT compiling, go blocks are always compiled as normal Clojure code to be run on vthreads and will throw at runtime if vthreads are not available (Java <21)

"avoid" - means that vthreads will not be used by core.async - you can use this to minimize impacts if you are not yet ready to utilize vthreads in your app. If AOT compiling, go blocks will use IOC. At runtime, io-thread and the :io thread pool use platform threads

Note: existing IOC compiled go blocks from older core.async versions continue to work (we retain and load the IOC state machine runtime - this does not require the analyzer), and you can interact with the same channels from both IOC and vthread code.

Facilities for async programming and communication.

Set Java system property `clojure.core.async.go-checking` to true
to validate go blocks do not invoke core.async blocking operations.
Property is read once, at namespace load time. Recommended for use
primarily during development. Invalid blocking calls will throw in
go block threads - use Thread.setDefaultUncaughtExceptionHandler()
to catch and handle.

Use the Java system property `clojure.core.async.executor-factory`
to specify a function that will provide ExecutorServices for
application-wide use by core.async in lieu of its defaults. The
property value should name a fully qualified var. The function
will be passed a keyword indicating the context of use of the
executor, and should return either an ExecutorService, or nil to
use the default. Results per keyword will be cached and used for
the remainder of the application. Possible context arguments are:

:io - used in async/io-thread, for :io workloads in flow/process,
and for dispatch handling if no explicit dispatch handler is
provided (see below)

:mixed - used by async/thread and for :mixed workloads in
flow/process

:compute - used for :compute workloads in flow/process

:core-async-dispatch - used for completion fn handling (e.g. in put!
and take!, as well as go block IOC thunk processing) throughout
core.async. If not supplied the ExecutorService for :io will be
used instead.

The set of contexts may grow in the future so the function should
return nil for unexpected contexts.

Use the Java system property `clojure.core.async.vthreads` to control
how core.async uses JDK 21+ virtual threads. The property can be one of
the following values:

unset - core.async will opportunistically use vthreads when available
(≥ Java 21) and will otherwise use the old IOC impl. io-thread and :io
thread pool will run on platform threads if vthreads are not available.
If AOT compiling, go blocks will always use IOC so that the resulting
bytecode works on all JVMs (so no change in compiled output)

"target" - means that you are targeting virtual threads. At runtime
from source, go blocks will throw if vthreads are not available.
If AOT compiling, go blocks are always compiled as normal Clojure
code to be run on vthreads and will throw at runtime if vthreads are
not available (Java <21)

"avoid" - means that vthreads will not be used by core.async - you can
use this to minimize impacts if you are not yet ready to utilize vthreads
in your app. If AOT compiling, go blocks will use IOC. At runtime, io-thread
and the :io thread pool use platform threads

Note: existing IOC compiled go blocks from older core.async versions continue
to work (we retain and load the IOC state machine runtime - this does not
require the analyzer), and you can interact with the same channels from both
IOC and vthread code.
raw docstring

clojure.core.async.flow

Note - Alpha, work-in-progress, names and other details are in flux

A library for building concurrent, event driven data processing flows out of communication-free functions, while centralizing control, reporting, execution and error handling. Built on core.async.

The top-level construct is the flow, comprising: a set of processes (generally, threads) - concurrent activities a set of channels flowing data into and out of the processes a set of channels for centralized control, reporting, error-handling, and execution of the processes

The flow library itself constructs processes, channels and flows. The user provides configuration data and process logic (step-fns) that specify how the flow should work.

A flow is constructed from flow configuration data which defines a directed graph of processes and the connections between them. Processes describe their I/O requirements and the flow (library) itself creates channels and passes them to the processes that requested them. See 'create-flow' for the details. The flow configuration provides a centralized place for policy decisions regarding process settings, threading, buffering etc.

It is expected that applications will rarely define instances of the process protocol but instead use the API function 'process' that implements the process protocol in terms of calls to ordinary functions (step-fns) that might include no communication or core.async code. In this way the library helps you achieve a strict separation of your application logic from its execution, communication, lifecycle, error handling and monitoring.

Note that at several points the library calls upon the user to supply ids for processes, inputs, outputs etc. These should be keywords. When a namespaced keyword is required it is explicitly stated. This documentation refers to various keywords utilized by the library itself as ::flow/xyz, where ::flow is an alias for clojure.core.async.flow

Flows support the Clojure 'datafy' protocol to support observability. See also the 'ping' and 'ping-proc' fns for a live view of processes.

A process is represented in the flow definition by an implementation of spi/ProcLauncher that starts it. See the spi docs for details.

Note - Alpha, work-in-progress, names and other details are in flux 

A library for building concurrent, event driven data processing
flows out of communication-free functions, while centralizing
control, reporting, execution and error handling. Built on core.async.

The top-level construct is the flow, comprising:
a set of processes (generally, threads) - concurrent activities
a set of channels flowing data into and out of the processes
a set of channels for centralized control, reporting, error-handling,
  and execution of the processes

The flow library itself constructs processes, channels and flows. The
user provides configuration data and process logic (step-fns) that
specify how the flow should work.

A flow is constructed from flow configuration data which defines a
directed graph of processes and the connections between
them. Processes describe their I/O requirements and the
flow (library) itself creates channels and passes them to the
processes that requested them. See 'create-flow' for the
details. The flow configuration provides a centralized place for
policy decisions regarding process settings, threading, buffering etc.

It is expected that applications will rarely define instances of the
process protocol but instead use the API function 'process' that
implements the process protocol in terms of calls to ordinary
functions (step-fns) that might include no communication or
core.async code. In this way the library helps you achieve a strict
separation of your application logic from its execution,
communication, lifecycle, error handling and monitoring.

Note that at several points the library calls upon the user to
supply ids for processes, inputs, outputs etc. These should be
keywords. When a namespaced keyword is required it is explicitly
stated. This documentation refers to various keywords utilized by
the library itself as ::flow/xyz, where ::flow is an alias for
clojure.core.async.flow

Flows support the Clojure 'datafy' protocol to support
observability. See also the 'ping' and 'ping-proc' fns for a live
view of processes.

A process is represented in the flow definition by an implementation
of spi/ProcLauncher that starts it. See the spi docs for
details.
raw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
Move to previous article
Move to next article
Ctrl+/Jump to the search field
× close