whew.core — com.github.igrishaev/whew 0.1.0

A number of wrappers on top of CompletableFuture.

->future clj

(->future x)

Turn a value into a future. Relies on the IFuture protocol.

-FUNC-FOLDER clj

A special Function instance to fold/collapse nested futures into a flat one.

all-of clj

(all-of futures)

Accepts a collection of values or futures and returns a new future with a vector of values in the same order.

any-of clj

(any-of futures)

Accepts a collection of values or futures. Returns a new future with a value from the first completed (or failed) future.

biconsumer clj macro

(biconsumer [a b] & body)

bifunction clj macro

(bifunction [a b] & body)

cancel clj

(cancel f)

Try to cancel a given future.

cancelled? clj

(cancelled? f)

Check if a future has been canceled.

catch clj macro

(catch f [e] & body)

Handles an exception that comes from a future. The e binding argument is assigned to an exception instance. The exception is unwrapped in advance meaning instead of ExecutionException you'll get its cause.

Returns a new CompletableFuture instance with a value produced by a block of code.

catch-fn clj

(catch-fn f func)

(catch-fn f func & args)

Like catch but accepts a 1-arity function that handles an unwrapped exception.

chain clj macro

(chain f & funcs)

Pass a future though a series of 1-arity functions, each one accepting a value and returning either a new value or a future.

deref clj

(deref f)

(deref f timeout-ms timeout-val)

Like the standard deref but flattens a nested future before .get-ting a value from it. Might be called with a timeout and a default value.

e-unwrap clj

(e-unwrap e)

Given a CompletionException or ExecutionException instance, dig recursively for a wrapped exception.

enumerate clj

(enumerate coll)

EXECUTOR_CLJ_POOLED clj

EXECUTOR_CLJ_SOLO clj

EXECUTOR_DEFAULT clj

EXECUTOR_FJ_COMMON clj

failed? clj

(failed? f)

Check if a future instance has already failed. For non-future values, return nil.

fold clj

(fold f)

Turn a future that returns a future, that returns a future, and so on... into a one-level future.

for clj macro

(for bindings & body)

Like for but:

• each body expression is wrapped into a future;
• the result is a future with a vector of values in the same order.

All the default for features are supported (:let, :when and so on).

@(for [x [1 2 3]] {:x x}) [{:x 1} {:x 2} {:x 3}]

function clj macro

(function [this bind] & body)

Produce a Function instance from a block of code. The first binding argument represents the instance for recursive calls. The second argument is bound to the incoming parameter.

FUT_ARR_CLASS clj

future clj macro

(future & body)

Acts like future-async.

future-array clj

(future-array coll)

Turn a Clojure collection of CompletableFuture instances into a native array.

future-array? clj

(future-array? x)

Is it a native array of CompletableFuture instances?

future-async clj macro

(future-async & body)

Produce an asynchronous CompletableFuture instance from a block of code.

future-sync clj macro

(future-sync & body)

Evaluate a block of code and emit a completed future instance with the result. The block is executed synchronously in the current thread.

future-via clj macro

(future-via [executor] & body)

Spawn a new CompletableFuture within a custom executor instance (e.g. a fixed thread executor pool, virtual executor and so on).

future? clj

(future? x)

Check if a given argument is an instance of CompletableFuture.

handle clj macro

(handle f [r e] & body)

Handles both a result and a possible exception in place.

• r is bound to a result, or nil;
• e is bount to an exception, or nil;
• body is an arbitrary block of code that checks if e is nil and produces either a value, a future or throws an exception.

@(-> (future 42) (handle [r e] (if e {:error (ex-message e)} (future (inc r))))) 43

Returns a new future.

handle-fn clj macro

(handle-fn f func)

Like handle but accepts 2-arity function with a result and an exception. Returns a new future.

IFuture clj protocol

-to-future clj

(-to-future x)

let clj macro

(let bindings & body)

Like let but:

• each binding value might produce a future;
• the body will be executed with dereferenced values when all the futures are ready.

Binding should not depend on each other (overlap). The result is a new CompletableFuture instance with a valur produced by the block of code.

@(let [a (future (future 1)) b (future (future 2))] (+ a b)) 3

loop clj macro

(loop bindings & body)

Like loop but produces a future that produces a fututure that produces... and so on. Key features:

• return a future with a handler that calls itself recursively;
• binding values can be futures as well;
• for recur, there is a special macro with the same naem (don't mix it with the standard recur).

@(loop [i 0 acc []] (if (< i 3) (recur (inc i) (future (future (conj acc i)))) (future (future acc)))) [1 2 3]

map clj

(map f coll)

(map f coll & colls)

Like map but works with collection(s) of futures. Any value of a collection might be a future. The f function gets applied with then-fn. It might produce a future as well.

Can accept multiple collections; arity of the f function should match the number of collections. Every nth future is taken from collections, and one all of them are ready, plain values are passed into a function.

Return a lazy collection of futures.

recur clj macro

(recur & args)

A special value for loop (see below).

recur? clj

(recur? x)

set-executor! clj

(set-executor! executor)

Set a default global executor for all async futures.

supplier clj macro

(supplier & body)

Produce a Supplier instance from a block of code.

then clj macro

(then f [bind] & body)

Apply a block of code to a future. Better used with the -> macro as follows:

(-> (future 42) (then [x] (let [a 1 b 2] (+ a b x))))

The first argument is a future, which might be nested. The second binding artument is a value that comes from the future. The block of code produces a new value for the future. It might return another future as well.

Return a new CompletableFuture instance.

then-fn clj

(then-fn f func)

(then-fn f func & args)

Like then but accepts a function that accepts a result of a future, and produces either a new value or a future.

(-> (future 42) (then-fn inc))

Also accepts additional arguments to the function:

(-> (future 42) (then-fn + 1 2 3))

Return a new CompletableFuture instance.

throw! clj macro

(throw! message)

(throw! message & args)

timeout clj macro

(timeout f timeout-ms)

(timeout f timeout-ms & body)

A macro to set timeout for given future. Without a block of code, just limits the execution time. When time is up, a future ends up with a timeout exception.

If the block of code presents, it provides a value for a future should it completes due to timeout.

Examples:

;; let this future spend up to 1 second but no more (-> (future (some-long-action ...)) (timeout 1000))

;; the same but provide a fallback (-> (future (some-long-action ...)) (timeout 1000 (log/error ....) {:error 'try next time'}))

zip clj macro

(zip & forms)

Turn a number of forms into futures. Return a new CompletableFuture instance with a vector of values in the same order.

@(zip 1 (future 2) 3) [1 2 3]