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
chain_fun :: (any -> Etude.Forkable.t)
map_fun :: (any -> any)
Functions
Specs
async((() -> any)) :: Etude.Forkable.t
Create a future that executes a fun
in a Task
.
Specs
async(module, atom, [any]) :: Etude.Forkable.t
Create a future that calls apply(mod, fun, args)
in a Task
Specs
chain(Etude.Forkable.t, on_ok :: chain_fun) :: Etude.Forkable.t
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
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}
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.
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.
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"
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}}
Specs
fork(Etude.Forkable.t) :: {:ok, any} | {:error, any}
Start execution of a future with the default %Etude.State{}
See fork/2
Specs
fork(Etude.Forkable.t, Etude.State.t) ::
{:ok, any, Etude.State.t} |
{:error, any, Etude.State.t}
Start execution of a future
Specs
fork!(Etude.Forkable.t) :: any | no_return
Start execution of a future while raising any errors
See fork/2
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}
Specs
map(Etude.Forkable.t, on_ok :: map_fun) :: Etude.Forkable.t
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"}
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"}}
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.
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.
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"}
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
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]
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
Specs
wrap((() -> any)) :: Etude.Forkable.t
Wrap a function; catching any exceptions and returning them as error
futures.