1 use crate::{Interest, Registry, Token}; 2 3 use 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", features = "net"), doc = "```")] 42 #[cfg_attr(not(all(feature = "os-poll", features = "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 /// ``` 75 pub 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 register( &mut self, registry: &Registry, token: Token, interests: Interest, ) -> io::Result<()>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 reregister( &mut self, registry: &Registry, token: Token, interests: Interest, ) -> io::Result<()>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 deregister(&mut self, registry: &Registry) -> io::Result<()>111 fn deregister(&mut self, registry: &Registry) -> io::Result<()>; 112 } 113 114 impl<T> Source for Box<T> 115 where 116 T: Source + ?Sized, 117 { register( &mut self, registry: &Registry, token: Token, interests: Interest, ) -> io::Result<()>118 fn register( 119 &mut self, 120 registry: &Registry, 121 token: Token, 122 interests: Interest, 123 ) -> io::Result<()> { 124 (&mut **self).register(registry, token, interests) 125 } 126 reregister( &mut self, registry: &Registry, token: Token, interests: Interest, ) -> io::Result<()>127 fn reregister( 128 &mut self, 129 registry: &Registry, 130 token: Token, 131 interests: Interest, 132 ) -> io::Result<()> { 133 (&mut **self).reregister(registry, token, interests) 134 } 135 deregister(&mut self, registry: &Registry) -> io::Result<()>136 fn deregister(&mut self, registry: &Registry) -> io::Result<()> { 137 (&mut **self).deregister(registry) 138 } 139 } 140