Skip to main content

Module scaffold

Module scaffold 

Source
Expand description

Macros that assemble a C entry point out of the primitives in crate::ffi.

§What is repeated, and why a macro

crate::ffi hands out the materials — a last-error slot, a panic guard, the two boundary failure reasons. Assembling them is five steps, and only one of them says anything about the library:

  1. clear the slot, so a caller polling it does not read a previous failure. The slot is cleared on entry, not on success: a body that itself calls another entry point on this thread leaves that call’s failure visible
  2. reject a null handle with crate::ffi::invalid_argument and return the sentinel
  3. run the body inside crate::ffi::catch ← the only step with domain content
  4. move the result across the ABI, reporting crate::ffi::invalid_output if it cannot
  5. record a failure and return the sentinel

Steps 1, 2, 4 and 5 are about eighteen lines with no library content in them, and the sentinel in steps 2 and 5 differs by return type — null for a pointer, -1 for a count. That is why these are several macros rather than one: a single general macro would have to be told the sentinel, and being told is how the wrong one gets used.

§Names are spelled out, not built

Every macro takes the exported function name in full, following crate::export_last_error_abi!: macro_rules! cannot concatenate identifiers, and an exported symbol appearing literally in the source is what someone greps for. Doc comments are passed through from the call site, because what an entry point means is not something this crate knows.