etude v1.0.0-beta.3 Etude

Etude is a futures library for Elixir/Erlang.

Summary

Functions

Create a future that executes a fun in a Task

Create a future that calls apply(mod, fun, args) in a Task

Call a function when future returns ok and return a new future value

Call a function when future returns an error and return a new future value

Call a function when future returns either an ok or error and return a new future value

Call one function when future returns an ok and another with error; where each one return a new future value

Delay execution of a future for a period in milliseconds

Wrap an error in a future

Start execution of a future with the default %Etude.State{}

Start execution of a future

Start execution of a future while raising any errors

Execute a list of futures with an optional concurrency limit

Apply a function over a successful future’s value

Apply a function over a future’s error

Apply a function over a both the future’s ok or error value

Apply different functions over success and error values

Wrap a success value in a future

Retry a future until an ok value or the limit is reached

Select the first n futures that return ok

Select the first future that returns ok

Wrap a function; catching any exceptions and returning them as error futures

Types

map_fun :: (any -> any)

Functions

async(fun)

Specs

async((() -> any)) :: Etude.Forkable.t

Create a future that executes a fun in a Task.

async(mod, fun, args)

Specs

async(module, atom, [any]) :: Etude.Forkable.t

Create a future that calls apply(mod, fun, args) in a Task

chain(future, on_ok)

Specs

Call a function when future returns ok and return a new future value.

iex> ok(1) |> chain(&error(&1)) |> fork()
{:error, 1}

iex> ok(2) |> chain(&ok(&1 * 5)) |> fork!()
10
chain_error(future, on_error)

Specs

chain_error(Etude.Forkable.t, on_error :: chain_fun) :: Etude.Forkable.t

Call a function when future returns an error and return a new future value.

iex> error(1) |> chain_error(&ok(&1)) |> fork!()
1

iex> error(2) |> chain_error(&error(&1 * 5)) |> fork()
{:error, 10}
chain_fold(future, on_value)

Specs

chain_fold(Etude.Forkable.t, on_value :: chain_fun) :: Etude.Forkable.t

Call a function when future returns either an ok or error and return a new future value.

chain_over(future, on_success, on_error)

Specs

chain_over(Etude.Forkable.t, on_success :: chain_fun, on_error :: chain_fun) :: Etude.Forkable.t

Call one function when future returns an ok and another with error; where each one return a new future value.

delay(future, time_ms)

Specs

delay(Etude.Forkable.t, time_ms :: pos_integer) :: Etude.Forkable.t

Delay execution of a future for a period in milliseconds.

iex> ok("Hello!") |> delay(10) |> fork!()
"Hello!"

iex> error(:foo) |> delay(10) |> fork()
{:error, :foo}

iex> ok("Hello") |> delay(10) |> map(&(&1 <> ", Joe")) |> fork!()
"Hello, Joe"
error(error)

Specs

error(any) :: Etude.Forkable.t

Wrap an error in a future.

iex> 1 |> error() |> fork()
{:error, 1}

iex> %{uh: :oh} |> error() |> fork()
{:error, %{uh: :oh}}
fork(future)

Specs

fork(Etude.Forkable.t) :: {:ok, any} | {:error, any}

Start execution of a future with the default %Etude.State{}

See fork/2

fork(future, state)

Specs

fork(Etude.Forkable.t, Etude.State.t) ::
  {:ok, any, Etude.State.t} |
  {:error, any, Etude.State.t}

Start execution of a future

fork!(future)

Specs

fork!(Etude.Forkable.t) :: any | no_return

Start execution of a future while raising any errors

See fork/2

join(futures, concurrency \\ :infinity)

Specs

join([Etude.Forkable.t], concurrency :: pos_integer | :infinity) :: Etude.Forkable.t

Execute a list of futures with an optional concurrency limit

If any of the resulting futures fails, the pending futures will be canceled or not executed.

iex> [ok(1), ok(2), ok(3)] |> join() |> fork!()
[1, 2, 3]

iex> [ok(4) |> delay(15),
...>  ok(5) |> delay(10),
...>  ok(6) |> delay(5)] |> join(1) |> fork!()
[4, 5, 6]

iex> [ok(7), ok(8), error(9)] |> join() |> fork()
{:error, 9}
map(future, on_ok)

Specs

Apply a function over a successful future’s value.

iex> ok(1) |> map(&(&1 + &1)) |> fork!()
2

iex> ok(%{hello: nil}) |> map(&%{&1 | hello: "Robert"}) |> fork!()
%{hello: "Robert"}
map_error(future, on_error)

Specs

map_error(Etude.Forkable.t, on_error :: map_fun) :: Etude.Forkable.t

Apply a function over a future’s error.

iex> error(1) |> map_error(&(&1 + &1)) |> fork()
{:error, 2}

iex> error(%{hello: nil}) |> map_error(&%{&1 | hello: "Mike"}) |> fork()
{:error, %{hello: "Mike"}}
map_fold(future, on_value)

Specs

map_fold(Etude.Forkable.t, on_value :: map_fun) :: Etude.Forkable.t

Apply a function over a both the future’s ok or error value.

map_over(future, on_ok, on_error)

Specs

map_over(Etude.Forkable.t, on_ok :: map_fun, on_error :: map_fun) :: Etude.Forkable.t

Apply different functions over success and error values.

ok(value)

Specs

ok(any) :: Etude.Ok.t

Wrap a success value in a future.

iex> 1 |> ok() |> fork!()
1

iex> %{hello: "Joe"} |> ok() |> fork!()
%{hello: "Joe"}
retry(future, limit \\ :infinity)

Specs

retry(Etude.Forkable.t, limit :: pos_integer) :: Etude.Forkable.t
retry(Etude.Forkable.t, limit :: :infinity) ::
  Etude.Forkable.t |
  no_return

Retry a future until an ok value or the limit is reached.

iex> wrap(fn ->
...>   if :rand.uniform() > 0.5 do
...>     throw :error
...>   else
...>     :foo
...>   end
...> end) |> retry() |> fork!()
:foo
select(futures, count)

Specs

select([Etude.Forkable.t], count :: pos_integer) :: Etude.Forkable.t

Select the first n futures that return ok.

iex> [ok(1), ok(2), ok(3)] |> select(2) |> fork!()
[1, 2]

iex> [ok(1) |> delay(5),
...>  ok(2) |> delay(10),
...>  ok(3) |> delay(6)] |> select(2) |> fork!()
[1, 3]
select_first(futures)

Specs

select_first([Etude.Forkable.t]) :: Etude.Forkable.t

Select the first future that returns ok.

iex> [ok(1), ok(2), ok(3)] |> select_first() |> fork!()
1

iex> [ok(1) |> delay(10),
...>  ok(2) |> delay(7),
...>  ok(3) |> delay(5)] |> select_first() |> fork!()
3
wrap(fun)

Specs

wrap((() -> any)) :: Etude.Forkable.t

Wrap a function; catching any exceptions and returning them as error futures.