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}
140