Trait PolydatSetup

Source

pub trait PolydatSetup { }

Expand description

SRD-80 PR B.6 — construction-time setup contract for nodes that derive a pre-computed runtime state from their const args (e.g. combinations parsing a charset pattern into segments + modulus, regex_match compiling a pattern, histribution parsing a distribution spec).

The contract: the operator-provided setup function is called EXACTLY ONCE per node instance, at construction time (new()). Its result is stored in a struct field; eval- time access is a plain &T borrow.

Type-level enforcement: the #[poly_const(...)] attribute on a &T argument tells the macro to generate this construction pattern. The macro is the sole party emitting setup_fn(...) calls and it generates the call exactly once inside new(). The contract is inviolable because no other code path can reach the setup function — the macro hides it inside the constructor.

In effect, the function pointer behaves as FnOnce — invoked one time, by one site, never again. The FnOnce semantics aren’t expressed as a trait bound because they don’t need to be: the macro is the only caller, and the macro respects single-call by construction.

Library author idiom:

pub struct ParsedPattern {
    pub segments: Vec<Segment>,
    pub modulus: u64,
}

impl ParsedPattern {
    /// Single-call setup. Macro invokes once in `new()`.
    fn from_pattern(pattern: &str) -> Self { /* parse */ }
}

#[polydat_node(category = String)]
fn combinations(
    input: u64,
    pattern: Const<&str>,
    #[poly_const(ParsedPattern::from_pattern, from = pattern)]
    parsed: &ParsedPattern,
) -> String {
    // parsed is a borrow of the cached struct field —
    // no recomputation, no clone, no ceremony at the call site.
    let mut r = input % parsed.modulus;
    /* ... */
}

Marker trait — purely a documentation handle for types intended to be polydat-setup targets. The macro doesn’t dispatch on this; the attribute is the dispatch surface. Implementing the trait gives library authors a way to signal intent and improve cargo doc discoverability.