cache_padded/
lib.rs

1//! Prevent false sharing by padding and aligning to the length of a cache line.
2//!
3//! In concurrent programming, sometimes it is desirable to make sure commonly accessed shared data
4//! is not all placed into the same cache line. Updating an atomic value invalidates the whole cache
5//! line it belongs to, which makes the next access to the same cache line slower for other CPU
6//! cores. Use [`CachePadded`] to ensure updating one piece of data doesn't invalidate other cached
7//! data.
8//!
9//! # Size and alignment
10//!
11//! Cache lines are assumed to be N bytes long, depending on the architecture:
12//!
13//! * On x86-64, aarch64, and powerpc64, N = 128.
14//! * On arm, mips, mips64, and riscv64, N = 32.
15//! * On s390x, N = 256.
16//! * On all others, N = 64.
17//!
18//! Note that N is just a reasonable guess and is not guaranteed to match the actual cache line
19//! length of the machine the program is running on.
20//!
21//! The size of `CachePadded<T>` is the smallest multiple of N bytes large enough to accommodate
22//! a value of type `T`.
23//!
24//! The alignment of `CachePadded<T>` is the maximum of N bytes and the alignment of `T`.
25//!
26//! # Examples
27//!
28//! Alignment and padding:
29//!
30//! ```
31//! use cache_padded::CachePadded;
32//!
33//! let array = [CachePadded::new(1i8), CachePadded::new(2i8)];
34//! let addr1 = &*array[0] as *const i8 as usize;
35//! let addr2 = &*array[1] as *const i8 as usize;
36//!
37//! assert!(addr2 - addr1 >= 64);
38//! assert_eq!(addr1 % 64, 0);
39//! assert_eq!(addr2 % 64, 0);
40//! ```
41//!
42//! When building a concurrent queue with a head and a tail index, it is wise to place indices in
43//! different cache lines so that concurrent threads pushing and popping elements don't invalidate
44//! each other's cache lines:
45//!
46//! ```
47//! use cache_padded::CachePadded;
48//! use std::sync::atomic::AtomicUsize;
49//!
50//! struct Queue<T> {
51//!     head: CachePadded<AtomicUsize>,
52//!     tail: CachePadded<AtomicUsize>,
53//!     buffer: *mut T,
54//! }
55//! ```
56
57#![no_std]
58#![forbid(unsafe_code)]
59#![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)]
60#![deprecated(
61    since = "1.3.0",
62    note = "This crate is now deprecated in favor of [crossbeam-utils::CachePadded](https://docs.rs/crossbeam-utils/latest/crossbeam_utils/struct.CachePadded.html)."
63)]
64
65use core::fmt;
66use core::ops::{Deref, DerefMut};
67
68/// Pads and aligns data to the length of a cache line.
69// Starting from Intel's Sandy Bridge, spatial prefetcher is now pulling pairs of 64-byte cache
70// lines at a time, so we have to align to 128 bytes rather than 64.
71//
72// Sources:
73// - https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-optimization-manual.pdf
74// - https://github.com/facebook/folly/blob/1b5288e6eea6df074758f877c849b6e73bbb9fbb/folly/lang/Align.h#L107
75//
76// ARM's big.LITTLE architecture has asymmetric cores and "big" cores have 128-byte cache line size.
77//
78// Sources:
79// - https://www.mono-project.com/news/2016/09/12/arm64-icache/
80//
81// powerpc64 has 128-byte cache line size.
82//
83// Sources:
84// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_ppc64x.go#L9
85#[cfg_attr(
86    any(
87        target_arch = "x86_64",
88        target_arch = "aarch64",
89        target_arch = "powerpc64",
90    ),
91    repr(align(128))
92)]
93// arm, mips, mips64, and riscv64 have 32-byte cache line size.
94//
95// Sources:
96// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_arm.go#L7
97// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips.go#L7
98// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mipsle.go#L7
99// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips64x.go#L9
100// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_riscv64.go#L7
101#[cfg_attr(
102    any(
103        target_arch = "arm",
104        target_arch = "mips",
105        target_arch = "mips64",
106        target_arch = "riscv64",
107    ),
108    repr(align(32))
109)]
110// s390x has 256-byte cache line size.
111//
112// Sources:
113// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_s390x.go#L7
114#[cfg_attr(target_arch = "s390x", repr(align(256)))]
115// x86 and wasm have 64-byte cache line size.
116//
117// Sources:
118// - https://github.com/golang/go/blob/dda2991c2ea0c5914714469c4defc2562a907230/src/internal/cpu/cpu_x86.go#L9
119// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_wasm.go#L7
120//
121// All others are assumed to have 64-byte cache line size.
122#[cfg_attr(
123    not(any(
124        target_arch = "x86_64",
125        target_arch = "aarch64",
126        target_arch = "powerpc64",
127        target_arch = "arm",
128        target_arch = "mips",
129        target_arch = "mips64",
130        target_arch = "riscv64",
131        target_arch = "s390x",
132    )),
133    repr(align(64))
134)]
135#[derive(Clone, Copy, Default, Hash, PartialEq, Eq)]
136pub struct CachePadded<T>(T);
137
138impl<T> CachePadded<T> {
139    /// Pads and aligns a piece of data to the length of a cache line.
140    ///
141    /// # Examples
142    ///
143    /// ```
144    /// use cache_padded::CachePadded;
145    ///
146    /// let padded = CachePadded::new(1);
147    /// ```
148    pub const fn new(t: T) -> CachePadded<T> {
149        CachePadded(t)
150    }
151
152    /// Returns the inner data.
153    ///
154    /// # Examples
155    ///
156    /// ```
157    /// use cache_padded::CachePadded;
158    ///
159    /// let padded = CachePadded::new(7);
160    /// let data = padded.into_inner();
161    /// assert_eq!(data, 7);
162    /// ```
163    pub fn into_inner(self) -> T {
164        self.0
165    }
166}
167
168impl<T> Deref for CachePadded<T> {
169    type Target = T;
170
171    fn deref(&self) -> &T {
172        &self.0
173    }
174}
175
176impl<T> DerefMut for CachePadded<T> {
177    fn deref_mut(&mut self) -> &mut T {
178        &mut self.0
179    }
180}
181
182impl<T: fmt::Debug> fmt::Debug for CachePadded<T> {
183    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
184        f.debug_tuple("CachePadded").field(&self.0).finish()
185    }
186}
187
188impl<T> From<T> for CachePadded<T> {
189    fn from(t: T) -> Self {
190        CachePadded::new(t)
191    }
192}
cache_padded/lib.rs

cache_padded/
lib.rs
