Struct GracefulPhasedCellAsync

Source

pub struct GracefulPhasedCellAsync<T: Send + Sync> { /* private fields */ }

Available on crate features graceful and tokio only.

Expand description

An asynchronous, thread-safe PhasedCellAsync that supports graceful cleanup and graceful read.

This cell is the asynchronous version of GracefulPhasedCellSync, designed for tokio-based applications and building upon PhasedCellAsync. It provides:

Graceful Cleanup: It ensures that all ongoing read operations complete before allowing the cell to fully transition to the Cleanup phase.
Graceful Read: If a read operation is attempted while the cell is in the Setup phase and transitioning to Read, the read operation will wait for the transition to complete and for the cell to enter the Read phase.

Implementations§

Source §

impl<T: Send + Sync> GracefulPhasedCellAsync<T>

Source

pub const fn new(data: T) -> Self

Creates a new GracefulPhasedCellAsync in the Setup phase, containing the provided data.

§Examples

use setup_read_cleanup::graceful::GracefulPhasedCellAsync;

let cell = GracefulPhasedCellAsync::new(10);

Source

pub fn phase_relaxed(&self) -> Phase

Returns the current phase of the cell with relaxed memory ordering.

This method is faster than phase but provides weaker memory ordering guarantees.

§Examples

use setup_read_cleanup::{Phase, graceful::GracefulPhasedCellAsync};

let cell = GracefulPhasedCellAsync::new(10);
assert_eq!(cell.phase_relaxed(), Phase::Setup);

Source

pub fn phase(&self) -> Phase

Returns the current phase of the cell with acquire memory ordering.

This method provides stronger memory ordering guarantees than phase_relaxed.

§Examples

use setup_read_cleanup::{Phase, graceful::GracefulPhasedCellAsync};

let cell = GracefulPhasedCellAsync::new(10);
assert_eq!(cell.phase(), Phase::Setup);

Source

pub fn read_relaxed(&self) -> Result<&T, PhasedError>

Returns a reference to the contained data with relaxed memory ordering.

This method attempts to return a reference to the contained data immediately without waiting. It is only successful if the cell is in the Read phase. It increments the internal counter to track active readers for graceful cleanup. It provides weaker memory ordering guarantees.

§Errors

Returns an error if the cell is not in the Read phase or the data is unavailable.

Source

pub async fn read_async(&self) -> Result<&T, PhasedError>

Returns a reference to the contained data with acquire memory ordering.

This method attempts to return a reference to the contained data immediately without waiting. It is only successful if the cell is in the Read phase. If the cell is in a Setup -> Read transition, this method will wait until the transition is complete and the cell enters the Read phase. It increments the internal counter to track active readers for graceful cleanup. It provides stronger memory ordering guarantees than read_relaxed.

§Errors

Returns an error if the cell is not in the Read phase (after waiting, if applicable) or the data is unavailable.

Source

pub fn finish_reading(&self)

Signals that a read operation has finished.

This decrements the internal counter of active readers.

Source

pub async fn transition_to_cleanup_async<F, E>( &self, timeout: Duration, f: F, ) -> Result<(), PhasedError>
where F: FnMut(&mut T) -> Pin<Box<dyn Future<Output = Result<(), E>> + Send>>, E: Error + Send + Sync + 'static,

Asynchronously and gracefully transitions the cell to the Cleanup phase.

This method can be called from either the Setup or the Read phase. It waits for all active read operations to complete before executing the provided async closure f and moving to the Cleanup phase.

§Errors

Returns an error if the wait times out, the phase transition fails, or the closure returns an error. If the provided async closure panics, the cell’s phase will be transitioned to Cleanup, and the panic will be resumed.

Source

pub async fn transition_to_read_async<F, E>( &self, f: F, ) -> Result<(), PhasedError>
where F: FnMut(&mut T) -> Pin<Box<dyn Future<Output = Result<(), E>> + Send>>, E: Error + Send + Sync + 'static,

Asynchronously transitions the cell from the Setup phase to the Read phase.

This method takes an async closure f which is executed on the contained data during the transition.

§Errors

Returns an error if the cell is not in the Setup phase or if the closure returns an error. If the provided async closure panics, the cell’s phase will be reverted to Setup, and the panic will be resumed.

Source