region 4.0.0

Cross-platform virtual memory API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! Page related functions.

use crate::os;
use core::sync::atomic::{AtomicUsize, Ordering};

/// Returns the operating system's page size.
///
/// This function uses an internally cached page size, and can be called
/// repeatedly without incurring a significant performance penalty.
///
/// # Examples
///
/// ```
/// # use region::page;
/// let size = page::size(); // Most likely 4096
/// ```
#[inline]
pub fn size() -> usize {
  static PAGE_SIZE: AtomicUsize = AtomicUsize::new(0);

  match PAGE_SIZE.load(Ordering::Relaxed) {
    0 => {
      let size = os::page_size();
      PAGE_SIZE.store(size, Ordering::Relaxed);
      size
    }
    size => size,
  }
}

/// Rounds an address down to its closest page boundary.
///
/// # Examples
///
/// ```
/// # use region::page;
/// let unaligned_pointer = (page::size() + 1) as *const ();
///
/// assert_eq!(page::floor(unaligned_pointer), page::size() as *const _);
/// ```
#[inline]
pub fn floor<T>(address: *const T) -> *const T {
  let address = address.addr() & !(size() - 1);
  core::ptr::with_exposed_provenance(address)
}

/// Rounds an address up to its closest page boundary.
///
/// # Examples
///
/// ```
/// # use region::page;
/// let unaligned_pointer = (page::size() - 1) as *const ();
///
/// assert_eq!(page::ceil(unaligned_pointer), page::size() as *const _);
/// ```
#[inline]
pub fn ceil<T>(address: *const T) -> *const T {
  match address.addr().checked_add(size()) {
    Some(offset) => {
      let address = (offset - 1) & !(size() - 1);
      core::ptr::with_exposed_provenance(address)
    }
    None => floor(address),
  }
}

#[cfg(test)]
mod tests {
  use super::*;

  #[test]
  fn page_size_is_reasonable() {
    let pz = size();

    assert!(pz > 0);
    assert_eq!(pz % 2, 0);
    assert_eq!(pz, size());
  }

  #[test]
  fn page_rounding_works() {
    let pz = size();
    let point = core::ptr::without_provenance::<()>(1);

    assert_eq!(floor(point).addr(), 0);
    assert_eq!(floor(core::ptr::without_provenance::<()>(pz)).addr(), pz);
    assert_eq!(
      floor(core::ptr::without_provenance::<()>(usize::MAX)).addr() % pz,
      0
    );

    assert_eq!(ceil(point).addr(), pz);
    assert_eq!(ceil(core::ptr::without_provenance::<()>(pz)).addr(), pz);
    assert_eq!(
      ceil(core::ptr::without_provenance::<()>(usize::MAX)).addr() % pz,
      0
    );
  }
}