futurama.core — com.github.k13labs/futurama 1.3.0

Futurama is a Clojure library for more deeply integrating async abstractions in the Clojure and JVM ecosystem with Clojure.

async and thread blocks are dispatched over an internal thread pool, which defaults to using the ForkJoinPool/commonPool. They work very similarly to core.async go blocks and thread blocks. Notable different ways are that, async and thread blocks will return Throwable values when exceptions are uncaught, and that taking a value from an async result using !<! or !<!! will reduce nested async values to a single result.

The dynamic variables *async-factory* and *thread-factory* can be bound to control which async result type is returned when the async or thread macros are used. If an *async-factory* is bound but no *thread-factory*, then calls to thread will use the *async-factory*, or if a factory is not defined then the default async-promise-factory will be used instead.

Possible factories supported are:

• async-channel-factory: creates a core.async channel result, with a buffer of size 1.
• async-promise-factory: creates a core.async promise-channel result.
• async-deferred-factory: creates a manifold deferred result.
• async-future-factory: creates a CompletableFuture result.

Use the Java system property futurama.executor-factory to specify a function that will provide ExecutorServices for application-wide use by futurama in lieu of its defaults. To ensure that futurama uses the same thread pool as core.async, you can set the property to the value clojure.core.async.impl.dispatch/executor-for. 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 for :io workloads, default workload for async dispatch, use via (thread :io ...) or (async :io ...). :mixed - used for :mixed workloads, default workload for thread dispatch. :compute - used for :compute workloads, use via (thread :compute ...) or (async :compute ...).

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

Copied from core.async, because this is super useful:

Set Java system property clojure.core.async.go-checking to true to validate async 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.

!<! clj macro

(!<! v)copy

An improved macro version of <!, which also rethrows exceptions returned over the channel. Must be called INSIDE a (go ...) or (async ...) block.

• Will return nil if closed.
• Will park if nothing is available.
• Will throw if an Exception is taken from port.
• Will return the raw value if it is not a ReadPort
• Will fully read through any async result returned

!<!! clj macro

(!<!! v)copy

An improved macro version of <!!, which also rethrows exceptions returned over the channel. Must be called OUTSIDE a (go ...) or (async ...) block.

• Will return nil if closed.
• Will block if nothing is available.
• Will throw if a Exception is taken from port.
• Will return the raw value if it is not a ReadPort
• Will fully read through any async result returned

!<!* clj macro

(!<!* coll)copy

Like !<! but works with collections of async values

*async-factory* clj

*thread-factory* clj

*thread-pool* clj

->async-reader clj

(->async-reader x)copy

Creates an AsyncReader to read anything via take!

<! clj macro

(<! v)copy

An improved macro version of <!, which also rethrows exceptions returned over the channel. Must be called INSIDE a (go ...) or (async ...) block.

• Will return nil if closed.
• Will park if nothing is available.
• Will throw if an Exception is taken from port.
• Will return the raw value if it is not a ReadPort

<!! clj macro

(<!! v)copy

An improved macro version of <!!, which also rethrows exceptions returned over the channel. Must be called OUTSIDE a (go ...) or (async ...) block.

• Will return nil if closed.
• Will block if nothing is available.
• Will throw if a Exception is taken from port.
• Will return the raw value if it is not a ReadPort

<!* clj macro

(<!* coll)copy

Like <! but works with collections of async values

async clj macro

(async & workload-and-body)copy

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. Upon completion of the operation, the body will be resumed.

async 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 an instance of the (async-factory) which will receive the result of the body when completed; the pool used can be specified via *thread-pool* binding.

async! clj macro

(async! pool port & body)copy

Asynchronously executes the body, returning port immediately to te 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. Upon completion of the operation, the body will be resumed.

The success or failure output will be put! in port.

async 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 the provided port which will receive the result of the body when completed; the pool used can be specified via *thread-pool* binding.

async-> clj macro

(async-> v & call-seq)copy

Threads the expr through the forms which can return async result. Inserts v as the second item in the first form, making a list of it if it is not a list already. If there are more forms, inserts the first form as the second item in second form, etc.

async->> clj macro

(async->> v & call-seq)copy

Threads the expr through the forms which can return async result. Inserts x as the last item in the first form, making a list of it if it is not a list already. If there are more forms, inserts the first form as the last item in second form, etc.

async-cancel! clj

(async-cancel! item)copy

Cancels the async item.

async-cancellable? clj

(async-cancellable? v)copy

Determines if v satisfies? AsyncCancellable

async-cancelled? clj

(async-cancelled?)copy

(async-cancelled? item)copy

Checks if the current executing async item or one of its parents or provided item has been cancelled. Also checks if the thread has been interrupted and restores the interrupt status.

async-channel-factory clj

(async-channel-factory)copy

Creates a core async channel of size 1

async-completed? clj

(async-completed? x)copy

Checks if the provided AsyncCompletableReader instance is completed?

async-deferred-factory clj

(async-deferred-factory)copy

Creates a new Manifold Deferred

async-every? clj

(async-every? pred coll)copy

Returns true if (pred x) is logical true for every x in coll, else false.

async-factory clj

(async-factory)copy

builds a result object to be used inside async! macro, this function uses the *async-factory* it's is bound, or the default factory of async-promise-factory.

async-for clj macro

(async-for bindings & body)copy

works like a for macro, but supports core.async operations. bindings are initially bound and collected, then the data is iterated over using a loop and the output collected; note that only the body of the for can contain <! and !<! calls. This is implicitly wrapped in an async block.

async-future-factory clj

(async-future-factory)copy

Creates a new CompletableFuture

async-map clj

(async-map f coll & coll-seq)copy

Asynchronously returns the result of applying f to the set of first items of each coll, followed by applying f to the set of second items in each coll, until any one of the colls is exhausted. Any remaining items in other colls are ignored. Function f should accept number-of-colls arguments.

async-postwalk clj

(async-postwalk f form)copy

Performs a depth-first, post-order traversal of form. Calls f on each sub-form, uses f's return value in place of the original. Recognizes all Clojure data structures. Consumes seqs as with doall.

async-prewalk clj

(async-prewalk f form)copy

Like postwalk, but does pre-order traversal.

async-promise-factory clj

(async-promise-factory)copy

Creates a core async promise channel

async-reduce clj

(async-reduce f coll)copy

(async-reduce f init coll)copy

Like core/reduce except, when init is not provided, (f) is used, and async results are read with !<!.

async-some clj

(async-some pred coll)copy

Concurrently executes (pred x) and returns the first returned logical true value of (pred x) for any x in coll, else nil. One common idiom is to use a set as pred, for example this will return :fred if :fred is in the sequence, otherwise nil: (some #{:fred} coll). Please beware that unlike clojure.core/some this function returns the first asynchronous result that completes and evaluates to logical true, but not necessarily the first one in sequential order.

async-walk clj

(async-walk inner outer form)copy

Traverses form, an arbitrary data structure. inner and outer are functions. Applies inner to each element of form, building up a data structure of the same type, then applies outer to the result. Recognizes all Clojure data structures. Consumes seqs as with doall.

async? clj

(async? v)copy

returns true if v instance satisfies? core.async's ReadPort

ASYNC_CANCELLED clj

get-pool clj

Given a workload tag, returns an ExecutorService instance and memoizes the result. By default, futurama will defer to a user factory (if provided via sys prop) or the ForkJoinPool/commonPool instance. When using core.async 1.7 or higher it's possible to set the futurama.executor-factory property to clojure.core.async.impl.dispatch/executor-for and futurama will use the same pools as core.async.

rethrow-exception clj

(rethrow-exception v)copy

throw v if it is an Exception

set-async-factory! clj

(set-async-factory! async-factory-fn)copy

alters the root binding of *async-factory* to be equal to async-factory-fn

set-thread-factory! clj

(set-thread-factory! thread-factory-fn)copy

alters the root binding of *thread-factory* to be equal to `thread-factory-fn

thread clj macro

(thread & workload-and-body)copy

Asynchronously invokes the body in a pooled thread, preserves the current thread binding frame, and returns the value in a port created via thread-factory, the pool used can be specified via *thread-pool*, or through a keyword :io, :mixed, :compute for example.

thread! clj macro

(thread! pool port & body)copy

Asynchronously invokes the body inside a pooled thread and return over a write port, preserves the current thread binding frame, the pool used can be specified via *thread-pool*.

thread-factory clj

(thread-factory)copy

builds a result object to be used inside thread! macro, this function uses the first available factory of *thread-factory* or *async-factory*, or if neither is bound then uses the default factory of async-future-factory.

unwrap-exception clj

(unwrap-exception ex)copy

unwraps an ExecutionException or CompletionException via ex-cause until the root exception is returned

with-async-factory clj macro

(with-async-factory async-factory-fn & body)copy

temporarily binds *async-factory* to the speficied async-factory-fn and executes body.

with-pool clj macro

(with-pool pool & body)copy

Utility macro which binds thread-pool to the supplied pool and then evaluates the body. The pool can be an ExecutorService or can also be a keyword/string to be passed to the futurama.executor-factory

with-thread-factory clj macro

(with-thread-factory thread-factory-fn & body)copy

temporarily binds *thread-factory* to the speficied thread-factory-fn and executes body.