# std/asyncfutures

Dark Mode

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

# Imports

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

# Types

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

  Typed future. Source Edit

    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

  Untyped future. Source Edit

    FutureError = object of Defect
      cause*: FutureBase

  Source Edit

    FutureVar[T] = distinct Future[T]

  Source Edit

# Consts

    isFutureLoggingEnabled = false

  Source Edit

    NimAsyncContinueSuffix = "NimAsyncContinue"

  For internal usage. Do not use. Source Edit

# Procs

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

  Source Edit

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

  Returns a future which will complete once both `fut1` and `fut2` complete. Source Edit

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

  Returns a future which will complete once either `fut1` or `fut2` complete. Source Edit

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

  Adds the callbacks proc to be called when the future completes.

  If future has already completed then `cb` will be called immediately.

  Source Edit

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

  Adds the callbacks proc to be called when the future completes.

  If future has already completed then `cb` will be called immediately.

  Source Edit

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

  Returns a future which will complete once all futures in `futs` complete. If the argument is empty, the returned future completes immediately.

  If the awaited futures are not `Future[void]`, the returned future will hold the values of all awaited futures in a sequence.

  If the awaited futures are `Future[void]`, this proc returns `Future[void]`.

  Source Edit

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

  Sets a callback on `future` which raises an exception if the future finished with an error.

  This should be used instead of `discard` to discard void futures, or use `waitFor` if you need to wait for the future's completion.

  Source Edit

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

  Clears the list of callbacks and sets the callback proc to be called when the future completes.

  If future has already completed then `cb` will be called immediately.

  It's recommended to use `addCallback` or `then` instead.

  Source Edit

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

  Sets the callback proc to be called when the future completes.

  If future has already completed then `cb` will be called immediately.

  Source Edit

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

  Call `cbproc` "soon".

  If async dispatcher is running, `cbproc` will be executed during next dispatcher tick.

  If async dispatcher is not running, `cbproc` will be executed immediately.

  Source Edit

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

  Resets the `finished` status of `future`. Source Edit

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

  Source Edit

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

  Source Edit

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

  Completes `future` with value `val`. Source Edit

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

  Completes a `FutureVar`. Source Edit

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

  Completes a `FutureVar` with value `val`.

  Any previously stored value will be overwritten.

  Source Edit

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

  Completes `future` with `error`. Source Edit

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

  Determines whether `future` completed with an error. Source Edit

    proc finished(future: FutureBase | FutureVar): bool

  Determines whether `future` has completed.

  `True` may indicate an error or a value. Use `failed` to distinguish.

  Source Edit

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

  Get current implementation of `callSoon`. Source Edit

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

  Returns a mutable value stored in `future`.

  Unlike `read`, this function will not raise an exception if the Future has not been finished.

  Source Edit

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

  Creates a new future.

  Specifying `fromProc`, which is a string specifying the name of the proc that this future belongs to, is a good habit as it helps with debugging.

  Source Edit

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

  Create a new `FutureVar`. This Future type is ideally suited for situations where you want to avoid unnecessary allocations of Futures.

  Specifying `fromProc`, which is a string specifying the name of the proc that this future belongs to, is a good habit as it helps with debugging.

  Source Edit

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

  Retrieves the value of `future`. Future must be finished otherwise this function will fail with a `ValueError` exception.

  If the result of the future is an error then that error will be raised.

  Source Edit

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

  Retrieves the exception stored in `future`.

  An `ValueError` exception will be thrown if no exception exists in the specified Future.

  Source Edit

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

  Change current implementation of `callSoon`. This is normally called when dispatcher from `asyncdispatcher` is initialized. Source Edit