source-academy / js-slang / 35676034146

86%

push

github

feat(conductor): add SourceDataHandler, js-slang's module data interface (#2082)

* feat(conductor): add SourceDataHandler, js-slang's module data interface

First slice of #2081. A Conductor module never holds a live reference into
the evaluator: pairs, arrays, closures and opaques all cross the boundary as
opaque identifiers, and the module comes back through `IDataHandler` to read
or write them. This is the table those identifiers index into.

Per the decision on #2081, the tables are private rather than backed by live
Source values. Values are therefore converted across the boundary, not
shared; that conversion is the interop layer's job and is not in this file.
This class never sees a js-slang value — engine values enter only through
`closure_make`'s `ExternCallable` and through `closure_call`'s arguments and
results.

Nothing registers it yet, so the evaluator bundles are byte-for-byte
unchanged. The async spine that lets a Source program actually call a module
function is the next slice, and the hard one.

Three things worth calling out:

Every method is `async`, including the ones that compute synchronously.
`IDataHandler` declares them Promise-returning, and without `async` a failed
lookup throws *synchronously* out of a call the caller may reasonably hold
as a promise. `require-await` is disabled for the file with that rationale.

The shapes accepted are deliberately more forgiving than the types suggest,
because the module bundles are shared with py-slang: `pair_head` and friends
work on a two-element ARRAY as well as a PAIR, and the list helpers accept a
flat ARRAY as well as a PAIR/EMPTY_LIST chain. Without that, a bundle that
works from Python breaks from Source.

`tie`/`untie` are no-ops rather than throws. Our tables hold strong
references for the handler's lifetime, so a tie is already guaranteed and an
untie cannot be honoured; py-slang throws `Method not implemented`, which
would abort a student's program over a call asking for some... (continued)

2433 of 2955 branches covered (82.34%)

Branch coverage included in aggregate %.

366 of 390 new or added lines in 10 files covered. (93.85%)

4749 of 5451 relevant lines covered (87.12%)

460674.41 hits per line