asyncfutures

Импорты

os, tables, strutils, times, heapqueue, options, deques, cstrutils, stacktraces

Типы

FutureBase = ref object of RootObj
  callbacks: CallbackList
  finished: bool
  error*: ref Exception      ## Stored exception
  errorStackTrace*: string
  when not false:
      stackTrace: seq[StackTraceEntry] ## For debugging purposes only.
      id: int
      fromProc: string

Нетипизированное будущее. Исходный код Редактировать

Future[T] = ref object of FutureBase
  value: T                   ## Stored value

Типизированное будущее. Исходный код Редактировать

FutureVar[T] = distinct Future[T]

Исходный код Редактировать

FutureError = object of Defect
  cause*: FutureBase

Исходный код Редактировать

Константы

isFutureLoggingEnabled = false

Исходный код Редактировать

NimAsyncContinueSuffix = "NimAsyncContinue"

Для внутреннего использования. Не использовать. Исходный код Редактировать

Процедуры

proc getCallSoonProc(): (proc (cbproc: proc ()) {...}{.gcsafe.}) {...}{.raises: [],
    tags: [].}

Получить текущую реализацию callSoon. Исходный код Редактировать

proc setCallSoonProc(p: (proc (cbproc: proc ()) {...}{.gcsafe.})) {...}{.raises: [],
    tags: [].}

Изменить текущую реализацию callSoon. Обычно вызывается при инициализации диспетчера из asyncdispatcher. Исходный код Редактировать

proc callSoon(cbproc: proc ()) {...}{.raises: [Exception], tags: [RootEffect].}

Вызвать cbproc "вскоре".

Если асинхронный диспетчер запущен, cbproc будет выполнен во время следующего тика диспетчера.

Если асинхронный диспетчер не запущен, cbproc будет выполнен немедленно.

Исходный код Редактировать

proc newFuture[T](fromProc: string = "unspecified"): owned(Future[T])

Создаёт новый фьючер.

Указание fromProc, что является строкой, указывающей имя процедуры, к которой относится этот фьючер, является хорошей практикой, так как это помогает при отладке.

Исходный код Редактировать

proc newFutureVar[T](fromProc = "unspecified"): owned(FutureVar[T])

Создаёт новый FutureVar. Этот тип Future идеально подходит для ситуаций, когда вы хотите избежать ненужных выделений памяти для Futures.

Указание fromProc, что является строкой, указывающей имя процедуры, к которой относится этот фьючер, является хорошей практикой, так как это помогает при отладке.

Исходный код Редактировать

proc clean[T](future: FutureVar[T])

Сбрасывает статус finished future. Исходный код Редактировать

proc complete[T](future: Future[T]; val: T)

Завершает future со значением val. Исходный код Редактировать

proc complete(future: Future[void]) {...}{.raises: [Exception], tags: [RootEffect].}

Завершает пустой future. Исходный код Редактировать

proc complete[T](future: FutureVar[T])

Завершает FutureVar. Исходный код Редактировать

proc complete[T](future: FutureVar[T]; val: T)

Завершает FutureVar со значением val.

Любое ранее сохранённое значение будет перезаписано.

Исходный код Редактировать

proc fail[T](future: Future[T]; error: ref Exception)

Завершает future с error. Исходный код Редактировать

proc clearCallbacks(future: FutureBase) {...}{.raises: [], tags: [].}

Исходный код Редактировать

proc addCallback(future: FutureBase; cb: proc () {...}{.closure, gcsafe.}) {...}{.
    raises: [Exception], tags: [RootEffect].}

Добавляет процедуру обратного вызова, которая будет вызвана при завершении фьючера.

Если фьючер уже завершён, то cb будет вызван немедленно.

Исходный код Редактировать

proc addCallback[T](future: Future[T];
                    cb: proc (future: Future[T]) {...}{.closure, gcsafe.})

Добавляет процедуру обратного вызова, которая будет вызвана при завершении фьючера.

Если фьючер уже завершён, то cb будет вызван немедленно.

Исходный код Редактировать

proc callback=(future: FutureBase; cb: proc () {...}{.closure, gcsafe.}) {...}{.
    raises: [Exception], tags: [RootEffect].}

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

Если фьючер уже завершён, то cb будет вызван немедленно.

Рекомендуется использовать addCallback или then вместо этого.

Исходный код Редактировать

proc callback=[T](future: Future[T];
                  cb: proc (future: Future[T]) {...}{.closure, gcsafe.})

Устанавливает процедуру обратного вызова, которая будет вызвана при завершении фьючера.

Если фьючер уже завершён, то cb будет вызван немедленно.

Исходный код Редактировать

proc `$`(stackTraceEntries: seq[StackTraceEntry]): string {...}{.
    raises: [ValueError], tags: [].}

Исходный код Редактировать

proc read[T](future: Future[T] | FutureVar[T]): T

Получает значение future. Фьючер должен быть завершён, иначе эта функция завершится с исключением ValueError.

Если результат фьючера — ошибка, то эта ошибка будет поднята.

Исходный код Редактировать

proc readError[T](future: Future[T]): ref Exception

Получает исключение, сохранённое в future.

Исключение ValueError будет выброшено, если в указанном фьючере нет исключения.

Исходный код Редактировать

proc mget[T](future: FutureVar[T]): var T

Возвращает изменяемое значение, хранящееся в future.

В отличие от read, эта функция не будет вызывать исключение, если фьючер не был завершен.

Исходный код Редактировать

proc finished(future: FutureBase | FutureVar): bool

Определяет, завершился ли future.

True может указывать на ошибку или значение. Используйте failed для различения.

Исходный код Редактировать

proc failed(future: FutureBase): bool {...}{.raises: [], tags: [].}

Определяет, завершился ли future с ошибкой. Исходный код Редактировать

proc asyncCheck[T](future: Future[T])

Устанавливает обратный вызов для future, который поднимает исключение, если фьючер завершился с ошибкой.

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

Исходный код Редактировать

proc `and`[T, Y](fut1: Future[T]; fut2: Future[Y]): Future[void]

Возвращает фьючер, который завершится, когда завершатся оба fut1 и fut2. Исходный код Редактировать

proc `or`[T, Y](fut1: Future[T]; fut2: Future[Y]): Future[void]

Возвращает фьючер, который завершится, когда завершится либо fut1, либо fut2. Исходный код Редактировать

proc all[T](futs: varargs[Future[T]]): auto

Возвращает фьючер, который завершится, когда завершатся все фьючеры в futs. Если аргумент пуст, возвращаемый фьючер завершится немедленно.

Если ожидаемые фьючеры не Future[void], возвращаемый фьючер будет содержать значения всех ожидаемых фьючеров в последовательности.

Если ожидаемые фьючеры являются Future[void], эта процедура возвращает Future[void].

Исходный код Редактировать