Skip to main content

api_ops

Macro api_ops 

Source
api_ops!() { /* proc-macro */ }
Expand description

Generate public-API traits, forwarding impls, rustdoc, metadata constants and a Markdown renderer from one operation registry per family.

The registry is the single source of truth: this macro generates method declarations and forwarding impls only; numerical bodies stay hand-written in the module named by each layer’s forward key. See tests/api_ops.rs for a complete working registry and docs/design/api-grammar/implementation.md section 4 for the design.

§Examples

The grammar (a text block, because a proc-macro crate cannot invoke its own macro from a doctest):

api_ops! {
    family: linalg;
    layer concrete {
        trait_doc: "...";
        trait_def: pub trait LinalgOps: AsView;
        impl_def: impl<X: AsView + ?Sized> LinalgOps for X;
        method_where: [];
        receiver: self;            // or `session` + `first_arg: &T;` (`&mut self`),
                                   // or `context` (`&self`, first operand is an argument)
        tensor_arg: &impl AsView;
        exec: &mut dyn Engine;     // optional
        dest: Dest;                // optional; enables `_into`
        result: Result;
        types { V = Tensor, R = Tensor } // `S` maps an operand typed `S`
        forward: crate::api::concrete;
        cfg: feature = "autodiff";   // optional; gates the trait and impl
        extra_decls { /* hand-written trait items (exception entries) */ }
        extra_impls { /* their impls */ }
    }
    layer core_eager { describe_only; }
    op svd {
        summary: "...";
        operands: (a);             // `name: Type` for typed operands
        options: SvdOptions;       // `options: none;`: no options type, no `_with`
        // optional: `generics: <Y: Bound>;` (method generics) and
        // `associated;` (no receiver, `Self: Sized`, e.g. concatenate)
        output: Svd<V, R>;         // `V`/`R`/... are the layer's `types` keys
        dtypes: "...";
        layers: [concrete];
        into: [];                  // overwrite | accumulate | scaled; with
                                   // `options: none;` the `_into` form takes no options
        layout: "...";
        errors: [Validation, NumericalFailure(NonConvergence)];
        omissions: [];
        example concrete: r#"..."#;
        // optional, on a described layer: the canonical compiled signature
        // as `api/*.txt` renders it; the registry-conformance check requires it
        signature core_eager: "pub fn tenferro_ad::EagerSession<'_>::svd(..) -> ..";
    }
    exceptions {
        E08 {
            symbols: ["crate::svd_with_exec"];
            scope: "..."; category: "..."; owner_module: "...";
            reason: "..."; verification: "..."; exit_condition: "...";
            status: retired;       // or `retained`
        }
    }
}