1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
//! Automatic device selection, in the two places it can honestly happen.
//!
//! There are exactly two questions, and they have different answers at
//! different times:
//!
//! 1. **Which backend was this binary built to target?** Answered at compile
//! time by `BestDevice` / [`best_device!`](crate::best_device), from the
//! enabled Cargo features, in the order CUDA -> Metal -> WGPU -> CPU.
//! 2. **Which backend can actually run here?** Answered at runtime by probing
//! real hardware. That lives in `incin-backends::detect_device`, returns a
//! [`DeviceId`](crate::tensor::device::DeviceId), and is used with the fully
//! dynamic tier.
//!
//! # Why the compile-time half does not probe hardware
//!
//! `PROPOSALS.md` ยง1.2.2 fixes the meaning of a static device: *"'Static
//! device' means a compile-time logical selector, not compile-time hardware
//! discovery."* The Macro policy section adds that macros are *"inappropriate
//! for hardware discovery"*, and decision `D-006` records that device
//! existence is never provable before runtime, which is why every `Device`
//! constructor is fallible.
//!
//! Those rules exist because the build host and the run host are routinely
//! different machines:
//!
//! * `docker build` does not expose the GPU even on a GPU host -- `--gpus` is a
//! *run* flag. A probing macro would compile every containerized deployment
//! to CPU, which is the most common way an ML binary ships.
//! * Cross-compilation probes the wrong machine by construction.
//! * A GPU-less CI runner would silently produce a binary with *different
//! types* than a developer's machine, so a type error appears only in CI.
//! * Proc-macro expansion is cached and has no `rerun-if-env-changed`
//! equivalent, so a probe result can outlive the hardware that produced it.
//!
//! Selecting from features is deterministic, reproducible, and cross-compile
//! safe; probing at runtime is correct about the machine that actually
//! executes. Between them there is no case left for probing at build time.
use crateCpu;
use crateCudaN;
use crateMetalN;
use crateWgpuN;
/// The most capable device family this build can target, at ordinal 0.
///
/// Resolved from the features enabled on `incin-core` itself, in the order
/// CUDA -> Metal -> WGPU -> CPU. `incin-backends` forwards its own `cuda`/`metal`/`wgpu` features
/// here, so enabling `incin-backends/cuda` is what makes this `CudaN<U0>`.
///
/// This names a *logical selector*. It does not assert that the hardware
/// exists; that is checked when the device is initialized, and is why
/// `Device::to_incin` returns a `Result`.
///
/// ```rust
/// # extern crate incin_core as incin;
/// use incin::prelude::*;
/// // Naming the selector and building its stored field costs nothing and
/// // cannot fail, whichever family the features picked.
/// let field = <BestDevice as Device>::init(());
/// // Resolving it is where the hardware question is finally asked, which is
/// // why this returns a `Result` instead of a `DeviceId`.
/// let resolved = <BestDevice as Device>::to_incin(&field);
/// # let _ = resolved;
/// ```
pub type BestDevice = ;
/// The most capable device family this build can target, at ordinal 0.
pub type BestDevice = ;
/// The most capable device family this build can target, at ordinal 0.
pub type BestDevice = ;
/// The most capable device family this build can target, at ordinal 0.
pub type BestDevice = Cpu;
/// [`BestDevice`] at a caller-chosen ordinal.
///
/// `N` selects the device ordinal for the GPU families. The CPU has no
/// ordinal, so when this build resolves to `Cpu` the parameter is accepted
/// and ignored rather than failing to compile -- code written for a GPU build
/// still compiles on a CPU-only one, which is the whole point of the alias.
pub type BestDeviceAt<N> = ;
/// [`BestDevice`] at a caller-chosen ordinal.
pub type BestDeviceAt<N> = ;
/// [`BestDevice`] at a caller-chosen ordinal.
pub type BestDeviceAt<N> = ;
/// [`BestDevice`] at a caller-chosen ordinal, which the CPU ignores.
pub type BestDeviceAt<N> = ;
/// [`Cpu`] carrying an ignored ordinal parameter.
///
/// Exists only so [`BestDeviceAt`] has the same arity in every build. A bare
/// `type BestDeviceAt<N> = Cpu;` would also compile, but this spells out that
/// the ordinal is deliberately discarded rather than accidentally dropped.
pub type CpuAt<N> = Device;
/// Projects an ordinal-carrying pair back to its device.
/// Names the best device this build can target.
///
/// * `best_device!()` - ordinal 0, i.e. [`BestDevice`].
/// * `best_device!(U2)` - ordinal 2 via a `typenum` type, i.e.
/// [`BestDeviceAt<U2>`](BestDeviceAt). Ignored on a CPU-only build.
///
/// This is a naming convenience over the two aliases and nothing more. It
/// expands to a public type path, performs no discovery, and touches neither
/// the filesystem nor the network - the conditions `PROPOSALS.md` puts on every
/// public macro. Resolving the `cfg` inside this crate rather than inside the
/// macro body is load bearing: a `#[cfg(feature = "cuda")]` written in a
/// `macro_rules!` body is evaluated against the *calling* crate's features, so
/// it would read as disabled in every downstream crate and silently select CPU.
///
/// ```rust
/// type Dev = incin_core::best_device!();
/// type Second = incin_core::best_device!(incin_core::typenum::U1);
/// ```