future

Types

Future

pub type Future(input, result, reject)

Status

</>

The possible statuses of a future

pub type Status(result, reject) {
  Completed(Result(result, reject))
  Running
  Failed(reason: String)
  Released
}

Constructors

```
Completed(Result(result, reject))
```
The future has completed and returned a result
```
Running
```
The future is still executing code
```
Failed(reason: String)
```
The future has failed for the provided reason
```
Released
```
The future has been released and the state it once held is no longer available

Values

add_failure_handler

</>

pub fn add_failure_handler(
  future: Future(input, result, reject),
  handler: fn(String) -> Nil,
) -> Future(input, result, reject)

Adds a handler to the future that will be called if the future fails

The handler will be called with the reason for the failure

If the future is released (before or after) this will do nothing

This handler does not have to be released as it’s lifecycle is self contained

after

</>

pub fn after(
  future: Future(input, result, reject),
  executable: fn(Status(result, reject)) -> a,
) -> Future(input, result, reject)

Registers the given exectuable to be invoked once the future is complete

This just registers:

A new future via then
A handler via add_failure_handler

auto_release

</>

pub fn auto_release(
  future: Future(input, result, reject),
) -> Future(input, result, reject)

Automatically releases the future when it’s complete

The future returned is the one provided! You no longer need to call release on it (but doing so will do nothing)

from_failure

</>

pub fn from_failure(
  reason: String,
) -> Future(input, result, reject)

from_result

</>

pub fn from_result(
  result: Result(result, reject),
) -> Future(input, result, reject)

Creates a future from a result

This future will never have the status of running or failed

Just as with new you own the lifecycle of this future and must release it when you are done with it

is_complete

</>

pub fn is_complete(future: Future(input, result, reject)) -> Bool

If the future has completed, IE a result is available or failed or was released

new

</>

pub fn new(
  executable: fn(input) -> Result(result, reject),
  starting_value: input,
) -> Future(input, result, reject)

Creates a future from an executable

Please note that lifecycle management of this future is managed by YOU! You MUST release it when you are done with it else have a memory leak! (This comes from how the erlang gc works) If you want to immediately release the future on completion then use auto_release!

release

</>

pub fn release(future: Future(input, result, reject)) -> Nil

Releases the future, allowing it to be garbage collected

If the future is still running only the storage for the state will be released, the execution will continue and result will still be made available for chained futures If the future has completed it will be marked for garbage collection and the state will be made unavailable

You should assume that any future not released will never be garbage collected

status

</>

pub fn status(
  future: Future(input, result, reject),
) -> Status(result, reject)

Returns the status of the future

then

</>

pub fn then(
  future: Future(input, result, reject),
  next: fn(Result(result, reject)) -> Result(result2, reject2),
) -> Future(Result(result, reject), result2, reject2)

Chains a future with another future

If the first future fails, all chained futures will fail with the same reason with a prefix of “Prior future failed: “

If the first future is released BEFORE calling then, the second future will fail with the reason “Prior future was released before initialisation” If the first future is released AFTER calling then, the second future will operate as expected and still recieve the result of the first future

wait

</>

pub fn wait(future: Future(input, result, reject)) -> Nil

Blocks execution until the future is complete

If the future is already complete this will return immediately

This function is only available in the erlang target!