introduce coroutines to the language

tests/lang/s02_core/s99_coroutines/t01_coroutine_definition.nim

@@ -0,0 +1,11 @@
+discard """
+"""
+
+## Normal `proc`s and `func`s become coroutines by applying the `.coroutine`
+## pragma to their definition.
+
+proc coro1() {.coroutine.} =
+  discard
+
+func coro2() {.coroutine.} =
+  discard

tests/lang/s02_core/s99_coroutines/t02_signature_restrictions_1.nim

@@ -0,0 +1,13 @@
+discard """
+"""
+
+## Except for `openArray` and `var` types, there are no restrictions on the
+## number or type of the parameters, compared to non-coroutine procedures.
+
+proc a(x: int, y: seq[float], z: string) {.coroutine.} =
+  discard
+
+## Coroutines cannot return views, but there are no other restrictions.
+
+proc b(): float {.coroutine.} =
+  discard

tests/lang/s02_core/s99_coroutines/t02_signature_restrictions_2.nim

@@ -0,0 +1,12 @@
+discard """
+  matrix: "--errorMax:2"
+  action: reject
+"""
+
+proc a(x: openArray[int]) {.coroutine.} = #[tt.Error
+          ^ invalid type: 'openArray[int]']#
+  discard
+
+proc b(x: var int) {.coroutine.} = #[tt.Error
+          ^ invalid type: 'var int']#
+  discard

tests/lang/s02_core/s99_coroutines/t03_converter_cannot_be_coroutine.nim

@@ -0,0 +1,10 @@
+discard """
+  description: "Converters cannot be coroutines"
+  action: reject
+"""
+
+# XXX: maybe to restrictive, there's nothing preventing converters from being
+#      coroutines, even though there's likely little use of them being one
+
+converter conv(x: int): float {.coroutine.} =
+  discard

tests/lang/s02_core/s99_coroutines/t03_macro_cannot_be_coroutine.nim

@@ -0,0 +1,9 @@
+discard """
+  description: "Macros cannot be coroutines"
+  action: reject
+"""
+
+# XXX: perhaps too restrictive; it's not impossible to implement
+
+macro m() {.coroutine.} =
+  discard

tests/lang/s02_core/s99_coroutines/t03_method_cannot_be_coroutine.nim

@@ -0,0 +1,11 @@
+discard """
+  description: "Methods cannot be coroutines"
+  action: reject
+"""
+
+type
+  Base = object of RootObj
+  Sub = object of RootObj
+
+method m(x: ref Object) {.coroutine.} =
+  discard

tests/lang/s02_core/s99_coroutines/t04_launch_coroutine.nim

@@ -0,0 +1,27 @@
+
+## To launch a coroutine, the built-in ``launch`` routine is used. As its
+## single parameter, it expects the invocation of a coroutine.
+##
+## What happens is, in the following order:
+## 1. a managed heap cell of the coroutine's internal environment type is
+##    allocated
+## 2. the provided arguments are captured in the internal environment, either
+##    by copying or moving, depending on the parameter
+## 3. the status of the couroutine instance is set to the "suspended" state
+##
+## The instantiated coroutine is returned as the built-in ``Coroutine[T]``
+## type (where `T` is the return type of the coroutine), which is a
+## polymorphic ``ref`` type. A coroutine's internal environment type is always
+## derived from the ``Coroutine[T]`` type.
+##
+## The body of the coroutine is not executed yet.
+
+proc coro(x: int) {.coroutine.} =
+  discard
+
+# every routine invocation syntax is valid for ``launch``
+let instance = launch coro(1)
+doAssert instance is Coroutine[void]
+doAssert instance.state == csSuspended
+
+## It is legal to do nothing with an instantiated coroutine.

tests/lang/s02_core/s99_coroutines/t05_resume_coroutine.nim

@@ -0,0 +1,22 @@
+discard """
+  output: "here"
+"""
+
+## To resume a coroutine instance (that is, run it until the next suspension
+## point is reached), the built-in nullary ``resume`` routine is used. The
+## ``resume`` procedure returns a coroutine instance, which, by default, is
+## the same one that was resumed. Only an instance that is in the "suspended"
+## state can be resumed.
+##
+## Before passing control to the coroutine, ``resume`` sets the instance's
+## status to "running"
+
+proc coro() {.coroutine.}
+  echo "here"
+
+let instance = launch coro()
+discard resume(instance) # the echo will be executed
+
+## When a suspension point is reached, ``resume`` returns. If there's no more
+## code to run within the coroutine, prior to returning from ``resume``, the
+## state is set to "pending", otherwise it's set to "suspendend".

tests/lang/s02_core/s99_coroutines/t06_cancel_coroutine.nim

@@ -0,0 +1,28 @@
+
+## A coroutine can be cancelled, by raising an exception and letting it
+## propagate to the edge of the coroutine. Upon cancellation, the
+## ``resume`` call that started execution changes the state of the instance
+## to "aborted" and returns the instance.
+
+proc coro(cancel: bool) {.coroutine.}
+  if cancel:
+    raise CatchableError.newException("cancel")
+
+let instance = launch coro(true)
+doAssert instance.status == csSuspended
+
+resume(instance)
+doAssert instance.status == csAborted
+
+## If a coroutine instance is cancelled, the exception that caused
+## cancellation is stored in the coroutine instance object. It can be
+## extracted by using the built-in ``unwrap``.
+
+# XXX: unwrap needs a better name
+
+let error = unwrap(instance)
+doAssert error of CatchableError
+doAssert error.msg == "fail"
+
+## The call to ``unwrap`` moves the instance into the "finished" state.
+doAssert instance.status == csFinished

tests/lang/s02_core/s99_coroutines/t07_finish_coroutine.nim

@@ -0,0 +1,37 @@
+## Much like normal procedures, a coroutine can yield a result. The `result`
+## variable is stored as part of the coroutine instance object. To extract,
+## the result value, the built-in ``finish`` procedure needs to be called
+## on a "pending" instance. An instance enters the "pending" state when
+## the end of the coroutine's body is reached.
+
+proc coro(): int {.coroutine.} =
+  result = 1
+
+let instance = launch coro()
+resume(instance) # run to completion
+doAssert instance.status == csPending
+
+doAssert finish(instance) == 1
+
+## A successful call to ``finish`` moves the instance into the "finished"
+## state.
+doAssert instance.status == csFinished
+
+## An instance also enters the "pending" state when the coroutine exits due to
+## a ``return`` being executed.
+
+proc coro2(early: bool): int {.coroutine.} =
+  if early:
+    return 2
+  return 1
+
+var instance2 = launch coro2(true)
+
+resume(instance2)
+doAssert instance2.status == csPending
+
+doAssert finish(instance2) == 2
+doAssert instance2.status == csFinished
+
+## "finished" is the terminal state. There's no other state that the instance
+## can change to from it.

tests/lang/s02_core/s99_coroutines/t08_finish_with_void.nim

@@ -0,0 +1,15 @@
+
+## If a coroutine has no result (i.e., the return type is ``void``), then
+## ``finish`` returns nothing and only changes the status from "pending" to
+## "finished".
+
+proc coro() {.coroutine.} =
+  discard
+
+var instance = launch coro()
+
+resume(instance)
+doAssert instance.status == csPending
+
+finish(instance)
+doAssert instance.status == csFinished

tests/lang/s02_core/s99_coroutines/t09_finish_does_move.nim

@@ -0,0 +1,18 @@
+
+## Calling ``finish`` moves the result value out of the instance.
+
+type Object = object
+  value: int
+
+# copying is disallowed
+proc `=copy`(x: var Object, y: Object) {.error.}
+
+proc coro(): Object {.coroutine.} =
+  result = Object(value: 1)
+
+var instance = launch coro()
+resume(instance)
+
+# the value is moved out of the instance, no copy is made
+let o = finish(instance)
+doAssert o.value == 1

tests/lang/s02_core/s99_coroutines/t10_self_parameter.nim

@@ -0,0 +1,17 @@
+discard """
+  output: "Coroutine[void]\ncsRunning"
+"""
+
+## To access the active *instance* within the body of a coroutine, the hidden
+## ``self`` parameter is made available.
+
+# XXX: not a good solution, either the ``self`` parameter should be explicit
+#      (somehow), or there should be a magic procedure
+
+proc coro() {.coroutine.} =
+  # the self parameter is of type ``Coroutine[void]``
+  echo typeof(self)
+  echo self.status
+
+var instance = launch coro()
+resume(instance)

tests/lang/s02_core/s99_coroutines/t11_suspend_coroutine.nim

@@ -0,0 +1,48 @@
+discard """
+  output: '''
+outside: 1
+coro: 1
+outside: 2
+coro: 2
+outside: 3
+coro: 3'''
+"""
+
+## A coroutine can be suspended without returning or raising an exception.
+## This is achieved by calling the built-in ``suspend`` routine, which expects
+## a ``CoroutineBase`` as the parameter -- the instance passed to ``suspend``
+## is what ``resume`` will return.
+
+# IDEA: instead of the ``suspend`` routine, the ``yield`` keyword could be
+#       re-used, which could be much more convenient to use. It'd also be
+#       a bit easier to implement
+
+proc coro() {.coroutine.} =
+  echo "coro: 1"
+  suspend(self)
+  echo "coro: 2"
+  suspend(self)
+  echo "coro: 3"
+
+var instance = launch coro()
+let original = instance
+
+echo "outside: 1"
+instance = resume(instance)
+
+## After suspending, the coroutine is the "suspended" state.
+doAssert instance.status == csSuspended
+
+echo "outside: 2"
+instance = resume(instance)
+echo "outside: 3"
+instance = resume(instance)
+
+doAssert instance.status == csPending
+doAssert instance == original
+
+## The run-time type of the instance needs to be a sub-type of the coroutine
+## instance type that is suspended from, if it isn't, a ``SuspendDefect`` is
+## raised.
+
+# TODO: a test is missing

tests/lang/s02_core/s99_coroutines/t12_suspend_with_nil.nim

@@ -0,0 +1,17 @@
+## It is valid to pass `nil` to a ``suspend`` call, in which case ``resume``
+## will return `nil`.
+
+proc coro() {.coroutine.} =
+  suspend(nil)
+
+var instance = launch coro()
+# hold on to the instance:
+var original = instance
+
+doAssert resume(instance) == nil
+doAssert original.status == csSuspended
+
+# resume the instance. On reaching the body's end, the instance itself is
+# returned
+doAssert resume(original) == original
+doAssert original.status == csPending

tests/lang/s02_core/s99_coroutines/t13_custom_suspend.nim

@@ -0,0 +1,19 @@
+discard """
+  output: "custom"
+"""
+
+## The ``suspend`` built-in procedure is not special-cased with regards to
+## lookup. It can be overloaded like any other routine.
+
+template suspend(c: Coroutine) =
+  echo "custom"
+  system.suspend(c)
+
+# XXX: this could be a problem. A module could export a routine such as the
+#      above and thus override all suspend calls in the importing module!
+
+proc coro() {.coroutine.} =
+  suspend(self)
+
+var instance = launch coro()
+resume(instance)

tests/lang/s02_core/s99_coroutines/t14_illegal_operation.nim

@@ -0,0 +1,24 @@
+
+## What operations are valid on a coroutine instance depends on its state.
+## If performing an operation on a coroutine while in a state where the
+## operation is not applicable, a ``CoroutineError`` is raised. The coroutine
+## instance is not modified in this case.
+
+# XXX: a catchable error could be annoying in `.raises: []` routines where
+#      it's guaranteed that the operation is valid. Perhaps it should
+#      be a defect?
+
+proc coro() {.coroutine.} =
+  discard
+
+let instance = launch coro(false)
+doAssert instance.status == csSuspended
+
+var wasError = false
+# unwrap only legal when instance was aborted
+try:
+  unwrap(instance)
+except CoroutineError as e:
+  wasError = true
+
+doAssert wasError

tests/lang/s02_core/s99_coroutines/t15_custom_coroutine_type.nim

@@ -0,0 +1,22 @@
+discard """
+  output: "0"
+"""
+
+## The ``.coroutine`` pragma can be supplied with a type, which the internal
+## coroutine environment object then derives from. The type must be a non-
+## final ``ref`` sub-type of ``Coroutine[T]``, where `T` is the return type
+## of the coroutine.
+
+# TODO: a negative test is missing
+
+type Custom = ref object of Coroutine[void]
+  value: int
+
+proc coro() {.coroutine: Custom.} =
+  # the hidden `self` parameter is also of type ``Custom``
+  echo self.value
+
+## The instance returned by ``launch`` is of the provided coroutine type.
+var instance = launch coro()
+doAssert typeof(instance) is Custom
+doAssert instance.value == 0

tests/lang/s02_core/s99_coroutines/t16_generic_coroutine.nim

@@ -0,0 +1,12 @@
+discard """
+  output: "1"
+"""
+
+## A coroutine can be a generic routine.
+
+proc coro[T](x: T) {.coroutine.} =
+  echo x
+
+var instance = launch coro(1)
+doAssert instance is Coroutine[int]
+resume(instance)