# # Chronos # # (c) Copyright 2015 Dominik Picheta # (c) Copyright 2018-Present Status Research & Development GmbH # # Licensed under either of # Apache License, version 2.0, (LICENSE-APACHEv2) # MIT license (LICENSE-MIT) import os, tables, strutils, heapqueue, options, deques, cstrutils import srcloc export srcloc const LocCreateIndex = 0 LocCompleteIndex = 1 type # ZAH: This can probably be stored with a cheaper representation # until the moment it needs to be printed to the screen # (e.g. seq[StackTraceEntry]) StackTrace = string FutureState* {.pure.} = enum Pending, Finished, Cancelled, Failed FutureBase* = ref object of RootObj ## Untyped future. location: array[2, ptr SrcLoc] callbacks: Deque[AsyncCallback] cancelcb*: CallbackFunc child*: FutureBase state*: FutureState error*: ref Exception ## Stored exception errorStackTrace*: StackTrace stackTrace: StackTrace ## For debugging purposes only. id: int # ZAH: we have discussed some possible optimizations where # the future can be stored within the caller's stack frame. # How much refactoring is needed to make this a regular non-ref type? # Obviously, it will still be allocated on the heap when necessary. Future*[T] = ref object of FutureBase ## Typed future. value: T ## Stored value FutureStr*[T] = ref object of Future[T] ## Future to hold GC strings gcholder*: string FutureSeq*[A, B] = ref object of Future[A] ## Future to hold GC seqs gcholder*: seq[B] FutureVar*[T] = distinct Future[T] FutureDefect* = object of Defect cause*: FutureBase FutureError* = object of CatchableError CancelledError* = object of FutureError var currentID* {.threadvar.}: int currentID = 0 template setupFutureBase(loc: ptr SrcLoc) = new(result) result.state = FutureState.Pending result.stackTrace = getStackTrace() result.id = currentID result.location[LocCreateIndex] = loc currentID.inc() ## ZAH: As far as I undestand `fromProc` is just a debugging helper. ## It would be more efficient if it's represented as a simple statically ## known `char *` in the final program (so it needs to be a `cstring` in Nim). ## The public API can be defined as a template expecting a `static[string]` ## and converting this immediately to a `cstring`. proc newFuture[T](loc: ptr SrcLoc): Future[T] = setupFutureBase(loc) proc newFutureSeq[A, B](loc: ptr SrcLoc): FutureSeq[A, B] = setupFutureBase(loc) proc newFutureStr[T](loc: ptr SrcLoc): FutureStr[T] = setupFutureBase(loc) proc newFutureVar[T](loc: ptr SrcLoc): FutureVar[T] = FutureVar[T](newFuture[T](loc)) template newFuture*[T](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. newFuture[T](getSrcLocation(fromProc)) template newFutureSeq*[A, B](fromProc: static[string] = ""): auto = ## 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. newFutureSeq[A, B](getSrcLocation(fromProc)) template newFutureStr*[T](fromProc: static[string] = ""): auto = ## 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. newFutureStr[T](getSrcLocation(fromProc)) template newFutureVar*[T](fromProc: static[string] = ""): auto = ## 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. newFutureVar[T](getSrcLocation(fromProc)) proc clean*[T](future: FutureVar[T]) = ## Resets the ``finished`` status of ``future``. Future[T](future).state = FutureState.Pending Future[T](future).error = nil proc finished*(future: FutureBase | FutureVar): bool {.inline.} = ## Determines whether ``future`` has completed. ## ## ``True`` may indicate an error or a value. Use ``failed`` to distinguish. when future is FutureVar: result = (FutureBase(future).state != FutureState.Pending) else: result = (future.state != FutureState.Pending) proc cancelled*(future: FutureBase): bool {.inline.} = ## Determines whether ``future`` has cancelled. result = (future.state == FutureState.Cancelled) proc failed*(future: FutureBase): bool {.inline.} = ## Determines whether ``future`` completed with an error. result = (future.state == FutureState.Failed) proc checkFinished[T](future: Future[T], loc: ptr SrcLoc) = ## Checks whether `future` is finished. If it is then raises a ## ``FutureDefect``. if future.finished(): var msg = "" msg.add("An attempt was made to complete a Future more than once. ") msg.add("Details:") msg.add("\n Future ID: " & $future.id) msg.add("\n Creation location:") msg.add("\n " & $future.location[LocCreateIndex]) msg.add("\n First completion location:") msg.add("\n " & $future.location[LocCompleteIndex]) msg.add("\n Second completion location:") msg.add("\n " & $loc) msg.add("\n Stack trace to moment of creation:") msg.add("\n" & indent(future.stackTrace.strip(), 4)) when T is string: msg.add("\n Contents (string): ") msg.add("\n" & indent(future.value.repr, 4)) msg.add("\n Stack trace to moment of secondary completion:") msg.add("\n" & indent(getStackTrace().strip(), 4)) msg.add("\n\n") var err = newException(FutureDefect, msg) err.cause = future raise err else: future.location[LocCompleteIndex] = loc proc call(callbacks: var Deque[AsyncCallback]) = var count = len(callbacks) while count > 0: var item = callbacks.popFirst() if not(item.deleted): callSoon(item.function, item.udata) dec(count) proc add(callbacks: var Deque[AsyncCallback], item: AsyncCallback) = if len(callbacks) == 0: callbacks = initDeque[AsyncCallback]() callbacks.addLast(item) proc remove(callbacks: var Deque[AsyncCallback], item: AsyncCallback) = for p in callbacks.mitems(): if p.function == item.function and p.udata == item.udata: p.deleted = true proc complete[T](future: Future[T], val: T, loc: ptr SrcLoc) = if not(future.cancelled()): checkFinished(future, loc) doAssert(isNil(future.error)) future.value = val future.state = FutureState.Finished future.callbacks.call() template complete*[T](future: Future[T], val: T) = ## Completes ``future`` with value ``val``. complete(future, val, getSrcLocation()) proc complete(future: Future[void], loc: ptr SrcLoc) = if not(future.cancelled()): checkFinished(future, loc) doAssert(isNil(future.error)) future.state = FutureState.Finished future.callbacks.call() template complete*(future: Future[void]) = ## Completes a void ``future``. complete(future, getSrcLocation()) proc complete[T](future: FutureVar[T], loc: ptr SrcLoc) = if not(future.cancelled()): template fut: untyped = Future[T](future) checkFinished(fut, loc) doAssert(isNil(fut.error)) fut.state = FutureState.Finished fut.callbacks.call() template complete*[T](futvar: FutureVar[T]) = ## Completes a ``FutureVar``. complete(futvar, getSrcLocation()) proc complete[T](futvar: FutureVar[T], val: T, loc: ptr SrcLoc) = if not(futvar.cancelled()): template fut: untyped = Future[T](futvar) checkFinished(fut, loc) doAssert(isNil(fut.error)) fut.state = FutureState.Finished fut.value = val fut.callbacks.call() template complete*[T](futvar: FutureVar[T], val: T) = ## Completes a ``FutureVar`` with value ``val``. ## ## Any previously stored value will be overwritten. complete(futvar, val, getSrcLocation()) proc fail[T](future: Future[T], error: ref Exception, loc: ptr SrcLoc) = if not(future.cancelled()): checkFinished(future, loc) future.state = FutureState.Failed future.error = error future.errorStackTrace = if getStackTrace(error) == "": getStackTrace() else: getStackTrace(error) future.callbacks.call() template fail*[T](future: Future[T], error: ref Exception) = ## Completes ``future`` with ``error``. fail(future, error, getSrcLocation()) proc cancel[T](future: Future[T], loc: ptr SrcLoc) = if future.finished(): checkFinished(future, loc) else: var first = FutureBase(future) var last = first while not(isNil(last.child)) and not(last.child.cancelled()): last = last.child if last == first: checkFinished(future, loc) let isPending = (last.state == FutureState.Pending) last.state = FutureState.Cancelled last.error = newException(CancelledError, "") if not(isNil(last.cancelcb)): last.cancelcb(cast[pointer](last)) if isPending: # If Future's state was `Finished` or `Failed` callbacks are already # scheduled. last.callbacks.call() template cancel*[T](future: Future[T]) = ## Cancel ``future``. cancel(future, getSrcLocation()) proc clearCallbacks(future: FutureBase) = var count = len(future.callbacks) while count > 0: discard future.callbacks.popFirst() dec(count) proc addCallback*(future: FutureBase, cb: CallbackFunc, udata: pointer = nil) = ## Adds the callbacks proc to be called when the future completes. ## ## If future has already completed then ``cb`` will be called immediately. doAssert(not isNil(cb)) if future.finished(): callSoon(cb, udata) else: let acb = AsyncCallback(function: cb, udata: udata) future.callbacks.add acb proc addCallback*[T](future: Future[T], cb: CallbackFunc) = ## Adds the callbacks proc to be called when the future completes. ## ## If future has already completed then ``cb`` will be called immediately. future.addCallback(cb, cast[pointer](future)) proc removeCallback*(future: FutureBase, cb: CallbackFunc, udata: pointer = nil) = doAssert(not isNil(cb)) let acb = AsyncCallback(function: cb, udata: udata) future.callbacks.remove acb proc removeCallback*[T](future: Future[T], cb: CallbackFunc) = future.removeCallback(cb, cast[pointer](future)) proc `callback=`*(future: FutureBase, cb: CallbackFunc, udata: pointer = nil) = ## 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. # ZAH: how about `setLen(1); callbacks[0] = cb` future.clearCallbacks future.addCallback(cb, udata) proc `callback=`*[T](future: Future[T], cb: CallbackFunc) = ## Sets the callback proc to be called when the future completes. ## ## If future has already completed then ``cb`` will be called immediately. `callback=`(future, cb, cast[pointer](future)) proc `cancelCallback=`*[T](future: Future[T], cb: CallbackFunc) = ## Sets the callback procedure to be called when the future is cancelled. ## ## This callback will be called immediately as ``future.cancel()`` invoked. future.cancelcb = cb proc getHint(entry: StackTraceEntry): string = ## We try to provide some hints about stack trace entries that the user ## may not be familiar with, in particular calls inside the stdlib. result = "" if entry.procname == "processPendingCallbacks": if cmpIgnoreStyle(entry.filename, "asyncdispatch.nim") == 0: return "Executes pending callbacks" elif entry.procname == "poll": if cmpIgnoreStyle(entry.filename, "asyncdispatch.nim") == 0: return "Processes asynchronous completion events" if entry.procname.endsWith("_continue"): if cmpIgnoreStyle(entry.filename, "asyncmacro.nim") == 0: return "Resumes an async procedure" proc `$`*(entries: seq[StackTraceEntry]): string = result = "" # Find longest filename & line number combo for alignment purposes. var longestLeft = 0 for entry in entries: if isNil(entry.procName): continue let left = $entry.filename & $entry.line if left.len > longestLeft: longestLeft = left.len var indent = 2 # Format the entries. for entry in entries: if isNil(entry.procName): if entry.line == -10: result.add(spaces(indent) & "#[\n") indent.inc(2) else: indent.dec(2) result.add(spaces(indent) & "]#\n") continue let left = "$#($#)" % [$entry.filename, $entry.line] result.add((spaces(indent) & "$#$# $#\n") % [ left, spaces(longestLeft - left.len + 2), $entry.procName ]) let hint = getHint(entry) if hint.len > 0: result.add(spaces(indent+2) & "## " & hint & "\n") proc injectStacktrace(future: FutureBase) = const header = "\nAsync traceback:\n" var exceptionMsg = future.error.msg if header in exceptionMsg: # This is messy: extract the original exception message from the msg # containing the async traceback. let start = exceptionMsg.find(header) exceptionMsg = exceptionMsg[0..