blob: 177bcaf7476fe56f70d0a9b4f9eb3cf799046ac0 [file] [view]
# ksync
`ksync` is a Rust crate providing a token-based lock API, designed for
low-level, `no_std` environments like the Zircon kernel.
## Purpose
`ksync` separates lock states from data. Instead of encapsulating protected
data inside the lock struct itself (like `std::sync::Mutex<T>`), the data
resides in separate fields of the same struct, wrapped in `KCell`. Access to
these cells is granted only by presenting a `LockToken` (held by the
guards returned when locking).
This design is particularly useful when:
1. **Multiple fields need to be protected by the same lock** but we want to
keep them as distinct fields of the parent struct for clarity and layout
control.
2. **We need to support disjoint mutable borrows** of different guarded fields
simultaneously, which is normally difficult with a single standard lock
guard.
## Ergonomic Attribute Macro: `#[guarded]`
The primary way to use this crate is via the `#[guarded]` attribute macro.
Apply `#[guarded]` to your struct and use the helper attributes:
* `#[mutex]` to mark a `KMutex<RawLockType>` field (e.g.
`KMutex<TrackedMutex>`). The raw lock type is required; see
[Raw lock types](#raw-lock-types).
* `#[brwlock]` to mark a `BrwLockPi<RawLockType>` (Reader-Writer) field (e.g.
`BrwLockPi<TrackedBrwLockPi>`).
* `#[guarded_by(lock_field_name)]` to mark fields protected by that lock.
Under the hood, the macro:
1. Rewrites guarded fields to `KCell<T, LockClass>`.
2. Generates unique lock class markers automatically.
3. Implements lock helper methods on the parent struct returning PinInit
blocks for custom projection guards (e.g., `MyStructMuGuard` or
`MyStructLockReadGuard`). These guards expose safe projection accessors
directly.
### Mutex Example
```rust
use crate::ksync_kernel::TrackedMutex;
use ksync::{guarded, KMutex, lock};
#[derive(Default)]
#[guarded]
struct ImageCache {
#[mutex]
mu: KMutex<TrackedMutex>,
#[guarded_by(mu)]
hits: u32,
#[guarded_by(mu)]
misses: u32,
pub path: String,
}
fn update_cache(cache: &ImageCache, is_hit: bool) {
// Acquire lock.
lock!(let mut guard = cache.lock_mu());
// Access fields safely on the guard:
if is_hit {
*guard.as_mut().hits_mut() += 1;
} else {
*guard.as_mut().misses_mut() += 1;
}
// Or obtain disjoint mutable borrows of multiple fields simultaneously
// using split accessors:
let fields = guard.as_mut().fields_mut();
if is_hit {
*fields.hits += 1;
} else {
*fields.misses += 1;
}
}
fn main() {
let cache = ImageCache {
hits: 42.into(), // Under the hood, hits is a KCell, initialized via Into
path: "/path/to/cache".to_string(),
..Default::default()
};
update_cache(&cache, true);
}
```
### Reader-Writer Lock Example
```rust
use crate::ksync_kernel::TrackedBrwLockPi;
use ksync::{guarded, BrwLockPi, lock};
#[derive(Default)]
#[guarded]
struct Database {
#[brwlock]
lock: BrwLockPi<TrackedBrwLockPi>,
#[guarded_by(lock)]
data: Vec<String>,
#[guarded_by(lock)]
query_count: u64,
}
fn read_data(db: &Database) -> usize {
// Shared read access
lock!(let guard = db.read_lock());
let len = guard.data().len();
// Access multiple fields via shared projection (disjoint read borrows):
let fields = guard.fields();
let _ = fields.data.len();
let _ = *fields.query_count;
len
}
fn append_data(db: &Database, value: String) {
// Exclusive write access
lock!(let mut guard = db.write_lock());
// Obtain disjoint mutable borrows of multiple fields simultaneously
// using split/projection accessors:
let fields = guard.as_mut().fields_mut();
fields.data.push(value);
*fields.query_count += 1;
}
```
### Multiple Mutexes
If your struct has multiple locks, the macro will automatically generate a
distinct, unique lock class for each lock field. You can lock them independently
and access their respective fields:
```rust
use crate::ksync_kernel::TrackedMutex;
use ksync::{guarded, KMutex, lock};
#[derive(Default)]
#[guarded]
struct DualCache {
#[mutex]
mu1: KMutex<TrackedMutex>,
#[mutex]
mu2: KMutex<TrackedMutex>,
#[guarded_by(mu1)]
data1: u32,
#[guarded_by(mu2)]
data2: i32,
}
fn process_dual_cache(cache: &DualCache) {
// Lock both mutexes independently.
lock!(let mut guard1 = cache.lock_mu1());
lock!(let mut guard2 = cache.lock_mu2());
// Access individual fields safely via guards:
*guard1.as_mut().data1_mut() = 100;
*guard2.as_mut().data2_mut() = -50;
// Split accessors work for each guard independently as well:
let fields1 = guard1.as_mut().fields_mut();
*fields1.data1 += 10;
}
fn main() {
let cache = DualCache::default();
process_dual_cache(&cache);
}
```
### Fields Guarded by Multiple Locks
A field can be annotated with `#[guarded_by(mu1, mu2, ...)]` (comparable to
`TA_GUARDED(mu1) TA_GUARDED(mu2)` in C++):
* **Reading** only requires holding **any one** of the guarding locks
(`guard1.shared()`, `guard2.shared()`, or `guard1.fields().shared`).
* **Mutating** requires holding **all** guarding locks simultaneously and
passing the remaining lock guard(s) or mutable token guard(s) to
`guard1.as_mut().shared_mut(&mut guard2, ...)`.
* In `guard1.as_mut().fields_mut()`, single-lock fields are projected mutably
(`&mut T`), whereas multi-lock fields are projected immutably (`&T`) since
`fields_mut()` only proves a single lock is held.
```rust
use crate::ksync_kernel::TrackedMutex;
use ksync::{guarded, KMutex, lock};
#[guarded]
struct SharedNode {
#[mutex]
mu1: KMutex<TrackedMutex>,
#[mutex]
mu2: KMutex<TrackedMutex>,
#[guarded_by(mu1, mu2)]
all_filled: bool,
}
fn check_and_arm(node: &SharedNode) {
// Reading requires only one lock:
{
lock!(let g1 = node.lock_mu1());
let _ = *g1.all_filled();
}
// Mutating requires both locks:
lock!(let mut g1 = node.lock_mu1());
lock!(let mut g2 = node.lock_mu2());
*g1.as_mut().all_filled_mut(&mut g2) = true;
}
```
## Raw Lock Types
`KMutex` and `BrwLockPi` are generic over their raw lock type, and there is no
default. The examples in this file use `TrackedMutex`, which refers to:
* In the kernel: `crate::ksync_kernel::TrackedMutex` (a lockdep-tracked
kernel `Mutex`). The other kernel raw locks (`TrackedCriticalMutex`,
`TrackedSpinlock`, `TrackedMonitoredSpinlock`, `TrackedBrwLockPi`,
`TrackedBrwLockNoPi`), the `KSpinlock` / `KMonitoredSpinlock` aliases, and
the `declare_singleton_mutex!`, `declare_singleton_critical_mutex!`,
`declare_singleton_spinlock!` and `declare_singleton_monitored_spinlock!`
macros are also in `crate::ksync_kernel`. These are defined in
`//zircon/kernel/lib/ksync` (the mutexes are defined alongside the kernel
`Mutex` in `//zircon/kernel/kernel/mutex.rs`, the spinlocks alongside the
kernel `SpinLock` in `//zircon/kernel/kernel/spinlock.rs`, and the
reader-writer locks alongside the kernel `BrwLock` in
`//zircon/kernel/kernel/brwlock.rs`, and re-exported from
`crate::ksync_kernel`), which is a `kernel_rust_mod`
compiled directly into the kernel crate rather than part of the `ksync`
crate.
* Outside the kernel (host builds and tests), use `ksync::RawMutex` in its
place.
Because only the kernel crate can name the kernel's raw locks, code outside of
the kernel crate that uses `ksync` (for example `fbl` or `region_alloc`) must
be generic over its lock type (`M: ksync::RawLock`) and let the kernel usage
site supply the concrete raw lock:
```rust
// In a library crate:
#[guarded]
pub struct Allocator<M: ksync::RawLock> {
#[mutex]
mu: KMutex<M>,
#[guarded_by(mu)]
next: u64,
}
// In the kernel crate:
type KernelAllocator = Allocator<crate::ksync_kernel::TrackedMutex>;
```
## Locked Inherent Methods
When porting C++ code that utilizes Clang's Thread Safety Analysis (e.g.,
methods annotated with `TA_REQ(mu)`) to Rust, this crate provides a safe analog
by declaring these lock-required methods directly on the generated Guard
structure instead of the parent struct.
This design pattern:
1. **Guarantees compile-time safety**: The method cannot be physically called
unless the caller has successfully acquired the lock and holds the Guard
object.
2. **Scopes lock lifetime**: The lock is scoped naturally by the Guard's
lifetime (RAII).
### Explicit Parent Struct Access
The generated Guard structure holds a private reference `parent` pointing to
the physical parent structure instance. Since the Guard is generated inside the
same module, you can explicitly access all un-guarded fields and call
lock-free parent methods through `self.parent`:
* **Read un-guarded fields**: `self.parent.remote_address`
* **Call lock-free methods**: `self.parent.is_local()`
For guarded fields, the Guard's inherent target accessors (like
`self.bytes_sent()`) or split accessors (`self.fields_mut()`) provide safe
access.
### Example
```rust
#[derive(Default)]
#[guarded]
struct Connection {
#[mutex]
mu: KMutex<TrackedMutex>,
#[guarded_by(mu)]
bytes_sent: u64,
// Un-guarded state
pub remote_address: String,
}
impl Connection {
// Lock-free method on the parent struct
pub fn is_local(&self) -> bool {
self.remote_address.starts_with("127.0.0.1")
}
}
// Locked methods declared on the generated Guard!
impl<'a> ConnectionMuGuard<'a> {
pub fn send_packet(mut self: core::pin::Pin<&mut Self>, size: u64) {
// 1. Access and mutate guarded fields:
let fields = self.as_mut().fields_mut();
*fields.bytes_sent += size;
// 2. Explicitly read un-guarded fields via self.parent:
if self.parent.remote_address.is_empty() {
return;
}
// 3. Explicitly call lock-free methods via self.parent:
if self.parent.is_local() {
// ...
}
}
}
fn main() {
use ksync::lock;
let mut conn = Connection {
remote_address: "127.0.0.1:8080".to_string(),
..Default::default()
};
// Scoped lock and execution:
lock!(let mut guard = conn.lock_mu());
guard.as_mut().send_packet(1024);
}
```
## Advanced Locking Features
### Temporarily Releasing Locks: `call_unlocked`
Guards provide `call_unlocked` to temporarily drop the held lock while running
a blocking operation or callback, and automatically reacquire the lock upon
completion:
```rust
lock!(let mut guard = my_struct.lock_mu());
// Temporarily drop lock to wait on an event or perform blocking I/O:
let result = guard.as_mut().call_unlocked(|| {
ready_event.wait();
compute_something()
});
// The lock is automatically re-acquired when call_unlocked returns.
*guard.as_mut().data_mut() = result;
```
### Aliased Locks: `AliasedLock` / `aliased_lock`
When two references point to the same physical lock instance (e.g. an operation
object borrowing its parent's lock), `ksync::aliased_lock` acquires the physical
mutex once while returning a `KMutexAliasedGuard` that provides proof tokens for
both lock classes:
```rust
// Acquires the lock once and verifies at runtime that both alias pointers match:
lock!(let mut guard = ksync::aliased_lock(&parent.mu, op.lock()));
// Access parent and child fields simultaneously with disjoint mutable tokens:
unsafe {
let (parent_token, op_token) = guard.as_mut().tokens_mut();
*parent.guard_mu_mut(parent_token).data_mut() = 1;
*op.guard_mu_mut(op_token).value_mut() = 2;
}
```
### Lock Flags Configuration
You can configure lock validation flags directly in `#[mutex]` and `#[brwlock]`:
```rust
#[guarded]
struct StreamDispatcherState {
#[mutex(flags = lockdep::LOCK_FLAGS_ACTIVE_LIST_DISABLED)]
seek_lock: KMutex<TrackedMutex>,
#[guarded_by(seek_lock)]
seek: u64,
}
```