Skip to main content

burn_capture/
capture.rs

1//! Non-executing router channel used to capture Burn operation graphs.
2
3use alloc::{boxed::Box, collections::BTreeMap, format, string::String, sync::Arc, vec::Vec};
4use burn_backend::{
5    BoolStore, DType, DTypeUsage, DTypeUsageSet, DeviceId, DeviceOps, DeviceSettings,
6    ExecutionError, RouterDeviceType, Shape, TensorData,
7};
8use burn_ir::{
9    GraphBindings, GraphId, GraphIr, IrVisitorMut, OperationIr, TensorId, TensorIr, TensorStatus,
10};
11use burn_std::{device::Device, future::DynFut};
12use hashbrown::{HashMap, HashSet};
13use portable_atomic::{AtomicU64, Ordering};
14use spin::Mutex;
15
16use burn_router::{
17    Graph, MultiBackendBridge, RouterChannel, RouterClient, RouterClientRegistration, RouterTensor,
18    register_scoped_client,
19};
20
21static DEVICE_COUNTER: AtomicU64 = AtomicU64::new(0);
22static TENSOR_COUNTER: AtomicU64 = AtomicU64::new(0);
23
24/// Backend type that records operations instead of executing them.
25pub type CaptureBackend = burn_router::BackendRouter<CaptureChannel>;
26
27/// Reusable logical device for isolated graph-capture scopes.
28///
29/// Device identifiers are deliberately monotonic and never recycled. This keeps stale tensor
30/// handles from aliasing a newer capture device without requiring an identity registry. Since a
31/// [`DeviceId`] has a `u16` backend-local index, creating more than 65,536 capture devices in one
32/// process will panic. A device can be reused for any number of sequential capture scopes.
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub struct CaptureDevice {
35    id: u16,
36}
37
38impl CaptureDevice {
39    /// Capture one operation scope on this reusable device.
40    ///
41    /// The closure receives a [`CaptureScope`] and must return the token produced by
42    /// [`CaptureScope::complete`], declaring both the runtime input and requested output tensor
43    /// IDs. A fresh session is installed before the closure runs and is always unregistered
44    /// afterward, including while unwinding from a panic. Only one scope may be active on a capture
45    /// device at a time. Calling `complete` closes the session immediately, so the closure must not
46    /// perform more tensor operations before returning the completion token.
47    pub fn capture_scope(
48        &self,
49        capture: impl FnOnce(CaptureScope) -> CompletedCaptureScope,
50    ) -> Result<CapturedGraph, CaptureError> {
51        let session = Arc::new(CaptureSession::default());
52        let client = CaptureClient::new(*self, session.clone());
53        // Bind this reusable device to the new session client for exactly this scope. BackendRouter
54        // operations call `get_client`, which now finds this client instead of trying the channel's
55        // intentionally unsupported unscoped initialization path.
56        let registration = register_scoped_client::<CaptureChannel>(self, client.clone())
57            .ok_or(CaptureError::AlreadyActive)?;
58        let guard = CaptureScopeGuard {
59            client,
60            _registration: registration,
61        };
62        guard.complete(capture(CaptureScope { session }))
63    }
64}
65
66impl Default for CaptureDevice {
67    fn default() -> Self {
68        let id = DEVICE_COUNTER.fetch_add(1, Ordering::Relaxed);
69        assert!(
70            id <= u16::MAX as u64,
71            "capture device identifier space exhausted"
72        );
73        Self { id: id as u16 }
74    }
75}
76
77impl Device for CaptureDevice {
78    fn from_id(device_id: DeviceId) -> Self {
79        assert_eq!(
80            device_id.type_id,
81            u16::from(RouterDeviceType::Capture),
82            "invalid capture device type"
83        );
84        Self {
85            id: device_id.index_id,
86        }
87    }
88
89    fn to_id(&self) -> DeviceId {
90        DeviceId {
91            type_id: RouterDeviceType::Capture.into(),
92            index_id: self.id,
93        }
94    }
95}
96
97impl DeviceOps for CaptureDevice {
98    fn defaults(&self) -> DeviceSettings {
99        DeviceSettings::new(
100            DType::F32,
101            DType::I64,
102            DType::Bool(BoolStore::U8),
103            Default::default(),
104        )
105    }
106}
107
108/// Final result of a capture scope.
109#[derive(Clone, Debug)]
110pub struct CapturedGraph {
111    /// Ordered operation graph with caller-declared boundaries.
112    pub graph: GraphIr,
113    /// Concrete values supplied through tensor initialization, keyed by tensor ID.
114    pub values: BTreeMap<TensorId, TensorData>,
115}
116
117/// Token passed to a [`CaptureDevice::capture_scope`] closure.
118///
119/// Call [`complete`](Self::complete) after recording the operations in the scope. The closure's
120/// return type requires the resulting completion token, so a successful capture cannot omit its
121/// explicit graph boundaries.
122#[derive(Debug)]
123pub struct CaptureScope {
124    // The scope owns the authority to close its session. Keeping this private prevents callers
125    // from manufacturing completion tokens detached from the active router registration.
126    session: Arc<CaptureSession>,
127}
128
129impl CaptureScope {
130    /// Complete the scope with ordered runtime input and graph output tensor IDs.
131    ///
132    /// Module parameters and other initialized constants should not be listed as runtime inputs;
133    /// their retained tensor values remain available in [`CapturedGraph::values`].
134    /// The active session is closed before this returns; subsequent operations through tensors or
135    /// the capture device are rejected even if the closure has not returned yet.
136    pub fn complete(
137        self,
138        inputs: impl IntoIterator<Item = TensorId>,
139        outputs: impl IntoIterator<Item = TensorId>,
140    ) -> CompletedCaptureScope {
141        let inputs = inputs.into_iter().collect();
142        let outputs = outputs.into_iter().collect();
143        self.session.state.lock().close();
144        CompletedCaptureScope { inputs, outputs }
145    }
146}
147
148/// Completion token required from a [`CaptureDevice::capture_scope`] closure.
149///
150/// This value can only be created by [`CaptureScope::complete`]. It carries the explicit graph
151/// boundaries back to the capture device for validation and finalization.
152#[derive(Debug)]
153pub struct CompletedCaptureScope {
154    inputs: Vec<TensorId>,
155    outputs: Vec<TensorId>,
156}
157
158#[derive(Debug, Default)]
159struct CaptureSession {
160    state: Mutex<CaptureState>,
161}
162
163/// Owns the session client and its router binding for one capture scope.
164///
165/// The registration makes every router lookup for the device resolve to `client`. Dropping this
166/// guard removes that lookup entry so the reusable device can be bound to a fresh session later.
167struct CaptureScopeGuard {
168    client: CaptureClient,
169    // Owns the global router entry until completion, error, or panic unwinding.
170    _registration: RouterClientRegistration<CaptureChannel>,
171}
172
173impl CaptureScopeGuard {
174    fn complete(self, scope: CompletedCaptureScope) -> Result<CapturedGraph, CaptureError> {
175        let mut state = self.client.state().lock();
176        let inputs: Vec<_> = scope
177            .inputs
178            .into_iter()
179            .map(|id| state.resolve_alias(id))
180            .collect();
181        let outputs: Vec<_> = scope
182            .outputs
183            .into_iter()
184            .map(|id| state.resolve_alias(id))
185            .collect();
186        let known: HashSet<_> = state
187            .operations
188            .iter()
189            .flat_map(OperationIr::nodes)
190            .map(|tensor| tensor.id)
191            .chain(state.values.keys().copied())
192            .collect();
193        for (boundary, ids) in [("input", &inputs), ("output", &outputs)] {
194            let mut unique = HashSet::new();
195            if let Some(id) = ids.iter().find(|id| !unique.insert(**id)) {
196                return Err(CaptureError::DuplicateBoundary {
197                    boundary,
198                    tensor: *id,
199                });
200            }
201            if let Some(id) = ids.iter().find(|id| !known.contains(*id)) {
202                return Err(CaptureError::UnknownBoundary {
203                    boundary,
204                    tensor: *id,
205                });
206            }
207        }
208
209        let inferred = GraphIr::classify(&state.operations);
210        for &id in &inputs {
211            if !inferred.inputs.contains(&id) && !state.values.contains_key(&id) {
212                return Err(CaptureError::InvalidInput { tensor: id });
213            }
214        }
215        for &id in &inferred.inputs {
216            if !inputs.contains(&id) && !state.values.contains_key(&id) {
217                return Err(CaptureError::UndeclaredInput { tensor: id });
218            }
219        }
220        for &id in &outputs {
221            // Returning a graph input directly is valid. A computed output, however, must not have
222            // been consumed in place or explicitly dropped according to boundary classification.
223            let consumed = state.operations.iter().any(|operation| {
224                matches!(operation, OperationIr::Drop(tensor) if tensor.id == id)
225                    || operation
226                        .nodes()
227                        .into_iter()
228                        .any(|tensor| tensor.id == id && tensor.status == TensorStatus::ReadWrite)
229            });
230            if consumed || (!inferred.inputs.contains(&id) && !inferred.outputs.contains(&id)) {
231                return Err(CaptureError::InvalidOutput { tensor: id });
232            }
233        }
234        let operations = core::mem::take(&mut state.operations);
235        // Tensor handles can outlive the scope (for example, module running states shared across
236        // clones). Keep initialized data in the closed session so those handles can still be
237        // materialized onto another device without allowing any further graph operations.
238        let values = state.values.clone();
239        let captured = CapturedGraph {
240            graph: GraphIr {
241                operations,
242                inputs,
243                outputs,
244            },
245            values,
246        };
247        drop(state);
248        Ok(captured)
249    }
250}
251
252impl Drop for CaptureScopeGuard {
253    fn drop(&mut self) {
254        // Also close scopes that unwind before returning a completion token. Tensor handles can
255        // retain a clone of the session client after the router registration itself is removed.
256        self.client.state().lock().close();
257    }
258}
259
260/// Error returned while finalizing a capture.
261#[derive(Clone, Debug, PartialEq, Eq)]
262pub enum CaptureError {
263    /// Another capture scope is already active on the device.
264    AlreadyActive,
265    /// Capture was requested through a user-facing device using another backend.
266    InvalidDevice,
267    /// A declared boundary tensor was never initialized or referenced.
268    UnknownBoundary {
269        /// Whether this is an input or output boundary.
270        boundary: &'static str,
271        /// Unknown tensor ID.
272        tensor: TensorId,
273    },
274    /// A tensor was declared more than once at the same boundary.
275    DuplicateBoundary {
276        /// Whether this is an input or output boundary.
277        boundary: &'static str,
278        /// Repeated tensor ID.
279        tensor: TensorId,
280    },
281    /// A tensor dependency was neither initialized nor declared as a runtime input.
282    UndeclaredInput {
283        /// Tensor read by the graph without an available source.
284        tensor: TensorId,
285    },
286    /// A declared input is produced within the graph rather than supplied externally.
287    InvalidInput {
288        /// Invalid input tensor ID.
289        tensor: TensorId,
290    },
291    /// A declared output is consumed in place or otherwise cannot survive the graph.
292    InvalidOutput {
293        /// Invalid output tensor ID.
294        tensor: TensorId,
295    },
296}
297
298impl core::fmt::Display for CaptureError {
299    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
300        match self {
301            Self::AlreadyActive => write!(f, "a capture scope is already active on this device"),
302            Self::InvalidDevice => write!(f, "capture scope requires a capture device"),
303            Self::UnknownBoundary { boundary, tensor } => {
304                write!(f, "unknown graph {boundary} tensor {tensor}")
305            }
306            Self::DuplicateBoundary { boundary, tensor } => {
307                write!(f, "duplicate graph {boundary} tensor {tensor}")
308            }
309            Self::UndeclaredInput { tensor } => {
310                write!(f, "graph reads undeclared input tensor {tensor}")
311            }
312            Self::InvalidInput { tensor } => {
313                write!(
314                    f,
315                    "graph input tensor {tensor} is produced within the graph"
316                )
317            }
318            Self::InvalidOutput { tensor } => {
319                write!(f, "graph output tensor {tensor} does not survive the graph")
320            }
321        }
322    }
323}
324
325/// Router channel selecting the non-executing capture client.
326///
327/// Capture clients are scope-specific: [`CaptureDevice::capture_scope`] creates the client and
328/// installs it with `register_scoped_client` before any tensor operations run. An unscoped client
329/// would have no lifecycle owner or completed graph boundary, so it is intentionally unsupported.
330#[derive(Clone)]
331pub struct CaptureChannel;
332
333impl RouterChannel for CaptureChannel {
334    type Device = CaptureDevice;
335    type Bridge = CaptureBridge;
336    type Client = CaptureClient;
337
338    fn name(_device: &Self::Device) -> String {
339        "capture".into()
340    }
341
342    fn init_client(_device: &Self::Device) -> Self::Client {
343        // `get_client` reaches this only when no capture scope registered its client first.
344        panic!("capture tensor operations must run inside CaptureDevice::capture_scope")
345    }
346
347    fn get_tensor_handle(tensor: &TensorIr, client: &Self::Client) -> TensorData {
348        client
349            .state()
350            .lock()
351            .value(tensor.id)
352            .unwrap_or_else(|| panic!("capture tensor {} has no initialized value", tensor.id))
353    }
354
355    fn register_tensor(
356        client: &Self::Client,
357        handle: TensorData,
358        _shape: Shape,
359        _dtype: DType,
360    ) -> RouterTensor<Self::Client> {
361        client.register_tensor_data(handle)
362    }
363}
364
365/// Bridge for materialized values between independent capture devices.
366///
367/// Only initialized tensors have handles in the capture backend, so values reaching this bridge
368/// are concrete and can safely initialize a tensor in another capture scope. Computed tensors have
369/// no materialized handle and are rejected by [`CaptureChannel::get_tensor_handle`] first.
370pub struct CaptureBridge;
371
372impl MultiBackendBridge for CaptureBridge {
373    type TensorHandle = TensorData;
374    type Device = CaptureDevice;
375
376    fn change_backend_float(
377        tensor: TensorData,
378        _shape: Shape,
379        _target: &Self::Device,
380    ) -> TensorData {
381        tensor
382    }
383    fn change_backend_int(tensor: TensorData, _shape: Shape, _target: &Self::Device) -> TensorData {
384        tensor
385    }
386    fn change_backend_bool(
387        tensor: TensorData,
388        _shape: Shape,
389        _target: &Self::Device,
390    ) -> TensorData {
391        tensor
392    }
393}
394
395#[derive(Debug)]
396struct CaptureState {
397    operations: Vec<OperationIr>,
398    values: BTreeMap<TensorId, TensorData>,
399    graphs: HashMap<GraphId, Graph>,
400    aliases: HashMap<TensorId, TensorId>,
401    closed: bool,
402}
403
404impl Default for CaptureState {
405    fn default() -> Self {
406        Self {
407            operations: Vec::new(),
408            values: BTreeMap::new(),
409            graphs: HashMap::new(),
410            aliases: HashMap::new(),
411            closed: false,
412        }
413    }
414}
415
416impl CaptureState {
417    fn close(&mut self) {
418        self.closed = true;
419    }
420
421    fn assert_open(&self) {
422        assert!(!self.closed, "capture scope is already complete");
423    }
424
425    /// Resolve a fusion alias to the tensor ID that owns the computation or initializer.
426    fn resolve_alias(&self, mut id: TensorId) -> TensorId {
427        while let Some(source) = self.aliases.get(&id) {
428            id = *source;
429        }
430        id
431    }
432
433    fn value(&self, id: TensorId) -> Option<TensorData> {
434        self.values.get(&self.resolve_alias(id)).cloned()
435    }
436
437    /// Record a computation after replacing runtime-only fusion aliases with graph dependencies.
438    ///
439    /// Router `Drop` operations only manage handle lifetimes. Excluding them keeps the captured
440    /// computation independent of incidental Rust cloning and ensures closure-local boundary
441    /// tensors may be dropped before the scope is finalized.
442    fn register_op(&mut self, mut op: OperationIr) {
443        if matches!(op, OperationIr::Drop(_)) {
444            return;
445        }
446        self.assert_open();
447        op.visit_mut(&mut AliasVisitor {
448            aliases: &self.aliases,
449        });
450        self.operations.push(op);
451    }
452}
453
454struct AliasVisitor<'a> {
455    aliases: &'a HashMap<TensorId, TensorId>,
456}
457
458impl IrVisitorMut for AliasVisitor<'_> {
459    fn visit_tensor_mut(&mut self, tensor: &mut TensorIr) {
460        while let Some(source) = self.aliases.get(&tensor.id) {
461            tensor.id = *source;
462        }
463    }
464}
465
466/// Client that records router operations and locally retains initialized values.
467#[derive(Clone)]
468pub struct CaptureClient {
469    device: CaptureDevice,
470    session: Arc<CaptureSession>,
471}
472
473impl CaptureClient {
474    fn new(device: CaptureDevice, session: Arc<CaptureSession>) -> Self {
475        Self { device, session }
476    }
477
478    fn state(&self) -> &Mutex<CaptureState> {
479        &self.session.state
480    }
481}
482
483impl RouterClient for CaptureClient {
484    type Device = CaptureDevice;
485
486    fn register_op(&self, op: OperationIr) {
487        self.state().lock().register_op(op);
488    }
489
490    fn read_tensor_async(&self, tensor: TensorIr) -> DynFut<Result<TensorData, ExecutionError>> {
491        let value = self.state().lock().value(tensor.id);
492        Box::pin(async move {
493            value.ok_or_else(|| ExecutionError::WithContext {
494                reason: format!("captured tensor {} has no concrete value", tensor.id),
495            })
496        })
497    }
498
499    fn sync(&self) -> Result<(), ExecutionError> {
500        Ok(())
501    }
502    fn flush(&self) {}
503
504    fn create_empty_handle(&self) -> TensorId {
505        self.state().lock().assert_open();
506        TensorId::new(TENSOR_COUNTER.fetch_add(1, Ordering::Relaxed))
507    }
508
509    fn register_tensor_data(&self, data: TensorData) -> RouterTensor<Self> {
510        let mut state = self.state().lock();
511        state.assert_open();
512        let id = TensorId::new(TENSOR_COUNTER.fetch_add(1, Ordering::Relaxed));
513        let shape = data.shape().clone();
514        let dtype = data.dtype();
515        state.values.insert(id, data);
516        drop(state);
517        RouterTensor::new(id, shape, dtype, self.clone())
518    }
519
520    fn device(&self) -> Self::Device {
521        self.device
522    }
523
524    fn seed(&self, _seed: u64) {
525        panic!("seeding is not supported during graph capture")
526    }
527
528    fn dtype_usage(&self, dtype: DType) -> DTypeUsageSet {
529        match dtype {
530            // Capture records these operations without executing dtype-specific kernels. The
531            // router's quantized operations are not implemented yet, so quantized tensors remain
532            // the only dtype family that capture cannot represent through the backend API.
533            DType::QFloat(_) => DTypeUsageSet::empty(),
534            _ => DTypeUsage::general(),
535        }
536    }
537
538    fn register_and_execute_graph(
539        &self,
540        graph_id: GraphId,
541        relative_graph: Vec<OperationIr>,
542        bindings: GraphBindings,
543    ) {
544        let graph = Graph::new(relative_graph);
545        let bound = graph.bind(bindings);
546        let mut state = self.state().lock();
547        state.graphs.insert(graph_id, graph);
548        for operation in bound.operations {
549            state.register_op(operation);
550        }
551    }
552
553    fn execute_graph(&self, graph_id: GraphId, bindings: GraphBindings) {
554        let graph = self
555            .state()
556            .lock()
557            .graphs
558            .get(&graph_id)
559            .cloned()
560            .unwrap_or_else(|| panic!("capture graph {graph_id:?} was not registered"));
561        let bound = graph.bind(bindings);
562        let mut state = self.state().lock();
563        for operation in bound.operations {
564            state.register_op(operation);
565        }
566    }
567
568    fn register_alias(&self, new_id: TensorId, src_id: TensorId) {
569        let mut state = self.state().lock();
570        state.assert_open();
571        let source = state.resolve_alias(src_id);
572        if source != new_id {
573            state.aliases.insert(new_id, source);
574        }
575    }
576}
577
578#[cfg(test)]
579mod tests {
580    use super::*;
581    use alloc::vec;
582    #[cfg(feature = "std")]
583    use burn_backend::Backend;
584    use burn_backend::ops::FloatTensorOps;
585    use burn_ir::{CustomOpIr, ScalarIr};
586    use burn_router::get_client;
587
588    fn tensor(id: u64, shape: impl Into<Shape>) -> TensorIr {
589        TensorIr::uninit(TensorId::new(id), shape.into(), DType::F32)
590    }
591
592    #[test]
593    fn backend_router_operations_are_captured() {
594        let device = CaptureDevice::default();
595        let captured = device
596            .capture_scope(|scope| {
597                let lhs = CaptureBackend::float_from_data(TensorData::from([1.0f32, 2.0]), &device);
598                let rhs = CaptureBackend::float_from_data(TensorData::from([3.0f32, 4.0]), &device);
599                let lhs_id = lhs.id();
600                let rhs_id = rhs.id();
601                let output = CaptureBackend::float_add(lhs, rhs);
602                let output_id = output.id();
603
604                scope.complete([lhs_id, rhs_id], [output_id])
605            })
606            .unwrap();
607        assert_eq!(captured.values.len(), 2);
608        assert!(
609            captured.graph.operations.iter().any(|operation| matches!(
610                operation,
611                OperationIr::NumericFloat(_, burn_ir::NumericOperationIr::Add(_))
612            )),
613            "captured operations: {:?}",
614            captured.graph.operations
615        );
616        assert!(
617            captured
618                .graph
619                .operations
620                .iter()
621                .all(|operation| !matches!(operation, OperationIr::Drop(_))),
622            "tensor lifetime operations must not be part of a computation graph"
623        );
624    }
625
626    #[test]
627    fn captures_operations_values_and_explicit_boundaries() {
628        let device = CaptureDevice::default();
629        let captured = device
630            .capture_scope(|scope| {
631                let client = get_client::<CaptureChannel>(&device);
632                let input = client.register_tensor_data(TensorData::from([1.0f32, 2.0]));
633                let input_id = input.id();
634                let input_ir = input.into_ir();
635                let output_id = client.create_empty_handle();
636                let output_ir = TensorIr::uninit(output_id, Shape::new([2]), DType::F32);
637                client.register_op(OperationIr::Custom(CustomOpIr::new(
638                    "identity",
639                    &[input_ir],
640                    &[output_ir],
641                )));
642
643                scope.complete([input_id], [output_id])
644            })
645            .unwrap();
646        let input_id = captured.graph.inputs[0];
647        let output_id = captured.graph.outputs[0];
648        assert_eq!(captured.graph.inputs, [input_id]);
649        assert_eq!(captured.graph.outputs, [output_id]);
650        assert_eq!(captured.graph.operations.len(), 1);
651        assert_eq!(
652            captured.values.get(&input_id),
653            Some(&TensorData::from([1.0f32, 2.0]))
654        );
655    }
656
657    #[cfg(feature = "std")]
658    #[test]
659    fn escaped_tensors_cannot_record_after_their_scope_completes() {
660        let device = CaptureDevice::default();
661        let mut escaped_output = None;
662        let first = device
663            .capture_scope(|scope| {
664                let lhs = CaptureBackend::float_from_data(TensorData::from([1.0f32]), &device);
665                let rhs = CaptureBackend::float_from_data(TensorData::from([2.0f32]), &device);
666                let lhs_id = lhs.id();
667                let rhs_id = rhs.id();
668                let output = CaptureBackend::float_add(lhs, rhs);
669                let output_id = output.id();
670                escaped_output = Some(output);
671
672                scope.complete([lhs_id, rhs_id], [output_id])
673            })
674            .unwrap();
675        assert!(!first.graph.operations.is_empty());
676
677        let next = device
678            .capture_scope(|scope| {
679                let fresh = CaptureBackend::float_from_data(TensorData::from([3.0f32]), &device);
680                let fresh_id = fresh.id();
681                let stale = escaped_output.take().unwrap();
682                let operation = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
683                    CaptureBackend::float_add(stale, fresh)
684                }));
685
686                assert!(operation.is_err());
687                scope.complete([fresh_id], [])
688            })
689            .unwrap();
690        assert_eq!(next.graph.operations.len(), 1);
691        assert!(matches!(next.graph.operations[0], OperationIr::Init(_)));
692    }
693
694    #[test]
695    fn initialized_tensor_can_move_from_completed_scope_to_new_device() {
696        let first_device = CaptureDevice::default();
697        let second_device = CaptureDevice::default();
698        let mut escaped = None;
699
700        first_device
701            .capture_scope(|scope| {
702                let tensor =
703                    CaptureBackend::float_from_data(TensorData::from([1.0f32, 2.0]), &first_device);
704                let tensor_id = tensor.id();
705                escaped = Some(tensor);
706                scope.complete([tensor_id], [])
707            })
708            .unwrap();
709
710        let captured = second_device
711            .capture_scope(|scope| {
712                let tensor =
713                    CaptureBackend::float_to_device(escaped.take().unwrap(), &second_device);
714                let output = CaptureBackend::float_neg(tensor);
715                let output_id = output.id();
716                scope.complete([], [output_id])
717            })
718            .unwrap();
719
720        assert_eq!(captured.values.len(), 1);
721        assert!(matches!(
722            captured.graph.operations.last(),
723            Some(OperationIr::NumericFloat(
724                _,
725                burn_ir::NumericOperationIr::Neg(_)
726            ))
727        ));
728    }
729
730    #[cfg(feature = "std")]
731    #[test]
732    fn completing_scope_immediately_rejects_more_operations() {
733        let device = CaptureDevice::default();
734        let captured = device
735            .capture_scope(|scope| {
736                let client = get_client::<CaptureChannel>(&device);
737                let completed = scope.complete([], []);
738                let tensor_result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
739                    CaptureBackend::float_from_data(TensorData::from([1.0f32]), &device)
740                }));
741                let handle = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
742                    client.create_empty_handle()
743                }));
744                let operation = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
745                    client.register_op(OperationIr::Custom(CustomOpIr::new(
746                        "late",
747                        &[],
748                        &[tensor(99_000, [1])],
749                    )))
750                }));
751
752                assert!(tensor_result.is_err());
753                assert!(handle.is_err());
754                assert!(operation.is_err());
755                completed
756            })
757            .unwrap();
758
759        assert!(captured.graph.operations.is_empty());
760    }
761
762    #[test]
763    fn capture_device_can_be_reused_for_sequential_scopes() {
764        let device = CaptureDevice::default();
765        let first = device
766            .capture_scope(|scope| scope.complete([], []))
767            .unwrap();
768        let second = device
769            .capture_scope(|scope| scope.complete([], []))
770            .unwrap();
771
772        assert!(first.graph.operations.is_empty());
773        assert!(second.graph.operations.is_empty());
774    }
775
776    #[cfg(feature = "std")]
777    #[test]
778    fn tensor_operations_require_an_active_scope() {
779        let device = CaptureDevice::default();
780        let panic = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
781            let _ = CaptureBackend::float_from_data(TensorData::from([1.0f32]), &device);
782        }));
783
784        assert!(panic.is_err());
785        assert!(device.capture_scope(|scope| scope.complete([], [])).is_ok());
786    }
787
788    #[test]
789    fn overlapping_scopes_on_one_device_are_rejected() {
790        let device = CaptureDevice::default();
791        let outer = device.capture_scope(|scope| {
792            let inner = device.capture_scope(|scope| scope.complete([], []));
793            assert!(matches!(inner, Err(CaptureError::AlreadyActive)));
794            scope.complete([], [])
795        });
796
797        assert!(outer.is_ok());
798    }
799
800    #[test]
801    fn separate_devices_support_overlapping_scopes() {
802        let first = CaptureDevice::default();
803        let second = CaptureDevice::default();
804
805        let outer = first.capture_scope(|outer| {
806            let inner = second
807                .capture_scope(|inner| inner.complete([], []))
808                .unwrap();
809            assert!(inner.graph.operations.is_empty());
810            outer.complete([], [])
811        });
812
813        assert!(outer.is_ok());
814    }
815
816    #[cfg(feature = "std")]
817    #[test]
818    fn panicking_scope_releases_its_router_registration() {
819        let device = CaptureDevice::default();
820        let mut escaped = None;
821        let panic = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
822            let _ = device.capture_scope(|_| -> CompletedCaptureScope {
823                escaped = Some(CaptureBackend::float_from_data(
824                    TensorData::from([1.0f32]),
825                    &device,
826                ));
827                panic!("capture failed")
828            });
829        }));
830
831        assert!(panic.is_err());
832        let stale = escaped.unwrap();
833        let operation = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
834            CaptureBackend::float_neg(stale)
835        }));
836        assert!(operation.is_err());
837        assert!(device.capture_scope(|scope| scope.complete([], [])).is_ok());
838    }
839
840    #[test]
841    fn capture_devices_have_distinct_monotonic_ids() {
842        let first = CaptureDevice::default();
843        let second = CaptureDevice::default();
844
845        assert_ne!(first, second);
846        assert!(first.to_id().index_id < second.to_id().index_id);
847    }
848
849    #[test]
850    fn capture_device_id_round_trips() {
851        let device = CaptureDevice::default();
852        let restored = CaptureDevice::from_id(device.to_id());
853        assert_eq!(restored, device);
854        assert_eq!(
855            restored.to_id().type_id,
856            u16::from(RouterDeviceType::Capture)
857        );
858    }
859
860    #[test]
861    fn invalid_boundary_is_reported() {
862        let device = CaptureDevice::default();
863        let captured = device.capture_scope(|scope| {
864            let client = get_client::<CaptureChannel>(&device);
865            let _tensor = client.register_tensor_data(TensorData::from([3i64]));
866            scope.complete([TensorId::new(u64::MAX)], [])
867        });
868
869        assert!(matches!(
870            captured,
871            Err(CaptureError::UnknownBoundary { .. })
872        ));
873    }
874
875    #[test]
876    fn duplicate_boundary_is_reported() {
877        let device = CaptureDevice::default();
878        let mut duplicate = None;
879        let captured = device.capture_scope(|scope| {
880            let client = get_client::<CaptureChannel>(&device);
881            let tensor = client.register_tensor_data(TensorData::from([3i64]));
882            let id = tensor.id();
883            duplicate = Some(id);
884            scope.complete([id, id], [])
885        });
886
887        assert!(matches!(
888            captured,
889            Err(CaptureError::DuplicateBoundary { tensor, .. }) if Some(tensor) == duplicate
890        ));
891    }
892
893    #[test]
894    fn dangling_graph_input_is_reported() {
895        let device = CaptureDevice::default();
896        let captured = device.capture_scope(|scope| {
897            let client = get_client::<CaptureChannel>(&device);
898            let missing = tensor(90_000, [1]);
899            let output_id = client.create_empty_handle();
900            client.register_op(OperationIr::Custom(CustomOpIr::new(
901                "dangling",
902                &[missing],
903                &[tensor(output_id.value(), [1])],
904            )));
905            scope.complete([], [output_id])
906        });
907
908        assert!(matches!(
909            captured,
910            Err(CaptureError::UndeclaredInput { .. })
911        ));
912    }
913
914    #[test]
915    fn graph_produced_tensor_cannot_be_declared_as_input() {
916        let device = CaptureDevice::default();
917        let captured = device.capture_scope(|scope| {
918            let client = get_client::<CaptureChannel>(&device);
919            let input = client.register_tensor_data(TensorData::from([1.0f32]));
920            let output_id = client.create_empty_handle();
921            client.register_op(OperationIr::Custom(CustomOpIr::new(
922                "produce",
923                &[input.into_ir()],
924                &[tensor(output_id.value(), [1])],
925            )));
926            scope.complete([output_id], [output_id])
927        });
928
929        assert!(matches!(captured, Err(CaptureError::InvalidInput { .. })));
930    }
931
932    #[test]
933    fn read_write_tensor_cannot_be_declared_as_output() {
934        let device = CaptureDevice::default();
935        let captured = device.capture_scope(|scope| {
936            let client = get_client::<CaptureChannel>(&device);
937            let input = client.register_tensor_data(TensorData::from([1.0f32]));
938            let input_id = input.id();
939            let mut input = input.into_ir();
940            input.status = TensorStatus::ReadWrite;
941            let output_id = client.create_empty_handle();
942            client.register_op(OperationIr::Custom(CustomOpIr::new(
943                "consume_in_place",
944                &[input],
945                &[tensor(output_id.value(), [1])],
946            )));
947            scope.complete([input_id], [input_id])
948        });
949
950        assert!(matches!(captured, Err(CaptureError::InvalidOutput { .. })));
951    }
952
953    #[test]
954    fn capture_supports_every_non_quantized_dtype() {
955        let device = CaptureDevice::default();
956        let captured = device.capture_scope(|scope| {
957            let client = get_client::<CaptureChannel>(&device);
958            for dtype in [
959                DType::F64,
960                DType::F32,
961                DType::Flex32,
962                DType::F16,
963                DType::BF16,
964                DType::I64,
965                DType::I32,
966                DType::I16,
967                DType::I8,
968                DType::U64,
969                DType::U32,
970                DType::U16,
971                DType::U8,
972                DType::Bool(BoolStore::Native),
973                DType::Bool(BoolStore::U8),
974                DType::Bool(BoolStore::U32),
975            ] {
976                assert_eq!(
977                    client.dtype_usage(dtype),
978                    DTypeUsage::general(),
979                    "{dtype:?}"
980                );
981            }
982            assert!(
983                client
984                    .dtype_usage(DType::QFloat(
985                        burn_backend::quantization::QuantScheme::default()
986                    ))
987                    .is_empty()
988            );
989            scope.complete([], [])
990        });
991
992        assert!(captured.is_ok());
993    }
994
995    #[cfg(feature = "std")]
996    #[test]
997    fn seeding_capture_device_is_rejected() {
998        let device = CaptureDevice::default();
999        let captured = device.capture_scope(|scope| {
1000            let seeded = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
1001                CaptureBackend::seed(&device, 42)
1002            }));
1003            assert!(seeded.is_err());
1004            scope.complete([], [])
1005        });
1006
1007        assert!(captured.is_ok());
1008    }
1009
1010    #[test]
1011    fn self_alias_is_ignored() {
1012        let device = CaptureDevice::default();
1013        let captured = device.capture_scope(|scope| {
1014            let client = get_client::<CaptureChannel>(&device);
1015            let id = client.create_empty_handle();
1016            client.register_alias(id, id);
1017            assert_eq!(client.state().lock().resolve_alias(id), id);
1018            scope.complete([], [])
1019        });
1020
1021        assert!(captured.is_ok());
1022    }
1023
1024    #[test]
1025    fn cached_graph_invocations_are_bound_and_recorded() {
1026        let device = CaptureDevice::default();
1027        let input_1 = TensorId::new(10_000);
1028        let output_1 = TensorId::new(10_001);
1029        let input_2 = TensorId::new(20_000);
1030        let output_2 = TensorId::new(20_001);
1031        let captured = device
1032            .capture_scope(|scope| {
1033                let client = get_client::<CaptureChannel>(&device);
1034                let relative_input = tensor(0, Shape::new([0]));
1035                let relative_intermediate = tensor(1, Shape::new([0]));
1036                let relative_output = tensor(2, Shape::new([0]));
1037                let relative_graph = vec![
1038                    OperationIr::Custom(CustomOpIr::new(
1039                        "first",
1040                        core::slice::from_ref(&relative_input),
1041                        core::slice::from_ref(&relative_intermediate),
1042                    )),
1043                    OperationIr::Custom(CustomOpIr::with_scalars(
1044                        "second",
1045                        core::slice::from_ref(&relative_intermediate),
1046                        core::slice::from_ref(&relative_output),
1047                        vec![ScalarIr::UInt(0)],
1048                    )),
1049                ];
1050                let graph_id = GraphId(7);
1051
1052                client.register_and_execute_graph(
1053                    graph_id,
1054                    relative_graph,
1055                    GraphBindings {
1056                        tensors: vec![(relative_input.id, input_1), (relative_output.id, output_1)],
1057                        shapes: vec![3],
1058                        scalars: vec![ScalarIr::Float(1.5)],
1059                        ranges: vec![],
1060                    },
1061                );
1062                client.execute_graph(
1063                    graph_id,
1064                    GraphBindings {
1065                        tensors: vec![(relative_input.id, input_2), (relative_output.id, output_2)],
1066                        shapes: vec![5],
1067                        scalars: vec![ScalarIr::Float(2.5)],
1068                        ranges: vec![],
1069                    },
1070                );
1071
1072                scope.complete([input_1, input_2], [output_1, output_2])
1073            })
1074            .unwrap();
1075        assert_eq!(captured.graph.operations.len(), 4);
1076
1077        let OperationIr::Custom(first_1) = &captured.graph.operations[0] else {
1078            panic!("expected first custom operation")
1079        };
1080        let OperationIr::Custom(second_1) = &captured.graph.operations[1] else {
1081            panic!("expected second custom operation")
1082        };
1083        let OperationIr::Custom(first_2) = &captured.graph.operations[2] else {
1084            panic!("expected first custom operation")
1085        };
1086        let OperationIr::Custom(second_2) = &captured.graph.operations[3] else {
1087            panic!("expected second custom operation")
1088        };
1089        assert_eq!(first_1.inputs[0].id, input_1);
1090        assert_eq!(second_1.outputs[0].id, output_1);
1091        assert_eq!(first_1.outputs[0].id, second_1.inputs[0].id);
1092        assert_eq!(first_1.inputs[0].shape, Shape::new([3]));
1093        assert_eq!(second_1.scalars, [ScalarIr::Float(1.5)]);
1094        assert_eq!(first_2.inputs[0].id, input_2);
1095        assert_eq!(second_2.outputs[0].id, output_2);
1096        assert_eq!(first_2.outputs[0].id, second_2.inputs[0].id);
1097        assert_ne!(first_1.outputs[0].id, first_2.outputs[0].id);
1098        assert_eq!(first_2.inputs[0].shape, Shape::new([5]));
1099        assert_eq!(second_2.scalars, [ScalarIr::Float(2.5)]);
1100    }
1101
1102    #[test]
1103    fn computed_fusion_aliases_resolve_to_their_source() {
1104        let device = CaptureDevice::default();
1105        let mut source = None;
1106        let mut alias = None;
1107        let captured = device
1108            .capture_scope(|scope| {
1109                let client = get_client::<CaptureChannel>(&device);
1110                let input = client.register_tensor_data(TensorData::from([1.0f32, 2.0]));
1111                let input_id = input.id();
1112                let source_id = client.create_empty_handle();
1113                let alias_id = client.create_empty_handle();
1114                let output_id = client.create_empty_handle();
1115
1116                client.register_op(OperationIr::Custom(CustomOpIr::new(
1117                    "produce",
1118                    &[input.into_ir()],
1119                    &[TensorIr::uninit(source_id, Shape::new([2]), DType::F32)],
1120                )));
1121                client.register_alias(alias_id, source_id);
1122                client.register_op(OperationIr::Custom(CustomOpIr::new(
1123                    "consume",
1124                    &[TensorIr::uninit(alias_id, Shape::new([2]), DType::F32)],
1125                    &[TensorIr::uninit(output_id, Shape::new([2]), DType::F32)],
1126                )));
1127                source = Some(source_id);
1128                alias = Some(alias_id);
1129
1130                scope.complete([input_id], [output_id])
1131            })
1132            .unwrap();
1133        let source_id = source.unwrap();
1134        let alias_id = alias.unwrap();
1135        let OperationIr::Custom(consume) = &captured.graph.operations[1] else {
1136            panic!("expected alias consumer")
1137        };
1138        assert_eq!(consume.inputs[0].id, source_id);
1139        assert!(!captured.graph.inputs.contains(&alias_id));
1140    }
1141
1142    #[test]
1143    fn initialized_aliases_share_the_source_value_and_boundary() {
1144        let device = CaptureDevice::default();
1145        let mut source = None;
1146        let captured = device
1147            .capture_scope(|scope| {
1148                let client = get_client::<CaptureChannel>(&device);
1149                let tensor = client.register_tensor_data(TensorData::from([4i64]));
1150                let source_id = tensor.id();
1151                let alias_id = client.create_empty_handle();
1152                client.register_alias(alias_id, source_id);
1153
1154                assert_eq!(
1155                    client.state().lock().value(alias_id),
1156                    Some(TensorData::from([4i64]))
1157                );
1158                source = Some(source_id);
1159                scope.complete([alias_id], [])
1160            })
1161            .unwrap();
1162        let source_id = source.unwrap();
1163        assert_eq!(captured.graph.inputs, [source_id]);
1164        assert!(captured.values.contains_key(&source_id));
1165    }
1166}