types.Thread.wakeupthrow

Method on every thread

thread.wakeupthrow(value, [rethrow: bool], ...): any

Resumes a suspended thread by throwing value at its suspend call, instead of returning from it normally.

The binding carries no declaration string, so the VM cannot report parameter names. The names above are from this page; the types and attributes still come from the VM. The VM also cannot tell an optional parameter from a variadic tail here, so read the brackets and any trailing ... from the prose below, not from the signature.

Parameters

`value`	any	thrown inside the thread, at the point it is suspended
`rethrow`	bool	when the thread does not catch `value` and dies from it, whether to re-throw that same error out of this call; defaults to `true` optional
`...`	any	repeats

Return value

Whatever the thread passes to its next suspend, or returns, if it catches value and keeps running. null if the thread dies from value and rethrow is false.

Errors

value is required: calling with no arguments throws wrong number of parameters passed to native closure 'wakeupthrow' (1 passed, at least 2 required) before the thread is touched.

Throws cannot wakeup a idle thread or cannot wakeup a running thread for the same reasons wakeup does - only a "suspended" thread can be resumed this way.

When the thread does not catch value and dies from it, this call re-throws the same error, unless rethrow is false.

Notes

The signature shows rethrow as optional and ends in ..., but nothing past rethrow is ever read - a third argument is accepted and silently ignored, the same way extra arguments are for wakeup.

rethrow only controls whether this call reports the error to its own caller; it cannot silence an uncaught value. A thread runs on its own stack with its own exception traps, so a try/catch around the call to wakeupthrow never sees value unless the thread's own body lets it escape - and if it does escape, the host's runtime error reporter (if one is installed, as the command-line tool does) reports it straight from there, dumping that thread's own callstack and source path to the error stream, regardless of rethrow. Only a try/catch inside the thread's own body can prevent that report. Either way the thread goes back to "idle" and can be started again with call.

Example

examples/types/thread/wakeupthrow.nut

function body() {
    try { suspend() } catch(e) { println("caught", e) }
    return "recovered"
}
let t = newthread(body)
t.call()
println("t.wakeupthrow(\"boom\") =", t.wakeupthrow("boom"))          // caught inside; rethrow default is moot
println("t.getstatus() =", t.getstatus())

let t2 = newthread(body)
t2.call()
println("t2.wakeupthrow(\"boom\", false) =", t2.wakeupthrow("boom", false))  // caught inside too; rethrow only matters when uncaught

Output:

caught boom
t.wakeupthrow("boom") = recovered
t.getstatus() = idle
caught boom
t2.wakeupthrow("boom", false) = recovered