chronos/futures

Search:
Group by:
Source   Edit  

Types

CallbackFunc = proc (arg: pointer) {....gcsafe, raises: [].}
Source   Edit   
CancelledError = object of FutureError
Exception raised when accessing the value of a cancelled future Source   Edit   
Future[T] = ref object of FutureBase
  when T isnot void:
    internalValue*: T        ## Stored value
Typed future. Source   Edit   
FutureBase = ref object of InternalFutureBase
Untyped Future Source   Edit   
FutureDefect = object of Defect
  cause*: FutureBase
Source   Edit   
FutureError = object of CatchableError
  future*: FutureBase
Source   Edit   
FutureFlag {.pure.} = enum
  OwnCancelSchedule ## When OwnCancelSchedule is set, the owner of the future is responsible
                    ## for implementing cancellation in one of 3 ways:
                    ## 
                    ## * ensure that cancellation requests never reach the future by means of
                    ##   not exposing it to user code, `await` and `tryCancel`
                    ## * set `cancelCallback` to `nil` to stop cancellation propagation - this
                    ##   is appropriate when it is expected that the future will be completed
                    ##   in a regular way "soon"
                    ## * set `cancelCallback` to a handler that implements cancellation in an
                    ##   operation-specific way
                    ## 
                    ## If `cancelCallback` is not set and the future gets cancelled, a
                    ## `Defect` will be raised.
Source   Edit   
FutureState {.pure.} = enum
  Pending, Completed, Cancelled, Failed
Source   Edit   
InternalAsyncCallback = object
  function*: CallbackFunc
  udata*: pointer
Source   Edit   
InternalFutureBase = object of RootObj
  internalLocation*: array[LocationKind, ptr SrcLoc]
  internalCallback*: InternalAsyncCallback ## The vast majority of futures track a single callback only (the one
                                           ## installed by `await`) - to avoid allocating a seq (which involves
                                           ## making a separate allocation with space for several callbacks), we keep
                                           ## a spot in each future for that first one - the seq below will stay
                                           ## empty until a second callback is added
  internalCallbacks*: seq[InternalAsyncCallback]
  internalCancelcb*: CallbackFunc
  internalChild*: FutureBase
  internalState*: FutureState
  internalFlags*: FutureFlags
  internalError*: ref CatchableError ## Stored exception
  internalClosure*: iterator (f: FutureBase): FutureBase {....raises: [], gcsafe.}
  when chronosFutureId:
    internalId*: uint
  when chronosStackTrace:
    internalErrorStackTrace*: StackTrace
    internalStackTrace*: StackTrace ## For debugging purposes only.
  when chronosFutureTracking:
    internalNext*: FutureBase
    internalPrev*: FutureBase
Source   Edit   
LocationKind {.pure.} = enum
  Create, Finish
Source   Edit  

Procs

func cancelled(future: FutureBase): bool {.inline, ...raises: [], tags: [],
    forbids: [].}
Determines whether future has cancelled. Source   Edit   
func completed(future: FutureBase): bool {.inline, ...raises: [], tags: [],
    forbids: [].}
Determines whether future finished with a value. Source   Edit   
func error(future: FutureBase): ref CatchableError {....raises: [], tags: [],
    forbids: [].}

Return the error of future, or nil if future did not fail.

See readError for a version that raises a catchable error when the future has not failed.

Source   Edit   
func failed(future: FutureBase): bool {.inline, ...raises: [], tags: [],
                                        forbids: [].}
Determines whether future finished with an error. Source   Edit   
func finished(future: FutureBase): bool {.inline, ...raises: [], tags: [],
    forbids: [].}
Determines whether future has finished, i.e. future state changed from state Pending to one of the states (Finished, Cancelled, Failed). Source   Edit   
func flags(future: FutureBase): FutureFlags {....raises: [], tags: [], forbids: [].}
Source   Edit   
proc internalInitFutureBase(fut: FutureBase; loc: ptr SrcLoc;
                            state: FutureState; flags: FutureFlags) {.
    ...raises: [], tags: [], forbids: [].}
Source   Edit   
func location(future: FutureBase): array[LocationKind, ptr SrcLoc] {....raises: [],
    tags: [], forbids: [].}
Source   Edit   
func state(future: FutureBase): FutureState {....raises: [], tags: [], forbids: [].}
Source   Edit   
func value(future: Future[void]) {....raises: [], tags: [], forbids: [].}

Return the value in a completed future - raises Defect when fut.completed() is false.

See read for a version that raises a catchable error when future has not completed.

Source   Edit   
func value[T: not void](future: Future[T]): lent T {....raises: [].}

Return the value in a completed future - raises Defect when fut.completed() is false.

See read for a version that raises a catchable error when future has not completed.

Source   Edit  

Templates

template completed(F: type Future; fromProc: static[string] = ""): Future[void] {..}
Create a new completed future Source   Edit   
template completed[T: not void](F: type Future; valueParam: T;
                                fromProc: static[string] = ""): Future[T] {..}
Create a new completed future Source   Edit   
template failed[T](F: type Future[T]; errorParam: ref CatchableError;
                   fromProc: static[string] = ""): Future[T] {..}
Create a new failed future Source   Edit   
template id(fut: FutureBase): uint {..}
Source   Edit   
template init[T](F: type Future[T]; fromProc: static[string] = ""): Future[T] {..}

Creates a new pending 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 init[T](F: type Future[T]; fromProc: static[string] = "";
                 flags: static[FutureFlags]): Future[T] {..}

Creates a new pending 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  

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