imap-next 0.2.0

Thin sans I/O abstraction over IMAP's distinct protocol flows
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

use std::{
    fmt::{Debug, Formatter},
    marker::PhantomData,
    sync::atomic::{AtomicU64, Ordering},
};

pub trait Handle {
    fn from_raw(raw_handle: RawHandle) -> Self;
}

#[derive(Clone, Copy, Eq, PartialEq, Hash)]
pub struct RawHandle {
    generator_id: u64,
    handle_id: u64,
}

impl RawHandle {
    pub fn generator_id(&self) -> u64 {
        self.generator_id
    }

    pub fn handle_id(&self) -> u64 {
        self.handle_id
    }
}

pub struct HandleGenerator<H: Handle> {
    /// This ID is used to bind the handles to the generator instance, i.e. it's possible to
    /// distinguish handles generated by different generators. We hope that this might
    /// prevent bugs when the library user is dealing with handles from different sources.
    generator_id: u64,
    next_handle_id: u64,
    _h: PhantomData<H>,
}

impl<H: Handle> Debug for HandleGenerator<H> {
    fn fmt(&self, f: &mut Formatter) -> std::fmt::Result {
        f.debug_struct("HandleGenerator")
            .field("generator_id", &self.generator_id)
            .field("next_handle_id", &self.next_handle_id)
            .finish_non_exhaustive()
    }
}

impl<H: Handle> HandleGenerator<H> {
    pub fn generate(&mut self) -> H {
        let handle_id = self.next_handle_id;
        self.next_handle_id = self.next_handle_id.wrapping_add(1);

        H::from_raw(RawHandle {
            generator_id: self.generator_id,
            handle_id,
        })
    }
}

pub struct HandleGeneratorGenerator<H: Handle> {
    next_handle_generator_id: AtomicU64,
    _h: PhantomData<H>,
}

impl<H: Handle> HandleGeneratorGenerator<H> {
    pub const fn new() -> Self {
        Self {
            next_handle_generator_id: AtomicU64::new(0),
            _h: PhantomData,
        }
    }

    pub fn generate(&self) -> HandleGenerator<H> {
        // There is no synchronization required and we only care about each thread seeing a
        // unique value.
        let generator_id = self
            .next_handle_generator_id
            .fetch_add(1, Ordering::Relaxed);

        HandleGenerator {
            generator_id,
            next_handle_id: 0,
            _h: PhantomData,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{Handle, HandleGeneratorGenerator, RawHandle};

    struct TestHandle(RawHandle);

    impl Handle for TestHandle {
        fn from_raw(raw_handle: RawHandle) -> Self {
            Self(raw_handle)
        }
    }

    #[test]
    fn generated_handles_have_expected_ids() {
        let gen_gen = HandleGeneratorGenerator::<TestHandle>::new();

        for expected_generator_id in 0..100 {
            let mut gen = gen_gen.generate();

            for expected_handle_id in 0..100 {
                let handle = gen.generate();

                assert_eq!(expected_generator_id, handle.0.generator_id);
                assert_eq!(expected_handle_id, handle.0.handle_id);
            }
        }
    }
}