| 1 | // SPDX-License-Identifier: MIT |
| 2 | // |
| 3 | // This file is based on library/core/src/cell.rs from |
| 4 | // Rust 1.82.0. |
| 5 | // |
| 6 | // Permission is hereby granted, free of charge, to any |
| 7 | // person obtaining a copy of this software and associated |
| 8 | // documentation files (the "Software"), to deal in the |
| 9 | // Software without restriction, including without |
| 10 | // limitation the rights to use, copy, modify, merge, |
| 11 | // publish, distribute, sublicense, and/or sell copies of |
| 12 | // the Software, and to permit persons to whom the Software |
| 13 | // is furnished to do so, subject to the following |
| 14 | // conditions: |
| 15 | // |
| 16 | // The above copyright notice and this permission notice |
| 17 | // shall be included in all copies or substantial portions |
| 18 | // of the Software. |
| 19 | // |
| 20 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF |
| 21 | // ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED |
| 22 | // TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A |
| 23 | // PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT |
| 24 | // SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY |
| 25 | // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION |
| 26 | // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR |
| 27 | // IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 28 | // DEALINGS IN THE SOFTWARE. |
| 29 | |
| 30 | //! QEMU-specific mutable containers |
| 31 | //! |
| 32 | //! Rust memory safety is based on this rule: Given an object `T`, it is only |
| 33 | //! possible to have one of the following: |
| 34 | //! |
| 35 | //! - Having several immutable references (`&T`) to the object (also known as |
| 36 | //! **aliasing**). |
| 37 | //! - Having one mutable reference (`&mut T`) to the object (also known as |
| 38 | //! **mutability**). |
| 39 | //! |
| 40 | //! This is enforced by the Rust compiler. However, there are situations where |
| 41 | //! this rule is not flexible enough. Sometimes it is required to have multiple |
| 42 | //! references to an object and yet mutate it. In particular, QEMU objects |
| 43 | //! usually have their pointer shared with the "outside world very early in |
| 44 | //! their lifetime", for example when they create their [`MemoryRegion`s]. |
| 45 | //! Therefore, individual parts of a device must be made mutable in a |
| 46 | //! controlled manner; this module provides the tools to do so. |
| 47 | //! |
| 48 | //! [`MemoryRegion`s]: ../../system/memory/struct.MemoryRegion.html |
| 49 | //! |
| 50 | //! ## Cell types |
| 51 | //! |
| 52 | //! [`BqlCell<T>`] and [`BqlRefCell<T>`] allow doing this via the Big QEMU Lock. |
| 53 | //! While they are essentially the same single-threaded primitives that are |
| 54 | //! available in `std::cell`, the BQL allows them to be used from a |
| 55 | //! multi-threaded context and to share references across threads, while |
| 56 | //! maintaining Rust's safety guarantees. For this reason, unlike |
| 57 | //! their `std::cell` counterparts, `BqlCell` and `BqlRefCell` implement the |
| 58 | //! `Sync` trait. |
| 59 | //! |
| 60 | //! BQL checks are performed in debug builds but can be optimized away in |
| 61 | //! release builds, providing runtime safety during development with no overhead |
| 62 | //! in production. |
| 63 | //! |
| 64 | //! The two provide different ways of handling interior mutability. |
| 65 | //! `BqlRefCell` is best suited for data that is primarily accessed by the |
| 66 | //! device's own methods, where multiple reads and writes can be grouped within |
| 67 | //! a single borrow and a mutable reference can be passed around. Instead, |
| 68 | //! [`BqlCell`] is a better choice when sharing small pieces of data with |
| 69 | //! external code (especially C code), because it provides simple get/set |
| 70 | //! operations that can be used one at a time. |
| 71 | //! |
| 72 | //! Warning: While `BqlCell` and `BqlRefCell` are similar to their `std::cell` |
| 73 | //! counterparts, they are not interchangeable. Using `std::cell` types in |
| 74 | //! QEMU device implementations is usually incorrect and can lead to |
| 75 | //! thread-safety issues. |
| 76 | //! |
| 77 | //! ### Example |
| 78 | //! |
| 79 | //! ```ignore |
| 80 | //! # use bql::BqlRefCell; |
| 81 | //! # use qom::{Owned, ParentField}; |
| 82 | //! # use system::{InterruptSource, IRQState, SysBusDevice}; |
| 83 | //! # const N_GPIOS: usize = 8; |
| 84 | //! # struct PL061Registers { /* ... */ } |
| 85 | //! # unsafe impl ObjectType for PL061State { |
| 86 | //! # type Class = <SysBusDevice as ObjectType>::Class; |
| 87 | //! # const TYPE_NAME: &'static std::ffi::CStr = c"pl061"; |
| 88 | //! # } |
| 89 | //! struct PL061State { |
| 90 | //! parent_obj: ParentField<SysBusDevice>, |
| 91 | //! |
| 92 | //! // Configuration is read-only after initialization |
| 93 | //! pullups: u32, |
| 94 | //! pulldowns: u32, |
| 95 | //! |
| 96 | //! // Single values shared with C code use BqlCell, in this case via InterruptSource |
| 97 | //! out: [InterruptSource; N_GPIOS], |
| 98 | //! interrupt: InterruptSource, |
| 99 | //! |
| 100 | //! // Larger state accessed by device methods uses BqlRefCell or Mutex |
| 101 | //! registers: BqlRefCell<PL061Registers>, |
| 102 | //! } |
| 103 | //! ``` |
| 104 | //! |
| 105 | //! ### `BqlCell<T>` |
| 106 | //! |
| 107 | //! [`BqlCell<T>`] implements interior mutability by moving values in and out of |
| 108 | //! the cell. That is, an `&mut T` to the inner value can never be obtained as |
| 109 | //! long as the cell is shared. The value itself cannot be directly obtained |
| 110 | //! without copying it, cloning it, or replacing it with something else. This |
| 111 | //! type provides the following methods, all of which can be called only while |
| 112 | //! the BQL is held: |
| 113 | //! |
| 114 | //! - For types that implement [`Copy`], the [`get`](BqlCell::get) method |
| 115 | //! retrieves the current interior value by duplicating it. |
| 116 | //! - For types that implement [`Default`], the [`take`](BqlCell::take) method |
| 117 | //! replaces the current interior value with [`Default::default()`] and |
| 118 | //! returns the replaced value. |
| 119 | //! - All types have: |
| 120 | //! - [`replace`](BqlCell::replace): replaces the current interior value and |
| 121 | //! returns the replaced value. |
| 122 | //! - [`set`](BqlCell::set): this method replaces the interior value, |
| 123 | //! dropping the replaced value. |
| 124 | //! |
| 125 | //! ### `BqlRefCell<T>` |
| 126 | //! |
| 127 | //! [`BqlRefCell<T>`] uses Rust's lifetimes to implement "dynamic borrowing", a |
| 128 | //! process whereby one can claim temporary, exclusive, mutable access to the |
| 129 | //! inner value: |
| 130 | //! |
| 131 | //! ```ignore |
| 132 | //! fn clear_interrupts(&self, val: u32) { |
| 133 | //! // A mutable borrow gives read-write access to the registers |
| 134 | //! let mut regs = self.registers.borrow_mut(); |
| 135 | //! let old = regs.interrupt_status(); |
| 136 | //! regs.update_interrupt_status(old & !val); |
| 137 | //! } |
| 138 | //! ``` |
| 139 | //! |
| 140 | //! Borrows for `BqlRefCell<T>`s are tracked at _runtime_, unlike Rust's native |
| 141 | //! reference types which are entirely tracked statically, at compile time. |
| 142 | //! Multiple immutable borrows are allowed via [`borrow`](BqlRefCell::borrow), |
| 143 | //! or a single mutable borrow via [`borrow_mut`](BqlRefCell::borrow_mut). The |
| 144 | //! thread will panic if these rules are violated or if the BQL is not held. |
| 145 | #[cfg(feature = "debug_cell")] |
| 146 | use std::cell::Cell; |
| 147 | use std::{ |
| 148 | cell::UnsafeCell, |
| 149 | cmp::Ordering, |
| 150 | fmt, |
| 151 | marker::PhantomData, |
| 152 | mem, |
| 153 | ops::{Deref, DerefMut}, |
| 154 | ptr::NonNull, |
| 155 | }; |
| 156 | |
| 157 | /// A mutable memory location that is protected by the Big QEMU Lock. |
| 158 | /// |
| 159 | /// # Memory layout |
| 160 | /// |
| 161 | /// `BqlCell<T>` has the same in-memory representation as its inner type `T`. |
| 162 | #[repr(transparent)] |
| 163 | pub struct BqlCell<T> { |
| 164 | value: UnsafeCell<T>, |
| 165 | } |
| 166 | |
| 167 | // SAFETY: Same as for std::sync::Mutex. In the end this *is* a Mutex, |
| 168 | // except it is stored out-of-line |
| 169 | unsafe impl<T: Send> Send for BqlCell<T> {} |
| 170 | unsafe impl<T: Send> Sync for BqlCell<T> {} |
| 171 | |
| 172 | impl<T: Copy> Clone for BqlCell<T> { |
| 173 | #[inline] |
| 174 | fn clone(&self) -> BqlCell<T> { |
| 175 | BqlCell::new(self.get()) |
| 176 | } |
| 177 | } |
| 178 | |
| 179 | impl<T: Default> Default for BqlCell<T> { |
| 180 | /// Creates a `BqlCell<T>`, with the `Default` value for T. |
| 181 | #[inline] |
| 182 | fn default() -> BqlCell<T> { |
| 183 | BqlCell::new(Default::default()) |
| 184 | } |
| 185 | } |
| 186 | |
| 187 | impl<T: PartialEq + Copy> PartialEq for BqlCell<T> { |
| 188 | #[inline] |
| 189 | fn eq(&self, other: &BqlCell<T>) -> bool { |
| 190 | self.get() == other.get() |
| 191 | } |
| 192 | } |
| 193 | |
| 194 | impl<T: Eq + Copy> Eq for BqlCell<T> {} |
| 195 | |
| 196 | impl<T: PartialOrd + Copy> PartialOrd for BqlCell<T> { |
| 197 | #[inline] |
| 198 | fn partial_cmp(&self, other: &BqlCell<T>) -> Option<Ordering> { |
| 199 | self.get().partial_cmp(&other.get()) |
| 200 | } |
| 201 | } |
| 202 | |
| 203 | impl<T: Ord + Copy> Ord for BqlCell<T> { |
| 204 | #[inline] |
| 205 | fn cmp(&self, other: &BqlCell<T>) -> Ordering { |
| 206 | self.get().cmp(&other.get()) |
| 207 | } |
| 208 | } |
| 209 | |
| 210 | impl<T> From<T> for BqlCell<T> { |
| 211 | /// Creates a new `BqlCell<T>` containing the given value. |
| 212 | fn from(t: T) -> BqlCell<T> { |
| 213 | BqlCell::new(t) |
| 214 | } |
| 215 | } |
| 216 | |
| 217 | impl<T: fmt::Debug + Copy> fmt::Debug for BqlCell<T> { |
| 218 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 219 | self.get().fmt(f) |
| 220 | } |
| 221 | } |
| 222 | |
| 223 | impl<T: fmt::Display + Copy> fmt::Display for BqlCell<T> { |
| 224 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 225 | self.get().fmt(f) |
| 226 | } |
| 227 | } |
| 228 | |
| 229 | impl<T> BqlCell<T> { |
| 230 | /// Creates a new `BqlCell` containing the given value. |
| 231 | /// |
| 232 | /// # Examples |
| 233 | /// |
| 234 | /// ``` |
| 235 | /// use bql::BqlCell; |
| 236 | /// # bql::start_test(); |
| 237 | /// |
| 238 | /// let c = BqlCell::new(5); |
| 239 | /// ``` |
| 240 | #[inline] |
| 241 | pub const fn new(value: T) -> BqlCell<T> { |
| 242 | BqlCell { |
| 243 | value: UnsafeCell::new(value), |
| 244 | } |
| 245 | } |
| 246 | |
| 247 | /// Sets the contained value. |
| 248 | /// |
| 249 | /// # Examples |
| 250 | /// |
| 251 | /// ``` |
| 252 | /// use bql::BqlCell; |
| 253 | /// # bql::start_test(); |
| 254 | /// |
| 255 | /// let c = BqlCell::new(5); |
| 256 | /// |
| 257 | /// c.set(10); |
| 258 | /// ``` |
| 259 | #[inline] |
| 260 | pub fn set(&self, val: T) { |
| 261 | self.replace(val); |
| 262 | } |
| 263 | |
| 264 | /// Replaces the contained value with `val`, and returns the old contained |
| 265 | /// value. |
| 266 | /// |
| 267 | /// # Examples |
| 268 | /// |
| 269 | /// ``` |
| 270 | /// use bql::BqlCell; |
| 271 | /// # bql::start_test(); |
| 272 | /// |
| 273 | /// let cell = BqlCell::new(5); |
| 274 | /// assert_eq!(cell.get(), 5); |
| 275 | /// assert_eq!(cell.replace(10), 5); |
| 276 | /// assert_eq!(cell.get(), 10); |
| 277 | /// ``` |
| 278 | #[inline] |
| 279 | pub fn replace(&self, val: T) -> T { |
| 280 | assert!(crate::is_locked()); |
| 281 | // SAFETY: This can cause data races if called from multiple threads, |
| 282 | // but it won't happen as long as C code accesses the value |
| 283 | // under BQL protection only. |
| 284 | mem::replace(unsafe { &mut *self.value.get() }, val) |
| 285 | } |
| 286 | |
| 287 | /// Unwraps the value, consuming the cell. |
| 288 | /// |
| 289 | /// # Examples |
| 290 | /// |
| 291 | /// ``` |
| 292 | /// use bql::BqlCell; |
| 293 | /// # bql::start_test(); |
| 294 | /// |
| 295 | /// let c = BqlCell::new(5); |
| 296 | /// let five = c.into_inner(); |
| 297 | /// |
| 298 | /// assert_eq!(five, 5); |
| 299 | /// ``` |
| 300 | pub fn into_inner(self) -> T { |
| 301 | assert!(crate::is_locked()); |
| 302 | self.value.into_inner() |
| 303 | } |
| 304 | } |
| 305 | |
| 306 | impl<T: Copy> BqlCell<T> { |
| 307 | /// Returns a copy of the contained value. |
| 308 | /// |
| 309 | /// # Examples |
| 310 | /// |
| 311 | /// ``` |
| 312 | /// use bql::BqlCell; |
| 313 | /// # bql::start_test(); |
| 314 | /// |
| 315 | /// let c = BqlCell::new(5); |
| 316 | /// |
| 317 | /// let five = c.get(); |
| 318 | /// ``` |
| 319 | #[inline] |
| 320 | pub fn get(&self) -> T { |
| 321 | assert!(crate::is_locked()); |
| 322 | // SAFETY: This can cause data races if called from multiple threads, |
| 323 | // but it won't happen as long as C code accesses the value |
| 324 | // under BQL protection only. |
| 325 | unsafe { *self.value.get() } |
| 326 | } |
| 327 | } |
| 328 | |
| 329 | impl<T> BqlCell<T> { |
| 330 | /// Returns a raw pointer to the underlying data in this cell. |
| 331 | /// |
| 332 | /// # Examples |
| 333 | /// |
| 334 | /// ``` |
| 335 | /// use bql::BqlCell; |
| 336 | /// # bql::start_test(); |
| 337 | /// |
| 338 | /// let c = BqlCell::new(5); |
| 339 | /// |
| 340 | /// let ptr = c.as_ptr(); |
| 341 | /// ``` |
| 342 | #[inline] |
| 343 | pub const fn as_ptr(&self) -> *mut T { |
| 344 | self.value.get() |
| 345 | } |
| 346 | } |
| 347 | |
| 348 | impl<T: Default> BqlCell<T> { |
| 349 | /// Takes the value of the cell, leaving `Default::default()` in its place. |
| 350 | /// |
| 351 | /// # Examples |
| 352 | /// |
| 353 | /// ``` |
| 354 | /// use bql::BqlCell; |
| 355 | /// # bql::start_test(); |
| 356 | /// |
| 357 | /// let c = BqlCell::new(5); |
| 358 | /// let five = c.take(); |
| 359 | /// |
| 360 | /// assert_eq!(five, 5); |
| 361 | /// assert_eq!(c.into_inner(), 0); |
| 362 | /// ``` |
| 363 | pub fn take(&self) -> T { |
| 364 | self.replace(Default::default()) |
| 365 | } |
| 366 | } |
| 367 | |
| 368 | /// A mutable memory location with dynamically checked borrow rules, |
| 369 | /// protected by the Big QEMU Lock. |
| 370 | /// |
| 371 | /// See the [module-level documentation](self) for more. |
| 372 | /// |
| 373 | /// # Memory layout |
| 374 | /// |
| 375 | /// `BqlRefCell<T>` starts with the same in-memory representation as its |
| 376 | /// inner type `T`. |
| 377 | #[repr(C)] |
| 378 | pub struct BqlRefCell<T> { |
| 379 | // It is important that this is the first field (which is not the case |
| 380 | // for std::cell::BqlRefCell), so that we can use offset_of! on it. |
| 381 | // UnsafeCell and repr(C) both prevent usage of niches. |
| 382 | value: UnsafeCell<T>, |
| 383 | borrow: BqlCell<BorrowFlag>, |
| 384 | // Stores the location of the earliest currently active borrow. |
| 385 | // This gets updated whenever we go from having zero borrows |
| 386 | // to having a single borrow. When a borrow occurs, this gets included |
| 387 | // in the panic message |
| 388 | #[cfg(feature = "debug_cell")] |
| 389 | borrowed_at: Cell<Option<&'static std::panic::Location<'static>>>, |
| 390 | } |
| 391 | |
| 392 | // Positive values represent the number of `BqlRef` active. Negative values |
| 393 | // represent the number of `BqlRefMut` active. Right now QEMU's implementation |
| 394 | // does not allow to create `BqlRefMut`s that refer to distinct, nonoverlapping |
| 395 | // components of a `BqlRefCell` (e.g., different ranges of a slice). |
| 396 | // |
| 397 | // `BqlRef` and `BqlRefMut` are both two words in size, and so there will likely |
| 398 | // never be enough `BqlRef`s or `BqlRefMut`s in existence to overflow half of |
| 399 | // the `usize` range. Thus, a `BorrowFlag` will probably never overflow or |
| 400 | // underflow. However, this is not a guarantee, as a pathological program could |
| 401 | // repeatedly create and then mem::forget `BqlRef`s or `BqlRefMut`s. Thus, all |
| 402 | // code must explicitly check for overflow and underflow in order to avoid |
| 403 | // unsafety, or at least behave correctly in the event that overflow or |
| 404 | // underflow happens (e.g., see BorrowRef::new). |
| 405 | type BorrowFlag = isize; |
| 406 | const UNUSED: BorrowFlag = 0; |
| 407 | |
| 408 | #[inline(always)] |
| 409 | const fn is_writing(x: BorrowFlag) -> bool { |
| 410 | x < UNUSED |
| 411 | } |
| 412 | |
| 413 | #[inline(always)] |
| 414 | const fn is_reading(x: BorrowFlag) -> bool { |
| 415 | x > UNUSED |
| 416 | } |
| 417 | |
| 418 | impl<T> BqlRefCell<T> { |
| 419 | /// Creates a new `BqlRefCell` containing `value`. |
| 420 | /// |
| 421 | /// # Examples |
| 422 | /// |
| 423 | /// ``` |
| 424 | /// use bql::BqlRefCell; |
| 425 | /// |
| 426 | /// let c = BqlRefCell::new(5); |
| 427 | /// ``` |
| 428 | #[inline] |
| 429 | pub const fn new(value: T) -> BqlRefCell<T> { |
| 430 | BqlRefCell { |
| 431 | value: UnsafeCell::new(value), |
| 432 | borrow: BqlCell::new(UNUSED), |
| 433 | #[cfg(feature = "debug_cell")] |
| 434 | borrowed_at: Cell::new(None), |
| 435 | } |
| 436 | } |
| 437 | } |
| 438 | |
| 439 | // This ensures the panicking code is outlined from `borrow_mut` for |
| 440 | // `BqlRefCell`. |
| 441 | #[inline(never)] |
| 442 | #[cold] |
| 443 | #[cfg(feature = "debug_cell")] |
| 444 | fn panic_already_borrowed(source: &Cell<Option<&'static std::panic::Location<'static>>>) -> ! { |
| 445 | // If a borrow occurred, then we must already have an outstanding borrow, |
| 446 | // so `borrowed_at` will be `Some` |
| 447 | panic!("already borrowed at {:?}", source.take().unwrap()) |
| 448 | } |
| 449 | |
| 450 | #[inline(never)] |
| 451 | #[cold] |
| 452 | #[cfg(not(feature = "debug_cell"))] |
| 453 | fn panic_already_borrowed() -> ! { |
| 454 | panic!("already borrowed") |
| 455 | } |
| 456 | |
| 457 | impl<T> BqlRefCell<T> { |
| 458 | #[inline] |
| 459 | #[allow(clippy::unused_self)] |
| 460 | fn panic_already_borrowed(&self) -> ! { |
| 461 | #[cfg(feature = "debug_cell")] |
| 462 | { |
| 463 | panic_already_borrowed(&self.borrowed_at) |
| 464 | } |
| 465 | #[cfg(not(feature = "debug_cell"))] |
| 466 | { |
| 467 | panic_already_borrowed() |
| 468 | } |
| 469 | } |
| 470 | |
| 471 | /// Immutably borrows the wrapped value. |
| 472 | /// |
| 473 | /// The borrow lasts until the returned `BqlRef` exits scope. Multiple |
| 474 | /// immutable borrows can be taken out at the same time. |
| 475 | /// |
| 476 | /// # Panics |
| 477 | /// |
| 478 | /// Panics if the value is currently mutably borrowed. |
| 479 | /// |
| 480 | /// # Examples |
| 481 | /// |
| 482 | /// ``` |
| 483 | /// use bql::BqlRefCell; |
| 484 | /// # bql::start_test(); |
| 485 | /// |
| 486 | /// let c = BqlRefCell::new(5); |
| 487 | /// |
| 488 | /// let borrowed_five = c.borrow(); |
| 489 | /// let borrowed_five2 = c.borrow(); |
| 490 | /// ``` |
| 491 | /// |
| 492 | /// An example of panic: |
| 493 | /// |
| 494 | /// ```should_panic |
| 495 | /// use bql::BqlRefCell; |
| 496 | /// # bql::start_test(); |
| 497 | /// |
| 498 | /// let c = BqlRefCell::new(5); |
| 499 | /// |
| 500 | /// let m = c.borrow_mut(); |
| 501 | /// let b = c.borrow(); // this causes a panic |
| 502 | /// ``` |
| 503 | #[inline] |
| 504 | #[track_caller] |
| 505 | pub fn borrow(&self) -> BqlRef<'_, T> { |
| 506 | if let Some(b) = BorrowRef::new(&self.borrow) { |
| 507 | // `borrowed_at` is always the *first* active borrow |
| 508 | if b.borrow.get() == 1 { |
| 509 | #[cfg(feature = "debug_cell")] |
| 510 | self.borrowed_at.set(Some(std::panic::Location::caller())); |
| 511 | } |
| 512 | |
| 513 | crate::block_unlock(true); |
| 514 | |
| 515 | // SAFETY: `BorrowRef` ensures that there is only immutable access |
| 516 | // to the value while borrowed. |
| 517 | let value = unsafe { NonNull::new_unchecked(self.value.get()) }; |
| 518 | BqlRef { value, borrow: b } |
| 519 | } else { |
| 520 | self.panic_already_borrowed() |
| 521 | } |
| 522 | } |
| 523 | |
| 524 | /// Mutably borrows the wrapped value. |
| 525 | /// |
| 526 | /// The borrow lasts until the returned `BqlRefMut` or all `BqlRefMut`s |
| 527 | /// derived from it exit scope. The value cannot be borrowed while this |
| 528 | /// borrow is active. |
| 529 | /// |
| 530 | /// # Panics |
| 531 | /// |
| 532 | /// Panics if the value is currently borrowed. |
| 533 | /// |
| 534 | /// # Examples |
| 535 | /// |
| 536 | /// ``` |
| 537 | /// use bql::BqlRefCell; |
| 538 | /// # bql::start_test(); |
| 539 | /// |
| 540 | /// let c = BqlRefCell::new("hello".to_owned()); |
| 541 | /// |
| 542 | /// *c.borrow_mut() = "bonjour".to_owned(); |
| 543 | /// |
| 544 | /// assert_eq!(&*c.borrow(), "bonjour"); |
| 545 | /// ``` |
| 546 | /// |
| 547 | /// An example of panic: |
| 548 | /// |
| 549 | /// ```should_panic |
| 550 | /// use bql::BqlRefCell; |
| 551 | /// # bql::start_test(); |
| 552 | /// |
| 553 | /// let c = BqlRefCell::new(5); |
| 554 | /// let m = c.borrow(); |
| 555 | /// |
| 556 | /// let b = c.borrow_mut(); // this causes a panic |
| 557 | /// ``` |
| 558 | #[inline] |
| 559 | #[track_caller] |
| 560 | pub fn borrow_mut(&self) -> BqlRefMut<'_, T> { |
| 561 | if let Some(b) = BorrowRefMut::new(&self.borrow) { |
| 562 | #[cfg(feature = "debug_cell")] |
| 563 | { |
| 564 | self.borrowed_at.set(Some(std::panic::Location::caller())); |
| 565 | } |
| 566 | |
| 567 | // SAFETY: this only adjusts a counter |
| 568 | crate::block_unlock(true); |
| 569 | |
| 570 | // SAFETY: `BorrowRefMut` guarantees unique access. |
| 571 | let value = unsafe { NonNull::new_unchecked(self.value.get()) }; |
| 572 | BqlRefMut { |
| 573 | value, |
| 574 | _borrow: b, |
| 575 | marker: PhantomData, |
| 576 | } |
| 577 | } else { |
| 578 | self.panic_already_borrowed() |
| 579 | } |
| 580 | } |
| 581 | |
| 582 | /// Returns a mutable reference to the underlying data in this cell, |
| 583 | /// while the owner already has a mutable reference to the cell. |
| 584 | /// |
| 585 | /// # Examples |
| 586 | /// |
| 587 | /// ``` |
| 588 | /// use bql::BqlRefCell; |
| 589 | /// |
| 590 | /// let mut c = BqlRefCell::new(5); |
| 591 | /// |
| 592 | /// *c.get_mut() = 10; |
| 593 | /// ``` |
| 594 | #[inline] |
| 595 | pub const fn get_mut(&mut self) -> &mut T { |
| 596 | self.value.get_mut() |
| 597 | } |
| 598 | |
| 599 | /// Returns a raw pointer to the underlying data in this cell. |
| 600 | /// |
| 601 | /// # Examples |
| 602 | /// |
| 603 | /// ``` |
| 604 | /// use bql::BqlRefCell; |
| 605 | /// |
| 606 | /// let c = BqlRefCell::new(5); |
| 607 | /// |
| 608 | /// let ptr = c.as_ptr(); |
| 609 | /// ``` |
| 610 | #[inline] |
| 611 | pub const fn as_ptr(&self) -> *mut T { |
| 612 | self.value.get() |
| 613 | } |
| 614 | } |
| 615 | |
| 616 | // SAFETY: Same as for std::sync::Mutex. In the end this is a Mutex that is |
| 617 | // stored out-of-line. Even though BqlRefCell includes Cells, they are |
| 618 | // themselves protected by the Big QEMU Lock. Furtheremore, the Big QEMU |
| 619 | // Lock cannot be released while any borrows is active. |
| 620 | unsafe impl<T> Send for BqlRefCell<T> where T: Send {} |
| 621 | unsafe impl<T> Sync for BqlRefCell<T> {} |
| 622 | |
| 623 | impl<T: Clone> Clone for BqlRefCell<T> { |
| 624 | /// # Panics |
| 625 | /// |
| 626 | /// Panics if the value is currently mutably borrowed. |
| 627 | #[inline] |
| 628 | #[track_caller] |
| 629 | fn clone(&self) -> BqlRefCell<T> { |
| 630 | BqlRefCell::new(self.borrow().clone()) |
| 631 | } |
| 632 | |
| 633 | /// # Panics |
| 634 | /// |
| 635 | /// Panics if `source` is currently mutably borrowed. |
| 636 | #[inline] |
| 637 | #[track_caller] |
| 638 | fn clone_from(&mut self, source: &Self) { |
| 639 | self.value.get_mut().clone_from(&source.borrow()) |
| 640 | } |
| 641 | } |
| 642 | |
| 643 | impl<T: Default> Default for BqlRefCell<T> { |
| 644 | /// Creates a `BqlRefCell<T>`, with the `Default` value for T. |
| 645 | #[inline] |
| 646 | fn default() -> BqlRefCell<T> { |
| 647 | BqlRefCell::new(Default::default()) |
| 648 | } |
| 649 | } |
| 650 | |
| 651 | impl<T: PartialEq> PartialEq for BqlRefCell<T> { |
| 652 | /// # Panics |
| 653 | /// |
| 654 | /// Panics if the value in either `BqlRefCell` is currently mutably |
| 655 | /// borrowed. |
| 656 | #[inline] |
| 657 | fn eq(&self, other: &BqlRefCell<T>) -> bool { |
| 658 | *self.borrow() == *other.borrow() |
| 659 | } |
| 660 | } |
| 661 | |
| 662 | impl<T: Eq> Eq for BqlRefCell<T> {} |
| 663 | |
| 664 | impl<T: PartialOrd> PartialOrd for BqlRefCell<T> { |
| 665 | /// # Panics |
| 666 | /// |
| 667 | /// Panics if the value in either `BqlRefCell` is currently mutably |
| 668 | /// borrowed. |
| 669 | #[inline] |
| 670 | fn partial_cmp(&self, other: &BqlRefCell<T>) -> Option<Ordering> { |
| 671 | self.borrow().partial_cmp(&*other.borrow()) |
| 672 | } |
| 673 | } |
| 674 | |
| 675 | impl<T: Ord> Ord for BqlRefCell<T> { |
| 676 | /// # Panics |
| 677 | /// |
| 678 | /// Panics if the value in either `BqlRefCell` is currently mutably |
| 679 | /// borrowed. |
| 680 | #[inline] |
| 681 | fn cmp(&self, other: &BqlRefCell<T>) -> Ordering { |
| 682 | self.borrow().cmp(&*other.borrow()) |
| 683 | } |
| 684 | } |
| 685 | |
| 686 | impl<T> From<T> for BqlRefCell<T> { |
| 687 | /// Creates a new `BqlRefCell<T>` containing the given value. |
| 688 | fn from(t: T) -> BqlRefCell<T> { |
| 689 | BqlRefCell::new(t) |
| 690 | } |
| 691 | } |
| 692 | |
| 693 | struct BorrowRef<'b> { |
| 694 | borrow: &'b BqlCell<BorrowFlag>, |
| 695 | } |
| 696 | |
| 697 | impl<'b> BorrowRef<'b> { |
| 698 | #[inline] |
| 699 | fn new(borrow: &'b BqlCell<BorrowFlag>) -> Option<BorrowRef<'b>> { |
| 700 | let b = borrow.get().wrapping_add(1); |
| 701 | if !is_reading(b) { |
| 702 | // Incrementing borrow can result in a non-reading value (<= 0) in these cases: |
| 703 | // 1. It was < 0, i.e. there are writing borrows, so we can't allow a read |
| 704 | // borrow due to Rust's reference aliasing rules |
| 705 | // 2. It was isize::MAX (the max amount of reading borrows) and it overflowed |
| 706 | // into isize::MIN (the max amount of writing borrows) so we can't allow an |
| 707 | // additional read borrow because isize can't represent so many read borrows |
| 708 | // (this can only happen if you mem::forget more than a small constant amount |
| 709 | // of `BqlRef`s, which is not good practice) |
| 710 | None |
| 711 | } else { |
| 712 | // Incrementing borrow can result in a reading value (> 0) in these cases: |
| 713 | // 1. It was = 0, i.e. it wasn't borrowed, and we are taking the first read |
| 714 | // borrow |
| 715 | // 2. It was > 0 and < isize::MAX, i.e. there were read borrows, and isize is |
| 716 | // large enough to represent having one more read borrow |
| 717 | borrow.set(b); |
| 718 | Some(BorrowRef { borrow }) |
| 719 | } |
| 720 | } |
| 721 | } |
| 722 | |
| 723 | impl Drop for BorrowRef<'_> { |
| 724 | #[inline] |
| 725 | fn drop(&mut self) { |
| 726 | let borrow = self.borrow.get(); |
| 727 | debug_assert!(is_reading(borrow)); |
| 728 | self.borrow.set(borrow - 1); |
| 729 | crate::block_unlock(false) |
| 730 | } |
| 731 | } |
| 732 | |
| 733 | impl Clone for BorrowRef<'_> { |
| 734 | #[inline] |
| 735 | fn clone(&self) -> Self { |
| 736 | BorrowRef::new(self.borrow).unwrap() |
| 737 | } |
| 738 | } |
| 739 | |
| 740 | /// Wraps a borrowed reference to a value in a `BqlRefCell` box. |
| 741 | /// A wrapper type for an immutably borrowed value from a `BqlRefCell<T>`. |
| 742 | /// |
| 743 | /// See the [module-level documentation](self) for more. |
| 744 | pub struct BqlRef<'b, T: 'b> { |
| 745 | // NB: we use a pointer instead of `&'b T` to avoid `noalias` violations, because a |
| 746 | // `BqlRef` argument doesn't hold immutability for its whole scope, only until it drops. |
| 747 | // `NonNull` is also covariant over `T`, just like we would have with `&T`. |
| 748 | value: NonNull<T>, |
| 749 | borrow: BorrowRef<'b>, |
| 750 | } |
| 751 | |
| 752 | impl<T> Deref for BqlRef<'_, T> { |
| 753 | type Target = T; |
| 754 | |
| 755 | #[inline] |
| 756 | fn deref(&self) -> &T { |
| 757 | // SAFETY: the value is accessible as long as we hold our borrow. |
| 758 | unsafe { self.value.as_ref() } |
| 759 | } |
| 760 | } |
| 761 | |
| 762 | impl<'b, T> BqlRef<'b, T> { |
| 763 | /// Copies a `BqlRef`. |
| 764 | /// |
| 765 | /// The `BqlRefCell` is already immutably borrowed, so this cannot fail. |
| 766 | /// |
| 767 | /// This is an associated function that needs to be used as |
| 768 | /// `BqlRef::clone(...)`. A `Clone` implementation or a method would |
| 769 | /// interfere with the widespread use of `r.borrow().clone()` to clone |
| 770 | /// the contents of a `BqlRefCell`. |
| 771 | #[must_use] |
| 772 | #[inline] |
| 773 | #[allow(clippy::should_implement_trait)] |
| 774 | pub fn clone(orig: &BqlRef<'b, T>) -> BqlRef<'b, T> { |
| 775 | BqlRef { |
| 776 | value: orig.value, |
| 777 | borrow: orig.borrow.clone(), |
| 778 | } |
| 779 | } |
| 780 | } |
| 781 | |
| 782 | impl<T: fmt::Debug> fmt::Debug for BqlRef<'_, T> { |
| 783 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 784 | (**self).fmt(f) |
| 785 | } |
| 786 | } |
| 787 | |
| 788 | impl<T: fmt::Display> fmt::Display for BqlRef<'_, T> { |
| 789 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 790 | (**self).fmt(f) |
| 791 | } |
| 792 | } |
| 793 | |
| 794 | struct BorrowRefMut<'b> { |
| 795 | borrow: &'b BqlCell<BorrowFlag>, |
| 796 | } |
| 797 | |
| 798 | impl<'b> BorrowRefMut<'b> { |
| 799 | #[inline] |
| 800 | fn new(borrow: &'b BqlCell<BorrowFlag>) -> Option<BorrowRefMut<'b>> { |
| 801 | // There must currently be no existing references when borrow_mut() is |
| 802 | // called, so we explicitly only allow going from UNUSED to UNUSED - 1. |
| 803 | match borrow.get() { |
| 804 | UNUSED => { |
| 805 | borrow.set(UNUSED - 1); |
| 806 | Some(BorrowRefMut { borrow }) |
| 807 | } |
| 808 | _ => None, |
| 809 | } |
| 810 | } |
| 811 | } |
| 812 | |
| 813 | impl Drop for BorrowRefMut<'_> { |
| 814 | #[inline] |
| 815 | fn drop(&mut self) { |
| 816 | let borrow = self.borrow.get(); |
| 817 | debug_assert!(is_writing(borrow)); |
| 818 | self.borrow.set(borrow + 1); |
| 819 | crate::block_unlock(false) |
| 820 | } |
| 821 | } |
| 822 | |
| 823 | /// A wrapper type for a mutably borrowed value from a `BqlRefCell<T>`. |
| 824 | /// |
| 825 | /// See the [module-level documentation](self) for more. |
| 826 | pub struct BqlRefMut<'b, T: 'b> { |
| 827 | // NB: we use a pointer instead of `&'b mut T` to avoid `noalias` violations, because a |
| 828 | // `BqlRefMut` argument doesn't hold exclusivity for its whole scope, only until it drops. |
| 829 | value: NonNull<T>, |
| 830 | _borrow: BorrowRefMut<'b>, |
| 831 | // `NonNull` is covariant over `T`, so we need to reintroduce invariance. |
| 832 | marker: PhantomData<&'b mut T>, |
| 833 | } |
| 834 | |
| 835 | impl<T> Deref for BqlRefMut<'_, T> { |
| 836 | type Target = T; |
| 837 | |
| 838 | #[inline] |
| 839 | fn deref(&self) -> &T { |
| 840 | // SAFETY: the value is accessible as long as we hold our borrow. |
| 841 | unsafe { self.value.as_ref() } |
| 842 | } |
| 843 | } |
| 844 | |
| 845 | impl<T> DerefMut for BqlRefMut<'_, T> { |
| 846 | #[inline] |
| 847 | fn deref_mut(&mut self) -> &mut T { |
| 848 | // SAFETY: the value is accessible as long as we hold our borrow. |
| 849 | unsafe { self.value.as_mut() } |
| 850 | } |
| 851 | } |
| 852 | |
| 853 | impl<T: fmt::Debug> fmt::Debug for BqlRefMut<'_, T> { |
| 854 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 855 | (**self).fmt(f) |
| 856 | } |
| 857 | } |
| 858 | |
| 859 | impl<T: fmt::Display> fmt::Display for BqlRefMut<'_, T> { |
| 860 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 861 | (**self).fmt(f) |
| 862 | } |
| 863 | } |