1use 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
24pub type CaptureBackend = burn_router::BackendRouter<CaptureChannel>;
26
27#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub struct CaptureDevice {
35 id: u16,
36}
37
38impl CaptureDevice {
39 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 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#[derive(Clone, Debug)]
110pub struct CapturedGraph {
111 pub graph: GraphIr,
113 pub values: BTreeMap<TensorId, TensorData>,
115}
116
117#[derive(Debug)]
123pub struct CaptureScope {
124 session: Arc<CaptureSession>,
127}
128
129impl CaptureScope {
130 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#[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
163struct CaptureScopeGuard {
168 client: CaptureClient,
169 _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 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 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 self.client.state().lock().close();
257 }
258}
259
260#[derive(Clone, Debug, PartialEq, Eq)]
262pub enum CaptureError {
263 AlreadyActive,
265 InvalidDevice,
267 UnknownBoundary {
269 boundary: &'static str,
271 tensor: TensorId,
273 },
274 DuplicateBoundary {
276 boundary: &'static str,
278 tensor: TensorId,
280 },
281 UndeclaredInput {
283 tensor: TensorId,
285 },
286 InvalidInput {
288 tensor: TensorId,
290 },
291 InvalidOutput {
293 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#[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 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
365pub 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 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 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#[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 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}