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    /// Opaque stack entry storage type used by the lock validation loop detector (e.g. LockDep).
13    type LockEntry: Default;
14
15    /// State returned from lock acquisition and subsequently passed to lock release.
16    type GuardState: Default + Copy;
17
18    /// Returns a PinInit block to initialize the raw mutex in-place.
19    fn init() -> impl PinInit<Self, core::convert::Infallible>
20    where
21        Self: Sized;
22
23    /// Convert the raw mutex reference to a standard c_void pointer for FFI.
24    fn as_mut_ptr(&self) -> *mut core::ffi::c_void;
25
26    /// Acquires the raw synchronization lock under a type-level lock class.
27    ///
28    /// # Safety
29    ///
30    /// 1. The `lcid` pointer must point to a valid dynamic `LockClassId` if not null (used for
31    ///    LockDep).
32    /// 2. The `entry` pointer must point to a valid, exclusive, stack-allocated `LockEntry` slot
33    ///    which will be registered in the thread's active list.
34    /// 3. The caller must ensure that the `entry` memory remains pinned on the stack and is not
35    ///    dropped or moved until the matching `release` call completes.
36    unsafe fn acquire(
37        &self,
38        lcid: *mut core::ffi::c_void,
39        entry: *mut Self::LockEntry,
40    ) -> Self::GuardState;
41
42    /// Releases the raw synchronization lock, restoring the state.
43    ///
44    /// # Safety
45    ///
46    /// 1. The `entry` pointer must match the exact same stack slot pointer passed to the
47    ///    corresponding `acquire` call.
48    /// 2. The `state` parameter must match the exact same state value returned by the corresponding
49    ///    `acquire` call.
50    /// 3. The caller must guarantee that the current thread actually holds this lock (i.e. we are
51    ///    releasing a lock we currently own).
52    unsafe fn release(&self, entry: *mut Self::LockEntry, state: Self::GuardState);
53}
ksync/raw_lock.rs

ksync/
raw_lock.rs
