utils.rs - source
Description: Source of the Rust file `library/std/src/sync/mpmc/utils.rs`.

#
std/sync/mpmc/
utils.rs

    1use crate::cell::Cell;
    2use crate::ops::{Deref, DerefMut};
    3
    4/// Pads and aligns a value to the length of a cache line.
    5#[derive(Clone, Copy, Default, Hash, PartialEq, Eq)]
    6// Starting from Intel's Sandy Bridge, spatial prefetcher is now pulling pairs of 64-byte cache
    7// lines at a time, so we have to align to 128 bytes rather than 64.
    8//
    9// Sources:
    10// - https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-optimization-manual.pdf
    11// - https://github.com/facebook/folly/blob/1b5288e6eea6df074758f877c849b6e73bbb9fbb/folly/lang/Align.h#L107
    12//
    13// ARM's big.LITTLE architecture has asymmetric cores and "big" cores have 128-byte cache line size.
    14//
    15// Sources:
    16// - https://www.mono-project.com/news/2016/09/12/arm64-icache/
    17//
    18// powerpc64 has 128-byte cache line size.
    19//
    20// Sources:
    21// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_ppc64x.go#L9
    22#[cfg_attr(
    23    any(target_arch = "x86_64", target_arch = "aarch64", target_arch = "powerpc64",),
    24    repr(align(128))
    25)]
    26// arm, mips and mips64 have 32-byte cache line size.
    27//
    28// Sources:
    29// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_arm.go#L7
    30// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips.go#L7
    31// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mipsle.go#L7
    32// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips64x.go#L9
    33#[cfg_attr(
    34    any(
    35        target_arch = "arm",
    36        target_arch = "mips",
    37        target_arch = "mips32r6",
    38        target_arch = "mips64",
    39        target_arch = "mips64r6",
    40    ),
    41    repr(align(32))
    42)]
    43// s390x has 256-byte cache line size.
    44//
    45// Sources:
    46// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_s390x.go#L7
    47#[cfg_attr(target_arch = "s390x", repr(align(256)))]
    48// x86, wasm and riscv have 64-byte cache line size.
    49//
    50// Sources:
    51// - https://github.com/golang/go/blob/dda2991c2ea0c5914714469c4defc2562a907230/src/internal/cpu/cpu_x86.go#L9
    52// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_wasm.go#L7
    53// - https://github.com/golang/go/blob/5e31f78c8a4ed1b872ddc194f0cd1ae931b37d7e/src/internal/cpu/cpu_riscv64.go#L7
    54//
    55// All others are assumed to have 64-byte cache line size.
    56#[cfg_attr(
    57    not(any(
    58        target_arch = "x86_64",
    59        target_arch = "aarch64",
    60        target_arch = "powerpc64",
    61        target_arch = "arm",
    62        target_arch = "mips",
    63        target_arch = "mips32r6",
    64        target_arch = "mips64",
    65        target_arch = "mips64r6",
    66        target_arch = "s390x",
    67    )),
    68    repr(align(64))
    69)]
    70pub struct CachePadded<T> {
    71    value: T,
    72}
    73
    74impl<T> CachePadded<T> {
    75    /// Pads and aligns a value to the length of a cache line.
    76    pub fn new(value: T) -> CachePadded<T> {
    77        CachePadded::<T> { value }
    78    }
    79}
    80
    81impl<T> Deref for CachePadded<T> {
    82    type Target = T;
    83
    84    fn deref(&self) -> &T {
    85        &self.value
    86    }
    87}
    88
    89impl<T> DerefMut for CachePadded<T> {
    90    fn deref_mut(&mut self) -> &mut T {
    91        &mut self.value
    92    }
    93}
    94
    95const SPIN_LIMIT: u32 = 6;
    96
    97/// Performs quadratic backoff in spin loops.
    98pub struct Backoff {
    99    step: Cell<u32>,
    100}
    101
    102impl Backoff {
    103    /// Creates a new `Backoff`.
    104    pub fn new() -> Self {
    105        Backoff { step: Cell::new(0) }
    106    }
    107
    108    /// Backs off using lightweight spinning.
    109    ///
    110    /// This method should be used for retrying an operation because another thread made
    111    /// progress. i.e. on CAS failure.
    112    #[inline]
    113    pub fn spin_light(&self) {
    114        let step = self.step.get().min(SPIN_LIMIT);
    115        for _ in 0..step.pow(2) {
    116            crate::hint::spin_loop();
    117        }
    118
    119        self.step.set(self.step.get() + 1);
    120    }
    121
    122    /// Backs off using heavyweight spinning.
    123    ///
    124    /// This method should be used in blocking loops where parking the thread is not an option.
    125    #[inline]
    126    pub fn spin_heavy(&self) {
    127        if self.step.get() <= SPIN_LIMIT {
    128            for _ in 0..self.step.get().pow(2) {
    129                crate::hint::spin_loop()
    130            }
    131        } else {
    132            crate::thread::yield_now();
    133        }
    134
    135        self.step.set(self.step.get() + 1);
    136    }
    137}