Class Coroutine

A Coroutine is similar to a Function, except that it can also yield values at different points along its lifetime. Every Coroutine has a callstack that belongs to it, as well as an exception state. A Coroutine's status can be discovered by one of the is_ methods.

The Coroutine type takes two types. The first is the type that the Coroutine will be returning or yielding. The second is the type that the Coroutine takes as a message. A Coroutine can take empty Unit messages for simplicity, or a more interesting type if a more bidirectional kind of messaging is wanted. A Coroutine can get the value resumed using Coroutine.receive while within the Coroutine.

The first argument of a Function to be made a Coroutine is always the Coroutine itself. If the Function specifies extra arguments, those arguments are to be passed to the intermediate result of Coroutine.create.

public static define build(fn: Function(Coroutine[A, B])): Coroutine[A, B]

Build a new Coroutine that wraps over the Function provided.

public static define build_with_value(fn: Function(Coroutine[A, B], C), value: C): Coroutine[A, B]

Build a new Coroutine that wraps over the Function provided. The base Function has the second argument set to 'value' exactly once before any resumption takes place. This method is provided so that a Coroutine can take an extra value (perhaps a Tuple) without needing to be a closure.

public define is_done: Boolean

Returns true if the Coroutine has returned a value instead of yielding, false otherwise.

public define is_failed: Boolean

Returns true if the Coroutine raised an exception, false otherwise.

public define is_running: Boolean

Returns true if the Coroutine is running, false otherwise. Note that this does not mean that the Coroutine is the one currently running, only that it is running.

public define is_waiting: Boolean

Returns true if the Coroutine is ready to be resumed, false otherwise.

public define receive: B

This function returns the value that the Coroutine is holding, so long as the Coroutine is the one currently running.

The value stored by the Coroutine is initially the first argument sent to the intermediate builder. Following that, it is the last value that was sent to the Coroutine using Coroutine.resume_with.

public static define resume(self: Coroutine[A, Unit]): Option[A]

Attempt to resume the Coroutine provided. A Coroutine can be resumed only if it is currently in the 'waiting' state.

This function does not send a value to the Coroutine which is why it requires the second parameter to be Unit.

If the Coroutine is suspended and yields a value, the result is a Some of that value.

Otherwise, this returns None.

Note that if a Coroutine returns a value instead of yielding, the value is ignored and the result is None.

public define resume_with(value: B): Option[A]

Attempt to resume the Coroutine provided. A Coroutine can be resumed only if it is currently in the 'waiting' state.

This function includes a value for the Coroutine to store. The value is stored only if the Coroutine is resumed. If stored, the old value is ejected from the Coroutine provided.

If the Coroutine is suspended and yields (or returns) a value, the result is a Some of that value.

Otherwise, this returns None.

public define yield(value: A)

Yield 'value' from the Coroutine given. Control returns to whatever invoked 'self'.