briny 0.7.1

Low-level enforcement of memory layout integrity
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
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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336

//! Traits to abstract common characteristics among types.

use core::{
    cell::{Cell, LazyCell, OnceCell, RefCell, RefMut, UnsafeCell},
    marker::PhantomData,
    mem::{ManuallyDrop, MaybeUninit},
    num::{
        NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize, NonZeroU128,
        NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize, Saturating, Wrapping,
    },
    ptr::NonNull,
    sync::atomic::{
        AtomicBool, AtomicI16, AtomicI32, AtomicI64, AtomicI8, AtomicIsize, AtomicU16, AtomicU32,
        AtomicU64, AtomicU8, AtomicUsize,
    },
};

use crate::raw::nonzero::MaybeNull;

/// A simple marker trait for types that have a consistent layout in memory.
///
/// # Safety
///
/// If this type does not have a stable layout, this is invalid. e.g., if the type
/// depends on something not listed in struct fields or assumes anything about the device.
pub unsafe trait StableLayout: Sized + 'static {}

unsafe impl StableLayout for () {}
unsafe impl StableLayout for u8 {}
unsafe impl StableLayout for i8 {}
unsafe impl StableLayout for u16 {}
unsafe impl StableLayout for i16 {}
unsafe impl StableLayout for u32 {}
unsafe impl StableLayout for i32 {}
unsafe impl StableLayout for u64 {}
unsafe impl StableLayout for i64 {}
unsafe impl StableLayout for u128 {}
unsafe impl StableLayout for i128 {}
unsafe impl StableLayout for usize {}
unsafe impl StableLayout for isize {}
unsafe impl StableLayout for f32 {}
unsafe impl StableLayout for f64 {}
unsafe impl StableLayout for bool {}
unsafe impl StableLayout for AtomicU8 {}
unsafe impl StableLayout for AtomicI8 {}
unsafe impl StableLayout for AtomicU16 {}
unsafe impl StableLayout for AtomicI16 {}
unsafe impl StableLayout for AtomicU32 {}
unsafe impl StableLayout for AtomicI32 {}
unsafe impl StableLayout for AtomicU64 {}
unsafe impl StableLayout for AtomicI64 {}
unsafe impl StableLayout for AtomicUsize {}
unsafe impl StableLayout for AtomicIsize {}
unsafe impl StableLayout for AtomicBool {}
unsafe impl StableLayout for NonZeroU8 {}
unsafe impl StableLayout for NonZeroI8 {}
unsafe impl StableLayout for NonZeroU16 {}
unsafe impl StableLayout for NonZeroI16 {}
unsafe impl StableLayout for NonZeroU32 {}
unsafe impl StableLayout for NonZeroI32 {}
unsafe impl StableLayout for NonZeroU64 {}
unsafe impl StableLayout for NonZeroI64 {}
unsafe impl StableLayout for NonZeroU128 {}
unsafe impl StableLayout for NonZeroI128 {}
unsafe impl StableLayout for NonZeroUsize {}
unsafe impl StableLayout for NonZeroIsize {}
unsafe impl<T: StableLayout, const N: usize> StableLayout for [T; N] {}
unsafe impl<T: StableLayout> StableLayout for MaybeUninit<T> {}
unsafe impl<T: 'static> StableLayout for *const T {}
unsafe impl<T: 'static> StableLayout for *mut T {}
unsafe impl<T: StableLayout> StableLayout for UnsafeCell<T> {}
unsafe impl<T: StableLayout> StableLayout for Cell<T> {}
unsafe impl<T: StableLayout> StableLayout for RefMut<'static, T> {}
unsafe impl<T: StableLayout> StableLayout for RefCell<T> {}
unsafe impl<T: StableLayout> StableLayout for OnceCell<T> {}
unsafe impl<T: StableLayout> StableLayout for LazyCell<T> {}
unsafe impl<T: StableLayout> StableLayout for ManuallyDrop<T> {}
unsafe impl<T: StableLayout> StableLayout for Wrapping<T> {}
unsafe impl<T: StableLayout> StableLayout for Saturating<T> {}
unsafe impl<T: 'static> StableLayout for PhantomData<T> {}
unsafe impl<T: StableLayout + NonNullable> StableLayout for MaybeNull<T> {}
unsafe impl<T: StableLayout> StableLayout for Option<T> {}

#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m128 {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m128bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m128d {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m128i {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m256 {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m256bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m256d {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m256i {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m512 {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m512bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m512d {}
#[cfg(target_arch = "x86_64")]
unsafe impl StableLayout for core::arch::x86_64::__m512i {}

#[cfg(feature = "half")]
unsafe impl StableLayout for half::f16 {}
#[cfg(feature = "half")]
unsafe impl StableLayout for half::bf16 {}

#[cfg(feature = "nightly_float")]
unsafe impl StableLayout for f16 {}
#[cfg(feature = "nightly_float")]
unsafe impl StableLayout for f128 {}

/// Marker trait for types subject to the null pointer optimization.
///
/// # Safety
///
/// If zeroed is a valid bitpattern, undefined behavior will occur
/// when trying to optimize memory.
pub unsafe trait NonNullable {}

unsafe impl NonNullable for () {}
unsafe impl NonNullable for NonZeroU8 {}
unsafe impl NonNullable for NonZeroI8 {}
unsafe impl NonNullable for NonZeroU16 {}
unsafe impl NonNullable for NonZeroI16 {}
unsafe impl NonNullable for NonZeroU32 {}
unsafe impl NonNullable for NonZeroI32 {}
unsafe impl NonNullable for NonZeroU64 {}
unsafe impl NonNullable for NonZeroI64 {}
unsafe impl NonNullable for NonZeroU128 {}
unsafe impl NonNullable for NonZeroI128 {}
unsafe impl NonNullable for NonZeroUsize {}
unsafe impl NonNullable for NonZeroIsize {}
unsafe impl<T> NonNullable for NonNull<T> {}
unsafe impl<T> NonNullable for &T {}
unsafe impl<T> NonNullable for &mut T {}

/// Marker trait for types subject to the null pointer optimization by the compiler.
///
/// # Safety
///
/// If the compiler can safely assume the type can't represent a zeroed bitpattern,
/// this is safe. It isn't safe to implement on `Pod` types.
pub unsafe trait CompilerAssumedNonNullable: NonNullable {}

unsafe impl CompilerAssumedNonNullable for NonZeroU8 {}
unsafe impl CompilerAssumedNonNullable for NonZeroI8 {}
unsafe impl CompilerAssumedNonNullable for NonZeroU16 {}
unsafe impl CompilerAssumedNonNullable for NonZeroI16 {}
unsafe impl CompilerAssumedNonNullable for NonZeroU32 {}
unsafe impl CompilerAssumedNonNullable for NonZeroI32 {}
unsafe impl CompilerAssumedNonNullable for NonZeroU64 {}
unsafe impl CompilerAssumedNonNullable for NonZeroI64 {}
unsafe impl CompilerAssumedNonNullable for NonZeroU128 {}
unsafe impl CompilerAssumedNonNullable for NonZeroI128 {}
unsafe impl CompilerAssumedNonNullable for NonZeroUsize {}
unsafe impl CompilerAssumedNonNullable for NonZeroIsize {}
unsafe impl<T> CompilerAssumedNonNullable for NonNull<T> {}
unsafe impl<T> CompilerAssumedNonNullable for &T {}
unsafe impl<T> CompilerAssumedNonNullable for &mut T {}

/// Marker trait for types that can be converted to/from bytes freely.
///
/// This doesn't mean any bitpattern would be valid for it, but it can be converted
/// to/from bytes without undefined behavior EVER occurring. different from POD by
/// enforcing that normal (non-atomic) operations are valid. This includes [`crate::ptr::read`],
/// [`crate::ptr::write`], and all the [`core`] counterparts.
///
/// # Safety
///
/// If the type isn't safe to write arbitrary bytes to or from it without atomics, it would
/// be unsound. Implementing this on a type that implements `Send` or `Sync` is usually a bad
/// idea unless it guarantees exclusivity even when not held.
pub unsafe trait RawConvert {}

unsafe impl RawConvert for () {}
unsafe impl RawConvert for u8 {}
unsafe impl RawConvert for i8 {}
unsafe impl RawConvert for u16 {}
unsafe impl RawConvert for i16 {}
unsafe impl RawConvert for u32 {}
unsafe impl RawConvert for i32 {}
unsafe impl RawConvert for u64 {}
unsafe impl RawConvert for i64 {}
unsafe impl RawConvert for u128 {}
unsafe impl RawConvert for i128 {}
unsafe impl RawConvert for isize {}
unsafe impl RawConvert for usize {}
unsafe impl RawConvert for f32 {}
unsafe impl RawConvert for f64 {}
unsafe impl RawConvert for bool {}
unsafe impl RawConvert for NonZeroU8 {}
unsafe impl RawConvert for NonZeroI8 {}
unsafe impl RawConvert for NonZeroU16 {}
unsafe impl RawConvert for NonZeroI16 {}
unsafe impl RawConvert for NonZeroU32 {}
unsafe impl RawConvert for NonZeroI32 {}
unsafe impl RawConvert for NonZeroU64 {}
unsafe impl RawConvert for NonZeroI64 {}
unsafe impl RawConvert for NonZeroU128 {}
unsafe impl RawConvert for NonZeroI128 {}
unsafe impl RawConvert for NonZeroUsize {}
unsafe impl RawConvert for NonZeroIsize {}
unsafe impl<T> RawConvert for NonNull<T> {}
unsafe impl<T: RawConvert, const N: usize> RawConvert for [T; N] {}
unsafe impl<T: RawConvert> RawConvert for Option<T> {}
unsafe impl<T: RawConvert> RawConvert for UnsafeCell<T> {}
unsafe impl<T: RawConvert> RawConvert for Cell<T> {}
unsafe impl<T: RawConvert> RawConvert for ManuallyDrop<T> {}
unsafe impl<T: RawConvert> RawConvert for Wrapping<T> {}
unsafe impl<T: RawConvert> RawConvert for Saturating<T> {}
unsafe impl<T> RawConvert for PhantomData<T> {}
unsafe impl<T: RawConvert + NonNullable> RawConvert for MaybeNull<T> {}

#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m128 {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m128bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m128d {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m128i {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m256 {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m256bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m256d {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m256i {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m512 {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m512bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m512d {}
#[cfg(target_arch = "x86_64")]
unsafe impl RawConvert for core::arch::x86_64::__m512i {}

#[cfg(feature = "half")]
unsafe impl RawConvert for half::f16 {}
#[cfg(feature = "half")]
unsafe impl RawConvert for half::bf16 {}

#[cfg(feature = "nightly_float")]
unsafe impl RawConvert for f16 {}
#[cfg(feature = "nightly_float")]
unsafe impl RawConvert for f128 {}

/// POD marker trait for *Plain Old Data*.
///
/// # Safety
///
/// - All bit patterns of `T` must be valid
/// - `T` must have no padding or initialized padding
/// - `T` must implement [`StableLayout`] + [`RawConvert`]
///
/// Violating any of these constraints is bound to cause undefined behavior.
pub unsafe trait Pod: StableLayout + RawConvert {}

unsafe impl Pod for () {}
unsafe impl Pod for usize {}
unsafe impl Pod for u8 {}
unsafe impl Pod for u16 {}
unsafe impl Pod for u32 {}
unsafe impl Pod for u64 {}
unsafe impl Pod for u128 {}
unsafe impl Pod for isize {}
unsafe impl Pod for i8 {}
unsafe impl Pod for i16 {}
unsafe impl Pod for i32 {}
unsafe impl Pod for i64 {}
unsafe impl Pod for i128 {}
unsafe impl Pod for f32 {}
unsafe impl Pod for f64 {}
unsafe impl<T: Pod, const N: usize> Pod for [T; N] {}
unsafe impl<T: Pod> Pod for ManuallyDrop<T> {}
unsafe impl<T: Pod> Pod for Wrapping<T> {}
unsafe impl<T: Pod> Pod for Saturating<T> {}
unsafe impl<T: 'static> Pod for PhantomData<T> {}
unsafe impl<T: CompilerAssumedNonNullable + RawConvert + StableLayout> Pod for Option<T> {}

#[cfg(feature = "half")]
unsafe impl Pod for half::f16 {}
#[cfg(feature = "half")]
unsafe impl Pod for half::bf16 {}

#[cfg(feature = "nightly_float")]
unsafe impl Pod for f16 {}
#[cfg(feature = "nightly_float")]
unsafe impl Pod for f128 {}

#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m128 {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m128bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m128d {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m128i {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m256 {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m256bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m256d {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m256i {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m512 {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m512bh {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m512d {}
#[cfg(target_arch = "x86_64")]
unsafe impl Pod for core::arch::x86_64::__m512i {}

/// Internal trait used to determine what types are safe to cast.
///
/// If a type is safe to cast to another type, but not any type, this should be used
/// instead of [`Pod`].
///
/// # Safety
///
/// This is less strict and is safe as long as it is safe to reinterpret the bytes
/// of any given `T` as a `U`. It isn't required, however, that any `U` can be
/// reinterpreted as a `T`. It is also completely unrelated to all other types.
pub unsafe trait Layout<T: StableLayout>: StableLayout {}

unsafe impl<T: Pod, U: Pod> Layout<U> for T {}