Структура Task.

Она содержит следующие поля:

• :pid - идентификатор процесса задачи; nil если задача не использует процесс задачи

• :ref - ссылка на монитор задачи

• :owner - идентификатор процесса, который запустил задачу

@spec async((() -> any())) :: t()

Запускает задачу, за которой необходимо ожидать.

fun должна быть анонимной функцией нулевой арности. Эта функция порождает процесс, который связан и контролируется процессом-вызывающим. Возвращается структура Task, содержащая соответствующую информацию. Разработчики должны в конечном итоге вызвать Task.await/2 или Task.yield/2, а затем Task.shutdown/2 для возвращённой задачи.

См. документацию модуля Task для получения дополнительной информации о общем использовании асинхронных задач.

Связывание

Эта функция порождает процесс, который связан и контролируется процессом-вызывающим. Часть связывания важна, потому что она прерывает задачу, если родительский процесс завершается. Она также гарантирует, что код до async/await имеет те же свойства после добавления вызова async. Например, представьте, что у вас есть следующее:

x = heavy_fun()
y = some_fun()
x + y

Теперь вы хотите сделать heavy_fun() асинхронным:

x = Task.async(&heavy_fun/0)
y = some_fun()
Task.await(x) + y

Как и прежде, если heavy_fun/0 завершается ошибкой, вся вычисление завершится ошибкой, включая процесс-вызывающий. Если вы не хотите, чтобы задача завершилась ошибкой, то необходимо изменить код heavy_fun/0 так же, как вы бы это сделали, если бы не использовали вызов async. Например, вернуть {:ok, val} | :error результаты или, в более крайних случаях, используя try/rescue. Другими словами, асинхронная задача должна рассматриваться как расширение процесса-вызывающего, а не как механизм для его изоляции от всех ошибок.

Если вы не хотите связывать вызывающий процесс с задачей, то вы должны использовать контролируемую задачу с Task.Supervisor и вызвать Task.Supervisor.async_nolink/2.

В любом случае, избегайте следующих действий:

• Установка :trap_exit в true - перехват выходов следует использовать только в особых случаях, так как это сделает ваш процесс неуязвимым не только к выходам из задачи, но и от любых других процессов.

  Кроме того, даже при перехвате выходов, вызов await всё равно завершится ошибкой, если задача завершилась без возврата результата.

• Отключение связи процесса задачи, запущенного с async/await. Если вы отключаете связь процессов, и задача не принадлежит ни одному супервайзеру, то могут остаться висящие задачи в случае завершения процесса-вызывающего.

@spec async(module(), atom(), [term()]) :: t()

Запускает задачу, за которой необходимо ожидать.

Аналогично async/1, за исключением того, что функция, которая должна быть запущена, задаётся указанным module, function_name, и args.

@spec async_stream(Enumerable.t(), (term() -> term()), keyword()) :: Enumerable.t()

Возвращает поток, который выполняет указанную функцию fun асинхронно для каждого элемента в enumerable.

Работает так же, как async_stream/5, но с анонимной функцией вместо кортежа модуль-имя_функции-аргументы. fun должна быть анонимной функцией с одним аргументом.

Каждый enumerable элемент передаётся как аргумент в заданную функцию fun и обрабатывается собственной задачей. Задачи будут связаны с процессом-вызывающим, аналогично async/1.

Пример

Подсчитайте количество кодовых точек в каждой строке асинхронно, а затем сложите счётчики с помощью reduce.

iex> strings = ["long string", "longer string", "there are many of these"]
iex> stream = Task.async_stream(strings, fn text -> text |> String.codepoints() |> Enum.count() end)
iex> Enum.reduce(stream, 0, fn {:ok, num}, acc -> num + acc end)
47

См. async_stream/5 для обсуждения, параметров и других примеров.

@spec async_stream(Enumerable.t(), module(), atom(), [term()], keyword()) ::
  Enumerable.t()

Возвращает поток, где заданная функция (module и function_name) отображается асинхронно на каждый элемент в enumerable.

Каждый элемент enumerable будет добавлен в качестве префикса к указанной args и обрабатываться собственной задачей. Эти задачи будут связаны со промежуточным процессом, который, в свою очередь, связан с процессом-вызывающим. Это означает, что ошибка в задаче приводит к завершению процесса-вызывающего, а ошибка в процессе-вызывающем завершает все задачи.

При потоковой передаче каждая задача будет выдавать {:ok, value} при успешном завершении или {:exit, reason} если вызывающий процесс перехватывает выходы. Порядок результатов зависит от значения параметра :ordered.

Уровень конкуретности и время, в течение которого задачи могут работать, можно контролировать с помощью параметров (см. раздел "Параметры" ниже).

Рассмотрите использование Task.Supervisor.async_stream/6 для запуска задач под супервайзером. Если вы обнаружите, что перехватываете выходы, чтобы убедиться, что ошибки в задачах не приводят к завершению процесса-вызывающего, воспользуйтесь Task.Supervisor.async_stream_nolink/6 для запуска задач, которые не связаны с процессом-вызывающим.

Параметры

• :max_concurrency - устанавливает максимальное количество задач, которые могут выполняться одновременно. По умолчанию System.schedulers_online/0.

• :ordered - определяет, должны ли результаты возвращаться в том же порядке, что и входной поток. Когда вывод упорядочен, Elixir может буферизировать результаты, чтобы вывести их в исходном порядке. Установка этого параметра в false отключает необходимость буферизации за счёт удаления порядка. Это также полезно, когда вы используете задачи только для побочных эффектов. Обратите внимание, что независимо от того, что :ordered установлено, задачи будут обрабатываться асинхронно. Если вам нужно обрабатывать элементы в порядке, рассмотрите использование Enum.map/2 или Enum.each/2 вместо этого. По умолчанию true.

• :timeout - максимальное время (в миллисекундах или :infinity) выполнения каждой задачи. По умолчанию 5000.

• :on_timeout - действие при истечении времени ожидания задачи. Возможные значения:

  • :exit (по умолчанию) - вызывающий процесс (процесс, который запустил задачи) завершается.
  • :kill_task - задача, которая превысила время ожидания, убивается. Выдаваемое значение для этой задачи — {:exit, :timeout}.

Пример

Давайте создадим поток и перечислим его:

stream = Task.async_stream(collection, Mod, :expensive_fun, [])
Enum.to_list(stream)

Конкурентность может быть увеличена или уменьшена с помощью параметра :max_concurrency. Например, если задачи связаны с интенсивной работой ввода-вывода, значение можно увеличить:

max_concurrency = System.schedulers_online() * 2
stream = Task.async_stream(collection, Mod, :expensive_fun, [], max_concurrency: max_concurrency)
Enum.to_list(stream)

Если вам не нужны результаты вычислений, вы можете запустить поток с помощью Stream.run/1. Также установите ordered: false, так как вам также не нужен порядок результатов:

stream = Task.async_stream(collection, Mod, :expensive_fun, [], ordered: false)
Stream.run(stream)

Первые завершённые асинхронные задачи

Вы также можете использовать async_stream/3 для выполнения M задач и поиска N завершённых задач. Например:

[
  &heavy_call_1/0,
  &heavy_call_2/0,
  &heavy_call_3/0
]
|> Task.async_stream(fn fun -> fun.() end, ordered: false, max_concurrency: 3)
|> Stream.filter(&match?({:ok, _}, &1))
|> Enum.take(2)

В примере выше мы выполняем три задачи и ждём завершения первых двух. Мы используем Stream.filter/2 для ограничения нас только успешно завершёнными задачами и затем Enum.take/2 для получения N элементов. Важно установить и ordered: false, и max_concurrency: M, где M — количество задач, чтобы убедиться, что все вызовы выполняются одновременно.

Внимание: несвязанный async + take

Если вы хотите потенциально обработать большое количество элементов и сохранить только часть результатов, вы можете обработать больше элементов, чем нужно. Давайте посмотрим на пример:

1..100
|> Task.async_stream(fn i ->
  Process.sleep(100)
  IO.puts(to_string(i))
end)
|> Enum.take(10)

Выполнение приведённого выше примера на машине с 8 ядрами обработает 16 элементов, хотя вам нужны только 10, так как async_stream/3 обрабатывает элементы одновременно. Это происходит, потому что он обрабатывает по 8 элементов одновременно. Затем все 8 элементов завершаются примерно в одно и то же время, вызывая запуск обработки 8 элементов. Из этих дополнительных 8 элементов будут использованы только 2, а остальные завершатся.

В зависимости от задачи, вы можете отфильтровать или ограничить количество элементов заранее:

1..100
|> Stream.take(10)
|> Task.async_stream(fn i ->
  Process.sleep(100)
  IO.puts(to_string(i))
end)
|> Enum.to_list()

В других случаях, вам, вероятно, нужно будет настроить :max_concurrency для ограничения количества элементов, которые могут быть обработаны, за счёт снижения конкурентности. Вы также можете установить количество элементов для взятия, чтобы оно было кратно :max_concurrency. Например, установить max_concurrency: 5 в приведённом выше примере.

@spec await(t(), timeout()) :: term()

Ожидает ответа задачи и возвращает его.

В случае завершения процесса задачи, вызывающий процесс завершится с той же причиной, что и задача.

Таймаут в миллисекундах или :infinity, может быть задан со значением по умолчанию 5000. Если таймаут истечёт, вызывающий процесс завершится. Если процесс задачи связан с вызывающим процессом, что происходит при запуске задачи с помощью async, то процесс задачи также завершится. Если процесс задачи обрабатывает завершения или не связан с вызывающим процессом, то он продолжит выполнение.

Эта функция предполагает, что монитор задачи всё ещё активен или сообщение монитора :DOWN находится в очереди сообщений. Если он был демонизирован или сообщение уже получено, эта функция будет ожидать в течение таймаута, ожидая сообщения.

Эта функция может быть вызвана только один раз для каждой заданной задачи. Если вам нужно многократно проверять, завершила ли длительно выполняющаяся задача вычисления, используйте yield/2 вместо этого.

Примеры

iex> task = Task.async(fn -> 1 + 1 end)
iex> Task.await(task)
2

Совместимость с поведением OTP

Не рекомендуется запускать длительно выполняющуюся задачу внутри поведения OTP, такого как GenServer. Вместо этого вы должны сопоставлять сообщение, поступающее из задачи, внутри вашего обратного вызова GenServer.handle_info/2.

GenServer получит два сообщения при handle_info/2:

• {ref, result} - сообщение с ответом, где ref — ссылка на монитор, возвращённая функцией task.ref, и result — результат задачи

• {:DOWN, ref, :process, pid, reason} - так как все задачи также отслеживаются, вы также получите сообщение :DOWN, отправленное функцией Process.monitor/1. Если вы получите сообщение :DOWN без ответа, это означает, что задача завершилась аварийно.

Ещё одно соображение, которое следует учитывать, заключается в том, что задачи, запущенные с помощью Task.async/1, всегда связаны со своими вызывающими сторонами, и вы, возможно, не захотите, чтобы GenServer завершился аварийно, если задача завершится аварийно. Поэтому предпочтительнее использовать Task.Supervisor.async_nolink/3 внутри поведений OTP. Для полноты приведён пример GenServer, который запускает задачи и обрабатывает их результаты:

defmodule GenServerTaskExample do
  use GenServer

  def start_link(opts) do
    GenServer.start_link(__MODULE__, :ok, opts)
  end

  def init(_opts) do
    # We will keep all running tasks in a map
    {:ok, %{tasks: %{}}}
  end

  # Imagine we invoke a task from the GenServer to access a URL...
  def handle_call(:some_message, _from, state) do
    url = ...
    task = Task.Supervisor.async_nolink(MyApp.TaskSupervisor, fn -> fetch_url(url) end)

    # After we start the task, we store its reference and the url it is fetching
    state = put_in(state.tasks[task.ref], url)

    {:reply, :ok, state}
  end

  # If the task succeeds...
  def handle_info({ref, result}, state) do
    # The task succeed so we can cancel the monitoring and discard the DOWN message
    Process.demonitor(ref, [:flush])

    {url, state} = pop_in(state.tasks[ref])
    IO.puts "Got #{inspect(result)} for URL #{inspect url}"
    {:noreply, state}
  end

  # If the task fails...
  def handle_info({:DOWN, ref, _, _, reason}, state) do
    {url, state} = pop_in(state.tasks[ref])
    IO.puts "URL #{inspect url} failed with reason #{inspect(reason)}"
    {:noreply, state}
  end
end

После определения сервера вам нужно запустить надзорную задачу выше и GenServer в вашем дереве надзора:

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

Supervisor.start_link(children, strategy: :one_for_one)

@spec await_many([t()], timeout()) :: [term()]

Ожидает ответы от нескольких задач и возвращает их.

Эта функция получает список задач и ожидает их ответы в заданном интервале времени. Она возвращает список результатов в том же порядке, что и задачи, переданные в аргументе tasks.

Если какой-либо из процессов задачи завершится аварийно, вызывающий процесс завершится с той же причиной, что и эта задача.

Таймаут в миллисекундах или :infinity, может быть задан со значением по умолчанию 5000. Если таймаут истечёт, вызывающий процесс завершится. Любые процессы задач, связанные с вызывающим процессом (что происходит при запуске задачи с помощью async) также завершатся. Любые процессы задач, обрабатывающие завершения или не связанные с вызывающим процессом, будут продолжать выполнение.

Эта функция предполагает, что мониторы задач всё ещё активны или сообщение монитора :DOWN находится в очереди сообщений. Если какие-либо задачи были демонизированы или сообщение уже получено, эта функция будет ожидать в течение заданного таймаута.

Эта функция может быть вызвана только один раз для каждой заданной задачи. Если вам нужно многократно проверять, завершила ли длительно выполняющаяся задача вычисления, используйте yield_many/2 вместо этого.

Совместимость с поведением OTP

Не рекомендуется запускать длительно выполняющиеся задачи внутри поведения OTP, такого как GenServer. См. await/2 для получения дополнительной информации.

Примеры

iex> tasks = [
...>   Task.async(fn -> 1 + 1 end),
...>   Task.async(fn -> 2 + 3 end)
...> ]
iex> Task.await_many(tasks)
[2, 5]

@spec child_spec(term()) :: Supervisor.child_spec()

Возвращает спецификацию для запуска задачи под управлением надзирателя.

arg передаётся как аргумент в Task.start_link/1 в поле :start спецификации.

Для получения дополнительной информации см. модуль Supervisor, функцию Supervisor.child_spec/2 и тип Supervisor.child_spec/0.

@spec completed(any()) :: t()

Запускает задачу, которая немедленно завершается с заданным result.

В отличие от async/1, эта задача не порождает связанный процесс. Она может быть ожидаема или передана как любая другая задача.

Использование

В некоторых случаях полезно создать задачу «completed», которая представляет задачу, которая уже была выполнена и сгенерировала результат. Например, при обработке данных вы можете определить, что некоторые входные данные недействительны до их отправки для дальнейшей обработки:

def process(data) do
  tasks =
    for entry <- data do
      if invalid_input?(entry) do
        Task.completed({:error, :invalid_input})
      else
        Task.async(fn -> further_process(entry) end)
      end
    end

  Task.await_many(tasks)
end

Во многих случаях Task.completed/1 можно избежать, вернув результат напрямую. Вам обычно потребуется эта функция только при работе с смешанной асинхронностью, когда группа входных данных будет обрабатываться частично синхронно и частично асинхронно.

Игнорирует существующую задачу.

Это означает, что задача продолжит выполняться, но она будет отключена, и вы больше не сможете её передать, ожидать или завершить.

Возвращает {:ok, reply} если ответ получен до игнорирования задачи, {:exit, reason} если задача завершилась аварийно до её игнорирования, в противном случае nil.

Важно: избегайте использования Task.async и последующего немедленного игнорирования задачи. Если вы хотите запустить задачи, результаты которых вас не интересуют, используйте Task.Supervisor.start_child/2 вместо этого.

Требуется Erlang/OTP 24+.

@spec shutdown(t(), timeout() | :brutal_kill) :: {:ok, term()} | {:exit, term()} | nil

Отключает и завершает задачу, а затем проверяет наличие ответа.

Возвращает {:ok, reply} если ответ получен во время завершения задачи, {:exit, reason} если задача завершилась аварийно, в противном случае nil. После завершения вы больше не можете её ожидать или передавать.

Второй аргумент — это либо таймаут, либо :brutal_kill. В случае таймаута задаче отправляется сигнал завершения :shutdown, и если она не завершится в течение таймаута, она убивается. С помощью :brutal_kill задача убивается сразу. В случае аварийного завершения задачи (возможно, убитой другим процессом), эта функция завершится с той же причиной.

Вызов этой функции не требуется при завершении вызывающего процесса, если вы не завершаетесь с причиной :normal или если задача обрабатывает завершения. Если вызывающий процесс завершается по причине отличной от :normal и задача не обрабатывает завершения, сигнал завершения вызывающего процесса остановит задачу. Вызывающий процесс может завершиться с причиной :shutdown для завершения всех связанных процессов, включая задачи, которые не обрабатывают завершения, без генерации сообщений об ошибках.

Если монитор задачи уже был демонизирован или получен, а в очереди сообщений нет ожидаемого ответа, эта функция вернёт {:exit, :noproc} как результат, или причина завершения не может быть определена.

@spec start((() -> any())) :: {:ok, pid()}

Запускает задачу.

fun должна быть анонимной функцией без аргументов.

Это следует использовать только в том случае, если задача используется для побочных эффектов (например, ввода-вывода), и вас не интересует её результат или успешное завершение.

Если текущий узел закрывается, узел завершится, даже если задача не была завершена. По этой причине рекомендуется использовать Task.Supervisor.start_child/2 вместо этого, что позволяет вам контролировать время завершения через параметр :shutdown.

@spec start(module(), atom(), [term()]) :: {:ok, pid()}

Запускает задачу.

Это следует использовать только в том случае, если задача используется для побочных эффектов (например, ввода-вывода), и вас не интересует её результат или успешное завершение.

Если текущий узел закрывается, узел завершится, даже если задача не была завершена. По этой причине рекомендуется использовать Task.Supervisor.start_child/2 вместо этого, что позволяет вам контролировать время завершения через параметр :shutdown.

@spec start_link((() -> any())) :: {:ok, pid()}

Запускает задачу в качестве части дерева управления с заданным fun.

fun должна быть анонимной функцией без аргументов.

Это используется для запуска статически контролируемой задачи в дереве управления.

@spec start_link(module(), atom(), [term()]) :: {:ok, pid()}

Запускает задачу в качестве части дерева управления с заданным module, function, и args.

Это используется для запуска статически контролируемой задачи в дереве управления.

@spec yield(t(), timeout()) :: {:ok, term()} | {:exit, term()} | nil

Временно блокирует вызывающий процесс, ожидая ответа задачи.

Возвращает {:ok, reply} если ответ получен, nil если ответ не получен, или {:exit, reason} если задача уже завершена. Имейте в виду, что обычно сбой задачи также приводит к завершению процесса, которому принадлежит задача. Поэтому эта функция может вернуть {:exit, reason} если выполняется хотя бы одно из следующих условий:

• процесс задачи завершился с причиной :normal
• процесс задачи не связан с вызывающим процессом (задача была запущена с Task.Supervisor.async_nolink/2 или Task.Supervisor.async_nolink/4)
• вызывающий процесс обрабатывает завершения

Таймаут, в миллисекундах или :infinity, может быть задан со значением по умолчанию 5000. Если время истечёт до получения сообщения от задачи, эта функция вернёт nil и монитор останется активным. Поэтому yield/2 можно вызывать несколько раз для одной и той же задачи.

Эта функция предполагает, что монитор задачи по-прежнему активен или сообщение монитора :DOWN находится в очереди сообщений. Если мониторинг был отключен или сообщение уже получено, эта функция будет ждать в течение таймаута, ожидая сообщения.

Если вы хотите остановить задачу, если она не ответит в течение timeout миллисекунд, вы должны объединить это с shutdown/1, как показано ниже:

case Task.yield(task, timeout) || Task.shutdown(task) do
  {:ok, result} ->
    result

  nil ->
    Logger.warn("Failed to get a result in #{timeout}ms")
    nil
end

Если вы хотите проверить задачу, но оставить её работающей после таймаута, вы можете объединить это с ignore/1, как показано ниже:

case Task.yield(task, timeout) || Task.ignore(task) do
  {:ok, result} ->
    result

  nil ->
    Logger.warn("Failed to get a result in #{timeout}ms")
    nil
end

Это гарантирует, что если задача завершит работу после таймаута, но до вызова shutdown/1, вы всё равно получите результат, так как shutdown/1 предназначен для обработки этого случая и возвращения результата.

@spec yield_many([t()], timeout()) :: [{t(), {:ok, term()} | {:exit, term()} | nil}]

Одновременное ожидание ответов от нескольких задач в заданном интервале времени.

Эта функция получает список задач и ожидает их ответы в заданном интервале времени. Она возвращает список пар с задачей в качестве первого элемента и результатом ожидания во втором. Задачи в возвращаемом списке будут в том же порядке, что и в входном аргументе tasks.

Аналогично yield/2, результат каждой задачи будет

• {:ok, term} если задача успешно сообщила свой результат в заданный интервал времени
• {:exit, reason} если задача завершилась
• nil если задача продолжает работать после истечения таймаута

Таймаут, в миллисекундах или :infinity, может быть задан со значением по умолчанию 5000.

См. yield/2 для получения дополнительной информации.

Пример

Task.yield_many/2 позволяет разработчикам запускать несколько задач и получать результаты, полученные в заданный промежуток времени. Если объединить это с Task.shutdown/2 (или Task.ignore/1), это позволяет нам собрать эти результаты и отменить (или проигнорировать) задачи, которые не ответили вовремя.

Давайте посмотрим пример.

tasks =
  for i <- 1..10 do
    Task.async(fn ->
      Process.sleep(i * 1000)
      i
    end)
  end

tasks_with_results = Task.yield_many(tasks, 5000)

results =
  Enum.map(tasks_with_results, fn {task, res} ->
    # Shut down the tasks that did not reply nor exit
    res || Task.shutdown(task, :brutal_kill)
  end)

# Here we are matching only on {:ok, value} and
# ignoring {:exit, _} (crashed tasks) and `nil` (no replies)
for {:ok, value} <- results do
  IO.inspect(value)
end

В примере выше мы создаём задачи, которые спят от 1 до 10 секунд и возвращают количество проспанных секунд. Если выполнить код сразу, вы увидите числа от 1 до 5, так как эти задачи ответили в заданное время. Все остальные задачи будут остановлены с помощью вызова Task.shutdown/2.