suspend

Global, available without an import

suspend(...): any

Pauses the running thread and hands its arguments to whoever resumes it.

examples/globals/suspend-basic.nut

let worker = newthread(function() {
  let reply = suspend("waiting")
  println("worker got", reply)
})

println("worker.call() =", worker.call())   // runs until suspend(), returns "waiting"
worker.wakeup("go")                          // resumes; suspend() returns "go" inside the thread

Output:

worker.call() = waiting
worker got go

Parameters

... any values passed to the caller of thread.call or thread.wakeup repeats

Return value

The arguments given to the thread.wakeup call that resumes this thread.

Errors

Throws cannot suspend through native calls/metamethods when a native function is on the stack between the thread's entry point and this call - for example inside an each or sort callback, or a metamethod.

Notes

Only meaningful on a thread created with newthread, while that thread is running after a thread.call or thread.wakeup: the value passed to suspend becomes that call's return value, and the thread stays paused until thread.wakeup is called on it, at which point suspend returns wakeup's own arguments.

Calling suspend directly in the main script, outside any such thread, throws cannot suspend the root vm, which a try/catch can handle like any other error.

Example

examples/globals/suspend.nut

let co = newthread(function() {
  let first = suspend("ready")         // pauses; "ready" becomes call()'s return value
  let second = suspend($"got {first}") // resumed with wakeup's argument as "first"
  println("finished with", second)
})

println("co.call() =", co.call())      // runs to the first suspend()
println("co.wakeup(\"a\") =", co.wakeup("a")) // suspend() returns "a"; runs to the second suspend()
co.wakeup("b")           // suspend() returns "b"; thread runs to completion