try-drop 0.2.0

Batteries included error handling mechanisms for drops which can fail
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

//! Types and traits for the unreachable drop strategy, a.k.a. the drop strategy which you should
//! never use.
//!
//! The unreachable drop strategy does not get reexported in [`drop_strategies`](super). This is
//! intentional; we want this to be hidden away as much as possible.
mod private {
    pub trait Sealed {}
}

use crate::TryDropStrategy;
use core::marker::PhantomData;

/// How safe will the [`UnreachableDropStrategy`] be.
pub trait Safety: private::Sealed {}

/// Just panic when an error occurs.
#[cfg_attr(
    feature = "derives",
    derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)
)]
pub enum Safe {}
impl Safety for Safe {}
impl private::Sealed for Safe {}

/// Tell to the compiler that this branch never happens, a.k.a. call
/// [`core::hint::unreachable_unchecked`].
///
/// Note that when `debug_assertions` or the debug profile is used, this will just panic instead.
#[cfg(feature = "ds-unreachable-unsafe")]
#[cfg_attr(
    feature = "derives",
    derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)
)]
pub enum Unsafe {}

#[cfg(feature = "ds-unreachable-unsafe")]
impl Safety for Unsafe {}

#[cfg(feature = "ds-unreachable-unsafe")]
impl private::Sealed for Unsafe {}

/// A try drop strategy whose error handling mechanism should never happen.
#[cfg_attr(
    feature = "derives",
    derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)
)]
pub struct UnreachableDropStrategy<S: Safety>(PhantomData<S>);

impl UnreachableDropStrategy<Safe> {
    /// Safe version of the unreachable drop strategy.
    pub const SAFE: Self = Self::safe();

    /// Create an unreachable drop strategy which just panics.
    pub const fn safe() -> Self {
        UnreachableDropStrategy(PhantomData)
    }
}

#[cfg(feature = "ds-unreachable-unsafe")]
impl UnreachableDropStrategy<Unsafe> {
    /// Unsafe version of the unreachable drop strategy.
    pub const UNSAFE: Self = Self::r#unsafe();

    /// Create an unreachable drop strategy which calls [`core::hint::unreachable_unchecked`]. Here
    /// be dragons!
    ///
    /// # Notes
    /// If debug assertions or the debug profile is used, this will just panic instead.
    ///
    /// While this function may be safe, the possible ramifications of continued use of this object
    /// as a drop strategy can eventually cause you to make undefined behavior if you aren't careful
    /// enough.
    pub const fn r#unsafe() -> Self {
        UnreachableDropStrategy(PhantomData)
    }
}

impl Default for UnreachableDropStrategy<Safe> {
    fn default() -> Self {
        Self::safe()
    }
}

impl TryDropStrategy for UnreachableDropStrategy<Safe> {
    fn handle_error(&self, error: crate::Error) {
        unreachable!("this error should not happen: {}", error)
    }
}

#[cfg(feature = "ds-unreachable-unsafe")]
impl TryDropStrategy for UnreachableDropStrategy<Unsafe> {
    fn handle_error(&self, error: crate::Error) {
        #[cfg(debug_assertions)]
        unreachable!(
            "panicking due to `debug_assertions` (debug profile), this error should not happen: {}",
            error
        );

        #[cfg(not(debug_assertions))]
        unsafe {
            core::hint::unreachable_unchecked()
        }
    }
}

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

    #[test]
    #[should_panic(expected = "internal error: entered unreachable code: this error should not happen: this will always fail")]
    fn test_unreachable_drop_strategy_safe() {
        let unreachable = UnreachableDropStrategy::safe();
        crate::install_thread_local_handlers(unreachable, unreachable);
        drop(fallible());
    }

    #[test]
    #[should_panic(expected = "internal error: entered unreachable code: panicking due to `debug_assertions` (debug profile), this error should not happen: this will always fail")]
    #[cfg(debug_assertions)]
    fn test_unreachable_drop_strategy_unsafe_debug_assertions() {
        let unreachable = UnreachableDropStrategy::r#unsafe();
        crate::install_thread_local_handlers(unreachable, unreachable);
        drop(fallible());
    }

    // it is not possible to test the release version of `UnreachableDropStrategy<Unsafe>, as
    // executing its try drop handler will cause undefined behavior.
}