rust: sync: introduce `LockClassKey`

//! This module contains the kernel APIs related to synchronisation that have been ported or

//! wrapped for usage by Rust code in the kernel.

use crate::types::Opaque;

mod arc;

pub use arc::{Arc, ArcBorrow, UniqueArc};

/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.

#[repr(transparent)]

pub struct LockClassKey(Opaque<bindings::lock_class_key>);

// SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and

// provides its own synchronization.

unsafe impl Sync for LockClassKey {}

impl LockClassKey {

    /// Creates a new lock class key.

    pub const fn new() -> Self {

        Self(Opaque::uninit())

    }

    #[allow(dead_code)]

    pub(crate) fn as_ptr(&self) -> *mut bindings::lock_class_key {

        self.0.get()

    }

}

/// Defines a new static lock class and returns a pointer to it.

#[doc(hidden)]

#[macro_export]

macro_rules! static_lock_class {

    () => {{

        static CLASS: $crate::sync::LockClassKey = $crate::sync::LockClassKey::new();

        &CLASS

    }};

}

/// Returns the given string, if one is provided, otherwise generates one based on the source code

/// location.

#[doc(hidden)]

#[macro_export]

macro_rules! optional_name {

    () => {

        $crate::c_str!(::core::concat!(::core::file!(), ":", ::core::line!()))

    };

    ($name:literal) => {

        $crate::c_str!($name)

    };

}