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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

#![doc = include_str!("../../doc/ptr/addr.md")]

use core::{
	any,
	fmt::{
		self,
		Debug,
		Display,
		Formatter,
		Pointer,
	},
	mem,
	ptr::NonNull,
};

use tap::{
	Pipe,
	TryConv,
};
use wyz::{
	comu::{
		Address,
		Const,
		Mut,
		Mutability,
	},
	fmt::FmtForward,
};

/// Ensures that an address is well-aligned to its referent type width.
#[inline]
pub fn check_alignment<M, T>(
	addr: Address<M, T>,
) -> Result<Address<M, T>, MisalignError<T>>
where M: Mutability {
	let ptr = addr.to_const();
	let mask = mem::align_of::<T>() - 1;
	if ptr as usize & mask != 0 {
		Err(MisalignError { ptr })
	}
	else {
		Ok(addr)
	}
}

/// Extension methods for raw pointers.
pub(crate) trait AddressExt {
	/// Tracks the original mutation capability of the source pointer.
	type Permission: Mutability;
	/// The type to which the pointer points.
	type Referent: Sized;

	/// Forcibly wraps a raw pointer as an `Address`, without handling errors.
	///
	/// In debug builds, this panics on null or misaligned pointers. In release
	/// builds, it is permitted to remove the error-handling codepaths and
	/// assume these invariants are upheld by the caller.
	///
	/// ## Safety
	///
	/// The caller must ensure that this is only called on non-null,
	/// well-aligned pointers. Pointers derived from Rust references or calls to
	/// the Rust allocator API will always satisfy this.
	unsafe fn into_address(self) -> Address<Self::Permission, Self::Referent>;
}

#[cfg(not(tarpaulin_include))]
impl<T> AddressExt for *const T {
	type Permission = Const;
	type Referent = T;

	unsafe fn into_address(self) -> Address<Const, T> {
		if cfg!(debug_assertions) {
			self.try_conv::<Address<_, _>>()
				.unwrap_or_else(|err| panic!("{}", err))
				.pipe(check_alignment)
				.unwrap_or_else(|err| panic!("{}", err))
		}
		else {
			Address::new(NonNull::new_unchecked(self as *mut T))
		}
	}
}

#[cfg(not(tarpaulin_include))]
impl<T> AddressExt for *mut T {
	type Permission = Mut;
	type Referent = T;

	unsafe fn into_address(self) -> Address<Mut, T> {
		if cfg!(debug_assertions) {
			self.try_conv::<Address<_, _>>()
				.unwrap_or_else(|err| panic!("{}", err))
				.pipe(check_alignment)
				.unwrap_or_else(|err| panic!("{}", err))
		}
		else {
			Address::new(NonNull::new_unchecked(self))
		}
	}
}

#[cfg(not(tarpaulin_include))]
impl<T> AddressExt for &T {
	type Permission = Const;
	type Referent = T;

	unsafe fn into_address(self) -> Address<Self::Permission, Self::Referent> {
		self.into()
	}
}

#[cfg(not(tarpaulin_include))]
impl<T> AddressExt for &mut T {
	type Permission = Mut;
	type Referent = T;

	unsafe fn into_address(self) -> Address<Self::Permission, Self::Referent> {
		self.into()
	}
}

/// The error produced when an address is insufficiently aligned to the width of
/// its type.
#[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct MisalignError<T> {
	/// The misaligned pointer.
	ptr: *const T,
}

impl<T> MisalignError<T> {
	/// The minimum address alignment of `T` values.
	const ALIGN: usize = mem::align_of::<T>();
	/// The number of least-significant-bits of an address that must be `0` in
	/// order for it to be validly aligned for `T`.
	const CTTZ: usize = Self::ALIGN.trailing_zeros() as usize;
}

#[cfg(not(tarpaulin_include))]
impl<T> Debug for MisalignError<T> {
	#[inline]
	fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
		fmt.debug_tuple("MisalignError")
			.field(&self.ptr.fmt_pointer())
			.field(&Self::ALIGN)
			.finish()
	}
}

#[cfg(not(tarpaulin_include))]
impl<T> Display for MisalignError<T> {
	#[inline]
	fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
		write!(
			fmt,
			"Type {} requires {}-byte alignment: address ",
			any::type_name::<T>(),
			Self::ALIGN,
		)?;
		Pointer::fmt(&self.ptr, fmt)?;
		write!(fmt, " must clear its least {} bits", Self::CTTZ)
	}
}

unsafe impl<T> Send for MisalignError<T> {}

unsafe impl<T> Sync for MisalignError<T> {}

#[cfg(feature = "std")]
impl<T> std::error::Error for MisalignError<T> {}