housekeeping 0.0.3

A concurrent memory reclaimer for periodic cleanups.
Documentation 
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

# `housekeeping`: Cleaning up while you're away

`housekeeping` is a concurrent memory reclamation library for Rust; it helps
build complex concurrent data structures. It is inspired by [`seize`] and
[`crossbeam_epoch`], but is simpler and offers lower-level interfaces.

[`seize`]: https://crates.io/crates/seize
[`crossbeam_epoch`]: https://crates.io/crates/crossbeam_epoch

With `housekeeping`, you can protect concurrent memory, allowing concurrent
objects to be deallocated at a safe time. This is more powerful than reference
counting with `Arc`, and is more efficient.

## Usage

`housekeeping` has two components: `Cleanups`, which is global state for
synchronizing threads and pending deallocation operations; and `Guard`, a
per-thread handle to the `Cleanups` which protects concurrent memory access and
allows concurrent objects to be deallocated safely.

```rust
// Global state for deferring deallocations (i.e. cleanups).
let cleanups = Arc::new(Cleanups::new());

// An atomic variable, pointing to memory protected by 'cleanups'.
let data: AtomicPtr<Data>;
let data: Box<Data> = Default::default();
let data_ptr = Box::into_raw(data);
data = AtomicPtr::new(data_ptr);

std::thread::scope(|s| {
    s.spawn(|| {
        // Obtain a guard for safely handling concurrent memory.
        let guard = cleanups.clone().register();

        // Replace the existing data.
        let new_data: Box<Data> = Box::new(somehow_compute());
        let new_data_ptr = Box::into_raw(new_data);
        let old_data_ptr = data.swap(new_data_ptr, Ordering::AcqRel);

        // Defer the cleanup of the existing data.
        // SAFETY:
        // - '*mut Data' can be sent between threads safely.
        // - The closure is 'move' and is 'static.
        unsafe { guard.defer_unchecked(move || {
            mem::drop(Box::from_raw(old_data_ptr))
        }) };
    });

    // Obtain a guard for safely handling concurrent memory.
    let guard = cleanups.clone().register();

    // Use the data.
    let data_ptr = data.load(Ordering::Acquire).cast_const();
    // SAFETY: Safe as long as 'guard' is held.
    somehow_consume(unsafe { &*data_ptr });
});

// Drop the last instance of the data.
let _ = unsafe { Box::from_raw(data.into_inner()) };
```

## Origin

`housekeeping` is being developed for [`krabby`], an experimental Rust
compiler, with different goals and limitations compared to [`seize`] and
[`crossbeam_epoch`]. It is offered as a standalone crate in the hope that it may
prove useful for other concurrent data structure libraries.

[`krabby`]: https://codeberg.org/bal-e/krabby

## License

Copyright (C) 2026 arya dradjica (<hut1zulljl4lxd2h@bal-e.org>)

`housekeeping` is available under the MIT or Apache-2.0 licenses,
at your option. Their terms are available in `LICENSES/MIT.txt` and
`LICENSES/Apache-2.0.txt` respectively.