task_supervisor (ex_stdlib v0.3.0)
View SourceA supervisor for dynamically spawned tasks, inspired by Elixir's Task.Supervisor.
A task supervisor is a dynamic_supervisor whose children are tasks. Tasks started with async/2 and async_nolink/2 return a task that works with the functions of the task module (await/2, yield/2, shutdown/2...).
{ok, Sup} = task_supervisor:start_link([{name, my_task_sup}]),
%% Fire and forget
{ok, _Pid} = task_supervisor:start_child(my_task_sup, fun() -> do_work() end),
%% Not linked to the caller: a crash in the task does not take it down
Task = task_supervisor:async_nolink(my_task_sup, fun() -> fetch() end),
case task:yield(Task, 1000) of
{ok, Result} -> Result;
{exit, Reason} -> {error, Reason};
nil -> task:shutdown(Task), {error, timeout}
end.Like task:async/1, an exception raised by the task function is sent back to the caller: await re-raises it and yield returns {exit, Reason}. If the task process itself exits, the caller of an async/2 task exits too (it is linked), while the caller of an async_nolink/2 task sees the exit through await/yield.
Summary
Functions
Starts a task under the supervisor that must be awaited on, with default options.
Starts a task under the supervisor that must be awaited on.
Like async/3 with Module:Function(Args...) and default options.
Like async/3 with Module:Function(Args...).
Starts a task under the supervisor that can be awaited on, but is not linked to the caller, with default options.
Starts a task under the supervisor that can be awaited on, but is not linked to the caller.
Like async_nolink/3 with Module:Function(Args...) and default options.
Like async_nolink/3 with Module:Function(Args...).
Runs Fun concurrently on each element of List under the supervisor, with default options. See task:async_stream/3.
Runs Fun concurrently on each element of List under the supervisor. The tasks are linked to the caller.
Like async_stream/4 with Module:Function(Elem, Args...) and default options.
Like async_stream/4 with Module:Function(Elem, Args...).
Like async_stream/3, but the tasks are not linked to the caller.
Like async_stream/4, but the tasks are not linked to the caller, so a task process that exits is reported as {exit, Reason}.
Like async_stream_nolink/4 with Module:Function(Elem, Args...) and default options.
Like async_stream_nolink/4 with Module:Function(Elem, Args...).
Returns a child specification to start a task supervisor under a supervisor, with the same options as start_link/1.
Returns the pids of all tasks running under the supervisor.
Starts a task as a child of the supervisor, with default options.
Starts a task as a child of the supervisor. The task is not linked to the caller and its result is discarded.
Like start_child/3 with Module:Function(Args...) and default options.
Like start_child/3 with Module:Function(Args...).
Starts an unnamed task supervisor.
Starts a task supervisor linked to the caller.
Stops the supervisor, shutting down all its tasks.
Terminates the task with the given pid.
Types
-type async_option() :: {shutdown, brutal_kill | timeout()}.
-type child_option() :: {restart, permanent | transient | temporary} | {shutdown, brutal_kill | timeout()}.
-type start_option() :: {name, atom() | {local, atom()} | {global, term()} | {via, module(), term()}} | {max_restarts, non_neg_integer()} | {max_seconds, pos_integer()} | {max_children, non_neg_integer() | infinity}.
Functions
-spec async(supervisor(), fun(() -> term())) -> task:task().
Starts a task under the supervisor that must be awaited on, with default options.
-spec async(supervisor(), fun(() -> term()), [async_option()]) -> task:task().
Starts a task under the supervisor that must be awaited on.
The task is linked to and monitored by the caller, as with task:async/1. Accepts the shutdown option (default 5000).
-spec async(supervisor(), module(), atom(), [term()]) -> task:task().
Like async/3 with Module:Function(Args...) and default options.
-spec async(supervisor(), module(), atom(), [term()], [async_option()]) -> task:task().
Like async/3 with Module:Function(Args...).
-spec async_nolink(supervisor(), fun(() -> term())) -> task:task().
Starts a task under the supervisor that can be awaited on, but is not linked to the caller, with default options.
-spec async_nolink(supervisor(), fun(() -> term()), [async_option()]) -> task:task().
Starts a task under the supervisor that can be awaited on, but is not linked to the caller.
If the task process exits, await/2 exits and yield/2 returns {exit, Reason} instead of the caller crashing. Accepts the shutdown option (default 5000).
-spec async_nolink(supervisor(), module(), atom(), [term()]) -> task:task().
Like async_nolink/3 with Module:Function(Args...) and default options.
-spec async_nolink(supervisor(), module(), atom(), [term()], [async_option()]) -> task:task().
Like async_nolink/3 with Module:Function(Args...).
-spec async_stream(supervisor(), list(), fun((term()) -> term())) -> [{ok, term()} | {exit, term()}].
Runs Fun concurrently on each element of List under the supervisor, with default options. See task:async_stream/3.
-spec async_stream(supervisor(), list(), fun((term()) -> term()), [task:stream_option() | async_option()]) -> [{ok, term()} | {exit, term()}].
Runs Fun concurrently on each element of List under the supervisor. The tasks are linked to the caller.
Accepts the options of task:async_stream/3 plus shutdown.
-spec async_stream(supervisor(), list(), module(), atom(), [term()]) -> [{ok, term()} | {exit, term()}].
Like async_stream/4 with Module:Function(Elem, Args...) and default options.
-spec async_stream(supervisor(), list(), module(), atom(), [term()], [task:stream_option() | async_option()]) -> [{ok, term()} | {exit, term()}].
Like async_stream/4 with Module:Function(Elem, Args...).
-spec async_stream_nolink(supervisor(), list(), fun((term()) -> term())) -> [{ok, term()} | {exit, term()}].
Like async_stream/3, but the tasks are not linked to the caller.
-spec async_stream_nolink(supervisor(), list(), fun((term()) -> term()), [task:stream_option() | async_option()]) -> [{ok, term()} | {exit, term()}].
Like async_stream/4, but the tasks are not linked to the caller, so a task process that exits is reported as {exit, Reason}.
-spec async_stream_nolink(supervisor(), list(), module(), atom(), [term()]) -> [{ok, term()} | {exit, term()}].
Like async_stream_nolink/4 with Module:Function(Elem, Args...) and default options.
-spec async_stream_nolink(supervisor(), list(), module(), atom(), [term()], [task:stream_option() | async_option()]) -> [{ok, term()} | {exit, term()}].
Like async_stream_nolink/4 with Module:Function(Elem, Args...).
-spec child_spec([start_option()]) -> supervisor:child_spec().
Returns a child specification to start a task supervisor under a supervisor, with the same options as start_link/1.
-spec children(supervisor()) -> [pid()].
Returns the pids of all tasks running under the supervisor.
-spec start_child(supervisor(), fun(() -> term())) -> {ok, pid()} | {error, term()}.
Starts a task as a child of the supervisor, with default options.
-spec start_child(supervisor(), fun(() -> term()), [child_option()]) -> {ok, pid()} | {error, term()}.
Starts a task as a child of the supervisor. The task is not linked to the caller and its result is discarded.
Options: restart (default temporary) and shutdown (default 5000). Returns {error, max_children} when the supervisor is full.
Like start_child/3 with Module:Function(Args...) and default options.
-spec start_child(supervisor(), module(), atom(), [term()], [child_option()]) -> {ok, pid()} | {error, term()}.
Like start_child/3 with Module:Function(Args...).
Starts an unnamed task supervisor.
-spec start_link([start_option()]) -> {ok, pid()} | {error, term()}.
Starts a task supervisor linked to the caller.
Options: name (an atom or a {local, _}, {global, _} or {via, _, _} tuple), max_restarts (default 3), max_seconds (default 5) and max_children (default infinity).
-spec stop(supervisor()) -> ok.
Stops the supervisor, shutting down all its tasks.
-spec terminate_child(supervisor(), pid()) -> ok | {error, not_found}.
Terminates the task with the given pid.