/rust/registry/src/index.crates.io-6f17d22bba15001f/mio-1.0.3/src/event/source.rs

Source (jump to first uncovered line)
use crate::{Interest, Registry, Token};

use std::io;

/// An event source that may be registered with [`Registry`].
///
/// Types that implement `event::Source` can be registered with
/// `Registry`. Users of Mio **should not** use the `event::Source` trait
/// functions directly. Instead, the equivalent functions on `Registry` should
/// be used.
///
/// See [`Registry`] for more details.
///
/// [`Registry`]: ../struct.Registry.html
///
/// # Implementing `event::Source`
///
/// Event sources are always backed by system handles, such as sockets or other
/// system handles. These `event::Source`s will be monitored by the system
/// selector. An implementation of `Source` will almost always delegates to a
/// lower level handle. Examples of this are [`TcpStream`]s, or the *unix only*
/// [`SourceFd`].
///
/// [`TcpStream`]: ../net/struct.TcpStream.html
/// [`SourceFd`]: ../unix/struct.SourceFd.html
///
/// # Dropping `event::Source`s
///
/// All `event::Source`s, 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 access to
/// [`Registry`] this cannot be done while being dropped.
///
/// [deregistered]: ../struct.Registry.html#method.deregister
///
/// # Examples
///
/// Implementing `Source` on a struct containing a socket:
///
#[cfg_attr(all(feature = "os-poll", feature = "net"), doc = "```")]
#[cfg_attr(not(all(feature = "os-poll", feature = "net")), doc = "```ignore")]
/// use mio::{Interest, Registry, Token};
/// use mio::event::Source;
/// use mio::net::TcpStream;
///
/// use std::io;
///
/// # #[allow(dead_code)]
/// pub struct MySource {
///     socket: TcpStream,
/// }
///
/// impl Source for MySource {
///     fn register(&mut self, registry: &Registry, token: Token, interests: Interest)
///         -> io::Result<()>
///     {
///         // Delegate the `register` call to `socket`
///         self.socket.register(registry, token, interests)
///     }
///
///     fn reregister(&mut self, registry: &Registry, token: Token, interests: Interest)
///         -> io::Result<()>
///     {
///         // Delegate the `reregister` call to `socket`
///         self.socket.reregister(registry, token, interests)
///     }
///
///     fn deregister(&mut self, registry: &Registry) -> io::Result<()> {
///         // Delegate the `deregister` call to `socket`
///         self.socket.deregister(registry)
///     }
/// }
/// ```
pub trait Source {
    /// Register `self` with the given `Registry` instance.
    ///
    /// This function should not be called directly. Use [`Registry::register`]
    /// instead. Implementors should handle registration by delegating the call
    /// to another `Source` type.
    ///
    /// [`Registry::register`]: ../struct.Registry.html#method.register
    fn register(
        &mut self,
        registry: &Registry,
        token: Token,
        interests: Interest,
    ) -> io::Result<()>;

    /// Re-register `self` with the given `Registry` instance.
    ///
    /// This function should not be called directly. Use
    /// [`Registry::reregister`] instead. Implementors should handle
    /// re-registration by either delegating the call to another `Source` type.
    ///
    /// [`Registry::reregister`]: ../struct.Registry.html#method.reregister
    fn reregister(
        &mut self,
        registry: &Registry,
        token: Token,
        interests: Interest,
    ) -> io::Result<()>;

    /// Deregister `self` from the given `Registry` instance.
    ///
    /// This function should not be called directly. Use
    /// [`Registry::deregister`] instead. Implementors should handle
    /// deregistration by delegating the call to another `Source` type.
    ///
    /// [`Registry::deregister`]: ../struct.Registry.html#method.deregister
    fn deregister(&mut self, registry: &Registry) -> io::Result<()>;
}

impl<T> Source for Box<T>
where
    T: Source + ?Sized,
{
    fn register(
        &mut self,
        registry: &Registry,
        token: Token,
        interests: Interest,
    ) -> io::Result<()> {
        (**self).register(registry, token, interests)
    }

    fn reregister(
        &mut self,
        registry: &Registry,
        token: Token,
        interests: Interest,
    ) -> io::Result<()> {
        (**self).reregister(registry, token, interests)
    }

    fn deregister(&mut self, registry: &Registry) -> io::Result<()> {
        (**self).deregister(registry)
    }
}

Coverage Report

Created: 2024-12-17 06:15

Line	Count	Source (jump to first uncovered line)
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", 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		/// ```
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
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
114		impl<T> Source for Box<T>
115		where
116		T: Source + ?Sized,
117		{
118	0	fn register(
119	0	&mut self,
120	0	registry: &Registry,
121	0	token: Token,
122	0	interests: Interest,
123	0	) -> io::Result<()> {
124	0	(**self).register(registry, token, interests)
125	0	}
126
127	0	fn reregister(
128	0	&mut self,
129	0	registry: &Registry,
130	0	token: Token,
131	0	interests: Interest,
132	0	) -> io::Result<()> {
133	0	(**self).reregister(registry, token, interests)
134	0	}
135
136	0	fn deregister(&mut self, registry: &Registry) -> io::Result<()> {
137	0	(**self).deregister(registry)
138	0	}
139		}