jflib-modrt 0.2.1

The runtime of a loadable JFLib module: no_std, no imports, served by its host
Documentation
  • Coverage
  • 49.72%
    89 out of 179 items documented0 out of 80 items with examples
  • Size
  • Source code size: 118.7 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.8 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 3s Average build duration of successful builds.
  • all releases: 3s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • JFLibrary/JFLib
    2 1 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • Graphsto

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

License

MIT or Apache-2.0, at your choice.