Module sync_kp 

Sync keypath module (sync_kp)

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

Naming convention (aligned with crate::Kp and crate::async_lock)

• then – chain with a plain crate::Kp
• then_sync – chain with another SyncKp for multi-level lock access

SHALLOW CLONING GUARANTEE & NO UNNECESSARY CLONES

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

1. SyncKp 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. NO Lock: Clone required for most operations:

   • lock_write takes &Lock (not &mut Lock) due to interior mutability
   • For Arc<Mutex<T>>: No cloning needed, we just use &Arc<...>
   • The actual data T inside is NEVER cloned during lock operations
   • This eliminates unnecessary Arc reference count increments

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

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

Performance Characteristics

• SyncKp::clone(): O(1) - copies a few pointers
• ArcMutexAccess::clone(): O(1) - no-op (zero-sized type)
• Lock operations: No Arc cloning needed - direct reference use
• Total: All operations are constant-time with no deep copying

Memory Safety

The design is safe because:

• Locks provide interior mutability (no &mut needed for write operations)
• Arc provides thread-safe reference counting
• Mutex ensures exclusive access when needed
• No dangling pointers or use-after-free possible
• Rust’s ownership system enforces correctness

Structs

ArcMutexAccess

Lock access implementation for Arc<Mutex>

ArcRwLockAccess

Lock access implementation for Arc<RwLock>

ComposedSyncKeyPath

Composes two crate::async_lock::SyncKeyPathLike steps (used by KpThenSyncKp::then / KpThenSyncKp::then_sync).

KpThenSyncKp

Keypath that chains a crate::Kp with a SyncKp. Use [crate::Kp::then_sync] to create.

RcRefCellAccess

Lock access implementation for Rc<RefCell>

StdMutexAccess

Lock access implementation for std::sync::Mutex (without Arc wrapper)

StdRwLockAccess

Lock access implementation for std::sync::RwLock (without Arc wrapper)

SyncKp

A keypath that handles locked values (e.g., Arc<Mutex>)

Traits

LockAccess

Trait for types that can provide lock/unlock behavior Converts from a Lock type to Inner or InnerMut value

Type Aliases

SyncKpArcMutexFor

Type alias for SyncKp over Arc<std::sync::Mutex>. Use with derive macro’s _lock() methods.

SyncKpArcMutexOptionFor

Type alias for SyncKp over Arc<std::sync::Mutex<Option>>; value is T (extract from Option).

SyncKpArcRwLockFor

Type alias for SyncKp over Arc<std::sync::RwLock>. Use with derive macro’s _lock() methods.

SyncKpArcRwLockOptionFor

Type alias for SyncKp over Arc<std::sync::RwLock<Option>>; value is T (extract from Option).

SyncKpType

Type alias for common SyncKp usage with Arc<Mutex>