Skip to main content

tenferro_extension_macros/
lib.rs

1//! Procedural macros for tenferro extension crates.
2//!
3//! # Examples
4//!
5//! ```
6//! use tenferro_extension_macros::ExtensionFamilyId;
7//!
8//! #[derive(ExtensionFamilyId)]
9//! #[tenferro_extension(namespace = "my-crate", name = "fft", version = 1)]
10//! struct FftOp;
11//!
12//! assert_eq!(FftOp::FAMILY_ID, "my-crate.fft.v1");
13//! ```
14
15mod api_ops;
16
17use proc_macro::TokenStream;
18use quote::{format_ident, quote};
19use syn::parse::{Parse, ParseStream};
20use syn::{parse_macro_input, DeriveInput, Expr, ExprLit, Ident, Lit, Path, Token};
21
22#[derive(Debug, Default)]
23struct ExtensionArgs {
24    namespace: Option<String>,
25    name: Option<String>,
26    version: Option<u64>,
27}
28
29struct RuntimeArgs {
30    runtime: Ident,
31    family_id: Path,
32    op_type: Path,
33    execute_reads: Option<Path>,
34    execute_in_session: Option<Path>,
35    session_supported: Option<Path>,
36    backend_bound: Path,
37}
38
39impl Parse for ExtensionArgs {
40    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
41        let mut args = Self::default();
42        while !input.is_empty() {
43            let key: syn::Ident = input.parse()?;
44            input.parse::<Token![=]>()?;
45            let value: Expr = input.parse()?;
46            match key.to_string().as_str() {
47                "namespace" => args.namespace = Some(expect_string(value, "namespace")?),
48                "name" => args.name = Some(expect_string(value, "name")?),
49                "version" => args.version = Some(expect_u64(value, "version")?),
50                other => {
51                    return Err(syn::Error::new(
52                        key.span(),
53                        format!("unsupported tenferro_extension argument {other:?}"),
54                    ));
55                }
56            }
57            if input.is_empty() {
58                break;
59            }
60            input.parse::<Token![,]>()?;
61        }
62        Ok(args)
63    }
64}
65
66impl Parse for RuntimeArgs {
67    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
68        let mut runtime = None;
69        let mut family_id = None;
70        let mut op_type = None;
71        let mut execute_reads = None;
72        let mut execute_in_session = None;
73        let mut session_supported = None;
74        let mut backend_bound = None;
75
76        while !input.is_empty() {
77            let key: Ident = input.parse()?;
78            input.parse::<Token![=]>()?;
79            match key.to_string().as_str() {
80                "runtime" => runtime = Some(input.parse()?),
81                "family_id" => family_id = Some(input.parse()?),
82                "op_type" => op_type = Some(input.parse()?),
83                "execute_reads" => execute_reads = Some(input.parse()?),
84                "execute_in_session" => execute_in_session = Some(input.parse()?),
85                "session_supported" => session_supported = Some(input.parse()?),
86                "backend_bound" => backend_bound = Some(input.parse()?),
87                other => {
88                    return Err(syn::Error::new(
89                        key.span(),
90                        format!("unsupported define_extension_runtime argument {other:?}"),
91                    ));
92                }
93            }
94            if input.is_empty() {
95                break;
96            }
97            input.parse::<Token![,]>()?;
98        }
99
100        Ok(Self {
101            runtime: required(runtime, "runtime")?,
102            family_id: required(family_id, "family_id")?,
103            op_type: required(op_type, "op_type")?,
104            execute_reads,
105            execute_in_session,
106            session_supported,
107            backend_bound: backend_bound
108                .unwrap_or_else(|| syn::parse_quote!(tenferro_tensor::Engine)),
109        })
110    }
111}
112
113/// Derive an inherent `FAMILY_ID` constant for an extension payload type.
114///
115/// The required attribute is:
116/// `#[tenferro_extension(namespace = "...", version = N)]`.
117/// `name = "..."` is optional; when omitted, the Rust type name is converted
118/// to snake_case.
119#[proc_macro_derive(ExtensionFamilyId, attributes(tenferro_extension))]
120pub fn derive_extension_family_id(input: TokenStream) -> TokenStream {
121    let input = parse_macro_input!(input as DeriveInput);
122    match expand_extension_family_id(input) {
123        Ok(tokens) => tokens.into(),
124        Err(err) => err.to_compile_error().into(),
125    }
126}
127
128/// Generate a standard extension module, preparation engine, and prepared
129/// operation.
130///
131/// Exactly one execution route must be supplied.
132///
133/// * `execute_reads` runs the operation inside the runtime-formed context and
134///   has this signature:
135///   `fn<B: Engine + ?Sized>(&OpType, &[TensorRead<'_>], &mut ExtensionExecutionContext<'_, B>)`.
136///   The generated owner entry opens the backend session and the context
137///   borrows it (`B` is `dyn Engine`), so the callback never runs on
138///   the owner. Prefer the session route below for new extensions.
139/// * the session route (`execute_in_session` + `session_supported`) is the
140///   preferred one: `session_supported` has signature
141///   `fn<B: BackendBound + 'static>(&OpType) -> bool` and `execute_in_session`
142///   has signature
143///   `fn(&OpType, &mut dyn Engine, &mut ExtensionCacheStore, &[TensorRead<'_>])`.
144///   With it, the generated owner entry forms the session itself and hands the
145///   extension only a session, so no operation ever runs on the owner.
146///
147/// The removed legacy `execute` argument is rejected, not silently ignored.
148#[proc_macro]
149pub fn define_extension_runtime(input: TokenStream) -> TokenStream {
150    let args = parse_macro_input!(input as RuntimeArgs);
151    match expand_extension_runtime(args) {
152        Ok(tokens) => tokens.into(),
153        Err(err) => err.to_compile_error().into(),
154    }
155}
156
157/// Generate public-API traits, forwarding impls, rustdoc, metadata constants
158/// and a Markdown renderer from one operation registry per family.
159///
160/// The registry is the single source of truth: this macro generates method
161/// declarations and forwarding impls only; numerical bodies stay hand-written
162/// in the module named by each layer's `forward` key. See
163/// `tests/api_ops.rs` for a complete working registry and
164/// `docs/design/api-grammar/implementation.md` section 4 for the design.
165///
166/// # Examples
167///
168/// The grammar (a `text` block, because a proc-macro crate cannot invoke its
169/// own macro from a doctest):
170///
171/// ```text
172/// api_ops! {
173///     family: linalg;
174///     layer concrete {
175///         trait_doc: "...";
176///         trait_def: pub trait LinalgOps: AsView;
177///         impl_def: impl<X: AsView + ?Sized> LinalgOps for X;
178///         method_where: [];
179///         receiver: self;            // or `session` + `first_arg: &T;` (`&mut self`),
180///                                    // or `context` (`&self`, first operand is an argument)
181///         tensor_arg: &impl AsView;
182///         exec: &mut dyn Engine;     // optional
183///         dest: Dest;                // optional; enables `_into`
184///         result: Result;
185///         types { V = Tensor, R = Tensor } // `S` maps an operand typed `S`
186///         forward: crate::api::concrete;
187///         cfg: feature = "autodiff";   // optional; gates the trait and impl
188///         extra_decls { /* hand-written trait items (exception entries) */ }
189///         extra_impls { /* their impls */ }
190///     }
191///     layer core_eager { describe_only; }
192///     op svd {
193///         summary: "...";
194///         operands: (a);             // `name: Type` for typed operands
195///         options: SvdOptions;       // `options: none;`: no options type, no `_with`
196///         // optional: `generics: <Y: Bound>;` (method generics) and
197///         // `associated;` (no receiver, `Self: Sized`, e.g. concatenate)
198///         output: Svd<V, R>;         // `V`/`R`/... are the layer's `types` keys
199///         dtypes: "...";
200///         layers: [concrete];
201///         into: [];                  // overwrite | accumulate | scaled; with
202///                                    // `options: none;` the `_into` form takes no options
203///         layout: "...";
204///         errors: [Validation, NumericalFailure(NonConvergence)];
205///         omissions: [];
206///         example concrete: r#"..."#;
207///         // optional, on a described layer: the canonical compiled signature
208///         // as `api/*.txt` renders it; the registry-conformance check requires it
209///         signature core_eager: "pub fn tenferro_ad::EagerSession<'_>::svd(..) -> ..";
210///     }
211///     exceptions {
212///         E08 {
213///             symbols: ["crate::svd_with_exec"];
214///             scope: "..."; category: "..."; owner_module: "...";
215///             reason: "..."; verification: "..."; exit_condition: "...";
216///             status: retired;       // or `retained`
217///         }
218///     }
219/// }
220/// ```
221#[proc_macro]
222pub fn api_ops(input: TokenStream) -> TokenStream {
223    let result = (|input: TokenStream| -> syn::Result<proc_macro2::TokenStream> {
224        let registry = syn::parse::Parser::parse(api_ops::parse_registry, input)?;
225        registry.validate()?;
226        api_ops::expand(&registry)
227    })(input);
228    match result {
229        Ok(tokens) => tokens.into(),
230        Err(err) => err.to_compile_error().into(),
231    }
232}
233
234fn expand_extension_family_id(input: DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
235    let mut parsed = None;
236    for attr in &input.attrs {
237        if attr.path().is_ident("tenferro_extension") {
238            let args = attr.parse_args::<ExtensionArgs>()?;
239            parsed = Some(args);
240        }
241    }
242    let args = parsed.ok_or_else(|| {
243        syn::Error::new_spanned(
244            &input.ident,
245            "missing #[tenferro_extension(namespace = \"...\", version = N)]",
246        )
247    })?;
248    let namespace = args.namespace.ok_or_else(|| {
249        syn::Error::new_spanned(&input.ident, "missing tenferro_extension namespace")
250    })?;
251    let version = args.version.ok_or_else(|| {
252        syn::Error::new_spanned(&input.ident, "missing tenferro_extension version")
253    })?;
254    let name = args
255        .name
256        .unwrap_or_else(|| to_snake_case(&input.ident.to_string()));
257    let family_id = format!("{namespace}.{name}.v{version}");
258    let ident = input.ident;
259
260    Ok(quote! {
261        impl #ident {
262            /// Stable extension family identifier generated by `ExtensionFamilyId`.
263            pub const FAMILY_ID: &'static str = #family_id;
264        }
265    })
266}
267
268fn expand_extension_runtime(args: RuntimeArgs) -> syn::Result<proc_macro2::TokenStream> {
269    let RuntimeArgs {
270        runtime,
271        family_id,
272        op_type,
273        execute_reads,
274        execute_in_session,
275        session_supported,
276        backend_bound,
277    } = args;
278    let module = format_ident!("{}Module", runtime);
279    let planning_config = format_ident!("{}PlanningConfig", runtime);
280    let prepared_operation = format_ident!("{}PreparedOperation", runtime);
281    let owner_execute = match (&execute_reads, &execute_in_session) {
282        (None, Some(execute_in_session)) => quote! {
283            fn execute(
284                &self,
285                context: &mut tenferro_runtime::ErasedExecutionContext<'_>,
286                extension_caches: &mut tenferro_runtime::ExtensionCacheStore,
287                inputs: &[tenferro_tensor::TensorRead<'_>],
288            ) -> tenferro_runtime::Result<Vec<tenferro_tensor::Tensor>> {
289                // The context is the engine itself; the extension runs on it.
290                let engine = context
291                    .downcast_mut::<B>(self.binding.context_identity())
292                    .map_err(|source| tenferro_runtime::Error::runtime_state_source(
293                        "extension",
294                        tenferro_runtime::ErrorPhase::Execution,
295                        source,
296                    ))?;
297                let engine: &mut dyn tenferro_tensor::Engine = engine;
298                Ok(#execute_in_session(&self.op, engine, extension_caches, inputs)?)
299            }
300        },
301        (Some(execute_reads), None) => quote! {
302            fn execute(
303                &self,
304                context: &mut tenferro_runtime::ErasedExecutionContext<'_>,
305                extension_caches: &mut tenferro_runtime::ExtensionCacheStore,
306                inputs: &[tenferro_tensor::TensorRead<'_>],
307            ) -> tenferro_runtime::Result<Vec<tenferro_tensor::Tensor>> {
308                let engine = context
309                    .downcast_mut::<B>(self.binding.context_identity())
310                    .map_err(|source| tenferro_runtime::Error::runtime_state_source(
311                        "extension",
312                        tenferro_runtime::ErrorPhase::Execution,
313                        source,
314                    ))?;
315                let engine: &mut dyn tenferro_tensor::Engine = engine;
316                let mut ctx = tenferro_runtime::ExtensionExecutionContext::new(
317                    engine,
318                    extension_caches,
319                );
320                Ok(#execute_reads(&self.op, inputs, &mut ctx)?)
321            }
322        },
323        (Some(execute_reads), Some(_)) => {
324            return Err(syn::Error::new_spanned(
325                execute_reads,
326                "supply either execute_reads or execute_in_session, not both",
327            ))
328        }
329        (None, None) => {
330            return Err(syn::Error::new_spanned(
331                &op_type,
332                "either execute_reads or execute_in_session must be supplied",
333            ))
334        }
335    };
336    let session_methods = match (execute_in_session, session_supported) {
337        (Some(execute_in_session), Some(session_supported)) => quote! {
338            fn supports_session(&self) -> bool {
339                #session_supported::<B>(&self.op)
340            }
341
342            fn execute_in_session(
343                &self,
344                session: &mut dyn tenferro_tensor::Engine,
345                extension_caches: &mut tenferro_runtime::ExtensionCacheStore,
346                inputs: &[tenferro_tensor::TensorRead<'_>],
347            ) -> tenferro_runtime::Result<Vec<tenferro_tensor::Tensor>> {
348                Ok(#execute_in_session(&self.op, session, extension_caches, inputs)?)
349            }
350        },
351        (None, None) => quote! {},
352        (Some(path), None) | (None, Some(path)) => {
353            return Err(syn::Error::new_spanned(
354                path,
355                "execute_in_session and session_supported must be supplied together",
356            ))
357        }
358    };
359    Ok(quote! {
360        pub(crate) struct #runtime<B: #backend_bound + 'static> {
361            engine_id: tenferro_runtime::EngineId,
362            _backend: std::marker::PhantomData<fn() -> B>,
363        }
364
365        pub(crate) struct #module<B: #backend_bound + 'static> {
366            module_id: tenferro_runtime::ExtensionModuleId,
367            engine_id: tenferro_runtime::EngineId,
368            _backend: std::marker::PhantomData<fn() -> B>,
369        }
370
371        #[derive(Debug, Default)]
372        pub(crate) struct #planning_config;
373
374        pub(crate) struct #prepared_operation<B: #backend_bound + 'static> {
375            binding: tenferro_runtime::PreparedOperationBinding,
376            specialization: tenferro_runtime::SpecializationProjection,
377            op: #op_type,
378            _backend: std::marker::PhantomData<fn() -> B>,
379        }
380
381        impl<B: #backend_bound + 'static> std::fmt::Debug for #runtime<B> {
382            fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
383                formatter
384                    .debug_struct(stringify!(#runtime))
385                    .field("family_id", &#family_id)
386                    .field("engine_id", &self.engine_id)
387                    .field("backend_type", &std::any::type_name::<B>())
388                    .finish()
389            }
390        }
391
392        impl<B: #backend_bound + 'static> std::fmt::Debug for #module<B> {
393            fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
394                formatter
395                    .debug_struct(stringify!(#module))
396                    .field("module_id", &self.module_id)
397                    .field("engine_id", &self.engine_id)
398                    .field("backend_type", &std::any::type_name::<B>())
399                    .finish()
400            }
401        }
402
403        impl<B: #backend_bound + 'static> std::fmt::Debug for #prepared_operation<B> {
404            fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
405                formatter
406                    .debug_struct(stringify!(#prepared_operation))
407                    .field("family_id", &#family_id)
408                    .field("binding", &self.binding)
409                    .field("specialization", &self.specialization)
410                    .field("backend_type", &std::any::type_name::<B>())
411                    .finish_non_exhaustive()
412            }
413        }
414
415        impl<B: #backend_bound + 'static> tenferro_runtime::ExtensionEngine for #runtime<B>
416        where
417            #op_type: Clone + Send + Sync + 'static,
418        {
419            fn family_id(&self) -> &'static str {
420                #family_id
421            }
422
423            fn engine_id(&self) -> &tenferro_runtime::EngineId {
424                &self.engine_id
425            }
426
427            fn context_identity(&self) -> tenferro_runtime::ExecutionContextIdentity {
428                tenferro_runtime::ExecutionContextIdentity::of::<B>()
429            }
430
431            fn prepare(
432                &self,
433                request: tenferro_runtime::ExtensionPrepareRequest<'_>,
434            ) -> std::result::Result<tenferro_runtime::PrepareCapability, tenferro_runtime::PrepareError> {
435                let op = request
436                    .operation()
437                    .as_any()
438                    .downcast_ref::<#op_type>()
439                    .cloned()
440                    .ok_or_else(|| tenferro_runtime::PrepareError::ProviderContract {
441                        source: tenferro_runtime::ProviderContractError::WrongOperationFamily {
442                            expected: tenferro_runtime::CoreCapabilityKind::Elementwise,
443                            operation: #family_id,
444                        },
445                    })?;
446                let prepared = std::sync::Arc::new(#prepared_operation::<B> {
447                    binding: request.binding().clone(),
448                    specialization: request.specialization().clone(),
449                    op,
450                    _backend: std::marker::PhantomData,
451                });
452                Ok(tenferro_runtime::PrepareCapability::Prepared(
453                    tenferro_runtime::PreparedOperationPlan::executable(prepared.clone(), prepared)
454                ))
455            }
456        }
457
458        impl tenferro_runtime::ExtensionPlanningConfig for #planning_config {
459            fn family_id(&self) -> &'static str {
460                #family_id
461            }
462
463            fn as_any(&self) -> &dyn std::any::Any {
464                self
465            }
466
467            fn payload_hash(&self, state: &mut dyn std::hash::Hasher) {
468                state.write_u8(0);
469            }
470
471            fn payload_eq(&self, other: &dyn tenferro_runtime::ExtensionPlanningConfig) -> bool {
472                other.as_any().downcast_ref::<Self>().is_some()
473            }
474
475            fn retained_bytes(&self) -> usize {
476                0
477            }
478        }
479
480        impl<B: #backend_bound + 'static> tenferro_runtime::PreparedOperation for #prepared_operation<B>
481        where
482            #op_type: Clone + Send + Sync + 'static,
483        {
484            fn binding(&self) -> &tenferro_runtime::PreparedOperationBinding {
485                &self.binding
486            }
487
488            fn specialization(&self) -> &tenferro_runtime::SpecializationProjection {
489                &self.specialization
490            }
491
492            fn retained_bytes(&self) -> usize {
493                0
494            }
495
496        }
497
498        impl<B: #backend_bound + 'static> tenferro_runtime::PreparedOperationExecutor for #prepared_operation<B>
499        where
500            #op_type: Clone + Send + Sync + 'static,
501        {
502            #owner_execute
503
504            #session_methods
505        }
506
507        impl<B: #backend_bound + 'static> tenferro_runtime::ExtensionModule for #module<B>
508        where
509            #op_type: Clone + Send + Sync + 'static,
510        {
511            fn module_id(&self) -> &tenferro_runtime::ExtensionModuleId {
512                &self.module_id
513            }
514
515            fn configure(
516                &self,
517                registrar: &mut tenferro_runtime::ExtensionModuleRegistrar<'_>,
518            ) -> std::result::Result<(), tenferro_runtime::ExtensionModuleError> {
519                registrar.register_engine(std::sync::Arc::new(#runtime::<B> {
520                    engine_id: self.engine_id.clone(),
521                    _backend: std::marker::PhantomData,
522                }))?;
523                registrar.register_planning_config(
524                    self.engine_id.clone(),
525                    std::sync::Arc::new(#planning_config),
526                )?;
527                Ok(())
528            }
529        }
530
531        #[doc = "Build this extension module for one runtime engine."]
532        #[doc = "\n# Errors\n\nReturns `RuntimeConfigError::MalformedIdentity` when the generated module identifier is invalid."]
533        pub fn extension_module<B: #backend_bound + 'static>(
534            engine_id: tenferro_runtime::EngineId,
535        ) -> std::result::Result<
536            std::sync::Arc<dyn tenferro_runtime::ExtensionModule>,
537            tenferro_runtime::RuntimeConfigError,
538        >
539        where
540            #op_type: Clone + Send + Sync + 'static,
541        {
542            Ok(std::sync::Arc::new(#module::<B> {
543                module_id: tenferro_runtime::ExtensionModuleId::new(format!("{}.module", #family_id))?,
544                engine_id,
545                _backend: std::marker::PhantomData,
546            }))
547        }
548
549    })
550}
551
552fn expect_string(value: Expr, field: &str) -> syn::Result<String> {
553    match value {
554        Expr::Lit(ExprLit {
555            lit: Lit::Str(value),
556            ..
557        }) => Ok(value.value()),
558        other => Err(syn::Error::new_spanned(
559            other,
560            format!("{field} must be a string literal"),
561        )),
562    }
563}
564
565fn expect_u64(value: Expr, field: &str) -> syn::Result<u64> {
566    match value {
567        Expr::Lit(ExprLit {
568            lit: Lit::Int(value),
569            ..
570        }) => value.base10_parse(),
571        other => Err(syn::Error::new_spanned(
572            other,
573            format!("{field} must be an integer literal"),
574        )),
575    }
576}
577
578fn required<T>(value: Option<T>, field: &str) -> syn::Result<T> {
579    value.ok_or_else(|| syn::Error::new(proc_macro2::Span::call_site(), format!("missing {field}")))
580}
581
582fn to_snake_case(input: &str) -> String {
583    let mut out = String::new();
584    let mut prev_lower_or_digit = false;
585    for ch in input.chars() {
586        if ch.is_ascii_uppercase() {
587            if prev_lower_or_digit {
588                out.push('_');
589            }
590            out.push(ch.to_ascii_lowercase());
591            prev_lower_or_digit = false;
592        } else {
593            prev_lower_or_digit = ch.is_ascii_lowercase() || ch.is_ascii_digit();
594            out.push(ch);
595        }
596    }
597    out
598}
599
600#[cfg(test)]
601mod tests;