chronos/internal/asyncfutures

Search:
Group by:
Source   Edit  

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

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: [], forbids: [].}
Deprecated: use LocationKind
Source   Edit   
proc addCallback(future: FutureBase; cb: CallbackFunc) {....raises: [], tags: [],
    forbids: [].}

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: [], forbids: [].}

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 allFinished[F: SomeFuture](futs: varargs[F]): InternalRaisesFuture[seq[F],
    (CancelledError,)] {....stackTrace: false, raises: [], gcsafe, raises: [].}
Source   Edit   
proc allFutures(futs: varargs[FutureBase]): InternalRaisesFuture[void,
    (CancelledError,)] {....stackTrace: false, raises: [], gcsafe, raises: [],
                         tags: [], forbids: [].}
Source   Edit   
proc allFutures[T, E](futs: varargs[InternalRaisesFuture[T, E]]): InternalRaisesFuture[
    void, (CancelledError,)] {....stackTrace: false, raises: [], gcsafe, raises: [].}
Source   Edit   
proc allFutures[T](futs: varargs[Future[T]]): InternalRaisesFuture[void,
    (CancelledError,)] {....stackTrace: false, raises: [], gcsafe, 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 asyncSpawn(future: Future[void]) {....raises: [], tags: [], forbids: [].}

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: [], tags: [], forbids: [].}
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: [], forbids: [].}
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 cancelCallback=(future: FutureBase; cb: CallbackFunc) {....raises: [],
    tags: [], forbids: [].}

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: [], forbids: [].}
Deprecated: Use `completed` instead
This is an alias for completed(future) procedure. Source   Edit   
proc futureContinue(fut: FutureBase) {....raises: [], gcsafe, raises: [],
                                       tags: [RootEffect], forbids: [].}
Source   Edit   
proc idleAsync(): InternalRaisesFuture[void, (CancelledError,)] {.
    ...stackTrace: false, raises: [], gcsafe, raises: [], tags: [], forbids: [].}
Source   Edit   
proc join(future: FutureBase): InternalRaisesFuture[void, (CancelledError,)] {.
    ...stackTrace: false, raises: [], gcsafe, raises: [], tags: [], forbids: [].}
Source   Edit   
proc join(future: SomeFuture): InternalRaisesFuture[void, (CancelledError,)] {.
    ...stackTrace: false, raises: [], gcsafe, 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(_: typeof([])) {.error: "`one` requires at least one future",
                          ...raises: [].}
Source   Edit   
proc one(fut0: SomeFuture; futs: varargs[SomeFuture]): InternalRaisesFuture[
    SomeFuture, (CancelledError,)] {....stackTrace: false, raises: [], gcsafe,
                                     raises: [].}
Source   Edit   
proc one(futs: openArray[SomeFuture]): InternalRaisesFuture[SomeFuture,
    (ValueError, CancelledError)] {....stackTrace: false, raises: [], gcsafe,
                                    raises: [].}
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 race(_: typeof([])) {.error: "`race` requires at least one future",
                           ...raises: [].}
Source   Edit   
proc race(fut0: FutureBase; futs: varargs[FutureBase]): InternalRaisesFuture[
    FutureBase, (CancelledError,)] {....stackTrace: false, raises: [], gcsafe,
                                     raises: [], tags: [], forbids: [].}
Source   Edit   
proc race(fut0: SomeFuture; futs: openArray[SomeFuture]): InternalRaisesFuture[
    SomeFuture, (CancelledError,)] {....stackTrace: false, raises: [], gcsafe,
                                     raises: [].}
Source   Edit   
proc race(futs: openArray[FutureBase]): InternalRaisesFuture[FutureBase,
    (ValueError, CancelledError)] {....stackTrace: false, raises: [], gcsafe,
                                    raises: [], tags: [], forbids: [].}
Source   Edit   
proc race(futs: openArray[SomeFuture]): InternalRaisesFuture[SomeFuture,
    (ValueError, CancelledError)] {....stackTrace: false, raises: [], gcsafe,
                                    raises: [].}
Source   Edit   
proc read(fut: Future[void]) {....raises: [CatchableError], raises: [], tags: [],
                               forbids: [].}

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: [], forbids: [].}

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: [], forbids: [].}
Source   Edit   
proc removeCallback(future: FutureBase; cb: CallbackFunc; udata: pointer) {.
    ...raises: [], tags: [], forbids: [].}
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: [],
                         tags: [], forbids: [].}
Source   Edit   
proc sleepAsync(ms: int): InternalRaisesFuture[void, (CancelledError,)] {.
    inline, ...deprecated: "Use sleepAsync(Duration)", stackTrace: false,
    raises: [], gcsafe, raises: [], tags: [], forbids: [].}
Deprecated: Use sleepAsync(Duration)
Source   Edit   
proc stepsAsync(number: int): InternalRaisesFuture[void, (CancelledError,)] {.
    ...stackTrace: false, raises: [], gcsafe, raises: [], tags: [], forbids: [].}
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 FutureT should return, because it can't be cancelled too.

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

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: [].}
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) {..}
Source   Edit   
macro internalRaiseIfError(fut: InternalRaisesFuture; raises, info: typed) {..}
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(futs: openArray[SomeFuture]): Future[void].Raising([]) {..}

Perform cancellation of all the futs. Returns Future which will be completed when all the futs become finished (completed with value, failed or cancelled).

NOTE: Compared to the tryCancel() call, this procedure call guarantees that all the futswill be finished (completed with value, failed or cancelled) as quickly as possible.

NOTE: It is safe to pass finished futures in futs (completed with value, failed or cancelled).

NOTE: If futs is an empty array, procedure returns completed Future.

Source   Edit   
template cancelAndWait(futs: varargs[FutureBase]): Future[void].Raising([]) {..}

Perform cancellation of all the futs. Returns Future which will be completed when all the futs become finished (completed with value, failed or cancelled).

NOTE: Compared to the tryCancel() call, this procedure call guarantees that all the futswill be finished (completed with value, failed or cancelled) as quickly as possible.

NOTE: It is safe to pass finished futures in futs (completed with value, failed or cancelled).

NOTE: If futs is an empty array, procedure returns completed Future.

Source   Edit   
template cancelAndWait(future: FutureBase): Future[void].Raising([]) {..}

Perform cancellation future return Future which will be completed when future become finished (completed with value, failed or cancelled).

NOTE: Compared to the tryCancel() call, this procedure call guarantees that futurewill be finished (completed with value, failed or cancelled) as quickly as possible.

Source   Edit   
template cancelAndWait(future: SomeFuture): Future[void].Raising([]) {..}

Perform cancellation future return Future which will be completed when future become finished (completed with value, failed or cancelled).

NOTE: Compared to the tryCancel() call, this procedure call guarantees that futurewill be finished (completed with value, failed or cancelled) as quickly as possible.

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: not void](future: Future[T]; val: chronosSink 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 internalFail(future: FutureBase; error: ref CatchableError) {..}
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  

Made with Nim. Generated: 2026-09-02 18:01:43 UTC