Module async_lock 

Async Lock Keypath Module

This module provides AsyncLockKp for safely navigating through async locked/synchronized data structures.

Naming convention (aligned with crate::lock::LockKp and crate::Kp)

• then – chain with a plain crate::Kp
• then_lock – chain with a sync crate::lock::LockKp
• then_async – chain with another async keypath (e.g. tokio RwLock)

Example: root_lock.then_lock(parking_kp).then_async(async_kp).then_lock(std_lock_kp)

SHALLOW CLONING GUARANTEE

IMPORTANT: All cloning operations in this module are SHALLOW (reference-counted) clones:

1. AsyncLockKp derives Clone: Clones function pointers and PhantomData only

   • prev and next fields contain function pointers (cheap to copy)
   • mid field is typically just PhantomData<T> (zero-sized, zero-cost)
   • No heap allocations or deep data copies

2. Lock: Clone bound (e.g., Arc<tokio::sync::Mutex<T>>):

   • For Arc<T>: Only increments the atomic reference count (one atomic operation)
   • The actual data T inside is NEVER cloned
   • This is the whole point of Arc - shared ownership without copying data

3. L: Clone bound (e.g., TokioMutexAccess<T>):

   • Only clones PhantomData<T> which is zero-sized
   • Compiled away completely - zero runtime cost

Structs

AsyncKeyPathThenKp

Keypath that chains an AsyncKeyPathLike (async get) with a crate::Kp (sync step). Use .get(&root).await to run.

AsyncLockKp

An async keypath that handles async locked values (e.g., Arc<tokio::sync::Mutex>)

AsyncLockKpThenLockKp

Keypath that goes through an async lock then a sync crate::lock::LockKp. Use AsyncLockKp::then_lock to create; then call AsyncLockKpThenLockKp::get or AsyncLockKpThenLockKp::get_mut with root.

ComposedAsyncLockKp

Chained async lock keypath: two or more async keypaths (Root -> V -> V2 -> …). Root is passed at get/get_mut time.

KpThenAsyncKeyPath

Keypath that chains a sync keypath (crate::Kp) with an AsyncKeyPathLike. Use crate::Kp::then_async to create; then .get(&root).await.

Traits

AsyncKeyPathLike

Trait for async keypaths (both AsyncLockKp and ComposedAsyncLockKp) so composition can be any depth.

AsyncLockLike

Async trait for types that can provide async lock/unlock behavior Converts from a Lock type to Inner or InnerMut value asynchronously

SyncKeyPathLike

Sync keypath that can be used as the “second” in AsyncLockKpThenLockKp for blanket impls. Also implemented for crate::Kp so crate::Kp::then_lock and crate::Kp::then_async can chain.