ClojureDocs

Namespaces

clojure.core.async

Facilities for async programming and communication.

go blocks are dispatched over an internal thread pool, which
defaults to 8 threads. The size of this pool can be modified using
the Java system property `clojure.core.async.pool-size`.

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.

A Clojure library providing facilities for async programming and communication.

Core.async is not provided as part of Clojure’s standard distribution, and must be included as a dependency.

Community Links
Vars in clojure.core.async

*^%

<!
takes a val from port. Must be called inside a (go ...) block. Will return nil if closed. Will park if nothing is available.
<!!
takes a val from port. Will return nil if closed. Will block if nothing is available. Not intended for use in direct or transitive calls from (go ...) blocks. Use the clojure.core.async.go-checking flag to detect invalid use (see namespace docs).
>!
puts a val into port. nil values are not allowed. Must be called inside a (go ...) block. Will park if no buffer space is available. Returns true unless port is already closed.
>!!
puts a val into port. nil values are not allowed. Will block if no buffer space is available. Returns true unless port is already closed. Not intended for use in direct or transitive calls from (go ...) blocks. Use the clojure.core.async.go-checking flag to detect invalid use (see namespace docs).

a

admix
Adds ch as an input to the mix
admix*
no doc
alt!
Makes a single choice between one of several channel operations, as if by alts!, returning the value of the result expr corresponding to the operation completed. Must be called inside a (go ...) block. Each clause takes the form of: channel-op[s] result-expr where channel-ops is one of: take-port - a single port to take [take-port | [put-port put-val] ...] - a vector of ports as per alts! :default | :priority - an option for alts! and result-expr is either a list beginning with a vector, whereupon that vector will be treated as a binding for the [val port] return of the operation, else any other expression. (alt! [c t] ([val ch] (foo ch val)) x ([v] v) [[out val]] :wrote :default 42) Each option may appear at most once. The choice and parking characteristics are those of alts!.
alt!!
Like alt!, except as if by alts!!, will block until completed, and not intended for use in (go ...) blocks.
alts!
Completes at most one of several channel operations. Must be called inside a (go ...) block. ports is a vector of channel endpoints, which can be either a channel to take from or a vector of [channel-to-put-to val-to-put], in any combination. Takes will be made as if by !. Unless the :priority option is true, if more than one port operation is ready a non-deterministic choice will be made. If no operation is ready and a :default value is supplied, [default-val :default] will be returned, otherwise alts! will park until the first operation to become ready completes. Returns [val port] of the completed operation, where val is the value taken for takes, and a boolean (true unless already closed, as per put!) for puts. opts are passed as :key val ... Supported options: :default val - the value to use if none of the operations are immediately ready :priority true - (default nil) when true, the operations will be tried in order. Note: there is no guarantee that the port exps or val exprs will be used, nor in what order should they be, so they should not be depended upon for side effects.
alts!!
Like alts!, except takes will be made as if by !!, will block until completed. Not intended for use in direct or transitive calls from (go ...) blocks. Use the clojure.core.async.go-checking flag to detect invalid use (see namespace docs).

b

buffer
Returns a fixed buffer of size n. When full, puts will block/park.

c

chan
Creates a channel with an optional buffer, an optional transducer (like (map f), (filter p) etc or a composition thereof), and an optional exception-handler. If buf-or-n is a number, will create and use a fixed buffer of that size. If a transducer is supplied a buffer must be specified. ex-handler must be a fn of one argument - if an exception occurs during transformation it will be called with the Throwable as an argument, and any non-nil return value will be placed in the channel.
close!
Closes a channel. The channel will no longer accept any puts (they will be ignored). Data in the channel remains available for taking, until exhausted, after which takes will return nil. If there are any pending takes, they will be dispatched with nil. Closing a closed channel is a no-op. Returns nil. Logically closing happens after all puts have been delivered. Therefore, any blocked or parked puts will remain blocked/parked until a taker releases them.

d

do-alt
no doc
do-alts
returns derefable [val port] if immediate, nil if enqueued
dropping-buffer
Returns a buffer of size n. When full, puts will complete but val will be dropped (no transfer).

f

filter<
Deprecated - this function will be removed. Use transducer instead
filter>
Deprecated - this function will be removed. Use transducer instead

g

go
Asynchronously executes the body, returning immediately to the calling thread. Additionally, any visible calls to ! and alt!/alts! channel operations within the body will block (if necessary) by 'parking' the calling thread rather than tying up an OS thread (or the only JS thread when in ClojureScript). Upon completion of the operation, the body will be resumed. go blocks should not (either directly or indirectly) perform operations that may block indefinitely. Doing so risks depleting the fixed pool of go block threads, causing all go block processing to stop. This includes core.async blocking ops (those ending in !!) and other blocking IO. Returns a channel which will receive the result of the body when completed
go-loop
Like (go (loop ...))

i

into
Returns a channel containing the single (collection) result of the items taken from the channel conjoined to the supplied collection. ch must close before into produces a result.
ioc-alts!
no doc

m

map
Takes a function and a collection of source channels, and returns a channel which contains the values produced by applying f to the set of first items taken from each source channel, followed by applying f to the set of second items from each channel, until any one of the channels is closed, at which point the output channel will be closed. The returned channel will be unbuffered by default, or a buf-or-n can be supplied
map<
Deprecated - this function will be removed. Use transducer instead
map>
Deprecated - this function will be removed. Use transducer instead
mapcat<
Deprecated - this function will be removed. Use transducer instead
mapcat>
Deprecated - this function will be removed. Use transducer instead
merge
Takes a collection of source channels and returns a channel which contains all values taken from them. The returned channel will be unbuffered by default, or a buf-or-n can be supplied. The channel will close after all the source channels have closed.
mix
Creates and returns a mix of one or more input channels which will be put on the supplied out channel. Input sources can be added to the mix with 'admix', and removed with 'unmix'. A mix supports soloing, muting and pausing multiple inputs atomically using 'toggle', and can solo using either muting or pausing as determined by 'solo-mode'. Each channel can have zero or more boolean modes set via 'toggle': :solo - when true, only this (ond other soloed) channel(s) will appear in the mix output channel. :mute and :pause states of soloed channels are ignored. If solo-mode is :mute, non-soloed channels are muted, if :pause, non-soloed channels are paused. :mute - muted channels will have their contents consumed but not included in the mix :pause - paused channels will not have their contents consumed (and thus also not included in the mix)
Mix
no doc
Mult
no doc
mult
Creates and returns a mult(iple) of the supplied channel. Channels containing copies of the channel can be created with 'tap', and detached with 'untap'. Each item is distributed to all taps in parallel and synchronously, i.e. each tap must accept before the next item is distributed. Use buffering/windowing to prevent slow taps from holding up the mult. Items received when there are no taps get dropped. If a tap puts to a closed channel, it will be removed from the mult.
Mux
no doc
muxch*
no doc

o

offer!
Puts a val into port if it's possible to do so immediately. nil values are not allowed. Never blocks. Returns true if offer succeeds.
onto-chan
Deprecated - use onto-chan! or onto-chan!!
onto-chan!
Puts the contents of coll into the supplied channel. By default the channel will be closed after the items are copied, but can be determined by the close? parameter. Returns a channel which will close after the items are copied. If accessing coll might block, use onto-chan!! instead
onto-chan!!
Like onto-chan! for use when accessing coll might block, e.g. a lazy seq of blocking operations

p

partition
Deprecated - this function will be removed. Use transducer instead
partition-by
Deprecated - this function will be removed. Use transducer instead
pipe
Takes elements from the from channel and supplies them to the to channel. By default, the to channel will be closed when the from channel closes, but can be determined by the close? parameter. Will stop consuming the from channel if the to channel closes
pipeline
Takes elements from the from channel and supplies them to the to channel, subject to the transducer xf, with parallelism n. Because it is parallel, the transducer will be applied independently to each element, not across elements, and may produce zero or more outputs per input. Outputs will be returned in order relative to the inputs. By default, the to channel will be closed when the from channel closes, but can be determined by the close? parameter. Will stop consuming the from channel if the to channel closes. Note this should be used for computational parallelism. If you have multiple blocking operations to put in flight, use pipeline-blocking instead, If you have multiple asynchronous operations to put in flight, use pipeline-async instead. See chan for semantics of ex-handler.
pipeline-async
Takes elements from the from channel and supplies them to the to channel, subject to the async function af, with parallelism n. af must be a function of two arguments, the first an input value and the second a channel on which to place the result(s). The presumption is that af will return immediately, having launched some asynchronous operation whose completion/callback will put results on the channel, then close! it. Outputs will be returned in order relative to the inputs. By default, the to channel will be closed when the from channel closes, but can be determined by the close? parameter. Will stop consuming the from channel if the to channel closes. See also pipeline, pipeline-blocking.
pipeline-blocking
Like pipeline, for blocking operations.
poll!
Takes a val from port if it's possible to do so immediately. Never blocks. Returns value if successful, nil otherwise.
promise-chan
Creates a promise channel with an optional transducer, and an optional exception-handler. A promise channel can take exactly one value that consumers will receive. Once full, puts complete but val is dropped (no transfer). Consumers will block until either a value is placed in the channel or the channel is closed, then return the value (or nil) forever. See chan for the semantics of xform and ex-handler.
Pub
no doc
pub
Creates and returns a pub(lication) of the supplied channel, partitioned into topics by the topic-fn. topic-fn will be applied to each value on the channel and the result will determine the 'topic' on which that value will be put. Channels can be subscribed to receive copies of topics using 'sub', and unsubscribed using 'unsub'. Each topic will be handled by an internal mult on a dedicated channel. By default these internal channels are unbuffered, but a buf-fn can be supplied which, given a topic, creates a buffer with desired properties. Each item is distributed to all subs in parallel and synchronously, i.e. each sub must accept before the next item is distributed. Use buffering/windowing to prevent slow subs from holding up the pub. Items received when there are no matching subs get dropped. Note that if buf-fns are used then each topic is handled asynchronously, i.e. if a channel is subscribed to more than one topic it should not expect them to be interleaved identically with the source.
put!
Asynchronously puts a val into port, calling fn1 (if supplied) when complete, passing false iff port is already closed. nil values are not allowed. If on-caller? (default true) is true, and the put is immediately accepted, will call fn1 on calling thread. fn1 may be run in a fixed-size dispatch thread pool and should not perform blocking IO, including core.async blocking ops (those that end in !!). Returns true unless port is already closed.

r

reduce
f should be a function of 2 arguments. Returns a channel containing the single result of applying f to init and the first item from the channel, then applying f to that result and the 2nd item, etc. If the channel closes without yielding items, returns init and f is not called. ch must close before reduce produces a result.
remove<
Deprecated - this function will be removed. Use transducer instead
remove>
Deprecated - this function will be removed. Use transducer instead

s

sliding-buffer
Returns a buffer of size n. When full, puts will complete, and be buffered, but oldest elements in buffer will be dropped (not transferred).
solo-mode
Sets the solo mode of the mix. mode must be one of :mute or :pause
split
Takes a predicate and a source channel and returns a vector of two channels, the first of which will contain the values for which the predicate returned true, the second those for which it returned false. The out channels will be unbuffered by default, or two buf-or-ns can be supplied. The channels will close after the source channel has closed.
sub
Subscribes a channel to a topic of a pub. By default the channel will be closed when the source closes, but can be determined by the close? parameter.
sub*
no doc

t

take
Returns a channel that will return, at most, n items from ch. After n items have been returned, or ch has been closed, the return channel will close. The output channel is unbuffered by default, unless buf-or-n is given.
take!
Asynchronously takes a val from port, passing to fn1. Will pass nil if closed. If on-caller? (default true) is true, and value is immediately available, will call fn1 on calling thread. fn1 may be run in a fixed-size dispatch thread pool and should not perform blocking IO, including core.async blocking ops (those that end in !!). Returns nil.
tap
Copies the mult source onto the supplied channel. By default the channel will be closed when the source closes, but can be determined by the close? parameter.
tap*
no doc
thread
Executes the body in another thread, returning immediately to the calling thread. Returns a channel which will receive the result of the body when completed, then close.
thread-call
Executes f in another thread, returning immediately to the calling thread. Returns a channel which will receive the result of calling f when completed, then close.
timeout
Returns a channel that will close after msecs
to-chan
Deprecated - use to-chan! or to-chan!!
to-chan!
Creates and returns a channel which contains the contents of coll, closing when exhausted. If accessing coll might block, use to-chan!! instead
to-chan!!
Like to-chan! for use when accessing coll might block, e.g. a lazy seq of blocking operations
toggle
Atomically sets the state(s) of one or more channels in a mix. The state map is a map of channels -> channel-state-map. A channel-state-map is a map of attrs -> boolean, where attr is one or more of :mute, :pause or :solo. Any states supplied are merged with the current state. Note that channels can be added to a mix via toggle, which can be used to add channels in a particular (e.g. paused) state.
toggle*
no doc
transduce
async/reduces a channel with a transformation (xform f). Returns a channel containing the result. ch must close before transduce produces a result.

u

unblocking-buffer?
Returns true if a channel created with buff will never block. That is to say, puts into this buffer will never cause the buffer to be full.
unique
Deprecated - this function will be removed. Use transducer instead
unmix
Removes ch as an input to the mix
unmix*
no doc
unmix-all
removes all inputs from the mix
unsub
Unsubscribes a channel from a topic of a pub
unsub*
no doc
unsub-all
Unsubscribes all channels from a pub, or a topic of a pub
untap
Disconnects a target channel from a mult
untap*
no doc
untap-all
Disconnects all target channels from a mult