Documentation
¶
Overview ¶
Package eventloop runs a moejs Runtime on an event loop: the Node.js timers (setTimeout, setInterval, setImmediate and their clear functions) and host work whose result comes back from another goroutine.
A bare Runtime has no timers, and the settle functions of Runtime.NewPromise may only be called from the goroutine that uses the runtime. A Loop owns its runtime while it runs, and is the one goroutine that uses it then:
rt := moejs.NewRuntime(moejs.Options{})
loop, err := eventloop.New(rt, eventloop.Options{})
err = loop.Run(func(rt *moejs.Runtime) error {
_, err := rt.RunScript(script) // may call setTimeout
return err
})
Run returns once nothing keeps the loop alive: no timer or immediate that is ref'd, no Hold not yet done, no promise of NewPromise not yet settled and no task not yet run. Other goroutines hand work to the loop with RunOnLoop, and a host function whose result comes from another goroutine returns a promise of NewPromise. Between runs the runtime is the host's again.
Phases ¶
One iteration of the loop has three phases, as Node's timers, poll and check phases: the timers due when the phase starts, in order of expiry, then of scheduling; the tasks posted before the phase started (RunOnLoop, Post, the done function of Hold, the settle function of NewPromise); the immediates set before the phase started. The promise jobs and queueMicrotask callbacks a callback or task queues run when it returns, before the next one. With nothing to run, the loop sleeps until the next timer is due or a task is posted.
Timers ¶
The timer functions follow Node.js:
- setTimeout and setInterval return a Timeout object with the methods ref, unref, hasRef, refresh, close and Symbol.toPrimitive, which returns the timer's numeric id; setImmediate returns an Immediate with ref, unref and hasRef.
- The callback gets the extra arguments, and the Timeout or Immediate as this. A callback that is not a function is a TypeError with the code ERR_INVALID_ARG_TYPE; a string is not evaluated.
- The delay goes through ToNumber and is truncated to whole milliseconds. NaN, a delay below 1 and one above 2147483647 are 1 ms, so a timer set by a callback runs in a later iteration.
- An interval is rescheduled for its delay after the time its callback started. refresh restarts a timer's delay from now, and runs a timeout that already fired again; a cleared timer stays cleared.
- clearTimeout and clearInterval take a Timeout, or the id its Symbol.toPrimitive returned, as a number or a string, once that was read; clearImmediate takes an Immediate. They ignore anything else, and work inside the timer's own callback.
- An unref'd timer or immediate does not keep Run alive, and runs only while something else does.
Differences from Node: the Timeout and Immediate objects have no own properties (JSON.stringify gives {}, and constructor.name is "Object"), their methods throw a TypeError when called on another object, a Proxy of one included, and a Timeout has no Symbol.dispose method. Timers expire in the order of their exact due times, where Node compares whole milliseconds. timers/promises, the AbortSignal options, util.promisify and Node's warning for a delay above 2147483647 are not provided.
Errors and interrupts ¶
A callback's exception stops the loop, as an uncaught exception ends a Node.js process, unless Options.OnError takes it. An interrupt always stops it, before it takes the next timer, task or immediate off its queues, which keep them. A loop is interrupted through Loop.Interrupt: Runtime.Interrupt alone stops the JavaScript running but does not wake a loop that sleeps. A rejection no handler catches is the host's business, through Runtime.SetPromiseRejectionTracker.
Idle and wake ¶
A host that bounds the CPU time of a run, or shares a few execution slots among many runtimes, learns from Options.OnIdle and Options.OnWake when the loop waits instead of running JavaScript. The loop calls OnIdle when nothing is to run now (no task, no immediate, no timer due) and something keeps it alive, right before it blocks, and OnWake once it woke with something to run, before it runs it. No JavaScript runs on the loop between the two. A loop that never has to wait, because work is pending or a timer is due whenever it looks, calls neither. A wake that finds nothing to run, such as a Hold released while another is still held, blocks again without a call. A wake that ends the loop, a stop, Terminate, an interrupt or, for Run, nothing left that keeps it alive, ends the run without OnWake, and Run returns what it would return without the hooks. So the calls alternate, OnIdle first, and a run may end after an OnIdle with no OnWake: the host knows which state it is in from the hook it saw last. The hooks run on the loop, so they are done when Run returns, or Stop for a loop started with Start.
An error from OnWake stops the loop as an interrupt does, before it takes anything off its queues, which keep it all for the next Run or Start: Run returns the error unchanged, or Stop for a loop started with Start. The run ends idle, with OnIdle the last hook, and the runtime is not interrupted, since no JavaScript was running. OnWake may block, to wait for a slot for example. Stop and Terminate wait for the loop, and so for OnWake: a host whose OnWake waits ends that wait when it stops the loop, through a context it cancels before it calls Stop or Terminate for example. When OnWake returns nil, a stop, Terminate or interrupt that came meanwhile ends the run before the loop runs anything, and the run ends awake. The time OnWake takes counts as time passed for the timers, so a timer that fell due meanwhile runs late. A panic in a hook is not recovered, as one in a host task is not, and the hooks must not call Stop or Terminate.
A host with a fixed number of slots takes one, and starts its watchdog, before Run, and after Run gives them back unless the run ended idle:
awake := false
loop, err := eventloop.New(rt, eventloop.Options{
OnIdle: func() { awake = false; watchdog.Pause(); <-slots },
OnWake: func() error {
select {
case slots <- struct{}{}:
case <-ctx.Done(): // cancelled before Stop or Terminate
return ctx.Err()
}
awake = true
watchdog.Resume()
return nil
},
})
slots <- struct{}{}
awake = true
watchdog.Resume()
err = loop.Run(fn)
if awake {
watchdog.Pause()
<-slots
}
Memory limit ¶
Options.MemoryLimit of the runtime bounds what the program keeps plus what it allocates, over the whole run: Run, or Start until Stop, starts a new budget (Runtime.ResetAllocation, which keeps the last measurement of what the program retains), and before each timer or immediate callback and each task the loop rebases it instead of resetting it (Runtime.RebaseAllocation): once enough was allocated since the last measurement, it measures what the runtime's JavaScript retains and counts that in place of what was allocated. Where an allocation would pass the limit before then, the runtime measures first (for an allocation a builtin makes, at the latest before the next callback), and stops the program only when it keeps too much. The measurement reaches what the loop holds for JavaScript, the callbacks and arguments of the pending timers and immediates and the promises of NewPromise not yet settled, and through them the async functions awaiting those promises: the loop registers them with Runtime.AddLiveRoots once the runtime has a limit, and Terminate removes them, so that a runtime that gets a new Loop does not keep the old one. It does not see values only the host's Go code holds, such as the captures of a task posted with RunOnLoop, unless the host registers them too. A program that keeps what it allocates, across however many callbacks and runs, stops near the limit; one that keeps little runs on, however much it allocates in all. The loop holds its mutex only while it adds its roots, not while the measurement walks the heap, so goroutines that post tasks or settle promises do not wait for it. Without a limit the loop does no work for it.
A callback that passes the limit stops the loop with its *moejs.InterruptedError, as any interrupt does, and so does a measurement that finds the program keeps more than the limit: the loop interrupts the runtime with the *moejs.MemoryLimitError before it takes the next timer, task or immediate off its queues. Either way errors.Is finds moejs.ErrMemoryLimit in what Run (or Stop) returns, and the interrupt stays pending (Runtime.ClearInterrupt).
Options.ResetMemoryPerTask restores the budget of earlier versions: a new one before each callback and task, with the promise jobs it queues. The limit then bounds what one macrotask allocates, not what the program keeps alive between them.
Index ¶
- Variables
- func Post(l *Loop, task func(*moejs.Runtime) error) bool
- type Loop
- func (l *Loop) Hold() (done func(fn func(*moejs.Runtime)))
- func (l *Loop) Interrupt(v any)
- func (l *Loop) NewPromise() (p moejs.Value, settle func(f func(*moejs.Runtime) (moejs.Value, error)))
- func (l *Loop) Run(fn func(*moejs.Runtime) error) (err error)
- func (l *Loop) RunOnLoop(fn func(*moejs.Runtime)) bool
- func (l *Loop) Runtime() *moejs.Runtime
- func (l *Loop) Start() error
- func (l *Loop) Stop() error
- func (l *Loop) StopNoWait()
- func (l *Loop) Terminate()
- type Options
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTerminated is Run's and Start's error once Terminate ended the // loop, and the value Terminate interrupts the runtime with. ErrTerminated = errors.New("eventloop: loop terminated") // ErrRunning is Run's and Start's error while the loop already runs, // started by Run or Start. ErrRunning = errors.New("eventloop: loop is already running") )
Functions ¶
func Post ¶
Post posts task to the loop l as l.RunOnLoop does, for a task that can fail: the loop handles its error as a callback's. An interrupt stops the loop; any other error goes to Options.OnError, or stops the loop when OnError is nil. A task that calls JavaScript or settles promises itself returns what that fails with, so that an exception of the jobs it runs or the error of a memory limit is not lost. Post returns false once Terminate ended the loop, and task is dropped. It is a function rather than a method so that a program that does not call it carries none of it.
Types ¶
type Loop ¶
type Loop struct {
// contains filtered or unexported fields
}
Loop is an event loop that owns one Runtime while it runs. Its methods may be called from any goroutine, except NewPromise, which a host function calls on the loop, and Stop and Terminate, which must not be called on the loop: they wait for it. On the loop means from Run's fn, a callback, a task, a host function JavaScript calls there, OnError, OnIdle or OnWake. A runtime has at most one Loop.
Example (Hooks) ¶
ExampleLoop_hooks gives a host a CPU-time watchdog and a limited number of execution slots, through Options.OnIdle and OnWake: the watchdog counts only the time the loop runs JavaScript, and the slot is free while the loop waits for a lookup that takes longer than the whole budget. The lookup does not stop the loop, but the endless loop after it does.
package main
import (
"errors"
"fmt"
"time"
"github.com/MoeForge/moejs"
"github.com/MoeForge/moejs/eventloop"
)
func main() {
slots := make(chan struct{}, 1) // one execution slot
rt := moejs.NewRuntime(moejs.Options{})
var loop *eventloop.Loop
wd := &watchdog{budget: 50 * time.Millisecond, expire: func() { loop.Interrupt("CPU budget spent") }}
loop, err := eventloop.New(rt, eventloop.Options{
OnIdle: func() {
wd.pause()
<-slots
},
OnWake: func() error {
slots <- struct{}{} // waits for a free slot
wd.resume()
return nil
},
})
if err != nil {
panic(err)
}
err = rt.SetGlobal("print", moejs.NativeFunc(func(_ *moejs.Realm, _ moejs.Value, args []moejs.Value) (moejs.Value, error) {
fmt.Println(moejs.Arg(args, 0).String())
return moejs.Undefined(), nil
}))
if err != nil {
panic(err)
}
err = rt.SetGlobal("lookup", moejs.NativeFunc(func(*moejs.Realm, moejs.Value, []moejs.Value) (moejs.Value, error) {
p, settle := loop.NewPromise()
go func() {
time.Sleep(100 * time.Millisecond) // I/O
settle(func(*moejs.Runtime) (moejs.Value, error) { return moejs.String("found"), nil })
}()
return p, nil
}))
if err != nil {
panic(err)
}
script, err := moejs.CompileScript("main.js", `(async () => {
print("lookup: " + await lookup());
for (;;) {}
})();`)
if err != nil {
panic(err)
}
slots <- struct{}{} // the run takes a slot
wd.resume()
err = loop.Run(func(rt *moejs.Runtime) error {
_, err := rt.RunScript(script)
return err
})
if wd.running {
// The run ended awake, holding its slot; one that ended idle
// paused the watchdog and released the slot in OnIdle.
wd.pause()
<-slots
}
var ie *moejs.InterruptedError
if errors.As(err, &ie) {
fmt.Println("stopped:", ie.Value)
rt.ClearInterrupt()
}
fmt.Println("free slots:", cap(slots)-len(slots))
}
// watchdog calls expire once the time it ran, between resume and pause,
// adds up to budget.
type watchdog struct {
budget time.Duration
expire func()
running bool
used time.Duration
since time.Time
timer *time.Timer
}
func (w *watchdog) resume() {
w.running, w.since = true, time.Now()
w.timer = time.AfterFunc(w.budget-w.used, w.expire)
}
func (w *watchdog) pause() {
w.timer.Stop()
w.running, w.used = false, w.used+time.Since(w.since)
}
Output: lookup: found stopped: CPU budget spent free slots: 1
func New ¶
New creates a loop for rt and installs setTimeout, clearTimeout, setInterval, clearInterval, setImmediate and clearImmediate as globals of rt, as the package documentation describes. The error is SetGlobal's.
func (*Loop) Hold ¶
Hold keeps the loop alive for host work in progress, until done is called. done may be called from any goroutine: it posts fn to the loop as RunOnLoop does (fn may be nil) and releases the hold. The first call counts and later calls do nothing; after Terminate, done drops fn. Hold may be called from any goroutine, but only a hold taken on the loop (in a host function or a callback) keeps a running Run from returning: one taken on another goroutine races with a Run that has nothing else left, and almost always loses it, so that it only keeps the next Run alive.
func (*Loop) Interrupt ¶
Interrupt interrupts the runtime (Runtime.Interrupt with v) and wakes the loop, which Runtime.Interrupt alone leaves asleep until its next timer or task. The JavaScript running stops, and the loop stops before it takes another timer, task or immediate off its queues, which keep them: Run returns the *moejs.InterruptedError, and Stop for a loop started with Start. As after Runtime.Interrupt, the interrupt stays pending, so the host calls Runtime.ClearInterrupt before it runs the loop or uses the runtime again. Interrupt may be called from any goroutine, the loop included.
func (*Loop) NewPromise ¶
func (l *Loop) NewPromise() (p moejs.Value, settle func(f func(*moejs.Runtime) (moejs.Value, error)))
NewPromise creates a pending promise for a host function to return, and keeps the loop alive until settle is called. It is called on the loop. settle may be called from any goroutine: the first call posts f to the loop, which settles the promise with what f returns there, and later calls do nothing. A nil error fulfills it with the value, or adopts the value when it is a thenable; any other error rejects it with the value JavaScript would catch from a host function that returned the error (Runtime.ThrownValue). An *moejs.InterruptedError leaves it pending and stops the loop. A nil f fulfills it with undefined. The jobs settling queues run before the loop goes on; what they throw, and what settling fails with (moejs.ErrForeign), goes to Options.OnError.
Example ¶
ExampleLoop_NewPromise gives JavaScript an asynchronous host function: it returns a promise of NewPromise and does its work on another goroutine, which settles the promise on the loop. The Go error of a failed lookup rejects it with an Error.
package main
import (
"errors"
"fmt"
"github.com/MoeForge/moejs"
"github.com/MoeForge/moejs/eventloop"
)
func main() {
rt := moejs.NewRuntime(moejs.Options{})
loop, err := eventloop.New(rt, eventloop.Options{})
if err != nil {
panic(err)
}
err = rt.SetGlobal("lookup", moejs.NativeFunc(func(_ *moejs.Realm, _ moejs.Value, args []moejs.Value) (moejs.Value, error) {
name := moejs.Arg(args, 0).String()
p, settle := loop.NewPromise()
go func() {
// Blocking work, such as I/O, runs off the loop.
var err error
if name == "" {
err = errors.New("empty name")
}
settle(func(rt *moejs.Runtime) (moejs.Value, error) {
if err != nil {
return moejs.Undefined(), err
}
return rt.FromGo(map[string]any{"name": name, "length": len(name)})
})
}()
return p, nil
}))
if err != nil {
panic(err)
}
mod, err := moejs.Compile("plugin.js", `export async function describe(name) {
try {
const r = await lookup(name);
return r.name + " has " + r.length + " letters";
} catch (e) {
return "failed: " + e.message;
}
}`)
if err != nil {
panic(err)
}
describe, err := mod.Hook("describe")
if err != nil {
panic(err)
}
var results []moejs.Value
err = loop.Run(func(rt *moejs.Runtime) error {
if err := rt.Load(mod); err != nil {
return err
}
for _, name := range []string{"moejs", ""} {
p, err := rt.Call(describe, moejs.String(name))
if err != nil {
return err
}
results = append(results, p)
}
return nil
})
if err != nil {
panic(err)
}
// Run returned: every promise of NewPromise is settled.
for _, p := range results {
_, v, _ := moejs.PromiseResult(p)
fmt.Println(v.String())
}
}
Output: moejs has 5 letters failed: empty name
func (*Loop) Run ¶
Run calls fn with the runtime on the calling goroutine and then runs the loop there until nothing keeps it alive, Stop or StopNoWait ends it, or an error or an interrupt stops it (Options.OnError, Interrupt). It returns fn's error at once when fn fails, the error that stopped the loop (an *moejs.InterruptedError for an interrupt), ErrTerminated once Terminate ended it, or nil. fn may be nil. fn runs on the loop: it must not call Stop or Terminate, which would wait for it.
What is still pending when Run returns, an unref'd timer or immediate, or anything after a stop, an error or an interrupt, stays pending: the next Run or Start continues it, and JavaScript the host runs on the runtime between them (Call) can set more. The runtime is the host's again between them. Run ends by releasing what would keep the values the callbacks and tasks made and dropped reachable for Go's collector until the runtime runs code again: the engine's scratch (engine Realm.ReleaseScratch), the registers and frame records they used, and the loop's own last batch of immediates and settled promises. A loop started with Start does the same when it ends.
A panic in fn or in a host task (the functions of RunOnLoop, of done and of settle, OnError, OnIdle and OnWake) is not recovered: it unwinds through Run, or ends the program for a loop started with Start. The loop is marked stopped first, and the tasks and immediates its phase had not run yet stay queued; the task that panicked is gone, and a promise whose settle function panicked stays pending.
Example ¶
ExampleLoop_Run runs a script that sets timers: Run returns once the last timer ran. The promise jobs of the script run before the loop starts.
package main
import (
"fmt"
"github.com/MoeForge/moejs"
"github.com/MoeForge/moejs/eventloop"
)
func main() {
rt := moejs.NewRuntime(moejs.Options{})
loop, err := eventloop.New(rt, eventloop.Options{})
if err != nil {
panic(err)
}
err = rt.SetGlobal("print", moejs.NativeFunc(func(_ *moejs.Realm, _ moejs.Value, args []moejs.Value) (moejs.Value, error) {
fmt.Println(moejs.Arg(args, 0).String())
return moejs.Undefined(), nil
}))
if err != nil {
panic(err)
}
script, err := moejs.CompileScript("main.js", `
let n = 0;
const tick = setInterval(() => {
print("tick " + ++n);
if (n === 3) clearInterval(tick);
}, 10);
setTimeout(() => print("timeout"), 5);
Promise.resolve().then(() => print("job"));
print("script");`)
if err != nil {
panic(err)
}
err = loop.Run(func(rt *moejs.Runtime) error {
_, err := rt.RunScript(script)
return err
})
if err != nil {
panic(err)
}
}
Output: script job timeout tick 1 tick 2 tick 3
func (*Loop) RunOnLoop ¶
RunOnLoop posts fn to the loop, which calls it with the runtime in its next tasks phase, and reports true. It may be called from any goroutine, the loop included. When the loop does not run, fn waits for the next Run or Start; a posted task keeps Run alive until it ran. RunOnLoop returns false once Terminate ended the loop, and fn is dropped.
func (*Loop) Start ¶
Start runs the loop on a new goroutine until Stop, StopNoWait or Terminate ends it, or an error stops it (Options.OnError): idle, it waits for tasks (RunOnLoop) and timers. While it runs, the host uses the runtime only through RunOnLoop. It returns ErrRunning when the loop already runs and ErrTerminated once Terminate ended it.
func (*Loop) Stop ¶
Stop ends the running loop, started by Run or Start, after the callback or task it is running returns (or Run's fn), and waits until it has ended. Timers, immediates, holds and posted tasks stay pending for the next Run or Start. Stop returns what ended the run it waited for, or the last run when none was running, as Run returns it: nil, the error that stopped it (Options.OnError), the *moejs.InterruptedError of an interrupt or ErrTerminated; for a loop started with Start it is how the host learns of that error. It must not be called on the loop, where it would wait for itself; StopNoWait may be.
func (*Loop) StopNoWait ¶
func (l *Loop) StopNoWait()
StopNoWait is Stop without the wait: the loop ends after the callback or task it is running returns. It may be called on the loop.
func (*Loop) Terminate ¶
func (l *Loop) Terminate()
Terminate ends the loop for good: it interrupts the runtime (Runtime.Interrupt with ErrTerminated), which stops the JavaScript the loop runs, drops every pending timer, immediate and task, and waits until a running loop has ended. Run and Start then return ErrTerminated, RunOnLoop returns false, the done function of Hold and the settle function of NewPromise do nothing, and setTimeout, setInterval and setImmediate throw. The interrupt is left pending also when no JavaScript was running, so the host calls Runtime.ClearInterrupt before it uses the runtime again; a new Loop may be created for it then. It must not be called on the loop, where it would wait for itself.
type Options ¶
type Options struct {
// OnError receives the errors of the callbacks the loop runs: what a
// timer or immediate callback throws, the first exception the jobs it
// queued throw (a queueMicrotask callback's), a Go panic as an
// *moejs.InternalError, and what the settle function of NewPromise
// fails with. It runs on the loop, which keeps running afterwards.
// When OnError is nil, such an error stops the loop: Run returns it,
// or Stop for a loop started with Start, as an uncaught exception ends
// a Node.js process. An interrupt always stops the loop and is never
// passed to OnError.
OnError func(err error)
// ResetMemoryPerTask resets the budget of the runtime's MemoryLimit
// before each callback and task (Runtime.ResetAllocation), as before:
// the limit then bounds what one macrotask allocates, not what the
// program keeps. By default the budget spans the run and the limit
// bounds what the program keeps plus what it allocates (see Memory
// limit in the package documentation).
ResetMemoryPerTask bool
// OnIdle is called when the loop has nothing to run and is about to
// block, waiting for a timer, a task or a stop: no JavaScript runs on
// the loop after it until OnWake. A host pauses its watchdog there, or
// releases an execution slot. It runs on the loop, without the loop's
// lock, and may call RunOnLoop, Post, Hold, Interrupt and StopNoWait,
// but not Stop or Terminate. A panic in it is not recovered. See Idle
// and wake in the package documentation.
OnIdle func()
// OnWake is called after the loop woke from the block OnIdle
// announced, once it has something to run and before it runs it. It
// may block, to take an execution slot for example. A non-nil error
// stops the loop as an interrupt does, before it takes anything off
// its queues, which keep it all: Run returns the error, or Stop for a
// loop started with Start. A wake that ends the loop (Stop,
// StopNoWait, Terminate, an interrupt, or nothing left that keeps Run
// alive) does not call OnWake. It runs on the loop, without the loop's
// lock, as OnIdle does.
OnWake func() error
}
Options configures New.