rust/kernel/sync/refcount.rs

Source file repositories/reference/linux-study-clean/rust/kernel/sync/refcount.rs

File Facts

System
Linux kernel
Corpus path
rust/kernel/sync/refcount.rs
Extension
.rs
Size
4397 bytes
Lines
117
Domain
Rust Kernel Layer
Bucket
Rust API Membrane
Inferred role
Rust Kernel Layer: implementation source
Status
source implementation candidate

Why This File Exists

Rust-side wrappers and abstractions around kernel C APIs, ownership contracts, allocation, synchronization, and module integration.

Dependency Surface

Detected Declarations

Annotated Snippet

pub fn set(&self, value: i32) {
        // SAFETY: `self.as_ptr()` is valid.
        unsafe { bindings::refcount_set(self.as_ptr(), value) }
    }

    /// Increment a refcount.
    ///
    /// It will saturate if overflows and `WARN`. It will also `WARN` if the refcount is 0, as this
    /// represents a possible use-after-free condition.
    ///
    /// Provides no memory ordering, it is assumed that caller already has a reference on the
    /// object.
    #[inline]
    pub fn inc(&self) {
        // SAFETY: self is valid.
        unsafe { bindings::refcount_inc(self.as_ptr()) }
    }

    /// Decrement a refcount.
    ///
    /// It will `WARN` on underflow and fail to decrement when saturated.
    ///
    /// Provides release memory ordering, such that prior loads and stores are done
    /// before.
    #[inline]
    pub fn dec(&self) {
        // SAFETY: `self.as_ptr()` is valid.
        unsafe { bindings::refcount_dec(self.as_ptr()) }
    }

    /// Decrement a refcount and test if it is 0.
    ///
    /// It will `WARN` on underflow and fail to decrement when saturated.
    ///
    /// Provides release memory ordering, such that prior loads and stores are done
    /// before, and provides an acquire ordering on success such that memory deallocation
    /// must come after.
    ///
    /// Returns true if the resulting refcount is 0, false otherwise.
    ///
    /// # Notes
    ///
    /// A common pattern of using `Refcount` is to free memory when the reference count reaches
    /// zero. This means that the reference to `Refcount` could become invalid after calling this
    /// function. This is fine as long as the reference to `Refcount` is no longer used when this
    /// function returns `false`. It is not necessary to use raw pointers in this scenario, see
    /// <https://github.com/rust-lang/rust/issues/55005>.
    #[inline]
    #[must_use = "use `dec` instead if you do not need to test if it is 0"]
    pub fn dec_and_test(&self) -> bool {
        // SAFETY: `self.as_ptr()` is valid.
        unsafe { bindings::refcount_dec_and_test(self.as_ptr()) }
    }
}

// SAFETY: `refcount_t` is thread-safe.
unsafe impl Send for Refcount {}

// SAFETY: `refcount_t` is thread-safe.
unsafe impl Sync for Refcount {}

Annotation

Implementation Notes