asyncdispatch

Этот модуль реализует асинхронное ввод-вывод. Он включает в себя диспетчер, реализацию типа Future, и макрос async, который позволяет писать асинхронный код в синхронном стиле с ключевым словом await.

Диспетчер выполняет роль цикла событий. Необходимо вызывать poll на нём (или функции, которые это делают за вас, такие как waitFor или runForever) для опроса на наличие ожидающих событий. Реализация основана на epoll в Linux, IO Completion Ports в Windows и select в других операционных системах.

Функция poll сама по себе не вернёт никаких событий. Вместо этого будет завершён соответствующий объект Future . Future — это тип, хранящий значение, которое ещё не доступно, но может стать доступным в будущем. Вы можете проверить, завершён ли future, используя функцию finished . Когда future завершён, это означает, что либо хранимое в нём значение теперь доступно, либо в нём содержится ошибка. Последнее происходит, когда операция по завершению future терпит неудачу с исключением. Вы можете отличить эти ситуации с помощью функции failed.

Объекты future также могут хранить процедуру обратного вызова, которая будет вызвана автоматически после завершения future.

Следовательно, future можно рассматривать как реализацию паттерна proactor. В этом паттерне вы запрашиваете действие, и после выполнения этого действия future завершается результатом этого действия. Запросы могут быть сделаны путём вызова соответствующих функций. Например, вызов функции recv создаст запрос на чтение данных из сокета. Future, возвращаемый функцией recv , будет завершён после того, как будет прочитано запрошенное количество данных или произойдёт исключение.

Код для чтения данных из сокета может выглядеть примерно так:

var future = socket.recv(100)
future.addCallback(
  proc () =
    echo(future.read)
)

Все асинхронные функции, возвращающие Future, не будут блокировать выполнение. Однако они не вернут результат сразу. Асинхронная функция будет иметь код, который будет выполнен до того, как будет сделан асинхронный запрос; в большинстве случаев этот код подготавливает запрос.

В приведённом примере функция recv вернёт новый экземпляр Future после запроса на чтение данных из сокета. Этот экземпляр Future завершится после того, как будет прочитано запрошенное количество данных, в данном случае 100 байт. Вторая строка устанавливает обратный вызов для этого future, который будет вызван после завершения future. Всё, что делает обратный вызов, это записывает данные, хранящиеся в future, в stdout. Функция read используется для этого и проверяет, завершился ли future с ошибкой (если да, то просто поднимает ошибку). В противном случае она возвращает значение future.

Асинхронные процедуры

Асинхронные процедуры устраняют сложность работы с обратными вызовами. Они достигают этого, позволяя писать асинхронный код так же, как вы пишете синхронный код.

Асинхронная процедура помечается с помощью директивы {.async.} . Когда процедура помечается директивой {.async.} , она должна иметь тип возвращаемого значения Future[T] или не иметь его вообще. Если вы не указываете тип возвращаемого значения, то предполагается Future[void].

Внутри асинхронных процедур можно использовать await для вызова любых процедур, которые возвращают Future; это включает асинхронные процедуры. Когда процедура "ожидается", асинхронная процедура, в которой она ожидает, приостановит своё выполнение до тех пор, пока future ожидаемой процедуры не завершится. В этот момент асинхронная процедура возобновит своё выполнение. В период приостановки асинхронной процедуры диспетчер будет запускать другие асинхронные процедуры.

Вызов await может использоваться во многих контекстах. Он может использоваться в правой части объявления переменной: var data = await socket.recv(100), в этом случае переменная будет автоматически установлена в значение future. Он может использоваться для ожидания объекта Future и процедуры, возвращающей Future[void]: await socket.send("foobar").

Если ожидаемое future завершится с ошибкой, то await повторно поднимет эту ошибку. Чтобы избежать этого, можно использовать ключевое слово yield вместо await. Следующий раздел демонстрирует различные способы обработки исключений в асинхронных процедурах.

Обработка исключений

Наиболее надёжный способ обработки исключений — использовать yield на future, а затем проверить свойство failed future. Например:

var future = sock.recv(100)
yield future
if future.failed:
  # Handle exception

Процедуры async также предоставляют ограниченную поддержку для оператора try.

try:
  let data = await sock.recv(100)
  echo("Received ", data)
except:
  # Handle exception

К сожалению, семантика оператора try может быть некорректной, и иногда компиляция может полностью завершиться неудачей. Поэтому лучше использовать первый стиль, когда это возможно.

Отбрасывание future

Future никогда не следует отбрасывать. Это связано с тем, что они могут содержать ошибки. Если результат Future вас не интересует, следует использовать процедуру asyncCheck вместо ключевого слова discard. Однако имейте в виду, что это не ждёт завершения, и для этого следует использовать waitFor.

Примеры

Примеры смотрите в документации модулей, реализующих асинхронный ввод-вывод. Хорошей отправной точкой является модуль asyncnet.

Исследование ожидающих future

Возможна ситуация, когда асинхронная процедура, или точнее Future[T], зависает и никогда не завершается. Это может произойти по разным причинам и вызвать серьёзные утечки памяти. В таких случаях трудно определить, какая процедура зависла.

К счастью, существует механизм, который отслеживает количество каждого ожидающего future. Для его включения необходимо скомпилировать с -d:futureLogging и использовать процедуру getFuturesInProgress для получения списка ожидающих future вместе со стековыми следами на момент их создания.

Вам также может быть полезно использовать этот пакет prometheus, который будет регистрировать ожидающие future в prometheus, что позволит вам анализировать их с помощью графиков.

Ограничения/Ошибки

Система эффектов (raises: []) не работает с асинхронными процедурами.

asyncdispatch модуль зависит от модуля asyncmacro для корректной работы.

Импорты

os, tables, strutils, times, heapqueue, options, asyncstreams, options, math, monotimes, asyncfutures, nativesockets, net, deques, winlean, sets, hashes, macros, strutils, asyncfutures, posix

Типы

CompletionData = object fd*: AsyncFD cb*: owned(proc (fd: AsyncFD; bytesTransferred: DWORD; errcode: OSErrorCode) {...}{. closure, gcsafe.}) cell*: ForeignCell: Исходный код Редактировать
PDispatcher = ref object of PDispatcherBase ioPort: Handle handles*: HashSet[AsyncFD]: Исходный код Редактировать
CustomRef = ref CustomObj: Исходный код Редактировать
AsyncFD = distinct int: Исходный код Редактировать
AsyncEvent = ptr AsyncEventImpl: Исходный код Редактировать
Callback = proc (fd: AsyncFD): bool {...}{.closure, gcsafe.}: Исходный код Редактировать

Процедуры

proc `==`(x: AsyncFD; y: AsyncFD): bool {...}{.borrow.}