Conveniences for spawning and awaiting tasks.

Tasks are processes meant to execute one particular action throughout their life-cycle, often with little or no communication with other processes. The most common use case for tasks is to convert sequential code into concurrent code by computing a value asynchronously:

task = Task.async(fn -> do_some_work() end)
res  = do_some_other_work()
res + Task.await(task)

Tasks spawned with async can be waited on by their caller process (and only their caller) as shown in the example above. They are implemented by spawning a process that sends a message to the caller once the given computation is performed.

Besides async/1 and await/2, tasks can also be started as part of supervision tree and dynamically spawned in remote nodes. We will explore all three scenarios next.

async and await

One of the common use of tasks is to convert sequential code into concurrent code with Task.async/1 while keeping its semantics. When invoked, a new process will be created, linked and monitored by the caller. Once the task action finishes, a message will be sent to the caller with the result.

Task.await/2 is used to read the message sent by the task. await will check the monitor setup by the call to async/1 to verify if the process exited for any abnormal reason (or in case exits are being trapped by the caller).

There are two important things to consider when using async:

1. If you are using async tasks, you must await a reply as they are always sent. If you are not expecting a reply, consider using Task.start_link/1 detailed below

2. async tasks link the caller and the spawned process. This means that, if the caller crashes, the task will crash too and vice-versa. This is on purpose, if the process meant to receive the result no longer exists, there is no purpose in completing computation of the result. If this is not desired, consider using Task.start_link/1 as well

Task.yield/2 is an alternative to await/2 where the caller will temporarily block, waiting until the task replies or crashes. If the result does not arrive within the timeout it can be called again at a later moment. This allows checking for the result of a task multiple times or to handle a timeout. If a reply does not arrive within the desired time, Task.shutdown/2 can be used to stop the task.

Supervised tasks

It is also possible to spawn a task inside a supervision tree with start_link/1 and start_link/3:

Task.start_link(fn -> IO.puts "ok" end)

Such tasks can be mounted in your supervision tree as:

import Supervisor.Spec

children = [
  worker(Task, [fn -> IO.puts "ok" end])
]

Since these tasks are supervised and not directly linked to the caller, they cannot be waited on. Note start_link/1, unlike async/1, returns {:ok, pid} (which is the result expected by supervision trees).

By default, most supervision strategies will try to restart a worker after it exits regardless of reason. If you design the task to terminate normally (as in the example with IO.puts/2 above), consider passing restart: :transient in the options to worker/3.

Dynamically supervised tasks

The Task.Supervisor module allows developers to dynamically create multiple supervised tasks.

A short example is:

{:ok, pid} = Task.Supervisor.start_link()
task = Task.Supervisor.async(pid, fn ->
  # Do something
end)
Task.await(task)

However, in the majority of cases, you want to add the task supervisor to your supervision tree:

import Supervisor.Spec

children = [
  supervisor(Task.Supervisor, [[name: MyApp.TaskSupervisor]])
]

Now you can dynamically start supervised tasks:

Task.Supervisor.start_child(MyApp.TaskSupervisor, fn ->
  # Do something
end)

Or even use the async/await pattern:

Task.Supervisor.async(MyApp.TaskSupervisor, fn ->
  # Do something
end) |> Task.await()

Finally, check Task.Supervisor for other operations supported by the Task supervisor.

Distributed tasks

Since Elixir provides a Task supervisor, it is easy to use a task supervisor to dynamically spawn tasks across nodes:

# In the remote node
Task.Supervisor.start_link(name: MyApp.DistSupervisor)

# In the client
Task.Supervisor.async({MyApp.DistSupervisor, :remote@local},
                      MyMod, :my_fun, [arg1, arg2, arg3])

Note that, when working with distributed tasks, one should use the async/4 function that expects explicit module, function and arguments, instead of async/2 that works with anonymous functions. That’s because anonymous functions expect the same module version to exist on all involved nodes. Check the Agent module documentation for more information on distributed processes as the limitations described in the agents documentation apply to the whole ecosystem.