async raises of

README.md

@@ -151,9 +151,9 @@ feet, in a certain section, is to not use `await` in it.
 
 ### Error handling
 
-Exceptions inheriting from `CatchableError` are caught by hidden `try` blocks
-and placed in the `Future.error` field, changing the future's status to
-`Failed`.
+Exceptions inheriting from `Exception` (or `CatchableError` when
+`-d:chronosStrictException` is enabled) are caught by hidden `try` blocks
+and placed in the `Future.error` field, changing the future status to `Failed`.
 
 When a future is awaited, that exception is re-raised, only to be caught again
 by a hidden `try` block in the calling async procedure. That's how these
@@ -211,6 +211,42 @@ originating from tasks on the dispatcher queue. It is however possible that
 `Defect` that happen in tasks bubble up through `poll` as these are not caught
 by the transformation.
 
+#### Checked exceptions
+
+By specifying a `asyncraises` list to an async procedure, you can check which
+exceptions can be thrown by it.
+```nim
+proc p1(): Future[void] {.async, asyncraises: [IOError].} =
+  assert not (compiles do: raise newException(ValueError, "uh-uh"))
+  raise newException(IOError, "works") # Or any child of IOError
+```
+
+Under the hood, the return type of `p1` will be rewritten to another type,
+which will convey raises informations to await.
+
+```nim
+proc p2(): Future[void] {.async, asyncraises: [IOError].} =
+  await p1() # Works, because await knows that p1
+             # can only raise IOError
+```
+
+The hidden type (`RaiseTrackingFuture`) is implicitely convertible into a Future.
+However, it may causes issues when creating callback or methods
+```nim
+proc p3(): Future[void] {.async, asyncraises: [IOError].} =
+  let fut: Future[void] = p1() # works
+  assert not compiles(await fut) # await lost informations about raises,
+                                 # so it can raise anything
+
+  # Callbacks
+  assert not(compiles do: let cb1: proc(): Future[void] = p1) # doesn't work
+  let cb2: proc(): Future[void] {.async, asyncraises: [IOError].} = p1 # works
+  assert not(compiles do:
+    type c = proc(): Future[void] {.async, asyncraises: [IOError, ValueError].}
+    let cb3: c = p1 # doesn't work, the raises must match _exactly_
+  )
+```
+
 ### Platform independence
 
 Several functions in `chronos` are backed by the operating system, such as

chronos/asyncfutures2.nim

@@ -11,6 +11,7 @@
 import std/[os, tables, strutils, heapqueue, options, deques, sequtils]
 import stew/base10
 import ./srcloc
+import macros
 export srcloc
 
 when defined(nimHasStacktracesModule):
@@ -60,6 +61,12 @@ type
       closure*: iterator(f: Future[T]): FutureBase {.raises: [Defect, CatchableError, Exception], gcsafe.}
     value: T ## Stored value
 
+  RaiseTrackingFuture*[T, E] = ref object of Future[T]
+    ## Future with a tuple of possible exception types
+    ## eg RaiseTrackingFuture[void, (ValueError, OSError)]
+    ## Will be injected by `asyncraises`, should generally
+    ## not be used manually
+
   FutureStr*[T] = ref object of Future[T]
     ## Future to hold GC strings
     gcholder*: string
@@ -109,6 +116,9 @@ template setupFutureBase(loc: ptr SrcLoc) =
 proc newFutureImpl[T](loc: ptr SrcLoc): Future[T] =
   setupFutureBase(loc)
 
+proc newRaiseTrackingFutureImpl[T, E](loc: ptr SrcLoc): RaiseTrackingFuture[T, E] =
+  setupFutureBase(loc)
+
 proc newFutureSeqImpl[A, B](loc: ptr SrcLoc): FutureSeq[A, B] =
   setupFutureBase(loc)
 
@@ -122,6 +132,19 @@ template newFuture*[T](fromProc: static[string] = ""): Future[T] =
   ## that this future belongs to, is a good habit as it helps with debugging.
   newFutureImpl[T](getSrcLocation(fromProc))
 
+macro getFutureExceptions(T: typedesc): untyped =
+  if getTypeInst(T)[1].len > 2:
+    getTypeInst(T)[1][2]
+  else:
+    ident"void"
+
+template newRaiseTrackingFuture*[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.
+  newRaiseTrackingFutureImpl[T, getFutureExceptions(typeof(result))](getSrcLocation(fromProc))
+
 template newFutureSeq*[A, B](fromProc: static[string] = ""): FutureSeq[A, B] =
   ## Create a new future which can hold/preserve GC sequence until future will
   ## not be completed.
@@ -251,6 +274,65 @@ template fail*[T](future: Future[T], error: ref CatchableError) =
   ## Completes ``future`` with ``error``.
   fail(future, error, getSrcLocation())
 
+macro checkFailureType(future, error: typed): untyped =
+  let e = getTypeInst(future)[2]
+  let types = getType(e)
+
+  if types.eqIdent("void"):
+    error("Can't raise exceptions on this Future")
+
+  expectKind(types, nnkBracketExpr)
+  expectKind(types[0], nnkSym)
+  assert types[0].strVal == "tuple"
+  assert types.len > 1
+
+  let toMatch =
+    if getTypeInst(error).kind == nnkRefTy:
+      getTypeInst(error)[0]
+    elif getTypeInst(error).kind == nnkBracketExpr:
+      getTypeInst(error)[1]
+    else:
+      error("Unhandled error type " & $getTypeInst(error).kind)
+      nil
+
+  # Can't find a way to check `is` in the macro. (sameType doesn't
+  # work for inherited objects). Dirty hack here, for [IOError, OSError],
+  # this will generate:
+  #
+  # static:
+  #   if not((`toMatch` is IOError) or (`toMatch` is OSError)
+  #     or (`toMatch` is CancelledError) or false):
+  #     raiseAssert("Can't fail with `toMatch`, only [IOError, OSError] is allowed")
+  var typeChecker = ident"false"
+
+  for errorType in types[1..^1]:
+    typeChecker = newCall("or", typeChecker, newCall("is", toMatch, errorType))
+  typeChecker = newCall(
+    "or", typeChecker,
+    newCall("is", toMatch, ident"CancelledError"))
+
+  let errorMsg = "Can't fail with " & repr(toMatch) & ". Only " & repr(types[1..^1]) & " allowed"
+
+  result = nnkStaticStmt.newNimNode(lineInfoFrom=error).add(
+    quote do:
+      if not(`typeChecker`):
+        raiseAssert(`errorMsg`)
+  )
+
+template fail*[T, E](future: RaiseTrackingFuture[T, E], error: ref CatchableError) =
+  checkFailureType(future, error)
+  fail(future, error, getSrcLocation())
+
+macro checkMultipleFailureType(future, errors: typed): untyped =
+  result = nnkStmtList.newTree()
+  for error in getTypeInst(errors):
+    let err2 = ident(error.strVal)
+    result.add(quote do: checkFailureType(`future`, `err2`))
+
+template fail*[T1, E1, T2, E2](future: RaiseTrackingFuture[T1, E1], failedFuture: RaiseTrackingFuture[T2, E2]) =
+  checkMultipleFailureType(future, E2)
+  fail(Future[T1](future), failedFuture.error, getSrcLocation())
+
 template newCancelledError(): ref CancelledError =
   (ref CancelledError)(msg: "Future operation cancelled!")