gaea 0.3.1

Low-level library to build event driven applications, supporting lightweight non-blocking I/O.
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

use std::io;

use crate::event;
use crate::os::{Interests, OsQueue, RegisterOption};

/// A handle that may be registered with [`OsQueue`].
///
/// Handles that implement `Evented` can be registered with [`OsQueue`]. The
/// methods on the trait **should not** be called directly, instead the
/// equivalent methods should be called on [`OsQueue`].
///
/// See [`OsQueue` documentation] for more details.
///
/// [`OsQueue` documentation]: OsQueue
///
/// # Implementing `Evented`
///
/// Implementations of `Evented` are always backed by *system* handles, which
/// are backed by sockets or other system handles. The `Evented` handles will be
/// monitored by the Operating System selector. In this case, an implementation
/// of `Evented` delegates to a lower level handle. Examples of this are
/// [`TcpStream`]s, or the *unix only* [`EventedFd`].
///
/// [`TcpStream`]: crate::net::TcpStream
/// [`EventedFd`]: crate::unix::EventedFd
///
/// # Dropping `Evented` types
///
/// All `Evented` types, unless otherwise specified, need to be deregistered
/// before being dropped for them to not leak resources. This goes against the
/// normal drop behaviour of types in Rust which cleanup after themselves, e.g.
/// a `File` will close itself. However since deregistering needs mutable access
/// to [`OsQueue`] this cannot be done while being dropped.
///
/// # Examples
///
/// Implementing `Evented` on a struct containing a system handle, such as a
/// [`TcpStream`].
///
/// ```
/// use std::io;
///
/// use gaea::event;
/// use gaea::net::TcpStream;
/// use gaea::os::{Evented, Interests, RegisterOption, OsQueue};
///
/// # #[allow(dead_code)]
/// pub struct MyEvented {
///     /// Our system handle that implements `Evented`.
///     socket: TcpStream,
/// }
///
/// impl Evented for MyEvented {
///     fn register(&mut self, os_queue: &mut OsQueue, id: event::Id, interests: Interests, opt: RegisterOption) -> io::Result<()> {
///         // Delegate the `register` call to `socket`.
///         self.socket.register(os_queue, id, interests, opt)
///     }
///
///     fn reregister(&mut self, os_queue: &mut OsQueue, id: event::Id, interests: Interests, opt: RegisterOption) -> io::Result<()> {
///         // Delegate the `reregister` call to `socket`.
///         self.socket.reregister(os_queue, id, interests, opt)
///     }
///
///     fn deregister(&mut self, os_queue: &mut OsQueue) -> io::Result<()> {
///         // Delegate the `deregister` call to `socket`.
///         self.socket.deregister(os_queue)
///     }
/// }
/// ```
pub trait Evented {
    /// Register `self` with the given `OsQueue` instance.
    ///
    /// This function should not be called directly, use [`OsQueue.register`]
    /// instead.
    ///
    /// [`OsQueue.register`]: crate::os::OsQueue::register
    fn register(&mut self, os_queue: &mut OsQueue, id: event::Id, interests: Interests, opt: RegisterOption) -> io::Result<()>;

    /// Reregister `self` with the given `OsQueue` instance.
    ///
    /// This function should not be called directly, use [`OsQueue.reregister`]
    /// instead.
    ///
    /// [`OsQueue.reregister`]: crate::os::OsQueue::reregister
    fn reregister(&mut self, os_queue: &mut OsQueue, id: event::Id, interests: Interests, opt: RegisterOption) -> io::Result<()>;

    /// Deregister `self` from the given `OsQueue` instance
    ///
    /// This function should not be called directly, use [`OsQueue.deregister`]
    /// instead.
    ///
    /// [`OsQueue.deregister`]: crate::os::OsQueue::deregister
    fn deregister(&mut self, os_queue: &mut OsQueue) -> io::Result<()>;
}