1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
use Device;
/// Releases `device`'s cached memory pages.
///
/// A `cargo test` binary runs every test in **one process**, so every test
/// shares one accelerator client — and with it one memory pool. `cubecl`'s
/// pools hand out slices of large pages and, by design, never return a page on
/// their own: the pool keeps the high-water mark so the next allocation of that
/// size is free. Within a single model that is exactly right. Across a suite of
/// independent tests, each loading its own model, it means the pool only ever
/// grows — until the card is full and some later, innocent test fails its next
/// allocation.
///
/// How fast it grows depends on the page sizes, and those are **not** the same
/// on every backend. `cubecl`'s wgpu runtime sizes its pages from
/// `max_storage_buffer_binding_size`, but its Vulkan/SPIR-V path sizes them
/// from a quarter of the device heap instead — so on a 24 GiB card the largest
/// pool allocates in 6 GiB pages rather than 2 GiB ones. A suite whose peak
/// working set is a couple of GiB can still exhaust the card, and it shows up
/// as `wgpu error: Out of Memory` from `Device::create_buffer` in whichever
/// test was running when the card filled — not in whichever test did the
/// allocating.
///
/// Only pages that are **entirely free** are returned, so this reclaims a
/// previous test's pool rather than the caller's own live tensors. It is a
/// no-op on backends without a pooled allocator, [`cpu_device`] among them.
///
/// Prefer [`DeviceMemoryGuard`] at a test's top over calling this at its
/// bottom: a trailing call is skipped by the panic it would be most useful
/// after.
///
/// [`cpu_device`]: crate::support::testing::cpu_device
/// Releases a device's cached memory pages when it drops.
///
/// Bind it at the top of a test that loads a model, so the pool that test grows
/// is handed back to the tests running after it:
///
/// ```
/// use bunsen::support::testing::{
/// DeviceMemoryGuard,
/// cpu_device,
/// };
///
/// let device = cpu_device();
/// let _memory = DeviceMemoryGuard::new(&device);
///
/// // ... load a model, run it, assert on it ...
/// ```
///
/// Two binding rules, both of them about *when* the guard drops:
///
/// * Bind it to a named `_`-prefixed local, never to bare `_`. `let _ = ..`
/// drops the guard immediately, releasing the pool before the test has
/// allocated anything.
/// * Bind it **before** the tensors it is meant to reclaim, and in a `let` of
/// its own. Locals drop in reverse declaration order, so a guard declared
/// first drops last — after the models and tensors, when their pages are
/// finally free. A guard declared after them, or destructured out of the same
/// tuple as them, drops first and reclaims nothing.
///
/// [`release_cached_device_memory`] says why a shared pool needs this at all,
/// and what "release" does and does not reclaim.
///
/// Pair it with `#[serial]`. The guard bounds what a suite accumulates *over*
/// time; it does nothing about what it holds *at once*, and tests running
/// concurrently each hold their own working set. A dozen of those is enough to
/// exhaust a 24 GiB card even though no single one comes close.