mio/event/
source.rs

1use crate::{Interest, Registry, Token};
2
3use std::io;
4
5/// An event source that may be registered with [`Registry`].
6///
7/// Types that implement `event::Source` can be registered with
8/// `Registry`. Users of Mio **should not** use the `event::Source` trait
9/// functions directly. Instead, the equivalent functions on `Registry` should
10/// be used.
11///
12/// See [`Registry`] for more details.
13///
14/// [`Registry`]: ../struct.Registry.html
15///
16/// # Implementing `event::Source`
17///
18/// Event sources are always backed by system handles, such as sockets or other
19/// system handles. These `event::Source`s will be monitored by the system
20/// selector. An implementation of `Source` will almost always delegates to a
21/// lower level handle. Examples of this are [`TcpStream`]s, or the *unix only*
22/// [`SourceFd`].
23///
24/// [`TcpStream`]: ../net/struct.TcpStream.html
25/// [`SourceFd`]: ../unix/struct.SourceFd.html
26///
27/// # Dropping `event::Source`s
28///
29/// All `event::Source`s, unless otherwise specified, need to be [deregistered]
30/// before being dropped for them to not leak resources. This goes against the
31/// normal drop behaviour of types in Rust which cleanup after themselves, e.g.
32/// a `File` will close itself. However since deregistering needs access to
33/// [`Registry`] this cannot be done while being dropped.
34///
35/// [deregistered]: ../struct.Registry.html#method.deregister
36///
37/// # Examples
38///
39/// Implementing `Source` on a struct containing a socket:
40///
41#[cfg_attr(all(feature = "os-poll", feature = "net"), doc = "```")]
42#[cfg_attr(not(all(feature = "os-poll", feature = "net")), doc = "```ignore")]
43/// use mio::{Interest, Registry, Token};
44/// use mio::event::Source;
45/// use mio::net::TcpStream;
46///
47/// use std::io;
48///
49/// # #[allow(dead_code)]
50/// pub struct MySource {
51///     socket: TcpStream,
52/// }
53///
54/// impl Source for MySource {
55///     fn register(&mut self, registry: &Registry, token: Token, interests: Interest)
56///         -> io::Result<()>
57///     {
58///         // Delegate the `register` call to `socket`
59///         self.socket.register(registry, token, interests)
60///     }
61///
62///     fn reregister(&mut self, registry: &Registry, token: Token, interests: Interest)
63///         -> io::Result<()>
64///     {
65///         // Delegate the `reregister` call to `socket`
66///         self.socket.reregister(registry, token, interests)
67///     }
68///
69///     fn deregister(&mut self, registry: &Registry) -> io::Result<()> {
70///         // Delegate the `deregister` call to `socket`
71///         self.socket.deregister(registry)
72///     }
73/// }
74/// ```
75pub trait Source {
76    /// Register `self` with the given `Registry` instance.
77    ///
78    /// This function should not be called directly. Use [`Registry::register`]
79    /// instead. Implementors should handle registration by delegating the call
80    /// to another `Source` type.
81    ///
82    /// [`Registry::register`]: ../struct.Registry.html#method.register
83    fn register(
84        &mut self,
85        registry: &Registry,
86        token: Token,
87        interests: Interest,
88    ) -> io::Result<()>;
89
90    /// Re-register `self` with the given `Registry` instance.
91    ///
92    /// This function should not be called directly. Use
93    /// [`Registry::reregister`] instead. Implementors should handle
94    /// re-registration by either delegating the call to another `Source` type.
95    ///
96    /// [`Registry::reregister`]: ../struct.Registry.html#method.reregister
97    fn reregister(
98        &mut self,
99        registry: &Registry,
100        token: Token,
101        interests: Interest,
102    ) -> io::Result<()>;
103
104    /// Deregister `self` from the given `Registry` instance.
105    ///
106    /// This function should not be called directly. Use
107    /// [`Registry::deregister`] instead. Implementors should handle
108    /// deregistration by delegating the call to another `Source` type.
109    ///
110    /// [`Registry::deregister`]: ../struct.Registry.html#method.deregister
111    fn deregister(&mut self, registry: &Registry) -> io::Result<()>;
112}
113
114impl<T> Source for Box<T>
115where
116    T: Source + ?Sized,
117{
118    fn register(
119        &mut self,
120        registry: &Registry,
121        token: Token,
122        interests: Interest,
123    ) -> io::Result<()> {
124        (**self).register(registry, token, interests)
125    }
126
127    fn reregister(
128        &mut self,
129        registry: &Registry,
130        token: Token,
131        interests: Interest,
132    ) -> io::Result<()> {
133        (**self).reregister(registry, token, interests)
134    }
135
136    fn deregister(&mut self, registry: &Registry) -> io::Result<()> {
137        (**self).deregister(registry)
138    }
139}
mio/event/source.rs

mio/event/
source.rs
