Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.

src/meta-native/meta-native.x

Meta functions and the native code they call.

Functions

Functions

x2c_register_extension

void x2c_register_extension(const char *name, Map (*targets)(void))

Registers package name’s compile-time part, linked into the compiler, whose targets returns its name-to-Func Map. The registration unit x2c build --extension generates calls it from a constructor.

Source: src/meta-native/modules.x:237

Compiler

Compiler.add_native_module

void Compiler.add_native_module(String path, Map (*entry)(void))

Records the name-to-Func Map that the entry of the native module loaded from absolute path returns. The Funcs, names, signatures, and path last for the process.

Source: src/meta-native/modules.x:178

Compiler.apply_meta_function

Var Compiler.apply_meta_function( Compiler c, String name, List arguments, Token site)

Applies the meta function spelled name to the evaluated arguments at site, outside any expansion. A call the project meta build leaves for the translation returns void.

Source: src/meta-native/calls.x:78

Compiler.bind_linked_meta

int Compiler.bind_linked_meta(Compiler c, List fn, Type type)

Binds the bodied meta definition fn, of function type type, to the compiler’s linked copy of it when the two definition texts hash the same, or always for a prelude component’s, instead of staging it. Returns whether it did; another edited definition is staged as user code.

Source: src/meta-native/linked.x:60

Compiler.bind_native_meta

int Compiler.bind_native_meta(Compiler c, String name)

Binds an included native meta function the first time compile-time code calls name. Returns whether the macro session now binds it. A declaration-producing macro can call one during collection, before the parse installs the advertisements, so the first lookup there installs the ones visible so far.

Source: src/meta-native/bindings.x:64

Compiler.bind_project_meta

int Compiler.bind_project_meta(Compiler c, String name)

Binds an advertised meta function and reports whether it was found. Its provider supplies the helper table and private helpers.

Source: src/meta-native/functions.x:229

Compiler.compiler_targets

Map Compiler.compiler_targets(void)

Returns the compiler’s own targets, the operations lib/meta.x declares with a bodyless meta prototype, loaded as the native module every request selects first.

Source: src/meta-native/modules.x:39

Compiler.evaluate_meta_expression

List Compiler.evaluate_meta_expression( Compiler c, List expression, Token site)

Executes an explicit meta call and inserts its result at a code boundary.

Source: src/meta-native/calls.x:13

Compiler.evaluate_meta_statement

List Compiler.evaluate_meta_statement( Compiler c, List expression, Symbol context, Token site)

Executes an explicit meta call written as a whole statement at context. A code List result binds there, so the call may return a statement as well as an expression.

Source: src/meta-native/calls.x:21

Compiler.extension_archive

String Compiler.extension_archive(void)

Returns the archive of the linked packages’ objects that the build of this compiler kept beside it, named by the compiler’s identity, or NULL when the compiler links none. Project meta code links it.

Source: src/meta-native/modules.x:255

Compiler.install_collected_meta_function

void Compiler.install_collected_meta_function( Compiler c, List declaration, Token marker)

Installs the stub of the bodied meta definition declaration whose body collection skips, so a file-scope constant after it can call it in the project’s helper. The full parse installs it again. The compiler’s linked copy answers while its source hashes agree; otherwise the definition replaces an earlier binding with a helper stub. A group that stages in process waits for the full parse.

Source: src/meta-native/functions.x:43

Compiler.install_meta_declaration

void Compiler.install_meta_declaration( Compiler c, List declaration, Token marker)

Applies a contextual meta marker to one initialized file-static value. The unit’s staged meta group holds the compile-time instance, which its module initializes for each unit.

Source: src/meta-native/functions.x:184

Compiler.install_meta_function

void Compiler.install_meta_function(Compiler c, List fn, Token marker)

Installs a bodied meta function. The project meta build compiled it into the project’s helper, so the session holds a stub that calls it there; the REPL’s stub stages the session’s group at the first call instead, and the project meta build’s own parse only groups it. A function whose body reaches a compiler operation, a template, or a compile-time-only function has no runtime form. A body that lets its own storage outlive a call is rejected where the storage leaves.

Source: src/meta-native/functions.x:20

Compiler.install_native_meta_effects

void Compiler.install_native_meta_effects(Compiler c, Map globs)

Records the native advertisements retained by included interfaces. Each binds on first use, so a unit with no compile-time code pays nothing.

Source: src/meta-native/bindings.x:42

Compiler.install_native_meta_function

void Compiler.install_native_meta_function( Compiler c, List declaration, Token marker)

Installs a prototype-only meta function from the compiler’s trusted native target registry. The declaration keeps its ordinary runtime form.

Source: src/meta-native/bindings.x:77

Compiler.install_project_meta_effect

void Compiler.install_project_meta_effect(Compiler c, List row)

Installs an included meta function’s evaluator advertisement.

Source: src/meta-native/functions.x:215

Compiler.linked_meta_provider_source

List Compiler.linked_meta_provider_source(String provider)

Returns a linked provider’s source and dependency hashes.

Source: src/meta-native/linked.x:99

Compiler.links_extension

int Compiler.links_extension(String name)

Reports whether package name’s compile-time part is linked into the compiler, so its import loads no module.

Source: src/meta-native/modules.x:246

Compiler.links_meta_function

int Compiler.links_meta_function(String name)

Reports whether the compiler links the meta function name.

Source: src/meta-native/linked.x:96

Compiler.load_native_module

String Compiler.load_native_module(String path)

Loads the native module at path once per process and returns its absolute path. Loading runs the module’s code inside the compiler, so it happens only on request. A module from another compiler, a file that is not a module, or an unsupported platform prints a diagnostic and exits.

Source: src/meta-native/modules.x:101

Compiler.matches_macro

int Compiler.matches_macro(Compiler c, MacroMatcher &matcher, List code)

Tests a registered macro with the candidate’s global and source bindings. A pattern derived without them reads none.

Source: src/meta-native/functions.x:142

Compiler.native_meta_accepts

int Compiler.native_meta_accepts(Compiler c, Var function, List signature)

Answers whether the native target function matches the declared signature. A declared Func parameter matches a target’s Var parameter, which takes the compile-time callable and adapts it. Aliases of one native type match each other.

Source: src/meta-native/bindings.x:178

Compiler.native_meta_module

String Compiler.native_meta_module(Compiler c, String name, Type &type)

Returns the selected file-backed native module that supplies name, with its native type, or NULL for a linked or absent target.

Source: src/meta-native/bindings.x:214

Compiler.native_meta_targets

List Compiler.native_meta_targets(List paths)

Returns the declared native targets advertised by meta interface rows, in the row form lib/lisp-targets.x generates its target inventory from, or only those declared in the files paths names when it is not empty. Sorting makes that inventory independent of Map order.

Source: src/meta-native/bindings.x:305

Compiler.native_module_loaded

int Compiler.native_module_loaded(String path)

Reports whether the native module at absolute path is loaded.

Source: src/meta-native/modules.x:203

Compiler.native_module_targets

Map Compiler.native_module_targets(String path)

Returns the name-to-Func Map of the loaded native module at absolute path.

Source: src/meta-native/modules.x:208

Compiler.preload_native_module

void Compiler.preload_native_module(String path)

Loads the native module at absolute path when this compiler built it and the platform loads modules. A process that loads a module before it forks translation workers lets them inherit it; anything else is left for the import to report.

Source: src/meta-native/modules.x:119

Compiler.project_meta_uses_linked

int Compiler.project_meta_uses_linked( Compiler c, String name, String provider)

Answers whether a provider’s function can use its linked body. Copied definitions retain precise callees; runtime bodies retain their provider’s source dependencies, including private helpers.

Source: src/meta-native/linked.x:34

Compiler.record_native_meta_effect

void Compiler.record_native_meta_effect( Compiler c, List declaration, Token marker)

The shallow interface retains the advertisement separately from the C declaration. That lets a client install the trusted evaluator binding without repeating the marker in every translation unit.

Source: src/meta-native/bindings.x:15

Compiler.record_project_meta_effect

void Compiler.record_project_meta_effect( Compiler c, List declaration, Token marker)

Records the provider of a public bodied meta function in its interface. The provider owns both its native body and its compile-time state.

Source: src/meta-native/functions.x:201

Compiler.run_meta_call

Var Compiler.run_meta_call( Compiler c, List expression, Token site, int slot)

Runs the explicit meta call expression at site. The project meta build’s own parse leaves a project function’s call for the translation: an expression takes a placeholder, and a template slot, which has none, is reported.

Source: src/meta-native/calls.x:71

Compiler.select_native_modules

void Compiler.select_native_modules(List paths)

Selects the loaded native modules, by absolute path, that bodyless meta prototypes bind in the current request. The first module in paths that defines a name supplies it.

Source: src/meta-native/modules.x:53

Compiler.select_package_module

void Compiler.select_package_module( Compiler c, String name, String root, Token token)

Selects package name’s native module, when it has one, after the modules already selected, and records it as a prerequisite of the unit. The module is <root>/builds/<name>.module; a worker loads it itself when the process has not. A module from another compiler, or one on a platform that loads none, is reported at the import token.

Source: src/meta-native/modules.x:73

Compiler.supplies_native_meta

int Compiler.supplies_native_meta(String name)

Reports whether the compiler itself supplies the native function name. Such a function exists only inside a compiler, so a meta function that reaches it has no runtime form.

Source: src/meta-native/modules.x:214

Design notes

A bodied meta function runs at compile time through a stub that calls its compiled copy, and a bodyless meta prototype binds a native function that the compiler links, a selected native module defines, or a linked package supplies. This unit owns those bindings, the region summaries a native signature implies, and the native modules, which a request loads once per process and never unloads.