Skip to main content

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}