ksync/
raw_lock.rs

1// Copyright 2026 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use pin_init::PinInit;
6
7/// Trait defining a raw, un-instrumented synchronization lock abstraction.
8///
9/// Implementors of `RawLock` supply the platform-specific lock storage, in-place pinning
10/// initialization logic, and raw synchronization entry points for lock validation systems.
11pub trait RawLock {
12    /// Flags specifying validation rules for the lock class.
13    const LOCK_FLAGS: lockdep::LockFlags = lockdep::LOCK_FLAGS_NONE;
14
15    /// Opaque stack entry storage type used by the lock validation loop detector (e.g. LockDep).
16    type LockEntry: Default;
17
18    /// State returned from lock acquisition and subsequently passed to lock release.
19    type GuardState: Default + Copy;
20
21    /// Returns a PinInit block to initialize the raw mutex in-place.
22    ///
23    /// # Safety
24    ///
25    /// The caller must ensure that `class_id` is either null or points to a valid,
26    /// static `LockClassId` that remains valid for the lifetime of the lock.
27    unsafe fn init(
28        class_id: *const core::ffi::c_void,
29    ) -> impl PinInit<Self, core::convert::Infallible>
30    where
31        Self: Sized;
32
33    /// Convert the raw mutex reference to a standard c_void pointer for FFI.
34    fn as_mut_ptr(&self) -> *mut core::ffi::c_void;
35
36    /// Acquires the raw synchronization lock under a type-level lock class.
37    ///
38    /// # Safety
39    ///
40    /// 1. The `entry` pointer must point to a valid, exclusive, stack-allocated `LockEntry` slot
41    ///    which will be registered in the thread's active list.
42    /// 2. The caller must ensure that the `entry` memory remains pinned on the stack and is not
43    ///    dropped or moved until the matching `release` call completes.
44    unsafe fn acquire(&self, entry: *mut Self::LockEntry) -> Self::GuardState;
45
46    /// Releases the raw synchronization lock, restoring the state.
47    ///
48    /// # Safety
49    ///
50    /// 1. The `entry` pointer must match the exact same stack slot pointer passed to the
51    ///    corresponding `acquire` call.
52    /// 2. The `state` parameter must match the exact same state value returned by the corresponding
53    ///    `acquire` call.
54    /// 3. The caller must guarantee that the current thread actually holds this lock (i.e. we are
55    ///    releasing a lock we currently own).
56    unsafe fn release(&self, entry: *mut Self::LockEntry, state: Self::GuardState);
57}
ksync/raw_lock.rs

ksync/
raw_lock.rs
