gc-arena 0.6.0

safe, incrementally garbage collected arenas
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

use core::marker::PhantomData;
use core::ptr::NonNull;

use crate::{
    types::GcBoxInner,
    {Gc, GcWeak},
};

/// Unsizes a [`Gc`] or [`GcWeak`] pointer.
///
/// This macro is a `gc_arena`-specific replacement for the nightly-only `CoerceUnsized` trait.
///
/// ## Usage
///
/// ```rust
/// # use std::fmt::Display;
/// # use gc_arena::{Gc, unsize};
/// # fn main() {
/// # gc_arena::arena::rootless_mutate(|mc| {
/// // Unsizing arrays to slices.
/// let mut slice;
/// slice = unsize!(Gc::new(mc, [1, 2]) => [u8]);
/// assert_eq!(slice.len(), 2);
/// slice = unsize!(Gc::new(mc, [42; 4]) => [u8]);
/// assert_eq!(slice.len(), 4);
///
/// // Unsizing values to trait objects.
/// let mut display;
/// display = unsize!(Gc::new(mc, "Hello world!".to_owned()) => dyn Display);
/// assert_eq!(display.to_string(), "Hello world!");
/// display = unsize!(Gc::new(mc, 123456) => dyn Display);
/// assert_eq!(display.to_string(), "123456");
/// # })
/// # }
/// ```
///
/// The `unsize` macro is safe, and will fail to compile when trying to coerce between
/// incompatible types.
/// ```rust,compile_fail
/// # use std::error::Error;
/// # use gc_arena::{Gc, unsize};
/// # fn main() {
/// # gc_arena::arena::rootless_mutate(|mc| {
/// // Error: `Option<char>` doesn't implement `Error`.
/// let _ = unsize!(Gc::new(mc, Some('💥')) => dyn Error);
/// # })
/// # }
/// ```
#[macro_export]
macro_rules! unsize {
    ($gc:expr => $ty:ty) => {{
        let gc = $gc;
        // SAFETY: the closure has a trivial body and must be a valid pointer
        // coercion, if it compiles. Additionally, the `__CoercePtrInternal` trait
        // ensures that the resulting GC pointer has the correct `'gc` lifetime.
        unsafe {
            $crate::__CoercePtrInternal::__coerce_unchecked(gc, |p: *mut _| -> *mut $ty { p })
        }
    }};
}

// Not public API; implementation detail of the `unsize` macro.
//
// Maps a raw pointer coercion (`*mut FromPtr -> *mut ToPtr`) to
// a smart pointer coercion (`Self -> Dst`).
#[doc(hidden)]
pub unsafe trait __CoercePtrInternal<Dst> {
    type FromPtr;
    type ToPtr: ?Sized;
    // SAFETY: `coerce` must be a valid pointer coercion; in particular, the coerced
    // pointer must have the same address and provenance as the original.
    unsafe fn __coerce_unchecked<F>(self, coerce: F) -> Dst
    where
        F: FnOnce(*mut Self::FromPtr) -> *mut Self::ToPtr;
}

unsafe impl<'gc, T, U: ?Sized> __CoercePtrInternal<Gc<'gc, U>> for Gc<'gc, T> {
    type FromPtr = T;
    type ToPtr = U;

    #[inline(always)]
    unsafe fn __coerce_unchecked<F>(self, coerce: F) -> Gc<'gc, U>
    where
        F: FnOnce(*mut T) -> *mut U,
    {
        let ptr = self.ptr.as_ptr() as *mut T;
        unsafe {
            Gc {
                ptr: NonNull::new_unchecked(coerce(ptr) as *mut GcBoxInner<U>),
                _invariant: PhantomData,
            }
        }
    }
}

unsafe impl<'gc, T, U: ?Sized> __CoercePtrInternal<GcWeak<'gc, U>> for GcWeak<'gc, T> {
    type FromPtr = T;
    type ToPtr = U;

    #[inline(always)]
    unsafe fn __coerce_unchecked<F>(self, coerce: F) -> GcWeak<'gc, U>
    where
        F: FnOnce(*mut T) -> *mut U,
    {
        unsafe {
            let inner = self.inner.__coerce_unchecked(coerce);
            GcWeak { inner }
        }
    }
}