chronos/futures

  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]
  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: [].}
Determines whether future has cancelled.   Source   Edit
func completed(future: FutureBase): bool {.inline, ...raises: [], tags: [].}
Determines whether future finished with a value.   Source   Edit
func error(future: FutureBase): ref CatchableError {....raises: [], tags: [].}

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: [].}
Determines whether future finished with an error.   Source   Edit
func finished(future: FutureBase): bool {.inline, ...raises: [], tags: [].}
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: [].}
  Source   Edit
proc internalInitFutureBase(fut: FutureBase; loc: ptr SrcLoc;
                            state: FutureState; flags: FutureFlags) {.
    ...raises: [], tags: [].}
  Source   Edit
func location(future: FutureBase): array[LocationKind, ptr SrcLoc] {....raises: [],
    tags: [].}
  Source   Edit
func state(future: FutureBase): FutureState {....raises: [], tags: [].}
  Source   Edit
func value(future: Future[void]) {....raises: [], tags: [].}

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