Native methods

[mattcce]

Based on top of #73

Redesign pending.

---

Introduction

Native methods in Java provide FFI functionality to call foreign functions. Native methods are especially useful in the CSE machine to implement primitive functions, and in some cases, are the only real way to do so.

Motivation

The motivation for implementing native methods initially stemmed from Object.hashCode, which itself is a native method.

Native methods have clear uses for some other cases as well, like with displaying or printing to standard output. Other specific uses for native methods are presently unclear, but having the ability to break out of the CSEC machine is certainly not a detriment.

Implementation

Notation note: we refer generally to a Java syntactic native method by the term native method, and the foreign function that is eventually called when the native method is invoked by the term foreign function.

Native methods are implemented using an escape hatch in the invoke instruction handler. We offer full and complete power to native methods, passing in the entire control, stash, and environment to foreign functions they call. This matches the power that foreign functions are expected to have.

The CSEC machine still handles argument resolution and returning. This is because FFI calls should function like normal functions to the CSEC machine, except that it ignores whatever happens while the foreign function is running. To this end, common foreign functions are expected to:

• collect/find its arguments from the environment supplied to it, if any,
• push a result of the valid type onto the top of the stash.

Note that the foreign function, using common utility methods that the rest of the CSEC machine uses, will have to appropriately deserialise and serialise the values. In particular, it must be able to destructure AST nodes that it expects and reconstruct valid AST nodes that the CSEC machine expects.

Because the full control, stash, and environment is passed to the foreign function, this allows foreign functions to effectively do anything to the CSEC machine state.

Such foreign functions are declared and implemented in a dictionary, that the invoke instruction will call. To the CSEC machine, the foreign function completes in one step, right after the invoke instruction is executed.

The dictionary used uses fully-qualified method descriptors to identify the correct foreign function. These are of the form:

identifier ( p1Type p1Itdentifier, … ): returnType

Note that foreign functions always have the same type:

({ control, stash, environment }: { control: Control; stash: Stash; environment: Environment }) => void

In particular, foreign functions always return nothing. Their results are to be injected directly into the stash that is provided, for use by the CSEC machine (and the program it is currently running).

The identifier is included in such a symbolic reference for the express purpose of making foreign functions easier to implement. Because foreign functions must retrieve their arguments from the environment, their implementations must be aware of the correct parameter identifiers.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	73.97% (+0.02% 🔼)	7202/9737
🟡	Branches	60.47% (+0.07% 🔼)	2363/3908
🟡	Functions	69.41% (-0.05% 🔻)	1291/1860
🟡	Lines	74.88% (-0.05% 🔻)	6776/9049

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / natives.ts	100%	100%	100%	100%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🔴	... / errors.ts	42.03% (-1.05% 🔻)	27.27%	14.71% (-0.92% 🔻)	43.94% (-0.13% 🔻)
🟢	... / interpreter.ts	98.76% (-0.28% 🔻)	91.03% (-0.87% 🔻)	98.15%	98.67% (-0.63% 🔻)
🟢	... / index.ts	73.98% (-0.39% 🔻)	52.59% (-0.42% 🔻)	95.83% (+0.18% 🔼)	83.59% (-0.66% 🔻)
🟡	types/errors.ts	64.06% (-0.45% 🔻)	0%	42.86% (-1.59% 🔻)	65.57% (-0.53% 🔻)
🔴	... / extractor.ts	48.65% (-0.13% 🔻)	36.97% (-0.09% 🔻)	45.28%	52.81% (-0.17% 🔻)

Test suite run success

1122 tests passing in 64 suites.

Report generated by 🧪jest coverage report action from 6b33b64