soothfast-macros API reference#

Generated by cargo soothfast docs reference Measurements and verified claims come from the latest baseline; CI gates them.

soothfast_macros#

bench ^proc_macro#

pub fn bench(attr: TokenStream, item: TokenStream) -> TokenStream

Register a bench harness function, optionally fed by a setup fn.

#[soothfast::bench(group = "sort", setup_sized = values_n, sizes(1024, 4096, 16384),
                 complexity = "n log n", alloc = 2, covers = "mylib::sorted")]
fn bench_sorted(input: &[f64]) { soothfast::keep(mylib::sorted(input)); }

setup = f feeds f() -> T as &T; setup_sized = f feeds f(n) -> T and enables sizes(...)/complexity sweeps (the plain measurement uses the largest size). Setup always runs outside the measured region. Route constant inputs through soothfast::keep or LLVM const-folds them.

fixture ^proc_macro#

pub fn fixture(attr: TokenStream, item: TokenStream) -> TokenStream

Mark a deterministic input-builder. Registers metadata only; the function is referenced by name from #[bench(setup = ...)] / setup_sized.

measured ^proc_macro#

pub fn measured(attr: TokenStream, item: TokenStream) -> TokenStream

Register a zero-argument function as a directly measured item.

#[soothfast::measured(group = "checksums", alloc = 0, p99 = "100us")]
pub fn lcg_checksum() -> u64 { ... }

Functions with parameters need #[soothfast::bench(setup = ...)] instead.

mock_seam ^proc_macro#

pub fn mock_seam(attr: TokenStream, item: TokenStream) -> TokenStream

Mark a mock-backend setup fn, resolved at runtime by name via soothfast::mock::activate — referenced from a markdown mock=NAME / mock=NAME(ARG) tag, which is plain text rather than a syn::Path, so (unlike #[fixture], wired at compile time through a macro attribute argument) this can't be called from a literal call site the macro controls; the registry stores a name-keyed fn pointer instead.

The annotated fn takes zero args or one &str (the tag's (ARG), "" when omitted) and returns any T: soothfast::registry::MockSeam.

route ^proc_macro#

pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream

Declare the spec operation a handler implements — the code-side half of cargo soothfast spec check. Stackable for handlers serving several surfaces (REST + GraphQL + MCP).

Spec generation infers the request and response shapes from the handler's own signature; request, response, status, params and path_params override that for what inference provably cannot see — erased returns, and detached markers whose empty signature says nothing at all.

#[soothfast::route(spec = "specs/openapi.yaml", operation = "getItem",
                 method = "GET", path = "/items/{id}")]
pub fn get_item(id: u64) -> String { ... }

// `impl IntoResponse` erases the type; name it explicitly.
#[soothfast::route(spec = "specs/openapi.yaml", operation = "createItem",
                 method = "POST", path = "/items",
                 response = "Item", status = 201)]
pub async fn create_item(body: Json<NewItem>) -> impl IntoResponse { ... }

// A detached marker states its whole contract. `path_params` types the
// `{placeholder}`s that would otherwise be bare strings.
#[soothfast::route(spec = "specs/openapi.yaml", operation = "listBySector",
                 method = "GET", path = "/sectors/{sector}",
                 params = "SectorQuery", path_params = "sector: Sector",
                 response = "[Item]")]
fn route_list_by_sector() {}