Features and utilities for Future that integrate it with the dispatcher and the rest of the async machinery

Imports

asyncengine, raisesfutures, ../config, ../futures

Types

FutureCompletedError = object of FutureError: Error raised when trying access the error of a completed Future Source Edit
FuturePendingError = object of FutureError: Error raised when trying to read a Future that is still pending Source Edit
FutureSeq[A; B] = ref object of Future[A] gcholder*: seq[B]: Deprecated Source Edit
FutureStr[T] = ref object of Future[T] gcholder*: string: Deprecated Source Edit

Procs

func `[]`(loc: array[LocationKind, ptr SrcLoc]; v: int): ptr SrcLoc {.
    ...deprecated: "use LocationKind", raises: [], tags: [].}

Deprecated: use LocationKind

Source Edit

proc `and`[T, Y](fut1: Future[T]; fut2: Future[Y]): Future[void] {.
    ...deprecated: "Use allFutures[T](varargs[Future[T]])", raises: [].}

Deprecated: Use allFutures[T](varargs[Future[T]])

Returns a future which will complete once both fut1 and fut2 finish.

If cancelled, fut1 and fut2 futures WILL NOT BE cancelled.

Source Edit

proc `or`[T, Y, E1, E2](fut1: InternalRaisesFuture[T, E1];
                        fut2: InternalRaisesFuture[Y, E2]): auto

Source Edit

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

Returns a future which will complete once either fut1 or fut2 finish.

If fut1 or fut2 future is failed, the result future will also be failed with an error stored in fut1 or fut2 respectively.

If both fut1 and fut2 future are completed or failed, the result future will depend on the state of fut1 future. So if fut1 future is failed, the result future will also be failed, if fut1 future is completed, the result future will also be completed.

If cancelled, fut1 and fut2 futures WILL NOT BE cancelled.

Source Edit

proc addCallback(future: FutureBase; cb: CallbackFunc) {....raises: [],
    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(future: FutureBase; cb: CallbackFunc; udata: pointer) {.
    ...raises: [], 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 all[T](futs: varargs[Future[T]]): auto {.
    ...deprecated: "Use allFutures(varargs[Future[T]])", raises: [].}

Deprecated: Use allFutures(varargs[Future[T]])

Returns a future which will complete once all futures in futs finish. 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].

Note, that if one of the futures in futs will fail, result of all() will also be failed with error from failed future.

TODO: This procedure has bug on handling cancelled futures from futs. So if future from futs list become cancelled, what must be returned? You can't cancel result retFuture because in such way infinite recursion will happen.

Source Edit

proc allFinished[F: SomeFuture](futs: varargs[F]): InternalRaisesFuture[seq[F],
    (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe, raises: [],
                         raises: [].}

Source Edit

proc allFutures(futs: varargs[FutureBase]): InternalRaisesFuture[void,
    (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe, raises: [],
                         raises: [], tags: [RootEffect].}

Source Edit

proc allFutures[T, E](futs: varargs[InternalRaisesFuture[T, E]]): InternalRaisesFuture[
    void, (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe,
                               raises: [], raises: [].}

Source Edit

proc allFutures[T](futs: varargs[Future[T]]): InternalRaisesFuture[void,
    (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe, raises: [],
                         raises: [].}

Source Edit

proc asyncCheck[T](future: Future[T]) {....deprecated: "Raises Defect on future failure, fix your code and use asyncSpawn!",
                                        raises: [].}

Deprecated: Raises Defect on future failure, fix your code and use asyncSpawn!

This function used to raise an exception through the poll call if the given future failed - there's no way to handle such exceptions so this function is now an alias for asyncSpawn Source Edit

proc asyncDiscard[T](future: Future[T]) {.
    ...deprecated: "Use asyncSpawn or `discard await`", raises: [].}

Deprecated: Use asyncSpawn or `discard await`

asyncDiscard will discard the outcome of the operation - unlike discard it also throws away exceptions! Use asyncSpawn if you're sure your code doesn't raise exceptions, or discard await to ignore successful outcomes Source Edit

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

Spawns a new concurrent async task.

Tasks may not raise exceptions or be cancelled - a Defect will be raised when this happens.

This should be used instead of discard and asyncCheck when calling an async procedure without await, to ensure exceptions in the returned future are not silently discarded.

Note, that if passed future is already finished, it will be checked and processed immediately.

Source Edit

proc callback=(future: FutureBase; cb: CallbackFunc) {....deprecated: "use addCallback/removeCallback/clearCallbacks instead to manage the callback list",
    raises: [], raises: [], raises: [], tags: [RootEffect].}

Deprecated: use addCallback/removeCallback/clearCallbacks instead to manage the callback list

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 callback=(future: FutureBase; cb: CallbackFunc; udata: pointer) {....deprecated: "use addCallback/removeCallback/clearCallbacks to manage the callback list",
    raises: [], tags: [RootEffect].}

Deprecated: use addCallback/removeCallback/clearCallbacks to manage the callback list

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 cancelAndWait(future: FutureBase; loc: ptr SrcLoc): InternalRaisesFuture[
    void, void] {.stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [],
                  tags: [RootEffect].}

Source Edit

proc cancelCallback=(future: FutureBase; cb: CallbackFunc) {....raises: [],
    tags: [].}

Sets the callback procedure to be called when the future is cancelled.

This callback will be called immediately as future.cancel() invoked and must be set before future is finished.

Source Edit

proc done(future: FutureBase): bool {....deprecated: "Use `completed` instead",
                                      raises: [], tags: [].}

Deprecated: Use `completed` instead

This is an alias for completed(future) procedure. Source Edit

proc futureContinue(fut: FutureBase) {....raises: [], gcsafe, raises: [],
                                       tags: [RootEffect].}

Source Edit

proc idleAsync(): InternalRaisesFuture[void, (CancelledError,)] {.
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [], tags: [].}

Source Edit

proc join(future: FutureBase): InternalRaisesFuture[void, (CancelledError,)] {.
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [],
    tags: [RootEffect].}

Source Edit

proc join(future: SomeFuture): InternalRaisesFuture[void, (CancelledError,)] {.
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [].}

Source Edit

proc noCancel[F: SomeFuture](future: F): auto {....raises: [].}

Prevent cancellation requests from propagating to future while forwarding its value or error when it finishes.

This procedure should be used when you need to perform operations which should not be cancelled at all cost, for example closing sockets, pipes, connections or servers. Usually it become useful in exception or finally blocks.

Source Edit

proc one[F: SomeFuture](fut0: F; futs: varargs[F]): InternalRaisesFuture[F,
    (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe, raises: [],
                         raises: [].}

Source Edit

proc one[F: SomeFuture](futs: openArray[F]): InternalRaisesFuture[F,
    (ValueError, CancelledError)] {.stackTrace: false, ...raises: [], gcsafe,
                                    raises: [], raises: [].}

Source Edit

proc oneIndex[T](futs: varargs[Future[T]]): Future[int] {.
    ...deprecated: "Use one[T](varargs[Future[T]])", raises: [].}

Deprecated: Use one[T](varargs[Future[T]])

Returns a future which will complete once one of the futures in futs complete.

If the argument is empty, the returned future FAILS immediately.

Returned future will hold index of completed/failed future in futs argument.

Source Edit

proc oneValue[T](futs: varargs[Future[T]]): Future[T] {.
    ...deprecated: "Use one[T](varargs[Future[T]])", raises: [].}

Deprecated: Use one[T](varargs[Future[T]])

Returns a future which will finish once one of the futures in futs finish.

If the argument is empty, returned future FAILS immediately.

Returned future will hold value of completed futs future, or error if future was failed.

Source Edit

proc race(fut0: FutureBase; futs: varargs[FutureBase]): InternalRaisesFuture[
    FutureBase, (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe,
                                     raises: [], raises: [], tags: [RootEffect].}

Source Edit

proc race(futs: openArray[FutureBase]): InternalRaisesFuture[FutureBase,
    (ValueError, CancelledError)] {.stackTrace: false, ...raises: [], gcsafe,
                                    raises: [], raises: [], tags: [RootEffect].}

Source Edit

proc race(futs: openArray[SomeFuture]): InternalRaisesFuture[FutureBase,
    (ValueError, CancelledError)] {.stackTrace: false, ...raises: [], gcsafe,
                                    raises: [], raises: [].}

Source Edit

proc read(fut: Future[void]) {....raises: [CatchableError], raises: [], tags: [].}

Checks that fut completed.

If the future failed or was cancelled, the corresponding exception will be raised.

If the future is still pending, FuturePendingError will be raised.

Source Edit

proc read[E](fut: InternalRaisesFuture[void, E])

Checks that fut completed.

If the future failed or was cancelled, the corresponding exception will be raised.

If the future is still pending, FuturePendingError will be raised.

Source Edit

proc read[T: not void; E](fut: InternalRaisesFuture[T, E]): lent T

Retrieves the value of fut.

If the future failed or was cancelled, the corresponding exception will be raised.

If the future is still pending, FuturePendingError will be raised.

Source Edit

proc read[T: not void](fut: Future[T]): lent T {....raises: [CatchableError],
    raises: [].}

Retrieves the value of fut.

If the future failed or was cancelled, the corresponding exception will be raised.

If the future is still pending, FuturePendingError will be raised.

Source Edit

proc readError(fut: FutureBase): ref CatchableError {....raises: [FutureError],
    raises: [], tags: [].}

Retrieves the exception of the failed or cancelled fut.

If the future was completed with a value, FutureCompletedError will be raised.

If the future is still pending, FuturePendingError will be raised.

Source Edit

proc removeCallback(future: FutureBase; cb: CallbackFunc) {....raises: [],
    tags: [RootEffect].}

Source Edit

proc removeCallback(future: FutureBase; cb: CallbackFunc; udata: pointer) {.
    ...raises: [], tags: [].}

Remove future from list of callbacks - this operation may be slow if there are many registered callbacks! Source Edit

proc sleepAsync(duration: Duration): InternalRaisesFuture[void,
    (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe, raises: [],
                         raises: [], tags: [].}

Source Edit

proc sleepAsync(ms: int): InternalRaisesFuture[void, (CancelledError,)] {.
    inline, ...deprecated: "Use sleepAsync(Duration)", stackTrace: false,
    ...raises: [], gcsafe, raises: [], raises: [], tags: [].}

Deprecated: Use sleepAsync(Duration)

Source Edit

proc stepsAsync(number: int): InternalRaisesFuture[void, (CancelledError,)] {.
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [],
    tags: [RootEffect].}

Source Edit

proc wait(fut: InternalRaisesFuture; deadline: SomeFuture): auto

Source Edit

proc wait(fut: InternalRaisesFuture; timeout = InfiniteDuration): auto

Source Edit

proc wait[T](fut: Future[T]; deadline: SomeFuture): Future[T] {....raises: [].}

Returns a future which will complete once future fut completes or if deadline future completes.

If deadline future completes before future fut - AsyncTimeoutError exception will be raised.

Note: deadline future will not be cancelled and/or failed.

Note: While waitUntil(future) operation is pending, please avoid any attempts to cancel future fut. If it happens waitUntil() could introduce undefined behavior - it could raiseCancelledError or AsyncTimeoutError.

If you need to cancel future - cancel waitUntil(future) instead.

Source Edit

proc wait[T](fut: Future[T]; timeout = -1): Future[T] {.inline,
    ...deprecated: "Use wait(Future[T], Duration)", raises: [].}

Deprecated: Use wait(Future[T], Duration)

Source Edit

proc wait[T](fut: Future[T]; timeout = InfiniteDuration): Future[T] {....raises: [].}

Returns a future which will complete once future fut completes or if timeout of timeout milliseconds has been expired.

If timeout is -1, then statement await wait(fut) is equal to await fut.

TODO: In case when fut got cancelled, what result Future[T] should return, because it can't be cancelled too.

Source Edit

proc waitFor(fut: Future[void]) {....raises: [CatchableError], raises: [],
                                  tags: [RootEffect].}

Blocks the current thread of execution until fut has finished.

If the future failed or was cancelled, the corresponding exception will be raised.

Must not be called recursively (from inside async procedures).

See also await, Future.read

Source Edit

proc waitFor[E](fut: InternalRaisesFuture[void, E])

Blocks the current thread of execution until fut has finished.

If the future failed or was cancelled, the corresponding exception will be raised.

Must not be called recursively (from inside async procedures).

See also await, Future.read

Source Edit

proc waitFor[T: not void; E](fut: InternalRaisesFuture[T, E]): lent T

Blocks the current thread of execution until fut has finished, returning its value.

If the future failed or was cancelled, the corresponding exception will be raised.

Must not be called recursively (from inside async procedures).

See also await, Future.read

Source Edit

proc waitFor[T: not void](fut: Future[T]): lent T {....raises: [CatchableError],
    raises: [].}

Blocks the current thread of execution until fut has finished, returning its value.

If the future failed or was cancelled, the corresponding exception will be raised.

Must not be called recursively (from inside async procedures).

See also await, Future.read

Source Edit

proc withTimeout[T](fut: Future[T]; timeout: Duration): InternalRaisesFuture[
    bool, (CancelledError,)] {.stackTrace: false, ...raises: [], gcsafe,
                               raises: [], raises: [].}

Source Edit

proc withTimeout[T](fut: Future[T]; timeout: int): Future[bool] {.inline,
    ...deprecated: "Use withTimeout(Future[T], Duration)", raises: [].}

Deprecated: Use withTimeout(Future[T], Duration)

Source Edit

Macros

macro internalRaiseIfError(fut: FutureBase; info: typed) {....raises: [].}: Source Edit
macro internalRaiseIfError(fut: InternalRaisesFuture; raises, info: typed) {. ...raises: [].}: Source Edit

Templates

template cancel(future: FutureBase) {....deprecated: "Please use cancelSoon() or cancelAndWait() instead".}

Deprecated: Please use cancelSoon() or cancelAndWait() instead

Cancel future. Source Edit

template cancelAndSchedule(future: FutureBase)

Source Edit

template cancelAndWait(future: FutureBase): Future[void].Raising([])

Cancel future. Source Edit

template cancelSoon(fut: FutureBase)

Source Edit

template cancelSoon(fut: FutureBase; acb: AsyncCallback)

Source Edit

template cancelSoon(fut: FutureBase; cb: CallbackFunc)

Source Edit

template cancelSoon(fut: FutureBase; cb: CallbackFunc; udata: pointer)

Source Edit

template complete(future: Future[void])

Completes a void future. Source Edit

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

Completes future with value val. Source Edit

template fail[T, E](future: InternalRaisesFuture[T, E];
                    error: ref CatchableError; warn: static bool = true)

Source Edit

template fail[T](future: Future[T]; error: ref CatchableError;
                 warn: static bool = false)

Completes future with error. Source Edit

template Finished() {....deprecated: "Use Completed instead".}

Deprecated: Use Completed instead

Source Edit

template Finished(T: type FutureState): FutureState {.
    ...deprecated: "Use FutureState.Completed instead".}

Deprecated: Use FutureState.Completed instead

Source Edit

template LocCompleteIndex(): untyped {....deprecated: "LocationKind.Finish".}

Deprecated: LocationKind.Finish

Source Edit

template LocCreateIndex(): auto {....deprecated: "LocationKind.Create".}

Deprecated: LocationKind.Create

Source Edit

template LocFinishIndex(): auto {....deprecated: "LocationKind.Finish".}

Deprecated: LocationKind.Finish

Source Edit

template newFuture[T](fromProc: static[string] = "";
                      flags: static[FutureFlags] = {}): auto

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

template newFutureSeq[A, B](fromProc: static[string] = ""): FutureSeq[A, B] {.
    ...deprecated.}

Deprecated

Create a new future which can hold/preserve GC sequence until future will not be completed.

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

template newFutureStr[T](fromProc: static[string] = ""): FutureStr[T] {.
    ...deprecated.}

Deprecated

Create a new future which can hold/preserve GC string until future will not be completed.

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

template newInternalRaisesFuture[T, E](fromProc: static[string] = ""): auto

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

template orImpl[T, Y](fut1: Future[T]; fut2: Future[Y]): untyped

Source Edit

template tryCancel(future: FutureBase): bool

Source Edit

Exports

Raising, InternalRaisesFuture, init, init, error, readError

chronos/internal/asyncfutures

Imports

Types

Procs

Macros

Templates

Exports