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.

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.

// 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.

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.