Crate setup_read_cleanup 

A library for managing data through distinct lifecycle phases.

This crate provides “phased cells”, a collection of smart pointer types that enforce a specific lifecycle for the data they manage: Setup -> Read -> Cleanup. This is useful for data that is initialized once, read by multiple threads or tasks for a period, and then explicitly destroyed.

Core Concepts

The lifecycle is divided into three phases:

• Setup: The initial phase. The data can be mutably accessed for initialization.
• Read: The operational phase. The data can only be accessed immutably. This phase is optimized for concurrent, lock-free reads.
• Cleanup: The final phase. The data can be mutably accessed again for deconstruction or resource cleanup.

Cell Variants

This crate offers several cell variants to suit different concurrency needs:

• PhasedCell: The basic cell. It is Sync if the contained data T is Send + Sync, allowing it to be shared across threads for reading. However, mutable access via get_mut_unlocked is not thread-safe and requires the caller to ensure exclusive access.

• PhasedCellSync: A thread-safe version that uses a std::sync::Mutex to allow for safe concurrent mutable access during the Setup and Cleanup phases.

• PhasedCellAsync: (Requires the tokio feature) An async version of PhasedCellSync that uses a tokio::sync::Mutex.

Graceful Cleanup

(Requires the graceful feature)

The graceful module provides wrappers that add graceful cleanup capabilities. When transitioning to the Cleanup phase, these cells will wait for a specified duration for all active read operations to complete.

• GracefulPhasedCell
• GracefulPhasedCellSync
• GracefulPhasedCellAsync (Requires both features)

Examples

Using a static PhasedCellSync to initialize data, read it from multiple threads, and then clean it up.

use setup_read_cleanup::{PhasedCellSync, Phase};
use std::thread;

struct MyData {
    items: Vec<i32>,
}

// Declare a static PhasedCellSync instance
static CELL: PhasedCellSync<MyData> = PhasedCellSync::new(MyData { items: Vec::new() });

fn main() {
    // --- Setup Phase ---
    assert_eq!(CELL.phase(), Phase::Setup);
    {
        let mut data = CELL.lock().unwrap();
        data.items.push(10);
        data.items.push(20);
    } // Lock is released here

    // --- Transition to Read Phase ---
    CELL.transition_to_read(|data| {
        data.items.push(30);
        Ok::<(), std::io::Error>(())
    }).unwrap();
    assert_eq!(CELL.phase(), Phase::Read);

    // --- Read Phase ---
    // Now, multiple threads can read the data concurrently.
    let mut handles = Vec::new();
    for i in 0..3 {
        handles.push(thread::spawn(move || {
            let data = CELL.read().unwrap(); // Access the static CELL
            println!("Thread {} reads: {:?}", i, data.items);
            assert_eq!(data.items, &[10, 20, 30]);
        }));
    }

    for handle in handles {
        handle.join().unwrap();
    }

    // --- Transition to Cleanup Phase ---
    CELL.transition_to_cleanup(|data| {
        println!("Cleaning up. Final item: {:?}", data.items.pop());
        Ok::<(), std::io::Error>(())
    }).unwrap();
    assert_eq!(CELL.phase(), Phase::Cleanup);
}

Features

• tokio: Enables the async cell variants (PhasedCellAsync, GracefulPhasedCellAsync) which use tokio::sync.
• graceful: Enables the graceful module, which provides cells with graceful cleanup capabilities.

Modules

gracefulgraceful

A module for graceful cleanup of phased cells.

Structs

PhasedCell

A cell that manages data through distinct Setup, Read, and Cleanup phases.

PhasedCellAsynctokio

An asynchronous, thread-safe cell for managing data through Setup, Read, and Cleanup phases.

PhasedCellSync

A thread-safe cell that manages data through Setup, Read, and Cleanup phases with support for concurrent mutable access.

PhasedError

A structure representing an error that occurred within a phased cell.

StdMutexGuard

A RAII implementation of a scoped lock for a PhasedCellSync.

TokioMutexGuardtokio

A RAII implementation of a scoped lock for a PhasedCellAsync.

Enums

Phase

Represents the current operational phase of a phased cell.

PhasedErrorKind

An enumeration of possible error kinds that can occur in a phased cell.