eventloop

func (*Loop) Hold ¶

func (l *Loop) Hold() (done func(fn func(*moejs.Runtime)))

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 ¶

func (l *Loop) Interrupt(v any)

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.

package main

import (
	"errors"
	"fmt"

	"github.com/Calcium-Ion/moejs"
	"github.com/Calcium-Ion/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 ¶

func (l *Loop) Run(fn func(*moejs.Runtime) error) (err error)

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.

A panic in fn or in a host task (the functions of RunOnLoop, of done and of settle, and OnError) 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.

package main

import (
	"fmt"

	"github.com/Calcium-Ion/moejs"
	"github.com/Calcium-Ion/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 ¶

func (l *Loop) RunOnLoop(fn func(*moejs.Runtime)) bool

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) Runtime ¶

func (l *Loop) Runtime() *moejs.Runtime

Runtime returns the loop's runtime.

func (*Loop) Start ¶

func (l *Loop) Start() error

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 ¶

func (l *Loop) Stop() error

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.