17b1f55e3SWedson Almeida Filho // SPDX-License-Identifier: GPL-2.0 27b1f55e3SWedson Almeida Filho 37b1f55e3SWedson Almeida Filho //! A wrapper for data protected by a lock that does not wrap it. 47b1f55e3SWedson Almeida Filho 57b1f55e3SWedson Almeida Filho use super::{lock::Backend, lock::Lock}; 67b1f55e3SWedson Almeida Filho use crate::build_assert; 77b1f55e3SWedson Almeida Filho use core::{cell::UnsafeCell, mem::size_of, ptr}; 87b1f55e3SWedson Almeida Filho 97b1f55e3SWedson Almeida Filho /// Allows access to some data to be serialised by a lock that does not wrap it. 107b1f55e3SWedson Almeida Filho /// 117b1f55e3SWedson Almeida Filho /// In most cases, data protected by a lock is wrapped by the appropriate lock type, e.g., 12*ed6d0bedSValentin Obst /// [`Mutex`] or [`SpinLock`]. [`LockedBy`] is meant for cases when this is not possible. 13*ed6d0bedSValentin Obst /// For example, if a container has a lock and some data in the contained elements needs 147b1f55e3SWedson Almeida Filho /// to be protected by the same lock. 157b1f55e3SWedson Almeida Filho /// 167b1f55e3SWedson Almeida Filho /// [`LockedBy`] wraps the data in lieu of another locking primitive, and only allows access to it 177b1f55e3SWedson Almeida Filho /// when the caller shows evidence that the 'external' lock is locked. It panics if the evidence 187b1f55e3SWedson Almeida Filho /// refers to the wrong instance of the lock. 197b1f55e3SWedson Almeida Filho /// 20*ed6d0bedSValentin Obst /// [`Mutex`]: super::Mutex 21*ed6d0bedSValentin Obst /// [`SpinLock`]: super::SpinLock 22*ed6d0bedSValentin Obst /// 237b1f55e3SWedson Almeida Filho /// # Examples 247b1f55e3SWedson Almeida Filho /// 257b1f55e3SWedson Almeida Filho /// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an 267b1f55e3SWedson Almeida Filho /// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in 277b1f55e3SWedson Almeida Filho /// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at 287b1f55e3SWedson Almeida Filho /// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also 297b1f55e3SWedson Almeida Filho /// locked; we enforce at run time that the right `InnerDirectory` is locked. 307b1f55e3SWedson Almeida Filho /// 317b1f55e3SWedson Almeida Filho /// ``` 327b1f55e3SWedson Almeida Filho /// use kernel::sync::{LockedBy, Mutex}; 337b1f55e3SWedson Almeida Filho /// 347b1f55e3SWedson Almeida Filho /// struct InnerFile { 357b1f55e3SWedson Almeida Filho /// bytes_used: u64, 367b1f55e3SWedson Almeida Filho /// } 377b1f55e3SWedson Almeida Filho /// 387b1f55e3SWedson Almeida Filho /// struct File { 397b1f55e3SWedson Almeida Filho /// _ino: u32, 407b1f55e3SWedson Almeida Filho /// inner: LockedBy<InnerFile, InnerDirectory>, 417b1f55e3SWedson Almeida Filho /// } 427b1f55e3SWedson Almeida Filho /// 437b1f55e3SWedson Almeida Filho /// struct InnerDirectory { 447b1f55e3SWedson Almeida Filho /// /// The sum of the bytes used by all files. 457b1f55e3SWedson Almeida Filho /// bytes_used: u64, 467b1f55e3SWedson Almeida Filho /// _files: Vec<File>, 477b1f55e3SWedson Almeida Filho /// } 487b1f55e3SWedson Almeida Filho /// 497b1f55e3SWedson Almeida Filho /// struct Directory { 507b1f55e3SWedson Almeida Filho /// _ino: u32, 517b1f55e3SWedson Almeida Filho /// inner: Mutex<InnerDirectory>, 527b1f55e3SWedson Almeida Filho /// } 537b1f55e3SWedson Almeida Filho /// 547b1f55e3SWedson Almeida Filho /// /// Prints `bytes_used` from both the directory and file. 557b1f55e3SWedson Almeida Filho /// fn print_bytes_used(dir: &Directory, file: &File) { 567b1f55e3SWedson Almeida Filho /// let guard = dir.inner.lock(); 577b1f55e3SWedson Almeida Filho /// let inner_file = file.inner.access(&guard); 587b1f55e3SWedson Almeida Filho /// pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used); 597b1f55e3SWedson Almeida Filho /// } 607b1f55e3SWedson Almeida Filho /// 617b1f55e3SWedson Almeida Filho /// /// Increments `bytes_used` for both the directory and file. 627b1f55e3SWedson Almeida Filho /// fn inc_bytes_used(dir: &Directory, file: &File) { 637b1f55e3SWedson Almeida Filho /// let mut guard = dir.inner.lock(); 647b1f55e3SWedson Almeida Filho /// guard.bytes_used += 10; 657b1f55e3SWedson Almeida Filho /// 667b1f55e3SWedson Almeida Filho /// let file_inner = file.inner.access_mut(&mut guard); 677b1f55e3SWedson Almeida Filho /// file_inner.bytes_used += 10; 687b1f55e3SWedson Almeida Filho /// } 697b1f55e3SWedson Almeida Filho /// 707b1f55e3SWedson Almeida Filho /// /// Creates a new file. 717b1f55e3SWedson Almeida Filho /// fn new_file(ino: u32, dir: &Directory) -> File { 727b1f55e3SWedson Almeida Filho /// File { 737b1f55e3SWedson Almeida Filho /// _ino: ino, 747b1f55e3SWedson Almeida Filho /// inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }), 757b1f55e3SWedson Almeida Filho /// } 767b1f55e3SWedson Almeida Filho /// } 777b1f55e3SWedson Almeida Filho /// ``` 787b1f55e3SWedson Almeida Filho pub struct LockedBy<T: ?Sized, U: ?Sized> { 797b1f55e3SWedson Almeida Filho owner: *const U, 807b1f55e3SWedson Almeida Filho data: UnsafeCell<T>, 817b1f55e3SWedson Almeida Filho } 827b1f55e3SWedson Almeida Filho 837b1f55e3SWedson Almeida Filho // SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can. 847b1f55e3SWedson Almeida Filho unsafe impl<T: ?Sized + Send, U: ?Sized> Send for LockedBy<T, U> {} 857b1f55e3SWedson Almeida Filho 867b1f55e3SWedson Almeida Filho // SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the 877b1f55e3SWedson Almeida Filho // data it protects is `Send`. 887b1f55e3SWedson Almeida Filho unsafe impl<T: ?Sized + Send, U: ?Sized> Sync for LockedBy<T, U> {} 897b1f55e3SWedson Almeida Filho 907b1f55e3SWedson Almeida Filho impl<T, U> LockedBy<T, U> { 917b1f55e3SWedson Almeida Filho /// Constructs a new instance of [`LockedBy`]. 927b1f55e3SWedson Almeida Filho /// 937b1f55e3SWedson Almeida Filho /// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure 947b1f55e3SWedson Almeida Filho /// that the right owner is being used to access the protected data. If the owner is freed, the 957b1f55e3SWedson Almeida Filho /// data becomes inaccessible; if another instance of the owner is allocated *on the same 967b1f55e3SWedson Almeida Filho /// memory location*, the data becomes accessible again: none of this affects memory safety 977b1f55e3SWedson Almeida Filho /// because in any case at most one thread (or CPU) can access the protected data at a time. new<B: Backend>(owner: &Lock<U, B>, data: T) -> Self987b1f55e3SWedson Almeida Filho pub fn new<B: Backend>(owner: &Lock<U, B>, data: T) -> Self { 997b1f55e3SWedson Almeida Filho build_assert!( 1007b1f55e3SWedson Almeida Filho size_of::<Lock<U, B>>() > 0, 1017b1f55e3SWedson Almeida Filho "The lock type cannot be a ZST because it may be impossible to distinguish instances" 1027b1f55e3SWedson Almeida Filho ); 1037b1f55e3SWedson Almeida Filho Self { 1047b1f55e3SWedson Almeida Filho owner: owner.data.get(), 1057b1f55e3SWedson Almeida Filho data: UnsafeCell::new(data), 1067b1f55e3SWedson Almeida Filho } 1077b1f55e3SWedson Almeida Filho } 1087b1f55e3SWedson Almeida Filho } 1097b1f55e3SWedson Almeida Filho 1107b1f55e3SWedson Almeida Filho impl<T: ?Sized, U> LockedBy<T, U> { 1117b1f55e3SWedson Almeida Filho /// Returns a reference to the protected data when the caller provides evidence (via a 1127b1f55e3SWedson Almeida Filho /// reference) that the owner is locked. 1137b1f55e3SWedson Almeida Filho /// 1147b1f55e3SWedson Almeida Filho /// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&U` that matches 1157b1f55e3SWedson Almeida Filho /// the data protected by the lock without actually holding it. 1167b1f55e3SWedson Almeida Filho /// 1177b1f55e3SWedson Almeida Filho /// # Panics 1187b1f55e3SWedson Almeida Filho /// 1197b1f55e3SWedson Almeida Filho /// Panics if `owner` is different from the data protected by the lock used in 1207b1f55e3SWedson Almeida Filho /// [`new`](LockedBy::new). access<'a>(&'a self, owner: &'a U) -> &'a T1217b1f55e3SWedson Almeida Filho pub fn access<'a>(&'a self, owner: &'a U) -> &'a T { 1227b1f55e3SWedson Almeida Filho build_assert!( 1237b1f55e3SWedson Almeida Filho size_of::<U>() > 0, 1247b1f55e3SWedson Almeida Filho "`U` cannot be a ZST because `owner` wouldn't be unique" 1257b1f55e3SWedson Almeida Filho ); 1267b1f55e3SWedson Almeida Filho if !ptr::eq(owner, self.owner) { 1277b1f55e3SWedson Almeida Filho panic!("mismatched owners"); 1287b1f55e3SWedson Almeida Filho } 1297b1f55e3SWedson Almeida Filho 1307b1f55e3SWedson Almeida Filho // SAFETY: `owner` is evidence that the owner is locked. 1317b1f55e3SWedson Almeida Filho unsafe { &*self.data.get() } 1327b1f55e3SWedson Almeida Filho } 1337b1f55e3SWedson Almeida Filho 1347b1f55e3SWedson Almeida Filho /// Returns a mutable reference to the protected data when the caller provides evidence (via a 1357b1f55e3SWedson Almeida Filho /// mutable owner) that the owner is locked mutably. 1367b1f55e3SWedson Almeida Filho /// 1377b1f55e3SWedson Almeida Filho /// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&mut U` that 1387b1f55e3SWedson Almeida Filho /// matches the data protected by the lock without actually holding it. 1397b1f55e3SWedson Almeida Filho /// 1407b1f55e3SWedson Almeida Filho /// Showing a mutable reference to the owner is sufficient because we know no other references 1417b1f55e3SWedson Almeida Filho /// can exist to it. 1427b1f55e3SWedson Almeida Filho /// 1437b1f55e3SWedson Almeida Filho /// # Panics 1447b1f55e3SWedson Almeida Filho /// 1457b1f55e3SWedson Almeida Filho /// Panics if `owner` is different from the data protected by the lock used in 1467b1f55e3SWedson Almeida Filho /// [`new`](LockedBy::new). access_mut<'a>(&'a self, owner: &'a mut U) -> &'a mut T1477b1f55e3SWedson Almeida Filho pub fn access_mut<'a>(&'a self, owner: &'a mut U) -> &'a mut T { 1487b1f55e3SWedson Almeida Filho build_assert!( 1497b1f55e3SWedson Almeida Filho size_of::<U>() > 0, 1507b1f55e3SWedson Almeida Filho "`U` cannot be a ZST because `owner` wouldn't be unique" 1517b1f55e3SWedson Almeida Filho ); 1527b1f55e3SWedson Almeida Filho if !ptr::eq(owner, self.owner) { 1537b1f55e3SWedson Almeida Filho panic!("mismatched owners"); 1547b1f55e3SWedson Almeida Filho } 1557b1f55e3SWedson Almeida Filho 1567b1f55e3SWedson Almeida Filho // SAFETY: `owner` is evidence that there is only one reference to the owner. 1577b1f55e3SWedson Almeida Filho unsafe { &mut *self.data.get() } 1587b1f55e3SWedson Almeida Filho } 1597b1f55e3SWedson Almeida Filho } 160