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:
- 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
- reject a null handle with
crate::ffi::invalid_argumentand return the sentinel - run the body inside
crate::ffi::catch← the only step with domain content - move the result across the ABI, reporting
crate::ffi::invalid_outputif it cannot - 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.