Crate shared_container

Crate shared_container 

Source
Expand description

§Shared Container - Type-Safe Shared Data Access

This library provides type-safe abstractions for shared data access across different runtime environments: synchronous multi-threaded, asynchronous (tokio), and single-threaded (WebAssembly).

§Quick Start

§Synchronous Usage

use shared_container::{Shared, SyncAccess};

let container = Shared::new(42);

// Read access
let guard = container.read().unwrap();
assert_eq!(*guard, 42);
drop(guard);

// Write access
let mut guard = container.write().unwrap();
*guard = 100;

§Asynchronous Usage (with async feature)

use shared_container::{AsyncShared, AsyncAccess};

let container = AsyncShared::new(42);

// Async read access
let guard = container.read_async().await;
assert_eq!(*guard, 42);
drop(guard);

// Async write access
let mut guard = container.write_async().await;
*guard = 100;

§Key Features

  • Type-Level Separation: Shared<T> for sync, AsyncShared<T> for async
  • Platform-Aware: Automatically uses the right backend based on target
    • Native: Arc<RwLock<T>>
    • WebAssembly: Rc<RefCell<T>>
    • Async: Arc<tokio::sync::RwLock<T>>
  • Explicit Errors: Result<_, AccessError> instead of Option or panics
  • Zero Runtime Overhead: No blocking operations or runtime initialization

§Feature Flags

  • async: Enables AsyncShared<T> and async trait methods (requires tokio)
  • std-sync (default): Legacy support for SharedContainer with std sync primitives
  • tokio-sync: Legacy support for SharedContainer with tokio primitives
  • wasm-sync: Legacy support for forcing WebAssembly backend

§Migration from 2.x

The old SharedContainer<T> API is deprecated. Migrate to the new type-safe API:

Old (2.x)New (0.3)
SharedContainer::new(v) (std-sync)Shared::new(v)
SharedContainer::new(v) (tokio-sync)AsyncShared::new(v)
container.read() → Option<_>container.read() → Result<_, AccessError>
container.read_async().awaitcontainer.read_async().await

§Error Handling

The new API uses AccessError enum for explicit error handling:

use shared_container::{Shared, SyncAccess, AccessError};

let container = Shared::new(42);
match container.read() {
    Ok(guard) => println!("Value: {}", *guard),
    Err(AccessError::Poisoned) => println!("Lock was poisoned"),
    Err(AccessError::BorrowConflict) => println!("Already borrowed"),
    Err(AccessError::UnsupportedMode) => println!("Wrong container type"),
}

Structs§

AsyncReadGuardasync
Read guard for asynchronous access.
AsyncSharedasync
An asynchronous shared container using tokio primitives.
AsyncWriteGuardasync
Write guard for asynchronous access.
Shared
A synchronous shared container that works across platforms.
SharedContainerDeprecated
A unified container for shared data that works in both multi-threaded and single-threaded environments.
WeakAsyncSharedasync
A weak reference to an AsyncShared<T>.
WeakShared
A weak reference to a Shared<T>.
WeakSharedContainerDeprecated
A weak reference to a SharedContainer.

Enums§

AccessError
Errors that can occur when accessing shared containers.
SharedAny
A universal container that can hold either sync or async variants.
SharedReadGuard
A read-only guard for accessing data in a SharedContainer.
SharedWriteGuard
A writable guard for accessing and modifying data in a SharedContainer.
SyncReadGuard
Read guard for synchronous access.
SyncWriteGuard
Write guard for synchronous access.
WeakSharedAny
A weak reference to a SharedAny<T>.

Traits§

AsyncAccessasync
Trait for asynchronous access to shared containers.
SyncAccess
Trait for synchronous access to shared containers.