This document covers the technical architecture, safety invariants, and macro code generation details of the ksync crate.
ksync implements a token-based synchronization pattern (also known as the “Ghost Token” pattern). Instead of encapsulating the protected data inside the mutex or reader-writer lock struct itself (like std::sync::Mutex<T>), it separates the lock state (KMutex, BrwLockPi) from the actual data storage (KCell).
+-------------------------------------------------------------+
| Parent Struct |
| |
| +-------------------+ +------------------------+ |
| | KMutex/BrwLockPi | | KCell<T, Class> | |
| | (Raw Lock State) | | (UnsafeCell wrapper) | |
| +--------+----------+ +-----------+------------+ |
+------------|-------------------------------|----------------+
| lock() / read_lock() | get(token)
v v
+--------+------------+ +--------+-------+
| Lock Guard | | &T / &mut T |
| |-------->| (Safe Access) |
| - LockToken | +----------------+
+---------------------+
LockToken<'a, Class>: A zero-sized type (ZST) that serves as compile-time proof that the lock for Class is currently held by the current thread. It has a lifetime 'a bound to the active lock guard.KMutex<Class, M>: The mutual exclusion lock state representation, wrapping a raw lock M: RawLock. Locking it acquires the raw lock and returns a KMutexGuard holding the LockToken. There is no default M: the kernel's TrackedMutex is not part of this crate (see Raw lock implementations).BrwLockPi<Class, L>: The priority-inheriting reader-writer lock state representation, wrapping a raw reader-writer lock L: RawSharedLock (again with no default). Locking it returns a BrwLockPiReadGuard or BrwLockPiWriteGuard holding the LockToken.KCell<T, Class>: A wrapper around core::cell::UnsafeCell<T>. It provides token-gated accessors (get(&self, token) and get_mut(&self, token)).While the LockToken and KCell share a compile-time Class type parameter to prevent mixing locks of different types, this type-level association is insufficient to guarantee memory safety.
To provide safety, the macro generates custom guard structures (e.g. MyStructMuGuard, MyStructLockReadGuard, MyStructLockWriteGuard) that wrap standard lock guards and hold a reference to the parent structure instance. These custom guards expose safe, compiler-checked projection accessors (such as .field() or .fields_mut()). This guarantees safe access to guarded fields without requiring any unsafe block or risking cross-instance token mixing.
ksync is split into two parts:
ksync crate (//src/lib/ksync:ksync) holds the lock traits (RawLock, RawSharedLock, LockPolicy, ...), the generic lock types (KMutex, BrwLockPi, KCell, ...), the macros, and the userspace raw locks used for host builds and tests.TrackedMutex, TrackedCriticalMutex, TrackedSpinlock, TrackedMonitoredSpinlock, TrackedBrwLockPi, TrackedBrwLockNoPi), their policies, the KSpinlock / KMonitoredSpinlock aliases, and the declare_singleton_mutex!, declare_singleton_critical_mutex!, declare_singleton_spinlock! and declare_singleton_monitored_spinlock! macros live in //zircon/kernel/lib/ksync. This is a kernel_rust_mod that is compiled directly into the kernel crate and mounted at crate::ksync_kernel. The mutexes are implemented directly on the Rust kernel Mutex in //zircon/kernel/kernel/mutex.rs, the spinlocks on the Rust kernel SpinLock and MonitoredSpinLock in //zircon/kernel/kernel/spinlock.rs, and the reader-writer locks on the Rust kernel BrwLockPi and BrwLockNoPi in //zircon/kernel/kernel/brwlock.rs, and re-exported from crate::ksync_kernel.As a result, neither the ksync crate nor any other non-kernel crate (such as fbl or region_alloc) can name the kernel's raw locks. Generic code is instead parameterized over its raw lock type (M: RawLock), and the final usage site in the kernel crate supplies the concrete raw lock (e.g. crate::ksync_kernel::TrackedMutex). For the same reason there is no default raw lock type: KMutex and BrwLockPi fields in a #[guarded] struct (e.g. KMutex<TrackedSpinlock> or BrwLockPi<TrackedBrwLockPi>) and declare_singleton_lock! must always name their raw lock type explicitly.
If a thread has unique exclusive access to the KCell container itself (either by holding ownership self or an exclusive borrow &mut self), it doesn't need a runtime lock token to access the data safely. The Rust borrow checker already guarantees compile-time thread exclusivity:
get_inner_mut(&mut self) -> &mut T: Accesses the inner value mutably via UnsafeCell::get_mut(). This is safe because the &mut self borrow ensures no other borrows of the cell are active.into_inner(self) -> T: Consumes the KCell container and returns the inner value T safely via UnsafeCell::into_inner().The #[guarded] attribute proc-macro parses a struct definition, rewrites its fields, and generates the lock acquisition methods.
#[guarded] pub struct MyStruct { #[mutex] pub mu: KMutex<TrackedMutex>, #[brwlock] pub lock: BrwLockPi<TrackedBrwLockPi>, #[guarded_by(mu)] pub data1: u32, #[guarded_by(lock)] pub data2: i32, }
// 1. Unique Lock Class marker structs generated automatically pub struct MyStructMuClass; pub struct MyStructLockClass; // 2. Struct fields rewritten to KMutex/BrwLockPi and KCell pub struct MyStruct { pub mu: ::ksync::KMutex<MyStructMuClass, TrackedMutex>, pub lock: ::ksync::BrwLockPi<MyStructLockClass, TrackedBrwLockPi>, pub data1: ::ksync::KCell<u32, MyStructMuClass>, pub data2: ::ksync::KCell<i32, MyStructLockClass>, } // 3. Custom projection guard structures (stack-pinned) pub struct MyStructMuGuard<'a> { parent: &'a MyStruct, inner: ::ksync::KMutexGuard<'a, MyStructMuClass, TrackedMutex>, _pin: ::core::marker::PhantomPinned, } pub struct MyStructLockReadGuard<'a> { parent: &'a MyStruct, inner: ::ksync::BrwLockPiReadGuard<'a, MyStructLockClass, TrackedBrwLockPi>, _pin: ::core::marker::PhantomPinned, } pub struct MyStructLockWriteGuard<'a> { parent: &'a MyStruct, inner: ::ksync::BrwLockPiWriteGuard<'a, MyStructLockClass, TrackedBrwLockPi>, _pin: ::core::marker::PhantomPinned, } // 4. Safe projection accessors and field projection structs pub struct MyStructLockReadFields<'b> { pub data2: &'b i32, _marker: ::core::marker::PhantomData<&'b ()>, } pub struct MyStructLockWriteFields<'b> { pub data2: &'b mut i32, _marker: ::core::marker::PhantomData<&'b ()>, } impl<'a> MyStructMuGuard<'a> { pub fn data1(&self) -> &u32 { unsafe { self.parent.data1.get(self.inner.token()) } } pub fn data1_mut(self: Pin<&mut Self>) -> &mut u32 { ... } pub fn fields<'b>(&'b self) -> MyStructMuFields<'b> { ... } pub fn fields_mut<'b>(self: Pin<&'b mut Self>) -> MyStructMuFieldsMut<'b> { ... } } impl<'a> MyStructLockReadGuard<'a> { pub fn data2(&self) -> &i32 { unsafe { self.parent.data2.get(self.inner.token()) } } pub fn fields<'b>(&'b self) -> MyStructLockReadFields<'b> { ... } } impl<'a> MyStructLockWriteGuard<'a> { pub fn data2(&self) -> &i32 { unsafe { self.parent.data2.get(self.inner.token()) } } pub fn data2_mut(self: Pin<&mut Self>) -> &mut i32 { ... } pub fn fields<'b>(&'b self) -> MyStructLockReadFields<'b> { ... } pub fn fields_mut<'b>(self: Pin<&'b mut Self>) -> MyStructLockWriteFields<'b> { ... } } // 5. Lock methods implemented on the parent struct returning PinInit blocks impl MyStruct { #[inline(always)] pub fn lock_mu(&self) -> impl pin_init::PinInit<MyStructMuGuard<'_>, ::core::convert::Infallible> { MyStructMuGuard::__new(self, ::ksync::KMutexGuard::new(&self.mu)) } #[inline(always)] pub fn read_lock(&self) -> impl pin_init::PinInit<MyStructLockReadGuard<'_>, ::core::convert::Infallible> { MyStructLockReadGuard::__new(self, ::ksync::BrwLockPiReadGuard::new(&self.lock)) } #[inline(always)] pub fn write_lock(&self) -> impl pin_init::PinInit<MyStructLockWriteGuard<'_>, ::core::convert::Infallible> { MyStructLockWriteGuard::__new(self, ::ksync::BrwLockPiWriteGuard::new(&self.lock)) } }