poll.rs

  1// SPDX-License-Identifier: GPL-2.0
  2
  3// Copyright (C) 2024 Google LLC.
  4
  5//! Utilities for working with `struct poll_table`.
  6
  7use crate::{
  8    bindings,
  9    fs::File,
 10    prelude::*,
 11    sync::{CondVar, LockClassKey},
 12};
 13use core::{marker::PhantomData, ops::Deref};
 14
 15/// Creates a [`PollCondVar`] initialiser with the given name and a newly-created lock class.
 16#[macro_export]
 17macro_rules! new_poll_condvar {
 18    ($($name:literal)?) => {
 19        $crate::sync::poll::PollCondVar::new(
 20            $crate::optional_name!($($name)?), $crate::static_lock_class!()
 21        )
 22    };
 23}
 24
 25/// Wraps the kernel's `poll_table`.
 26///
 27/// # Invariants
 28///
 29/// The pointer must be null or reference a valid `poll_table`.
 30#[repr(transparent)]
 31pub struct PollTable<'a> {
 32    table: *mut bindings::poll_table,
 33    _lifetime: PhantomData<&'a bindings::poll_table>,
 34}
 35
 36impl<'a> PollTable<'a> {
 37    /// Creates a [`PollTable`] from a valid pointer.
 38    ///
 39    /// # Safety
 40    ///
 41    /// The pointer must be null or reference a valid `poll_table` for the duration of `'a`.
 42    pub unsafe fn from_raw(table: *mut bindings::poll_table) -> Self {
 43        // INVARIANTS: The safety requirements are the same as the struct invariants.
 44        PollTable {
 45            table,
 46            _lifetime: PhantomData,
 47        }
 48    }
 49
 50    /// Register this [`PollTable`] with the provided [`PollCondVar`], so that it can be notified
 51    /// using the condition variable.
 52    pub fn register_wait(&self, file: &File, cv: &PollCondVar) {
 53        // SAFETY:
 54        // * `file.as_ptr()` references a valid file for the duration of this call.
 55        // * `self.table` is null or references a valid poll_table for the duration of this call.
 56        // * Since `PollCondVar` is pinned, its destructor is guaranteed to run before the memory
 57        //   containing `cv.wait_queue_head` is invalidated. Since the destructor clears all
 58        //   waiters and then waits for an rcu grace period, it's guaranteed that
 59        //   `cv.wait_queue_head` remains valid for at least an rcu grace period after the removal
 60        //   of the last waiter.
 61        unsafe { bindings::poll_wait(file.as_ptr(), cv.wait_queue_head.get(), self.table) }
 62    }
 63}
 64
 65/// A wrapper around [`CondVar`] that makes it usable with [`PollTable`].
 66///
 67/// [`CondVar`]: crate::sync::CondVar
 68#[pin_data(PinnedDrop)]
 69pub struct PollCondVar {
 70    #[pin]
 71    inner: CondVar,
 72}
 73
 74impl PollCondVar {
 75    /// Constructs a new condvar initialiser.
 76    pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> {
 77        pin_init!(Self {
 78            inner <- CondVar::new(name, key),
 79        })
 80    }
 81}
 82
 83// Make the `CondVar` methods callable on `PollCondVar`.
 84impl Deref for PollCondVar {
 85    type Target = CondVar;
 86
 87    fn deref(&self) -> &CondVar {
 88        &self.inner
 89    }
 90}
 91
 92#[pinned_drop]
 93impl PinnedDrop for PollCondVar {
 94    #[inline]
 95    fn drop(self: Pin<&mut Self>) {
 96        // Clear anything registered using `register_wait`.
 97        //
 98        // SAFETY: The pointer points at a valid `wait_queue_head`.
 99        unsafe { bindings::__wake_up_pollfree(self.inner.wait_queue_head.get()) };
100
101        // Wait for epoll items to be properly removed.
102        //
103        // SAFETY: Just an FFI call.
104        unsafe { bindings::synchronize_rcu() };
105    }
106}