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

ksync/
raw_lock.rs
