tenferro_xla/executor.rs
1use std::fmt;
2
3use tenferro_runtime::program::SemanticProgram;
4use tenferro_runtime::CompiledGraph;
5use tenferro_tensor::Tensor;
6
7use crate::Error;
8use crate::{lower_to_stablehlo, Result, StableHloModule};
9
10/// Options for the experimental XLA executor.
11///
12/// # Examples
13///
14/// ```
15/// use tenferro_xla::XlaExecutorOptions;
16///
17/// let options = XlaExecutorOptions::default();
18/// assert_eq!(options, XlaExecutorOptions::default());
19/// ```
20#[derive(Clone, Copy, Default, PartialEq, Eq)]
21#[non_exhaustive]
22pub struct XlaExecutorOptions {
23 _private: (),
24}
25
26impl fmt::Debug for XlaExecutorOptions {
27 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
28 f.debug_struct("XlaExecutorOptions").finish()
29 }
30}
31
32/// Experimental peer executor for XLA/PJRT.
33///
34/// # Examples
35///
36/// ```
37/// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
38/// use tenferro_xla::XlaExecutor;
39///
40/// let trace = TraceContext::new();
41/// let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
42/// let mut compiler = GraphCompiler::new();
43/// let y = x.neg().unwrap();
44/// let program = compiler.compile(&y).unwrap();
45/// let module = XlaExecutor::default()
46/// .lower_compiled_to_stablehlo(&program)
47/// .unwrap();
48/// assert!(module.as_str().contains("stablehlo.negate"));
49/// ```
50pub struct XlaExecutor {
51 options: XlaExecutorOptions,
52 #[cfg(feature = "pjrt")]
53 plugin: Option<crate::pjrt::PjrtPlugin>,
54}
55
56impl fmt::Debug for XlaExecutor {
57 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
58 f.debug_struct("XlaExecutor")
59 .field("options", &self.options)
60 .field("has_loaded_pjrt_plugin", &self.has_loaded_pjrt_plugin())
61 .finish()
62 }
63}
64
65impl XlaExecutor {
66 /// Create an executor with explicit options.
67 ///
68 /// # Examples
69 ///
70 /// ```
71 /// use tenferro_xla::{XlaExecutor, XlaExecutorOptions};
72 ///
73 /// let executor = XlaExecutor::new(XlaExecutorOptions::default());
74 /// assert_eq!(executor.options(), XlaExecutorOptions::default());
75 /// ```
76 pub fn new(options: XlaExecutorOptions) -> Self {
77 Self {
78 options,
79 #[cfg(feature = "pjrt")]
80 plugin: None,
81 }
82 }
83
84 /// Create an executor by loading PJRT configuration from environment variables.
85 ///
86 /// Without the `pjrt` feature this returns [`Error::PjrtFeatureDisabled`].
87 ///
88 /// # Examples
89 ///
90 /// ```
91 /// use tenferro_xla::{Error, XlaExecutor};
92 ///
93 /// if let Err(err) = XlaExecutor::from_env() {
94 /// assert!(matches!(err, Error::PjrtFeatureDisabled | Error::MissingEnv { .. } | Error::PluginLoad { .. }));
95 /// }
96 /// ```
97 ///
98 /// # Errors
99 ///
100 /// Without `pjrt`, returns `Error::PjrtFeatureDisabled`. With `pjrt`,
101 /// returns `Error::MissingEnv` for an unset plugin path or
102 /// `Error::PluginLoad` with the typed dynamic-library source.
103 #[cfg(not(feature = "pjrt"))]
104 pub fn from_env() -> Result<Self> {
105 Err(Error::PjrtFeatureDisabled)
106 }
107
108 /// Create an executor by loading PJRT configuration from environment variables.
109 ///
110 /// # Examples
111 ///
112 /// ```
113 /// use tenferro_xla::XlaExecutor;
114 ///
115 /// let _ = XlaExecutor::from_env();
116 /// ```
117 ///
118 /// # Errors
119 ///
120 /// Returns `Error::MissingEnv` when the configured plugin-path variable is
121 /// unset, or `Error::PluginLoad` with the typed dynamic-library source
122 /// when the path cannot be loaded.
123 #[cfg(feature = "pjrt")]
124 pub fn from_env() -> Result<Self> {
125 Self::from_env_var(crate::TENFERRO_PJRT_PLUGIN_ENV)
126 }
127
128 /// Create an executor by loading a PJRT plugin path from a specific
129 /// environment variable.
130 ///
131 /// # Examples
132 ///
133 /// ```
134 /// use tenferro_xla::XlaExecutor;
135 ///
136 /// let _ = XlaExecutor::from_env_var("__TENFERRO_XLA_DOCS_UNSET");
137 /// ```
138 ///
139 /// # Errors
140 ///
141 /// Returns `Error::MissingEnv` when `var` is unset, or `Error::PluginLoad`
142 /// with the typed dynamic-library source when its value cannot be loaded.
143 #[cfg(feature = "pjrt")]
144 pub fn from_env_var(var: &'static str) -> Result<Self> {
145 let plugin = crate::pjrt::PjrtPlugin::load_from_env(var)?;
146 Ok(Self {
147 options: XlaExecutorOptions::default(),
148 plugin: Some(plugin),
149 })
150 }
151
152 /// Return the executor options.
153 ///
154 /// # Examples
155 ///
156 /// ```
157 /// use tenferro_xla::XlaExecutor;
158 ///
159 /// assert_eq!(XlaExecutor::default().options(), Default::default());
160 /// ```
161 pub fn options(&self) -> XlaExecutorOptions {
162 self.options
163 }
164
165 /// Return whether this executor owns a loaded PJRT plugin.
166 ///
167 /// # Examples
168 ///
169 /// ```
170 /// use tenferro_xla::XlaExecutor;
171 ///
172 /// assert!(!XlaExecutor::default().has_loaded_pjrt_plugin());
173 /// ```
174 pub fn has_loaded_pjrt_plugin(&self) -> bool {
175 #[cfg(feature = "pjrt")]
176 {
177 self.plugin.is_some()
178 }
179 #[cfg(not(feature = "pjrt"))]
180 {
181 false
182 }
183 }
184
185 /// Lower a graph program to StableHLO without executing it.
186 ///
187 /// # Examples
188 ///
189 /// ```
190 /// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
191 /// use tenferro_xla::XlaExecutor;
192 ///
193 /// let trace = TraceContext::new();
194 /// let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
195 /// let mut compiler = GraphCompiler::new();
196 /// let y = x.neg().unwrap();
197 /// let program = compiler.compile(&y).unwrap();
198 /// let module = XlaExecutor::default().lower_to_stablehlo(program.program()).unwrap();
199 /// assert!(module.as_str().contains("stablehlo.negate"));
200 /// ```
201 ///
202 /// # Errors
203 ///
204 /// Returns `Error::UnsupportedDType`, `Error::UnsupportedOp`, or
205 /// `Error::NonStaticShape` for unsupported graph content, and
206 /// `Error::InvalidProgram` for inconsistent graph metadata.
207 pub fn lower_to_stablehlo(&self, program: &SemanticProgram) -> Result<StableHloModule> {
208 lower_to_stablehlo(program)
209 }
210
211 /// Lower a compiled graph to StableHLO without executing it.
212 ///
213 /// This is the preferred public lowering boundary for graph users. It
214 /// consumes [`CompiledGraph`] directly and does not route through native
215 /// [`Runtime`](tenferro_runtime::Runtime) execution staging.
216 ///
217 /// # Examples
218 ///
219 /// ```
220 /// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
221 /// use tenferro_xla::XlaExecutor;
222 ///
223 /// let trace = TraceContext::new();
224 /// let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
225 /// let mut compiler = GraphCompiler::new();
226 /// let y = x.neg().unwrap();
227 /// let program = compiler.compile(&y).unwrap();
228 /// let module = XlaExecutor::default()
229 /// .lower_compiled_to_stablehlo(&program)
230 /// .unwrap();
231 /// assert!(module.as_str().contains("stablehlo.negate"));
232 /// ```
233 ///
234 /// # Errors
235 ///
236 /// Returns `Error::UnsupportedDType`, `Error::UnsupportedOp`, or
237 /// `Error::NonStaticShape` for unsupported graph content, and
238 /// `Error::InvalidProgram` for inconsistent graph metadata.
239 pub fn lower_compiled_to_stablehlo(&self, program: &CompiledGraph) -> Result<StableHloModule> {
240 crate::lower_compiled_to_stablehlo(program)
241 }
242
243 /// Execute a graph program through a loaded PJRT plugin and return all outputs.
244 ///
245 /// Inputs must match the ordered semantic-program input metadata exactly. This
246 /// experimental execution path supports the same exact-static-shape,
247 /// `F32`/`F64` subset as StableHLO lowering.
248 ///
249 /// # Examples
250 ///
251 /// ```
252 /// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
253 /// use tenferro_tensor::Tensor;
254 /// use tenferro_xla::{Error, XlaExecutor};
255 ///
256 /// let trace = TraceContext::new();
257 /// let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
258 /// let mut compiler = GraphCompiler::new();
259 /// let y = x.neg().unwrap();
260 /// let program = compiler.compile(&y).unwrap();
261 /// let input = Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
262 /// let err = XlaExecutor::default()
263 /// .run_many_with_inputs(program.program(), &[&input])
264 /// .unwrap_err();
265 /// assert!(matches!(err, Error::PjrtFeatureDisabled | Error::PjrtPluginNotLoaded));
266 /// ```
267 ///
268 /// # Errors
269 ///
270 /// Returns `Error::PjrtFeatureDisabled` or `Error::PjrtPluginNotLoaded`
271 /// when no PJRT executor is available, `Error::InvalidProgram` for input
272 /// count/dtype/shape mismatches, and `Error::PjrtCall` for vendor status
273 /// failures.
274 pub fn run_many_with_inputs(
275 &self,
276 program: &SemanticProgram,
277 inputs: &[&Tensor],
278 ) -> Result<Vec<Tensor>> {
279 #[cfg(feature = "pjrt")]
280 {
281 let Some(plugin) = self.plugin.as_ref() else {
282 return Err(Error::PjrtPluginNotLoaded);
283 };
284 crate::pjrt::run_many_with_inputs(plugin, program, inputs)
285 }
286 #[cfg(not(feature = "pjrt"))]
287 {
288 let _ = (program, inputs);
289 Err(Error::PjrtFeatureDisabled)
290 }
291 }
292
293 /// Execute a compiled graph through a loaded PJRT plugin and return all outputs.
294 ///
295 /// This wrapper accepts the same [`CompiledGraph`] that native runtime
296 /// execution consumes, while preserving the current XLA/PJRT exact-static
297 /// `F32`/`F64` subset. It delegates to the semantic-program PJRT executor
298 /// and does not route through native [`Runtime`](tenferro_runtime::Runtime)
299 /// execution.
300 ///
301 /// # Examples
302 ///
303 /// ```
304 /// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
305 /// use tenferro_tensor::Tensor;
306 /// use tenferro_xla::{Error, XlaExecutor};
307 ///
308 /// let trace = TraceContext::new();
309 /// let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
310 /// let mut compiler = GraphCompiler::new();
311 /// let y = x.neg().unwrap();
312 /// let program = compiler.compile(&y).unwrap();
313 /// let input = Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
314 /// let err = XlaExecutor::default()
315 /// .run_compiled_many_with_inputs(&program, &[&input])
316 /// .unwrap_err();
317 /// assert!(matches!(err, Error::PjrtFeatureDisabled | Error::PjrtPluginNotLoaded));
318 /// ```
319 ///
320 /// # Errors
321 ///
322 /// Returns `Error::PjrtFeatureDisabled` or `Error::PjrtPluginNotLoaded`
323 /// when no PJRT executor is available, `Error::InvalidProgram` for input
324 /// count/dtype/shape mismatches, and `Error::PjrtCall` for vendor status
325 /// failures.
326 pub fn run_compiled_many_with_inputs(
327 &self,
328 program: &CompiledGraph,
329 inputs: &[&Tensor],
330 ) -> Result<Vec<Tensor>> {
331 self.run_many_with_inputs(program.program(), inputs)
332 }
333
334 /// Execute a single-output graph program through a loaded PJRT plugin.
335 ///
336 /// # Examples
337 ///
338 /// ```
339 /// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
340 /// use tenferro_tensor::Tensor;
341 /// use tenferro_xla::{Error, XlaExecutor};
342 ///
343 /// let trace = TraceContext::new();
344 /// let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
345 /// let mut compiler = GraphCompiler::new();
346 /// let y = x.neg().unwrap();
347 /// let program = compiler.compile(&y).unwrap();
348 /// let input = Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
349 /// let err = XlaExecutor::default().run_with_inputs(program.program(), &[&input]).unwrap_err();
350 /// assert!(matches!(err, Error::PjrtFeatureDisabled | Error::PjrtPluginNotLoaded));
351 /// ```
352 ///
353 /// # Errors
354 ///
355 /// Propagates the `run_many_with_inputs` errors and returns
356 /// `Error::InvalidProgram` if the program does not have exactly one
357 /// output.
358 pub fn run_with_inputs(&self, program: &SemanticProgram, inputs: &[&Tensor]) -> Result<Tensor> {
359 single_output_tensor(self.run_many_with_inputs(program, inputs)?)
360 }
361
362 /// Execute a single-output compiled graph through a loaded PJRT plugin.
363 ///
364 /// # Examples
365 ///
366 /// ```
367 /// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
368 /// use tenferro_tensor::Tensor;
369 /// use tenferro_xla::{Error, XlaExecutor};
370 ///
371 /// let trace = TraceContext::new();
372 /// let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
373 /// let mut compiler = GraphCompiler::new();
374 /// let y = x.neg().unwrap();
375 /// let program = compiler.compile(&y).unwrap();
376 /// let input = Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
377 /// let err = XlaExecutor::default()
378 /// .run_compiled_with_inputs(&program, &[&input])
379 /// .unwrap_err();
380 /// assert!(matches!(err, Error::PjrtFeatureDisabled | Error::PjrtPluginNotLoaded));
381 /// ```
382 ///
383 /// # Errors
384 ///
385 /// Propagates the `run_compiled_many_with_inputs` errors and returns
386 /// `Error::InvalidProgram` if the program does not have exactly one output.
387 pub fn run_compiled_with_inputs(
388 &self,
389 program: &CompiledGraph,
390 inputs: &[&Tensor],
391 ) -> Result<Tensor> {
392 single_output_tensor(self.run_compiled_many_with_inputs(program, inputs)?)
393 }
394}
395
396impl Default for XlaExecutor {
397 fn default() -> Self {
398 Self::new(XlaExecutorOptions::default())
399 }
400}
401
402fn single_output_tensor(mut outputs: Vec<Tensor>) -> Result<Tensor> {
403 if outputs.len() != 1 {
404 return Err(crate::Error::InvalidProgram {
405 message: format!(
406 "PJRT single-output execution expected 1 output, got {}",
407 outputs.len()
408 ),
409 });
410 }
411 Ok(outputs.remove(0))
412}
413
414#[cfg(test)]
415mod tests {
416 use super::{single_output_tensor, XlaExecutor, XlaExecutorOptions};
417 use crate::Error;
418 use tenferro_runtime::GraphCompiler;
419 use tenferro_tensor::Tensor;
420
421 #[test]
422 fn executor_options_and_debug_are_directly_covered() {
423 let options = XlaExecutorOptions::default();
424 let executor = XlaExecutor::new(options);
425
426 assert_eq!(executor.options(), options);
427 assert!(!executor.has_loaded_pjrt_plugin());
428 assert_eq!(format!("{options:?}"), "XlaExecutorOptions");
429 assert!(format!("{executor:?}").contains("has_loaded_pjrt_plugin"));
430 }
431
432 #[test]
433 fn default_executor_reports_missing_pjrt_before_dispatch() {
434 let trace = tenferro_runtime::TraceContext::new();
435 let x = trace.from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
436 let mut compiler = GraphCompiler::new();
437 let program = compiler.compile(&x.neg().unwrap()).unwrap();
438 let input = Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
439
440 let err = XlaExecutor::default()
441 .run_many_with_inputs(program.program(), &[&input])
442 .unwrap_err();
443 assert!(matches!(
444 err,
445 Error::PjrtFeatureDisabled | Error::PjrtPluginNotLoaded
446 ));
447 let err = XlaExecutor::default()
448 .run_with_inputs(program.program(), &[&input])
449 .unwrap_err();
450 assert!(matches!(
451 err,
452 Error::PjrtFeatureDisabled | Error::PjrtPluginNotLoaded
453 ));
454 }
455
456 #[test]
457 fn single_output_tensor_rejects_zero_or_multiple_outputs() {
458 let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap();
459 assert_eq!(
460 single_output_tensor(vec![tensor.duplicate().unwrap()])
461 .unwrap()
462 .as_slice::<f64>()
463 .unwrap(),
464 &[1.0]
465 );
466
467 let err = single_output_tensor(Vec::new()).unwrap_err();
468 assert!(
469 err.to_string().contains("got 0"),
470 "expected zero-output error, got {err:?}"
471 );
472
473 let err = single_output_tensor(vec![tensor.duplicate().unwrap(), tensor]).unwrap_err();
474 assert!(
475 err.to_string().contains("got 2"),
476 "expected multi-output error, got {err:?}"
477 );
478 }
479}