imminent.core — com.leonardoborges/imminent 0.2.0

Convenience namespace. Require this instead of the individual namespaces to prevent large namespace declarations. Its use is entirely optional.

->future clj

(->future promise)

Returns a Future backed by this promise

<*> clj

(<*> af)

(<*> af av)

(<*> af av & avs)

Performs a Haskell-style left-associative fapply on its arguments. (<*> f g h) is equivalent to (fapply (fapply f g) h). It always uses a two-argument fapply.

If only two arguments are supplied, it is equivalent to fapply. When called with one argument, creates a function that can accept the rest of the arguments and apply <*>.

alift clj

(alift f)

Lifts a n-ary function f into a applicative context

amb clj

(amb & fs)

The ambiguous function. Returns a future that will complete with the first Future in fs to return a value.

Applicative clj protocol

Applicative (applicative functor) is an abstraction for a context (box, container, computation) along with the abiliity to apply function(s) contained in the same type of context to all the things inside that context. Every Applicative should also implement Functor, although it can not be automatically forced by Clojure protocols.

A typical example is a clojure sequence, wich is a container of elements, with the ability to apply all the functions contained in another sequence to each of the elements, wich produces a new sequence of elements transformed by all the functions.

You create a new applicative functor type by extending the Applicative protocol and implementing pure and fapply methods, while observing applicative functor laws:

1. (fapply (pure x f) x) => (fmap f x)

2. Identity Law: (fapply (pure x identity) x) => x

3. Composition Law: (fapply (fapply (fapply (pure x (curry comp)) u) v) x) => (fapply u (fapply v x))

4. Homomorphism Law: (fapply (pure a f) (pure a x)) => (f x)

5. Interchange Law: (fapply u (pure a y)) => (fapply (pure a #(% y)) u)

Fluokitten's test library contains macros that generate tests for applicative functor laws.

The pure and fapply methods are not intended to be used directly by the caller, although you should use them directly from the implementation of this protocol if needed from other methods.

await clj

(await awaitable)

(await awaitable ms)

Blocks until the awaitable reference is done. Optionally awaits for up to 'ms' milliseconds, throwing a TimeoutException once time is up.

bind clj

(bind mv g)

(bind mv g mvs)

Applies the function g to the value(s) inside mv's context. Function g produces the result inside with the context, in contrast to fmap where function g is expect to produce normal values. If more monadic values are supplied in a sequence mvs, uses them as arguments for a vararg g. This method is intended to be used by fluokitten core's bind, not directly by clients. The third argument, mvs, contains a sequence of all additional arguments, normally supplied by core bind's varargs (protocol methods do not support varargs).

blocking-future clj macro

(blocking-future & body)

Dispatches body on a separate thread and returns a future that will eventually contain the result. body may block. See future-call

blocking-future-call clj

(blocking-future-call task)

Dispatches task on a separate thread and returns a future that will eventually contain the result of task. task may block.

complete clj

(complete promise value)

Completes this promise with the given value

completed? clj

(completed? fut)

Returns true when this future has been completed with a value or an exception. False otherwise

const-future clj

(const-future v)

Creates a new future and immediately completes it successfully with v

curry clj

(curry f)

(curry f arity)

Creates an automatically curried version of the function f. If arity is supplied, the function will be automatically curried when called with less arguments. If arity is not supplied, the default arity will depend on the arity of f. arity defaults to 2 if f can support it, otherwise it is 1.

---- Example: currying + (((curry +) 3) 5) => 8

((((curry + 3) 3) 5) 7) => 15

((curry +) 3 5 7) => 15

dderef clj

Same as (deref (deref x))

failed-future clj

(failed-future e)

failure clj

(failure v)

failure? clj

(failure? this)

fapply clj

(fapply ag av)

(fapply ag av avs)

Applies the function(s) inside ag's context to the value(s) inside av's context while preserving the context. Both contexts should be of the same (or compatible) type, and the type of the resulting context is determined by av's type. If more applicative functor values are supplied in a sequence avs, uses them as arguments for vararg function(s) inside the context ag. This method is intended to be used by fluokitten core's fapply, not directly by clients. The third argument, avs, contains a sequence of all additional arguments, normally supplied by core fapply's varargs (protocol methods do not support varargs).

filter clj

(filter fut pred)

Applies pred to the value of this Future. The new Future will contain a value of type success if (pre value) is true. It will contain a Failure wrapping a NoSuchElementException otherwise

filter-future clj

pred? needs to return a Future that yields a boolean. Returns a Future which yields a future containing all Futures which match pred?

flatmap clj

fmap clj

(fmap fv g)

(fmap fv g fvs)

Applies function g to the value(s) inside the context of the functor fv. The result is a functor of the same type as fv. If more functor values are supplied in a sequence fvs, uses them as arguments for a vararg g. This method is intended to be used by fluokitten core's fmap, not directly by clients. The first two arguments are reversed compared to core's fmap because protocol's polymorphism is based on java-based dispatch. The third parameter, fvs, contains a sequence of all additional arguments, normally supplied by core fmap's varargs (protocol methods do not support varargs).

from-try clj

(from-try f)

Creates a future from a function f. See try*

Functor clj protocol

Functor is an abstraction for a context (box, container, computation) along with the abiliity to apply a function to all the things inside that context. A typical example is a clojure sequence, wich is a container of elements, with the ability to apply a function to each of the elements, wich produces a new sequence of elements transformed by that function.

You create a new functor type by extending the Functor protocol and implementing fmap method, while observing functor laws:

1. (fmap identity) => identity , that is (fmap identity x) => (identity x)

2. (fmap (comp f g)) => (fmap f (fmap g)) or, when applied to a concrete functor (fmap (comp f g) x) => (fmap f (fmap g x))

(please note that core's fmap that has a different order of arguments has been used in these examples, as it would be used by clients)

Fluokitten's test library contains macros that generate tests for functor laws.

The fmap method is not intended to be used directly by the caller, although you should use it directly from the implementation of this protocol if needed from other methods.

future clj macro

(future & body)

Dispatches body on a separate thread and returns a future that will eventually contain the result. body must be free of side effects. See future-call

future-call clj

(future-call task)

Dispatches task on a separate thread and returns a future that will eventually contain the result of task. task must be free of side effects.

IAwaitable clj protocol

IFuture clj protocol

IPromise clj protocol

IReturn clj protocol

join clj

(join mv)

Flattens multiple monads nested in monadic into a single flat monad that contains ordinary, non-monadic value.

m-ctx clj

A simple, 'empty' future instance that can be used as a monad context to combinators that require one.

map clj

map-failure clj

(map-failure this f)

applies the supplied function to the internal value only if it is a Failure type

map-future clj

f needs to return a future. Maps f over vs and sequences all resulting futures. See sequence

mdo clj macro

(mdo bindings body)

A syntactic sugar for gluing together chained bind calls. The structure of mdo is similar to the structure of let.

bindings should be a vector of symbol - expression pairs in the form [sym1 exp1 sym2 exp2 ...]. while the body should be an expression that uses these symbols. Body is not wrapped in an implicit do block, so if multiple forms are needed in the block, they have to be explicitly wrapped with do.

If the bindings vector is empty, there are no bindings and no bind function calls, mdo simply evaluates body in that case.

(mdo [x some-monadic-value y some-other-monadic-value] some-expression)

expands to:

(bind some-monadic-value (fn [x] (bind some-other-monadic-value (fn [y] some-expression))))))

bind maintains an implicit context, so mdo too supports functions that depend on it, such are return and unit.

---- Example: (mdo [a [1 2] b [4 5] c [7]] (return (* a b c)))

=> [28 35 56 70]

Monad clj protocol

Monad is an abstraction for a context (box, container, computation) along with the ability to apply a function that accepts the value without the context and produces the result in a context. The resulting context may be different than the starting context. While the main idea with functors and applicatives is modifying the values inside the context, monad is more oriented towards modifying the context. Every Monad should also implement Applicative and Functor protocols, although this can not be automatically forced by Clojure compiler.

You create a new monad type by extending the Monad protocol and implementing bind and join methods, while observing monad laws:

1. Left Identity Law: (bind (pure m x) f) => (g x)

2. Right Identity Law: (bind m (pure m)) => m

3. Associativity Law: (bind (bind m f) g) => (bind m (fn [x] (bind (f x) g)

Fluokitten's test library contains macros that generate tests for monad laws.

The bind and join methods are not intended to be used directly by the caller, although you should use them directly from the implementation of this protocol if needed from other methods.

on-complete clj

(on-complete fut f)

applies f to a value of type 'IResult' once this future completes

on-failure clj

(on-failure fut f)

applies f to the result of this future iff it completes with a failure

on-success clj

(on-success fut f)

applies f to the result of this future iff it completes successfully

promise clj

(promise)

Creates a new, unresolved promise.

pure clj

(pure av v)

Takes any context av and any value a, and puts the value a in the same type of context. a should be put in the most minimal context possible that has appropriate type. av is needed only for proper dispatching and is not changed in any way.

reduce clj

(reduce f seed ms)

Returns a Future containing a list of the results yielded by all futures in ms further reduced using f and seed. See sequence and map

return clj

(return x)

A monad-agnostic version of pure, it is equivalent to (pure <current context>). Valid only inside a context-aware time-dependent dynamic scope. Otherwise, an IllegalArgumentException will be thrown complaining that there is no implementation found for class clojure.lang.Var$Unbound. The context is available inside the execution of bind method (and the methods and macros that use it internaly, such as >>= mdo), or inside the with-context macro. Also equivalent to the unit function.

---- Example 1: (defn f [x] (return (inc x))) (bind [1 2 3] f) => [2 3 4] (bind (just 1) f) => 2

---- Example 2: (f 1) => IllegalArgumentException (with-context [] (f 1)) => [1]

sequence clj

Given a list of futures, returns a future that will eventually contain a list of the results yielded by all futures. If any future fails, returns a Future representing that failure

success clj

(success v)

success? clj

(success? this)

try* clj

(try* f)

Wraps f in a try/catch. Returns the result of f in a Success type if successful. Returns a Failure containing the exception otherwise.

try-future clj macro

(try-future & body)

Wraps body in a try/catch. If an exception is thrown, returns a Future which yields a Failure containg the exception.

zip clj

(zip fut other)

Zips this future with 'other'. Resturns a new Future containing a two-element vector representing the result of each Future.