Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.
src/meta-native.x
Meta functions and the native code they call.
Functions
| Function | Summary |
|---|---|
x2c_register_extension | Registers package name’s compile-time part, linked into the compiler, whose targets returns its name-to-Func Map. |
Compiler.add_native_module | Records the name-to-Func Map that the entry of the native module loaded from absolute path returns. |
Compiler.bind_linked_meta | 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, instead of staging it. |
Compiler.bind_native_meta | Binds an included native meta function the first time compile-time code calls name. |
Compiler.compiler_targets | 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. |
Compiler.evaluate_meta_expression | Executes an explicit meta call and inserts its result at a code boundary. |
Compiler.extension_archive | 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. |
Compiler.install_meta_declaration | Applies a contextual meta marker to one initialized file-static value. |
Compiler.install_meta_function | Installs a bodied meta function. |
Compiler.install_native_meta_effects | Records the native advertisements retained by included interfaces. |
Compiler.install_native_meta_function | Installs a prototype-only meta function from the compiler’s trusted native target registry. |
Compiler.links_extension | Reports whether package name’s compile-time part is linked into the compiler, so its import loads no module. |
Compiler.load_native_module | Loads the native module at path once per process and returns its absolute path. |
Compiler.native_meta_accepts | Answers whether the native target function matches the declared signature. |
Compiler.native_meta_module | Returns the selected file-backed native module that supplies name, with its native type, or NULL for a linked or absent target. |
Compiler.native_meta_targets | 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. |
Compiler.native_module_loaded | Reports whether the native module at absolute path is loaded. |
Compiler.native_module_targets | Returns the name-to-Func Map of the loaded native module at absolute path. |
Compiler.preload_native_module | Loads the native module at absolute path when this compiler built it and the platform loads modules. |
Compiler.record_native_meta_effect | The shallow interface retains the advertisement separately from the C declaration. |
Compiler.run_meta_call | Runs the explicit meta call expression at site. |
Compiler.select_native_modules | Selects the loaded native modules, by absolute path, that bodyless meta prototypes bind in the current request. |
Compiler.select_package_module | Selects package name’s native module, when it has one, after the modules already selected, and records it as a prerequisite of the unit. |
Compiler.supplies_native_meta | Reports whether the compiler itself supplies the native function name. |
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.x:935
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.x:876
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, instead of staging it. Returns whether it did; an edited
definition is staged as user code.
Source: src/meta-native.x:647
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
macro import can call one during the caller’s collection pass, before
the parse installs the advertisements, so the first lookup there
installs the ones visible so far.
Source: src/meta-native.x:314
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.x:737
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.x:170
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.x:953
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.x:148
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.x:48
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.x:297
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.x:326
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.x:944
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.x:799
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.x:423
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.x:459
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.x:554
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.x:901
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.x:906
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.x:817
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.x:274
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.x:193
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.x:751
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.x:771
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.x:912
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.