jflib-modrt
The runtime inside a loadable module of JFLib. It is to a module what
jflib-rt is to an app: the allocator, the panic handler,
memcpy and its relatives, and the few operations JFLib needs to compute the same numbers
everywhere. The difference is where they come from. A module brings no runtime of its own and
imports nothing from the system; everything it needs it gets from the program that loaded it.
What a loadable module is
A loadable module is a library file, a .dll on Windows or a .so on Linux, that a JFLib program
loads while it runs, for a large piece of work it does not want to carry in its own executable.
The one module there is today is JFLib's JPEG XL writer, jxlenc: a program can leave the writer
out and load it from a file next to its executable on the first JPEG XL save, and the file it
writes is the same byte for byte as with the writer linked in.
A module is built without the standard library and links against nothing. It exports exactly one
function, <name>_module, which receives the host's table of functions and returns the module's
own. From then on the host's allocator is the module's allocator, so buffers move between the two
without a copy; the module's parallel loops run on the host's worker pool; its messages go out
through the host; and a panic inside it ends in the host's normal crash report. The host keeps
the module loaded for the rest of the process. The records both sides exchange are described in
JFLib's API reference under
plat/modabi.rs.
What this crate does
A module is a cdylib crate built with --cfg jflib_module that takes this crate as rt and
jflib-modplat as plat. The library crates compiled
into it (simd, gfx, img_core, img_jpeg, img_jxl, img_jxl_enc) take the two crates
under the same names when that cfg is set, so their sources compile unchanged. For them, modrt
carries rt's float semantics, CPU feature bits, spin lock and extended-precision math, from the
same source files as rt, so the results inside a module equal those of the app. A module also
honours the host's --simd sse2.
For the module itself, module_entry!(name, TABLE) defines the one export, host() gives the
host's table, and plugin_abi! is the calling convention of the export and the records. For the
JPEG XL writer, jxl_table::<W>() builds the module's table from a type that implements
JxlWriter, which receives the request as a safe JxlRequest.
Who needs it
Hardly anyone yet. Loadable modules are built and tested inside JFLib's repository, where jxlenc
lives (it is not published itself), but not yet for programs outside it, and this crate's
interface is no part of what JFLib's version number promises
(VERSIONING.md).
It is on crates.io because the crates that can be built into a module name it as their rt under
--cfg jflib_module. It is not part of the jflib facade. All of JFLib's crates share one version
and are released together.
Platforms
Windows and Linux, on x86-64 and ARM64: the systems where JFLib's programs load modules.
What's new in 0.2.1
Nothing in this crate. It is released again as 0.2.1 only because all of JFLib's crates move together. The changelog says the same.
Documentation
- API reference: the
records of host and module, and the host's side in
plat/modhost.rs - The module
jxlenc: a complete module in 44 lines - docs.rs
License
MIT or Apache-2.0, at your choice.