Struct singlefile::container_shared_async::ContainerAsync

pub struct ContainerAsync<T, Manager> { /* private fields */ }

Available on crate feature shared-async only.

A container that allows shared, asynchronous, thread-safe access to a file and its underlying contents. The in-memory A container that allows atomic reference-counted, asynchronous, mutable access (gated by an RwLock) to the underlying file and contents.

Implementations

impl<T, Manager> ContainerAsync<T, Manager>

pub fn manager(&self) -> &Manager

Gets a reference to the contained file manager.

It is inadvisable to manipulate the manager manually.

pub async fn access(&self) -> AccessGuard<'_, T>

Gets immutable access to the underlying value T.

pub async fn access_mut(&self) -> AccessGuardMut<'_, T>

Gets mutable access to the underlying value T.

pub async fn access_owned(&self) -> OwnedAccessGuard<T>

Gets immutable access to the underlying value T.

pub async fn access_owned_mut(&self) -> OwnedAccessGuardMut<T>

Gets mutable access to the underlying value T.

pub async fn operate<F, R>(&self, operation: F) -> Rwhere
    F: FnOnce(&T) -> R,

Grants the caller immutable access to the underlying value T, but only for the duration of the provided function or closure.

pub async fn operate_mut<F, R>(&self, operation: F) -> Rwhere
    F: FnOnce(&mut T) -> R,

Grants the caller mutable access to the underlying value T, but only for the duration of the provided function or closure.

impl<T, Format, Lock, Mode> ContainerAsync<T, FileManager<Format, Lock, Mode>>where
    Format: FileFormat<T> + Send + 'static,
    Format::FormatError: Send + 'static,
    Lock: FileLock + Send + 'static,
    Mode: FileMode<Format> + Send + 'static,
    T: Send + 'static,

pub async fn open<P: AsRef<Path>>(
    path: P,
    format: Format
) -> Result<Self, Error<Format::FormatError>>where
    Mode: Reading<T, Format>,

Opens a new ContainerAsync, returning an error if the file at the given path does not exist.

pub async fn create_or<P: AsRef<Path>>(
    path: P,
    format: Format,
    item: T
) -> Result<Self, Error<Format::FormatError>>

Opens a new ContainerAsync, writing the given value to the file if it does not exist.

pub async fn create_or_else<P: AsRef<Path>, C>(
    path: P,
    format: Format,
    closure: C
) -> Result<Self, Error<Format::FormatError>>where
    C: FnOnce() -> T + Send + 'static,

Opens a new ContainerAsync, writing the result of the given closure to the file if it does not exist.

pub async fn create_or_default<P: AsRef<Path>>(
    path: P,
    format: Format
) -> Result<Self, Error<Format::FormatError>>where
    T: Default,

Opens a new ContainerAsync, writing the default value of T to the file if it does not exist.

impl<T, Format, Lock, Mode> ContainerAsync<T, FileManager<Format, Lock, Mode>>where
    Format: FileFormat<T> + Send + Sync + 'static,
    Format::FormatError: Send + 'static,
    Lock: Send + Sync + 'static,
    Mode: Send + Sync + 'static,
    T: Send + Sync + 'static,

pub async fn operate_refresh<F, R>(
    &self,
    operation: F
) -> Result<R, Error<Format::FormatError>>where
    Mode: Reading<T, Format>,
    F: FnOnce(&T, T) -> R,

Reads a value from the managed file, replacing the current state in memory, immediately granting the caller immutable access to that state for the duration of the provided function or closure.

The provided closure takes (1) a reference to the new state, and (2) the old state.

This function acquires a mutable lock on the shared state.

pub async fn operate_mut_commit<F, R, U>(
    &self,
    operation: F
) -> Result<R, UserError<Format::FormatError, U>>where
    Mode: Writing<T, Format>,
    F: FnOnce(&mut T) -> Result<R, U>,

Grants the caller mutable access to the underlying value T, but only for the duration of the provided function or closure, immediately committing any changes made as long as no error was returned.

This function acquires a mutable lock on the shared state.

pub async fn refresh(&self) -> Result<T, Error<Format::FormatError>>where
    Mode: Reading<T, Format>,

Reads a value from the managed file, replacing the current state in memory.

Returns the value of the previous state if the operation succeeded.

This function acquires an immutable lock on the shared state.

pub async fn commit(&self) -> Result<(), Error<Format::FormatError>>where
    Mode: Writing<T, Format>,

Writes the current in-memory state to the managed file.

This function acquires an immutable lock on the shared state. Don’t call this if you currently have an access guard, use ContainerAsync::commit_guard instead.

pub async fn commit_guard(
    &self,
    guard: OwnedAccessGuard<T>
) -> Result<(), Error<Format::FormatError>>where
    Mode: Writing<T, Format>,

Writes to the managed file given an access guard.

pub async fn overwrite(&self, item: T) -> Result<(), Error<Format::FormatError>>where
    Mode: Writing<T, Format>,

Writes the given state to the managed file, replacing the in-memory state.

Trait Implementations

impl<T, Manager> Clone for ContainerAsync<T, Manager>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug, Manager: Debug> Debug for ContainerAsync<T, Manager>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, Manager> From<Container<T, Manager>> for ContainerAsync<T, Manager>

fn from(container: Container<T, Manager>) -> Self

Converts to this type from the input type.