Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 48 ยท Concurrency and OTP

Tasks and Parallel Work

Run work in parallel with Elixir's Task module: Task.async and await, timeouts, Task.Supervisor, and async_stream with bounded concurrency and back-pressure.

Sometimes you do not need a long-lived process with state. You just want to run a few things at the same time and collect the answers: call three services, resize ten images, check a list of URLs. In Elixir that job belongs to the Task module. A task is a process that does one piece of work and sends its result back to the process that started it.

In this lesson you will use Task.async/1 and Task.await/2, handle timeouts, run tasks under a supervisor so a crash does not take the caller down, and process big collections with Task.async_stream/3, which limits how many tasks run at once. You should already know processes and messages and supervisors.

Elixir cannot run on this site, so the Elixir snippets are read-only. The runnable examples are JavaScript stand-ins that use Promises. A Promise is not a process (it has no mailbox and no isolated memory), but Promise.all and a limit on active jobs show the same shape of work.

Task.async and Task.await

Task.async/1 starts a process that runs your function and returns a %Task{} struct. Task.await/2 waits for the reply and returns the value.

ELIXIR
task = Task.async(fn ->
  Process.sleep(500)
  :done
end)

# ... the caller can do other work here ...

Task.await(task)
# :done

The power comes from starting several tasks before waiting for any of them:

ELIXIR
urls = ["a.example", "b.example", "c.example"]

results =
  urls
  |> Enum.map(fn url -> Task.async(fn -> fetch(url) end) end)
  |> Enum.map(&Task.await/1)

The first Enum.map starts all tasks immediately. The second collects the results in the same order as the input. If each fetch takes one second, the whole thing takes about one second instead of three. Note that you must start all of them first; mapping async and await together in one function would run them one after another.

A few rules are worth memorizing:

  • Only the process that called Task.async can await that task. The reply arrives as a message in that caller's mailbox.
  • Task.async links the task to the caller. If the task crashes, the caller crashes too (unless it traps exits). That is the right default when the result is needed to continue.
  • Task.await/2 has a default timeout of 5,000 milliseconds. If it expires, the caller exits. It is not an ordinary error value.
  • Task.await_many/2 waits for a list of tasks at once.

The task lifecycle

async Start a linked process and get a %Task{}.
Work The task runs while the caller continues.
await The reply is read from the caller's mailbox.

Start every task first, then await them.

1 / 2

Parallel work in JavaScript

Here is a stand-in. Each fake request takes a different amount of time, but the total is close to the slowest one, and results come back in input order.

JS Starting all jobs before waiting

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Timeouts and Task.yield

When a result might never come, you want control over what happens. Task.yield/2 waits like await, but does not exit the caller when time runs out. It returns {:ok, result}, {:exit, reason} or nil. You then decide whether to keep waiting or call Task.shutdown/2 to stop the task:

ELIXIR
task = Task.async(fn -> slow_report() end)

case Task.yield(task, 2_000) || Task.shutdown(task) do
  {:ok, report} -> report
  {:exit, reason} -> {:error, reason}
  nil -> {:error, :timeout}
end

Task.shutdown/2 returns nil if the task is still running and was killed, or {:ok, result} if it finished just in time. This "yield, then shut down" pair is the standard way to give a task a deadline.

Task.Supervisor: tasks that may crash

A plain Task.async crash takes the caller with it. For work you expect to fail sometimes, start a Task.Supervisor in your supervision tree:

ELIXIR
children = [
  {Task.Supervisor, name: MyApp.TaskSupervisor}
]

Supervisor.start_link(children, strategy: :one_for_one)

Then use one of its functions:

ELIXIR
# The caller is NOT linked: if the task crashes, await gets an exit you can catch.
task = Task.Supervisor.async_nolink(MyApp.TaskSupervisor, fn -> risky() end)

case Task.yield(task, 5_000) || Task.shutdown(task) do
  {:ok, value} -> {:ok, value}
  {:exit, reason} -> {:error, reason}
  nil -> {:error, :timeout}
end

# Fire and forget: no result is returned.
Task.Supervisor.start_child(MyApp.TaskSupervisor, fn -> send_email() end)

async_nolink still lets you collect a result, but a failure arrives as {:exit, reason} instead of killing you. start_child is for side effects such as sending an email or writing an audit record.

Task.async_stream: many items, bounded concurrency

Starting one task for each of 100,000 items would flood the system. Task.async_stream/3 runs your function over a collection with at most max_concurrency tasks at a time. The default is the number of scheduler threads (System.schedulers_online/0, usually the number of CPU cores).

ELIXIR
1..20
|> Task.async_stream(fn n -> expensive(n) end, max_concurrency: 4)
|> Enum.map(fn {:ok, value} -> value end)

Each element of the stream is {:ok, result} (or {:exit, reason} when a task fails or times out). Useful options:

Option Meaning
max_concurrency How many tasks run at once.
ordered true (default) keeps input order; false emits results as they finish, which is faster.
timeout Per-item limit in ms (default 5,000).
on_timeout :exit (default, the caller exits) or :kill_task (that item becomes {:exit, :timeout}).

The stream is lazy. New tasks start only as the consumer asks for results, so a slow consumer naturally slows the producers down. That is back-pressure: work is never produced faster than it is consumed, and memory stays flat even for huge inputs. Pair it with streams for files that do not fit in memory.

A bounded runner in JavaScript

This stand-in runs a list of jobs with at most two active at a time, and records the highest number that was active.

JS Limiting concurrency like async_stream

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Timeouts per item

Imagine one item hangs. With the default on_timeout: :exit, the whole caller stops. With :kill_task, only that item fails:

ELIXIR
[100, 5_000, 200]
|> Task.async_stream(
  fn ms -> Process.sleep(ms); ms end,
  timeout: 1_000,
  on_timeout: :kill_task
)
|> Enum.to_list()
# [{:ok, 100}, {:exit, :timeout}, {:ok, 200}]

Choose the option based on whether one failure should abort the whole job. For a batch of independent items, :kill_task plus a filter on {:ok, _} is usually what you want.

When tasks are not the answer

  • If you need state that lives between calls, use an Agent or GenServer.
  • If the work must survive restarts or be retried later, you need a job queue, not a task. Tasks vanish when the node stops.
  • Do not use tasks for CPU-trivial work. Starting a process is cheap, but not free, and the data you capture in the closure is copied into the new process.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the correct way to run three tasks in parallel and collect results?

    Parallelism comes from starting every task before waiting for any. Awaiting each one right after starting it runs them one by one.
  2. 2. What happens when Task.await/2 times out?

    await exits the caller on timeout. Use Task.yield/2 followed by Task.shutdown/2 if you want to handle a missing result yourself.
  3. 3. Which function lets the caller survive a crashing task and still get the result when it succeeds?

    async_nolink starts a supervised task that is not linked to the caller, so a failure arrives as an exit you can handle.
  4. 4. What does max_concurrency do in Task.async_stream?

    Only that many tasks are active at once, and new ones start as results are consumed, which gives back-pressure.

Summary

  • Task.async/1 starts a linked process; Task.await/2 collects its result (default timeout 5 s, and a timeout exits the caller).
  • Start all tasks before awaiting to get real parallelism; Task.await_many/2 waits for a list.
  • Task.yield/2 plus Task.shutdown/2 gives a deadline without crashing the caller.
  • Task.Supervisor gives async_nolink for work that may fail and start_child for fire-and-forget jobs.
  • Task.async_stream/3 processes collections lazily with max_concurrency, ordered, timeout and on_timeout, which provides back-pressure.
  • Tasks are not durable: use a queue when work must survive a restart.

Next: shared lookups without a bottleneck process in ETS, Registry and Application State.