promissum - composable promise/future library for Clojure

Since promissum is a young project there may be some API breakage.

The simplest way to use promissum library in a Clojure project is by including it as a dependency:

The promise consists in a container that eventually will contain a value with builtin support for error handling. So the promise has three different states:

In summary: is the abstraction that represents the result of an asynchronous operation that will be eventually available.

The promissum's promise abstraction just works on top of the awesome CompletableFuture future/promise implementation available in JDK8. And offers a very lightweight layer on top of it.

It there several different ways to create a promise in promissum library. You can create it already resolved with initial value or already rejected with an exception.

Let start with a basic example using the commonly known promise delivering in clojure:

An other way to create a promise is using a factory function that can resolve or reject promise in asynchronous way. If you are familiar with javascript promises, you will found that very familiar:

promissum also exposes a clojure’s future alternative that works in the same way with the difference that it returns a CompletableFuture:

You should know that promise and future functions just return a CompletableFuture instance without additional wrapping.

The promissum library also exposes a convenient macro for clojure future macro replacement. It works in exactly manner that the clojure version, with a little difference that it returns a composable promise that can be easily chained in an asynchronous way.

See an example:

The promissum's promises can be used as drop in replacement for clojure promises, because them offers also blocking operations:

If you try to deref a promise that is rejected, the exception will be rereaised in the calling thread. You should take care that the reraised exception is wrapped in ExecutionException in the same way as builtin clojure promise/future does.

For avouid unnecesary pain constantly handling that, promissum exposes the await function. It has the same call signature as clojure builtin deref function but if promise contains a exception that exception will be reraised as is (without additional wrapping).

promissum provides useful predicates that will allow check the state of a promise in any time.

Let see some examples:

The done? predicate checks if a promise is fullfiled, independently if is resolved or rejected.

It there different ways to compose/chain computations using promises. We will start with the basic: lineal way of chaining computations.

That can be done using then or chain functions exposed in promissum.core namespace. Bot them are mainly interchangeable. The main differencia is that chain is variadic and then not.

And here the same example using the chain function instead of then:

Later, thanks to the cats library, it there other few methods of create promise compositions in more powerfull way: mlet and alet macros.

For demostration purposes, imagine that you have this function that emulates async operation and return a promise:

Now, we will try to use this function together with mlet macro and additionally messure the execution time:

The mlet bindings are executed sequentially, waiting in each step for promise resolution. If an error occurs in some step, the entire composition will be short-circuited, returing exceptionally resolved promise.

The main disadvantage of mlet is that it’s evaluation model is strictly secuential. It is ok for some use cases, when the sequential order is mandatory. But, if the strictly secuential model is not mandatory, mlet does not take the advantage of concurrency.

For solve this problem, it there alet macro. It is almost identical to mlet from the user experience, but internally it is based in very different abstractions.

Now, we will try to do the same example but using the alet macro:

We can observe that the return value is identical to the previous example, but it takes almost half of time to finish execute all the computations. This is happens because alet is more smarter macro and calculates de dependencies between declared bindings and executes them in batches; taking fully advantage of having fully miltithreaded/concurrent environment as is JVM.

You can read more about that here.

One of the advantages of using promise abstraction is that it natively has a notion of error, so you don’t need reinvent it. If some of the computations of the composed promise chain/pipeline raises an exception, that one is automatically propagated to the last promise making the effect of short-circuiting.

Let see an example:

For exception catching facilities, promissum exposes a catch function. It just works like then but with exceptions. It attaches a next computation that only will be executend if a previous computation resolves exceptionally:

The catch chain function also return a promise, that will be resolved or rejected depending on that will happen inside the catch handler.

In some circumstances you will want wait a completion of few promises at same time, and promissum also provides helpers for that.

Imagine that you have a collection of promises and you want to wait until all of them are resolved. This can be done using the all combinator:

It there are also circumstances where you only want arbitrary select of the first resolved promise. For this case, you can use the any combinator:

Later, for more advanced use cases, promissum is an algebraic structure that implements the associative binary operation usually called mappend:

If you are interested in knowing more about it, plase refer to the cats documentation.

Unlike Clojure and other Clojure contrib libs, does not have many restrictions for contributions. Just open a issue or pull request.

For run tests just execute this:

promissum is licensed under BSD (2-Clause) license: