com.xadecimal.async-style.impl
adocljmacro
(ado & exprs)Asynchronous do. Execute expressions one after the other, awaiting the result of each one before moving on to the next. Results are lost to the void, same as clojure.core/do, so side effects are expected. Returns a promise-chan which settles with the result of the last expression when the entire do! is done.
Asynchronous do. Execute expressions one after the other, awaiting the result of each one before moving on to the next. Results are lost to the void, same as clojure.core/do, so side effects are expected. Returns a promise-chan which settles with the result of the last expression when the entire do! is done.
aletcljmacro
(alet bindings & exprs)Asynchronous let. Binds result of async expressions to local binding, executing bindings in order one after the other.
Asynchronous let. Binds result of async expressions to local binding, executing bindings in order one after the other.
allclj
(all chans)Takes a seqable of chans as an input, and returns a promise-chan that settles after all of the given chans have fulfilled in ok?, with a vector of the taken ok? results of the input chans. This returned promise-chan will settle when all of the input's chans have fulfilled, or if the input seqable contains no chans (only values or empty). It settles in error? immediately upon any of the input chans returning an error? or non-chans throwing an error?, and will contain the error? of the first taken chan to return one.
Takes a seqable of chans as an input, and returns a promise-chan that settles after all of the given chans have fulfilled in ok?, with a vector of the taken ok? results of the input chans. This returned promise-chan will settle when all of the input's chans have fulfilled, or if the input seqable contains no chans (only values or empty). It settles in error? immediately upon any of the input chans returning an error? or non-chans throwing an error?, and will contain the error? of the first taken chan to return one.
all-settledclj
(all-settled chans)Takes a seqable of chans as an input, and returns a promise-chan that settles after all of the given chans have fulfilled in ok? or error?, with a vector of the taken ok? results and error? results of the input chans.
It is typically used when you have multiple asynchronous tasks that are not dependent on one another to complete successfully, or you'd always like to know the result of each chan even when one errors.
In comparison, the promise-chan returned by all may be more appropriate if the tasks are dependent on each other / if you'd like to immediately stop upon any of them returning an error?.
Takes a seqable of chans as an input, and returns a promise-chan that settles after all of the given chans have fulfilled in ok? or error?, with a vector of the taken ok? results and error? results of the input chans. It is typically used when you have multiple asynchronous tasks that are not dependent on one another to complete successfully, or you'd always like to know the result of each chan even when one errors. In comparison, the promise-chan returned by all may be more appropriate if the tasks are dependent on each other / if you'd like to immediately stop upon any of them returning an error?.
anyclj
(any chans)Returns a promise-chan that settles as soon as one of the chan in chans fulfills in ok?, with the value taken (and joined) from that chan.
Unlike race, this will ignore chans that fulfilled with an error?. So if the first chan to fulfill does so with an error?, any will keep waiting for another chan to eventually fulfill in ok?.
If all chans fulfill in error?, returns an error containing the list of all the errors.
Once a chan fulfills with an ok?, any cancels all the others.
Returns a promise-chan that settles as soon as one of the chan in chans fulfills in ok?, with the value taken (and joined) from that chan. Unlike race, this will ignore chans that fulfilled with an error?. So if the first chan to fulfill does so with an error?, any will keep waiting for another chan to eventually fulfill in ok?. If all chans fulfill in error?, returns an error containing the list of all the errors. Once a chan fulfills with an ok?, any cancels all the others.
asynccljmacro
(async & body)Asynchronously execute body on the async-pool with support for cancellation, implicit-try, and returning a promise-chan settled with the result or any exception thrown.
body will run on the async-pool, so if you plan on doing something blocking or compute heavy, use blocking or compute instead.
Asynchronously execute body on the async-pool with support for cancellation, implicit-try, and returning a promise-chan settled with the result or any exception thrown. body will run on the async-pool, so if you plan on doing something blocking or compute heavy, use blocking or compute instead.
awaitcljmacro
(await chan-or-value & body)Parking takes from chan-or-value so that any exception taken is re-thrown, and with taken result fully joined.
Supports implicit-try to handle thrown exceptions such as:
(async (await (async (/ 1 0)) (catch ArithmeticException e (println e)) (catch Exception e (println "Other unexpected excpetion")) (finally (println "done"))))
Parking takes from chan-or-value so that any exception taken is re-thrown,
and with taken result fully joined.
Supports implicit-try to handle thrown exceptions such as:
(async
(await (async (/ 1 0))
(catch ArithmeticException e
(println e))
(catch Exception e
(println "Other unexpected excpetion"))
(finally (println "done"))))await*cljmacro
(await* chan-or-value)Parking takes from chan-or-value so that any exception is returned, and with taken result fully joined.
Parking takes from chan-or-value so that any exception is returned, and with taken result fully joined.
blockingcljmacro
(blocking & body)Asynchronously execute body on the blocking-pool with support for cancellation, implicit-try, and returning a promise-chan settled with the result or any exception thrown.
body will run on the blocking-pool, so use this when you will be blocking or doing blocking io only.
Asynchronously execute body on the blocking-pool with support for cancellation, implicit-try, and returning a promise-chan settled with the result or any exception thrown. body will run on the blocking-pool, so use this when you will be blocking or doing blocking io only.
cancel!clj
(cancel! chan)(cancel! chan v)When called on chan, tries to tell processes currently executing over the chan that they should interrupt and short-circuit (aka cancel) their execution as soon as they can, as it is no longer needed.
The way cancellation is conveyed is by settling the return channel of async, blocking and compute blocks to a CancellationException, unless passed a v explicitly, in which case it will settle it with v.
That means by default a block that has its execution cancelled will return a CancellationException and thus awaiters and other takers of its result will see the exception and can handle it accordingly. If instead you want to cancel the block so it returns a value, pass in a v and the awaiters and takers will receive that value instead. You can't set nil as the cancelled value, attempting to do so will throw an IllegalArgumentException.
It is up to processes inside async, blocking and compute blocks to properly check for cancellation on a channel.
When called on chan, tries to tell processes currently executing over the chan that they should interrupt and short-circuit (aka cancel) their execution as soon as they can, as it is no longer needed. The way cancellation is conveyed is by settling the return channel of async, blocking and compute blocks to a CancellationException, unless passed a v explicitly, in which case it will settle it with v. That means by default a block that has its execution cancelled will return a CancellationException and thus awaiters and other takers of its result will see the exception and can handle it accordingly. If instead you want to cancel the block so it returns a value, pass in a v and the awaiters and takers will receive that value instead. You can't set nil as the cancelled value, attempting to do so will throw an IllegalArgumentException. It is up to processes inside async, blocking and compute blocks to properly check for cancellation on a channel.
cancelled?clj
(cancelled?)Returns true if execution context was cancelled and thus should be interrupted/short-circuited, false otherwise.
Users are expected, when inside an execution block like async, blocking or compute, to check using (cancelled? or check-cancelled!) as often as they can in case someone tried to cancel their execution, in which case they should interrupt/short-circuit the work as soon as they can.
Returns true if execution context was cancelled and thus should be interrupted/short-circuited, false otherwise. Users are expected, when inside an execution block like async, blocking or compute, to check using (cancelled? or check-cancelled!) as often as they can in case someone tried to cancel their execution, in which case they should interrupt/short-circuit the work as soon as they can.
catchclj
(catch chan error-handler)(catch chan pred-or-type error-handler)Parking takes fully joined value from chan. If value is an error of pred-or-type, will call error-handler with it.
Returns a promise-chan settled with the value or the return of the error-handler.
error-handler will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
Parking takes fully joined value from chan. If value is an error of pred-or-type, will call error-handler with it. Returns a promise-chan settled with the value or the return of the error-handler. error-handler will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
chainclj
(chain chan & fs)Chains multiple then together starting with chan like: (-> chan (then f1) (then f2) (then fs) ...)
fs will all run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
Chains multiple then together starting with chan like: (-> chan (then f1) (then f2) (then fs) ...) fs will all run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
check-cancelled!clj
(check-cancelled!)Throws if execution context was cancelled and thus should be interrupted/short-circuited, returns nil.
Users are expected, when inside an execution block like async, blocking or compute, to check using (cancelled? or check-cancelled!) as often as they can in case someone tried to cancel their execution, in which case they should interrupt/short-circuit the work as soon as they can.
Throws if execution context was cancelled and thus should be interrupted/short-circuited, returns nil. Users are expected, when inside an execution block like async, blocking or compute, to check using (cancelled? or check-cancelled!) as often as they can in case someone tried to cancel their execution, in which case they should interrupt/short-circuit the work as soon as they can.
cletcljmacro
(clet bindings & body)Concurrent let. Executes all bound expressions in an async block so that the bindings run concurrently. If a later binding or the body depends on an earlier binding, that reference is automatically replaced with an await. In a blocking/compute context, await is transformed to wait for proper blocking behavior.
Notes:
- Bindings are evaluated in the async-pool; therefore, they should not perform blocking I/O or heavy compute directly. If you need to do blocking operations or heavy compute, wrap the binding in a blocking or compute call.
- This macro only supports simple symbol bindings; destructuring (vector or map destructuring) is not supported.
- It will transform symbols even inside quoted forms, so literal code in quotes may be rewritten unexpectedly.
- Inner local bindings (e.g. via a nested let) that shadow an outer binding are not handled separately; the macro will attempt to rewrite every occurrence, which may lead to incorrect replacements.
- Anonymous functions that use parameter names identical to outer bindings will also be rewritten, which can cause unintended behavior if they are meant to shadow those bindings.
Concurrent let. Executes all bound expressions in an async block so that
the bindings run concurrently. If a later binding or the body depends on an
earlier binding, that reference is automatically replaced with an await.
In a blocking/compute context, await is transformed to wait for proper
blocking behavior.
Notes:
* Bindings are evaluated in the async-pool; therefore, they should not
perform blocking I/O or heavy compute directly. If you need to do blocking
operations or heavy compute, wrap the binding in a blocking or compute call.
* This macro only supports simple symbol bindings; destructuring (vector or
map destructuring) is not supported.
* It will transform symbols even inside quoted forms, so literal code in quotes
may be rewritten unexpectedly.
* Inner local bindings (e.g. via a nested let) that shadow an outer binding are
not handled separately; the macro will attempt to rewrite every occurrence,
which may lead to incorrect replacements.
* Anonymous functions that use parameter names identical to outer bindings
will also be rewritten, which can cause unintended behavior if they are meant
to shadow those bindings.computecljmacro
(compute & body)Asynchronously execute body on the compute-pool with support for cancellation, implicit-try, and returning a promise-chan settled with the result or any exception thrown.
body will run on the compute-pool, so use this when you will be doing heavy computation, and don't block, if you're going to block use blocking instead. If you're doing a very small computation, like polling another chan, use async instead.
Asynchronously execute body on the compute-pool with support for cancellation, implicit-try, and returning a promise-chan settled with the result or any exception thrown. body will run on the compute-pool, so use this when you will be doing heavy computation, and don't block, if you're going to block use blocking instead. If you're doing a very small computation, like polling another chan, use async instead.
compute'cljmacro
(compute' & body)Executes the body in the compute-pool, returning immediately to the calling thread. Returns a channel which will receive the result of the body when completed, then close.
Executes the body in the compute-pool, returning immediately to the calling thread. Returns a channel which will receive the result of the body when completed, then close.
deferclj
(defer ms value-or-fn)Waits ms time and then asynchronously executes value-or-fn, returning a promsie-chan settled with the result.
value-or-fn will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
Waits ms time and then asynchronously executes value-or-fn, returning a promsie-chan settled with the result. value-or-fn will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
error?clj
(error? v)Returns true if v is considered an error as per async-style's error representations, false otherwise. Valid error representations in async-style for now are:
- instances of Throwable
Returns true if v is considered an error as per async-style's error representations, false otherwise. Valid error representations in async-style for now are: * instances of Throwable
finallyclj
(finally chan f)Parking takes fully joined value from chan, and calls f with it no matter if the value is ok? or error?.
Returns a promise-chan settled with the taken value, and not the return of f, which means f is implied to be doing side-effect(s).
f will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
Parking takes fully joined value from chan, and calls f with it no matter if the value is ok? or error?. Returns a promise-chan settled with the taken value, and not the return of f, which means f is implied to be doing side-effect(s). f will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
handleclj
(handle chan f)(handle chan ok-handler error-handler)Asynchronously executes f with the result of chan once available (f result), unlike then, handle will always execute f, when chan's result is an error f is called with the error (f error).
Returns a promise-chan settled with the result of f.
Alternatively, one can pass an ok-handler and an error-handler and the respective one will be called based on if chan's result is ok (ok-handler result) or an error (error-handler error).
f, ok-handler and error-handler will all run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
Asynchronously executes f with the result of chan once available (f result), unlike then, handle will always execute f, when chan's result is an error f is called with the error (f error). Returns a promise-chan settled with the result of f. Alternatively, one can pass an ok-handler and an error-handler and the respective one will be called based on if chan's result is ok (ok-handler result) or an error (error-handler error). f, ok-handler and error-handler will all run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
ok?clj
(ok? v)Returns true if v is not considered an error as per async-style's error representations, false otherwise. Valid error representations in async-style for now are:
- instances of Throwable
Returns true if v is not considered an error as per async-style's error representations, false otherwise. Valid error representations in async-style for now are: * instances of Throwable
raceclj
(race chans)Returns a promise-chan that settles as soon as one of the chan in chans fulfill, with the value taken (and joined) from that chan.
Unlike any, this will also return the first error? to be returned by one of the chans. So if the first chan to fulfill does so with an error?, race will return a promise-chan settled with that error.
Once a chan fulfills, race cancels all the others.
Returns a promise-chan that settles as soon as one of the chan in chans fulfill, with the value taken (and joined) from that chan. Unlike any, this will also return the first error? to be returned by one of the chans. So if the first chan to fulfill does so with an error?, race will return a promise-chan settled with that error. Once a chan fulfills, race cancels all the others.
sleepclj
(sleep ms)Asynchronously sleep ms time, returns a promise-chan which settles after ms time.
Asynchronously sleep ms time, returns a promise-chan which settles after ms time.
thenclj
(then chan f)Asynchronously executes f with the result of chan once available, unless chan results in an error, in which case f is not executed.
Returns a promise-chan settled with the result of f or the error.
f will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
Asynchronously executes f with the result of chan once available, unless chan results in an error, in which case f is not executed. Returns a promise-chan settled with the result of f or the error. f will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
timecljmacro
(time expr)(time expr print-fn)Evaluates expr and prints the time it took. Returns the value of expr. If expr evaluates to a channel, it waits for channel to fulfill before printing the time it took.
Evaluates expr and prints the time it took. Returns the value of expr. If expr evaluates to a channel, it waits for channel to fulfill before printing the time it took.
timeoutclj
(timeout chan ms)(timeout chan ms timed-out-value-or-fn)If chan fulfills before ms time has passed, return a promise-chan settled with the result, else returns a promise-chan settled with a TimeoutException or the result of timed-out-value-or-fn.
In the case of a timeout, chan will be cancelled.
timed-out-value-or-fn will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
If chan fulfills before ms time has passed, return a promise-chan settled with the result, else returns a promise-chan settled with a TimeoutException or the result of timed-out-value-or-fn. In the case of a timeout, chan will be cancelled. timed-out-value-or-fn will run on the async-pool, so if you plan on doing something blocking or compute heavy, remember to wrap it in a blocking or compute respectively.
waitcljmacro
(wait chan-or-value & body)Blocking takes from chan-or-value so that any exception taken is re-thrown, and with taken result fully joined.
Supports implicit-try to handle thrown exceptions such as:
(wait (async (/ 1 0)) (catch ArithmeticException e (println e)) (catch Exception e (println "Other unexpected excpetion")) (finally (println "done")))
Blocking takes from chan-or-value so that any exception taken is re-thrown,
and with taken result fully joined.
Supports implicit-try to handle thrown exceptions such as:
(wait (async (/ 1 0))
(catch ArithmeticException e
(println e))
(catch Exception e
(println "Other unexpected excpetion"))
(finally (println "done")))wait*clj
(wait* chan-or-value)Blocking takes from chan-or-value so that any exception is returned, and with taken result fully joined.
Blocking takes from chan-or-value so that any exception is returned, and with taken result fully joined.
with-lockcljmacro
(with-lock lock & body)Run body while holding the given ReentrantLock.
Run body while holding the given ReentrantLock.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close