c-ares 13.0.0

A Rust wrapper for the c-ares library, for asynchronous DNS requests.
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

use crate::types::Socket;
use bitflags::bitflags;
use std::fmt;

bitflags!(
    /// Events used by FdEvents.
    #[derive(Copy, Clone, Eq, PartialEq, Debug, Hash, PartialOrd, Ord)]
    pub struct FdEventFlags: u32 {
        /// Read event (including disconnect/error).
        const READ = c_ares_sys::ares_fd_eventflag_t::ARES_FD_EVENT_READ as u32;
        /// Write event.
        const WRITE = c_ares_sys::ares_fd_eventflag_t::ARES_FD_EVENT_WRITE as u32;
    }
);

bitflags!(
    /// Flags used by [`crate::Channel::process_fds()`].
    #[derive(Copy, Clone, Eq, PartialEq, Debug, Hash, PartialOrd, Ord)]
    pub struct ProcessFlags: u32 {
        /// Skip any processing unrelated to the file descriptor events passed in.
        const SKIP_NON_FD = c_ares_sys::ares_process_flag_t::ARES_PROCESS_FLAG_SKIP_NON_FD as u32;
    }
);

/// Type holding a file descriptor and mask of events, used by [`crate::Channel::process_fds()`].
#[repr(transparent)]
pub struct FdEvents(c_ares_sys::ares_fd_events_t);

impl FdEvents {
    /// Returns a new `FdEvents`.
    pub fn new(socket: Socket, events: FdEventFlags) -> Self {
        let events = c_ares_sys::ares_fd_events_t {
            fd: socket,
            events: events.bits(),
        };
        FdEvents(events)
    }
}

impl fmt::Debug for FdEvents {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("FdEvents")
            .field("fd", &self.0.fd)
            .field("events", &FdEventFlags::from_bits_truncate(self.0.events))
            .finish()
    }
}

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

    #[test]
    fn fd_event_flags_empty() {
        let flags = FdEventFlags::empty();
        assert!(flags.is_empty());
    }

    #[test]
    fn fd_event_flags_read() {
        let flags = FdEventFlags::READ;
        assert!(flags.contains(FdEventFlags::READ));
        assert!(!flags.contains(FdEventFlags::WRITE));
    }

    #[test]
    fn fd_event_flags_write() {
        let flags = FdEventFlags::WRITE;
        assert!(flags.contains(FdEventFlags::WRITE));
        assert!(!flags.contains(FdEventFlags::READ));
    }

    #[test]
    fn fd_event_flags_combined() {
        let flags = FdEventFlags::READ | FdEventFlags::WRITE;
        assert!(flags.contains(FdEventFlags::READ));
        assert!(flags.contains(FdEventFlags::WRITE));
    }

    #[test]
    fn process_flags_empty() {
        let flags = ProcessFlags::empty();
        assert!(flags.is_empty());
    }

    #[test]
    fn process_flags_skip_non_fd() {
        let flags = ProcessFlags::SKIP_NON_FD;
        assert!(flags.contains(ProcessFlags::SKIP_NON_FD));
    }

    #[test]
    fn fd_events_new() {
        let events = FdEvents::new(42, FdEventFlags::READ);
        assert_eq!(events.0.fd, 42);
        assert_eq!(events.0.events, FdEventFlags::READ.bits());
    }

    #[test]
    fn debug_fd_events() {
        let events = FdEvents::new(42, FdEventFlags::READ | FdEventFlags::WRITE);
        let debug = format!("{events:?}");
        assert!(debug.contains("FdEvents"));
        assert!(debug.contains("42"));
        assert!(debug.contains("READ"));
        assert!(debug.contains("WRITE"));
    }
}