Coresume

coresume( cor, [...] )

Starts a coroutine, or resumes a suspended coroutine.

cor

The coroutine, as created by cocreate().

...

The arguments to pass to the coroutine's function or the coroutine's subsequent yields.

return-values

A boolean indicating whether or not the coroutine is alive.
If the coroutine finished or yielded, there is an undocumented second value - the value returned or yielded.
If the coroutine failed, there may be a second value with an exception string.

A coroutine is a special kind of function that can yield control back to the caller without completely exiting. The caller can then resume the coroutine as many times as needed until the function exits.

The coresume() function starts or resumes a coroutine created by cocreate(). Control returns to the coroutine function until the function yields or exits.

coresume() returns true if the given coroutine was active (suspended) when coresume() was called, or false if it was given a dead coroutine (and no code was executed by resuming). If a resumed coroutine function exits (rather than yields), the coroutine goes from suspended to dead, and a subsequent call to coresume() with the same coroutine will return false. It is more typical to use the costatus() function to test the status of a coroutine, but the return value from coresume() may be used instead.

In the event that coresume() returns false, it may also return a second value containing a string describing an exception that caused the routine to die unexpectedly, e.g. "attempt to index a nil value". A full stack trace can also be obtained by passing the dead coroutine to trace(). In fact, the code below is a very simple way to stop() with full stack trace when a coroutine dies unexpectedly:

local active, exception = coresume(co)
if exception then
  stop(trace(co, exception))
end

As of PICO-8 0.2.4b, when coresume() returns true, it also returns a second value from the coroutine function - the value passed to yield() if the coroutine yielded, or the value passed to return otherwise. However, this doesn't appear to be documented right now, so there may be some danger in relying on this. Note also that if multiple values are yielded or returned, only the first of those values will be returned from coresume()

coresume() may pass extra arguments to the coroutine. These arguments will be mapped to the coroutine's function arguments on the first call, and will be used as return values for yield() on subsequent calls.

Examples

function foo(a, b, c)
  print(a)
  print(b)
  print(c)
  a, _, c = yield()
  print(a)
  print(b)
  print(c)
end

local thread = cocreate(foo)
coresume(thread, 1, 2, 3) --> prints: 1 2 3
coresume(thread, 4, 5, 6) --> prints: 4 5 6

See cocreate() for a general example.

See also

• cocreate()
• costatus()
• yield()