incin_backends/lib.rs
1//! Incin's execution backends: the built-in CPU backend plus feature-gated
2//! CUDA, WGPU, Metal, and external Candle implementations behind one
3//! dispatch surface, with the capability registries and codegen helpers
4//! backend authors share.
5#![cfg_attr(not(feature = "std"), no_std)]
6#[macro_use]
7extern crate alloc;
8
9pub mod backend_kind;
10pub mod capability;
11/// The generated support tables in `docs/capabilities.md` (`UX-013`).
12#[cfg(feature = "std")]
13pub mod capability_docs;
14pub mod codegen;
15#[macro_use]
16#[cfg(any(
17 feature = "cpu",
18 feature = "wgpu",
19 feature = "cuda",
20 feature = "metal",
21 feature = "external-candle"
22))]
23pub(crate) mod descriptor_bind;
24pub mod dispatch;
25mod dispatch_capability;
26#[cfg(any(feature = "cpu", feature = "wgpu", feature = "cuda"))]
27mod dispatch_executor;
28pub use dispatch::DispatchBackend;
29
30/// Collective transport contracts and optional implementations.
31#[cfg(feature = "distributed")]
32pub mod dist;
33
34/// Runtime detection of the best device this machine can actually run on.
35#[cfg(feature = "std")]
36pub mod detect;
37#[cfg(feature = "std")]
38pub use detect::{detect_device, detect_device_in};
39
40// Originally just the two backends that allocate device buffers by byte
41// length. The external Candle adapter was in this list and never called
42// `byte_len` - Candle owns its own allocations - so `--features
43// external-candle` without a GPU backend compiled a module whose only
44// function was dead, which `-D warnings` rejects. `unsupported` below keeps
45// `external-candle`, because the Candle adapter does use those macros.
46// `checked_numel` widened the gate to `cpu`: it is the one implementation
47// `cpu::stride` and `iteration` both call, and a CPU-only build needs it too.
48#[cfg(any(feature = "cpu", feature = "cuda", feature = "wgpu"))]
49pub(crate) mod bytes;
50// Every caller of these macros is a GPU or external backend, so a CPU-only
51// build declared four macros it could not use and warned about all of them.
52// Gated the same way `bytes` above it already is.
53#[cfg(any(
54 feature = "cuda",
55 feature = "wgpu",
56 feature = "external-candle",
57 feature = "metal"
58))]
59pub(crate) mod unsupported;
60
61// Loop-tiling and operand-iteration plumbing for CPU kernels. Internal by
62// the `pub(crate)`-is-default rule in docs/API_DESIGN.md: it takes runtime
63// dimensions and sits below the descriptor contract, so it is not part of
64// the backend-authoring surface.
65#[cfg(any(feature = "cpu", feature = "cuda"))]
66pub(crate) mod iteration;
67
68pub(crate) mod layout;
69
70#[cfg(any(feature = "cpu", feature = "cuda"))]
71pub(crate) mod quant;
72
73/// Compile-time SIMD lane-width resolution for type-specialized kernels.
74///
75/// [`simd_lanes`] returns the number of elements of type `T` that fit into one
76/// SIMD register on the compile target. It is a pure `const fn` - no runtime
77/// feature detection, no overhead.
78pub mod simd;
79pub use simd::simd_lanes;
80
81/// Test-only deterministic backend fault injection.
82#[cfg(all(feature = "test-utils", feature = "cpu"))]
83#[doc(hidden)]
84pub mod test_utils {
85 pub use crate::cpu::var::{AssignFailureGuard, fail_assign_on, fail_assignments_at};
86}
87
88#[cfg(any(
89 feature = "cuda",
90 feature = "metal",
91 feature = "wgpu",
92 feature = "autotune"
93))]
94pub(crate) mod kernel;
95#[cfg(any(
96 feature = "cuda",
97 feature = "metal",
98 feature = "wgpu",
99 feature = "autotune"
100))]
101pub mod tuning;
102
103/// Backend parameterized by a target execution engine.
104pub type EngineBackend<E, D> = crate::target::EngineBackend<E, D>;
105/// Backend bound directly to one native device kind.
106pub type NativeBackend<D> = crate::target::NativeBackend<D>;
107
108/// Unified backend selected by device.
109///
110/// Static devices resolve to concrete implementations. `IncinBackend<Dyn>`
111/// resolves to [`DispatchBackend`] and selects its implementation at runtime.
112pub type IncinBackend<D = incin_core::tensor::device::Cpu> = NativeBackend<D>;
113
114pub mod nn_target;
115pub mod target;
116
117/// Single import surface for backend authors.
118pub mod prelude {
119 #[cfg(any(feature = "cpu", feature = "wgpu", feature = "cuda"))]
120 pub use super::IncinBackend;
121 #[cfg(feature = "std")]
122 pub use super::detect::{detect_device, detect_device_in};
123 pub use super::{EngineBackend, NativeBackend};
124
125 // Extension methods only resolve when their trait is in scope, so the
126 // traits are exported alongside the types they operate on.
127 pub use super::nn_target::InitOnTarget;
128 #[cfg(feature = "external-candle")]
129 pub use super::target::Candle;
130 pub use super::target::{
131 DtypeTarget, EngineOn, EngineSpec, GeneratedFill, Native, PrecisionSpec, RuntimeEngine,
132 Target, TargetExt, TensorData, TensorTarget, precision,
133 };
134 pub use incin_core::shapes::ShapeSpec;
135}
136
137#[cfg(feature = "cpu")]
138pub mod cpu;
139
140#[cfg(feature = "cuda")]
141/// Native CUDA backend (preview).
142pub mod cuda;
143
144#[cfg(feature = "wgpu")]
145pub mod wgpu;
146
147#[cfg(feature = "metal")]
148pub mod metal;
149
150/// Third-party backend integrations, and the conformance suite an author of one
151/// runs against their own backend.
152///
153/// Unconditional since `EXE-010`. The module was gated on `external-candle`,
154/// which made the backend-authoring surface reachable only by enabling one
155/// particular integration; the Candle adapter inside it keeps that gate.
156pub mod external;
157
158#[cfg(feature = "telemetry")]
159pub mod telemetry;
160
161#[cfg(feature = "telemetry")]
162pub use telemetry::set_emitter;