fast_talker/lib.rs
1#![doc = include_str!("../README.md")]
2#![warn(missing_docs)]
3
4use std::{
5 io,
6 net::SocketAddr,
7 ops::{Deref, DerefMut},
8 time::{Duration, SystemTime},
9};
10
11mod sys;
12
13pub mod clock;
14#[cfg(any(
15 target_os = "linux",
16 target_os = "android",
17 target_os = "macos",
18 windows
19))]
20pub mod counters;
21#[cfg(any(target_os = "linux", target_os = "android"))]
22mod cpus;
23#[cfg(any(target_os = "linux", target_os = "android"))]
24pub mod irq;
25pub mod latency;
26#[cfg(all(
27 feature = "monitor",
28 any(
29 target_os = "linux",
30 target_os = "android",
31 target_os = "macos",
32 windows
33 )
34))]
35pub mod monitor;
36#[cfg(any(target_os = "linux", target_os = "android"))]
37mod netlink;
38#[cfg(any(
39 target_os = "linux",
40 target_os = "android",
41 target_os = "macos",
42 windows
43))]
44pub mod nic;
45#[cfg(all(
46 feature = "options",
47 any(
48 target_os = "linux",
49 target_os = "android",
50 target_os = "macos",
51 windows
52 )
53))]
54pub mod noise;
55#[cfg(all(
56 feature = "options",
57 any(
58 target_os = "linux",
59 target_os = "android",
60 target_os = "macos",
61 windows
62 )
63))]
64pub mod options;
65#[cfg(all(
66 feature = "sys-check",
67 any(
68 target_os = "linux",
69 target_os = "android",
70 target_os = "macos",
71 windows
72 )
73))]
74pub mod sys_check;
75#[cfg(all(
76 feature = "sys-check",
77 any(
78 target_os = "linux",
79 target_os = "android",
80 target_os = "macos",
81 windows
82 )
83))]
84pub use sys_check::sys_check;
85#[cfg(any(
86 target_os = "linux",
87 target_os = "android",
88 target_os = "macos",
89 windows
90))]
91pub mod multicast;
92#[cfg(all(
93 feature = "plan",
94 any(
95 target_os = "linux",
96 target_os = "android",
97 target_os = "macos",
98 windows
99 )
100))]
101pub mod plan;
102#[cfg(all(
103 feature = "pyo3",
104 any(
105 target_os = "linux",
106 target_os = "android",
107 target_os = "macos",
108 windows
109 )
110))]
111pub mod py;
112#[cfg(any(
113 target_os = "linux",
114 target_os = "android",
115 target_os = "macos",
116 windows
117))]
118pub mod rt;
119#[cfg(any(
120 target_os = "linux",
121 target_os = "android",
122 target_os = "macos",
123 windows
124))]
125pub mod sockets;
126pub mod tcp;
127
128/// Where a packet's timestamp was taken. Ordered from least to most
129/// accurate, so `a.max(b)` is the better of two sources.
130#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
131#[non_exhaustive]
132pub enum Source {
133 /// `SystemTime::now()` in user space right after the receive or send
134 /// call returned. Includes scheduling latency, and for a receive the
135 /// time spent queued in the socket buffer.
136 UserSpace,
137 /// Stamped by the kernel network stack: on receive when the datagram
138 /// reached the socket, on send when it was handed to the driver.
139 Kernel,
140 /// Stamped by the network interface as the frame came off or went onto
141 /// the wire, converted into the system clock domain.
142 Hardware,
143}
144
145/// When one datagram arrived or left.
146#[derive(Debug, Clone, Copy, PartialEq, Eq)]
147#[non_exhaustive]
148pub struct Timestamp {
149 /// The time in the system wall clock (`CLOCK_REALTIME` on unix,
150 /// `GetSystemTimePreciseAsFileTime` on Windows) from the best source
151 /// available for that packet.
152 pub time: SystemTime,
153 /// Which clock `time` came from.
154 pub source: Source,
155 /// The unconverted NIC clock reading, when the interface stamped the
156 /// frame. Present even when `source` is not [`Source::Hardware`], which
157 /// happens when the NIC clock is not disciplined to the system clock and
158 /// the reading failed the sanity check in [`Config::tolerance`].
159 pub hardware_raw: Option<Duration>,
160}
161
162impl Timestamp {
163 /// Time since the stamp. Zero if the clock has stepped backwards since.
164 pub fn elapsed(&self) -> Duration {
165 SystemTime::now()
166 .duration_since(self.time)
167 .unwrap_or_default()
168 }
169}
170
171/// When one sent datagram left, from [`Timestamped::tx_timestamps`].
172#[derive(Debug, Clone, Copy, PartialEq, Eq)]
173#[non_exhaustive]
174pub struct TxTimestamp {
175 /// The [`Sent::id`] of the send, counting from 0.
176 pub id: u32,
177 /// When it was handed to the driver (`Source::Kernel`), left the wire
178 /// (`Source::Hardware`), or the send call returned
179 /// (`Source::UserSpace`).
180 pub timestamp: Timestamp,
181}
182
183/// One datagram sent with [`Timestamped::send_to`] or [`Timestamped::send`].
184#[derive(Debug, Clone, Copy, PartialEq, Eq)]
185#[non_exhaustive]
186pub struct Sent {
187 /// Bytes sent.
188 pub len: usize,
189 /// The [`TxTimestamp::id`] its transmit stamp will carry. `None`
190 /// without [`Config::transmit`].
191 pub id: Option<u32>,
192}
193
194/// One received datagram.
195#[derive(Debug, Clone, Copy, PartialEq, Eq)]
196#[non_exhaustive]
197pub struct Received {
198 /// Bytes written into the caller's buffer.
199 pub len: usize,
200 /// Sender address.
201 pub from: SocketAddr,
202 /// Arrival time.
203 pub timestamp: Timestamp,
204 /// Datagrams the socket has dropped for lack of buffer space since it
205 /// was created, as of when this one was queued (`SO_RXQ_OVFL`). Growth
206 /// since the previous datagram is how many were lost in between.
207 /// Datagrams already queued when drops happen don't see them; the next
208 /// one queued does. Linux only; `None` elsewhere.
209 pub drops: Option<u32>,
210}
211
212/// Whether to ask the network interface for hardware timestamps.
213///
214/// Linux only. Needs `CAP_NET_ADMIN`, a NIC with a PTP hardware clock, and
215/// that clock disciplined to the system clock (usually by `phc2sys`).
216#[derive(Debug, Clone, PartialEq, Eq, Default)]
217pub enum Hardware {
218 /// Enable on the interface owning the socket's bound address, if it is
219 /// bound to a specific one. On failure the socket falls back to kernel
220 /// stamps. If the interface's current setting can't be read, it is left
221 /// alone rather than overwritten.
222 #[default]
223 Auto,
224 /// Enable on the named interface (`"eth0"`). Failure is an error from
225 /// [`Timestamped::try_with_config`].
226 Interface(String),
227 /// Never touch NIC timestamping state.
228 Off,
229}
230
231/// Socket timestamping options.
232#[derive(Debug, Clone, PartialEq, Eq)]
233pub struct Config {
234 /// Hardware timestamp policy.
235 ///
236 /// Anything but [`Hardware::Off`], including the default
237 /// [`Hardware::Auto`], may change the interface's timestamping setting
238 /// (`SIOCSHWTSTAMP`). That setting is NIC-wide: it applies to every
239 /// socket and process using the interface, and it is not reverted when
240 /// the socket closes. An existing receive filter or transmit setting is
241 /// kept, so `ptp4l` keeps working.
242 pub hardware: Hardware,
243 /// How far a hardware stamp (performance-counter stamp on Windows) may
244 /// differ from the kernel or user-space stamp of the same packet before
245 /// it is treated as a foreign clock domain and dropped for the next best
246 /// source. On Linux the TAI-UTC offset is also accepted, since PTP
247 /// hardware clocks usually run in TAI.
248 pub tolerance: Duration,
249 /// Also timestamp sent datagrams, read back with
250 /// [`Timestamped::tx_timestamps`]. See [Transmit
251 /// timestamps](Timestamped#transmit-timestamps) for what each platform
252 /// stamps.
253 pub transmit: bool,
254 /// Lets [`Timestamped::send_at`] give each datagram the time it should
255 /// leave (`SO_TXTIME` on `CLOCK_TAI`). An ETF qdisc on the outgoing
256 /// queue (`Nic::set_etf`) holds it until then; `fq` reads the time as
257 /// `CLOCK_MONOTONIC` and drops it, and other qdiscs ignore it. Needs
258 /// `CAP_NET_ADMIN`, since the kernel only allows `CLOCK_MONOTONIC`
259 /// without it. Linux only; [`Timestamped::try_with_config`] fails
260 /// elsewhere.
261 pub txtime: Option<TxTime>,
262 /// Have the kernel report errors for sent datagrams, read back with
263 /// [`Timestamped::socket_errors`]: ICMP errors (port or host
264 /// unreachable, fragmentation needed) and local ones, such as a
265 /// datagram over the path MTU. Sets `IP_RECVERR` (and `IPV6_RECVERR`
266 /// on IPv6 sockets), which also makes a send the device queue dropped
267 /// fail with `ENOBUFS` instead of reporting success. Linux only;
268 /// [`Timestamped::try_with_config`] fails elsewhere. See
269 /// [`SocketError`] for what changes on the socket.
270 pub socket_errors: bool,
271}
272
273/// An error the network or the local stack reported for a datagram this
274/// socket sent, from [`Timestamped::socket_errors`] or
275/// [`sockets::socket_errors`]. Linux only.
276///
277/// With error reporting on, the kernel also hands the error to the next
278/// send or receive on the socket, which fails once with it, connected or
279/// not; reading the error queue first takes it out of the way. A socket
280/// with errors queued polls as readable (`POLLERR`, mio's
281/// `is_error()`), so drain them on every readable event.
282#[derive(Debug, Clone, Copy, PartialEq, Eq)]
283#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
284#[non_exhaustive]
285pub struct SocketError {
286 /// The error number: `ECONNREFUSED` for a port unreachable,
287 /// `EHOSTUNREACH`, `EMSGSIZE` for fragmentation needed, `ENOBUFS`.
288 pub errno: i32,
289 /// Who reported it.
290 pub origin: ErrorOrigin,
291 /// The ICMP or ICMPv6 type, for an ICMP error.
292 pub icmp_type: u8,
293 /// The ICMP or ICMPv6 code, for an ICMP error.
294 pub icmp_code: u8,
295 /// Extra information: the next-hop MTU for fragmentation needed
296 /// (`EMSGSIZE`).
297 pub info: u32,
298 /// The host that sent the ICMP error, often a router on the way.
299 pub offender: Option<std::net::IpAddr>,
300 /// Where the datagram the error is about was going.
301 pub destination: Option<SocketAddr>,
302}
303
304impl SocketError {
305 /// The error as an [`io::Error`].
306 pub fn error(&self) -> io::Error {
307 io::Error::from_raw_os_error(self.errno)
308 }
309}
310
311impl std::fmt::Display for SocketError {
312 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
313 write!(f, "{} ({})", self.error(), self.origin)?;
314 if let Some(to) = self.destination {
315 write!(f, " sending to {to}")?;
316 }
317 if let Some(by) = self.offender {
318 write!(f, ", reported by {by}")?;
319 }
320 Ok(())
321 }
322}
323
324/// Where a [`SocketError`] came from.
325#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
326#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
327#[non_exhaustive]
328pub enum ErrorOrigin {
329 /// This host's stack (`SO_EE_ORIGIN_LOCAL`).
330 Local,
331 /// An ICMP message.
332 Icmp,
333 /// An ICMPv6 message.
334 Icmp6,
335 /// Another origin, by number.
336 Other(u8),
337}
338
339impl std::fmt::Display for ErrorOrigin {
340 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
341 match self {
342 Self::Local => f.write_str("local"),
343 Self::Icmp => f.write_str("icmp"),
344 Self::Icmp6 => f.write_str("icmp6"),
345 Self::Other(n) => write!(f, "origin {n}"),
346 }
347 }
348}
349
350/// How [`Timestamped::send_at`] treats its time.
351#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
352pub enum TxTime {
353 /// Send at that time.
354 Launch,
355 /// Send by that time: the qdisc may release it early, and reports it
356 /// missed if it can't. Needs the ETF qdisc in deadline mode.
357 Deadline,
358}
359
360/// A timed send the qdisc dropped, from [`Timestamped::txtime_errors`].
361#[derive(Debug, Clone, Copy, PartialEq, Eq)]
362#[non_exhaustive]
363pub struct TxTimeError {
364 /// The time the send asked for.
365 pub time: SystemTime,
366 /// Why it was dropped.
367 pub kind: TxTimeErrorKind,
368}
369
370/// Why a timed send was dropped.
371#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
372#[non_exhaustive]
373pub enum TxTimeErrorKind {
374 /// Its time passed before the qdisc could send it.
375 Missed,
376 /// Its time was already past when it reached the qdisc, was earlier
377 /// than one already queued in launch mode, or the socket's clock didn't
378 /// match the qdisc's.
379 Invalid,
380}
381
382impl Config {
383 /// Kernel stamps, never touching the NIC: [`Config::default`] with
384 /// [`Hardware::Off`]. The choice for a library that stamps its own
385 /// sockets, since enabling hardware stamps changes a NIC-wide setting
386 /// that every other program on the interface sees. Packets still fall
387 /// back to user-space stamps where the kernel has none, flagged by
388 /// [`Timestamp::source`].
389 pub fn kernel_only() -> Self {
390 Self {
391 hardware: Hardware::Off,
392 ..Self::default()
393 }
394 }
395}
396
397impl Default for Config {
398 fn default() -> Self {
399 Self {
400 hardware: Hardware::Auto,
401 tolerance: Duration::from_millis(100),
402 transmit: false,
403 txtime: None,
404 socket_errors: false,
405 }
406 }
407}
408
409/// A socket's raw handle: a file descriptor on unix, a `SOCKET` on Windows.
410#[cfg(unix)]
411pub type RawSocket = std::os::fd::RawFd;
412
413/// A socket's raw handle: a file descriptor on unix, a `SOCKET` on Windows.
414#[cfg(windows)]
415pub type RawSocket = std::os::windows::io::RawSocket;
416
417/// Anything holding an open socket, on every platform.
418///
419/// Every function in this crate that takes a socket takes `&impl Handle`,
420/// so one call compiles on unix and Windows alike. Implemented for every
421/// type with a raw descriptor (`AsRawFd` on unix, `AsRawSocket` on
422/// Windows): std and mio sockets, [`Timestamped`],
423/// [`TimestampedStream`](tcp::TimestampedStream), and borrowed or owned
424/// descriptors.
425pub trait Handle {
426 /// The raw socket. Only valid while `self` is.
427 fn raw_socket(&self) -> RawSocket;
428}
429
430#[cfg(unix)]
431impl<T: std::os::fd::AsRawFd + ?Sized> Handle for T {
432 fn raw_socket(&self) -> RawSocket {
433 self.as_raw_fd()
434 }
435}
436
437#[cfg(windows)]
438impl<T: std::os::windows::io::AsRawSocket + ?Sized> Handle for T {
439 fn raw_socket(&self) -> RawSocket {
440 self.as_raw_socket()
441 }
442}
443
444/// The internal raw handle of a [`Handle`].
445pub(crate) fn raw(socket: &(impl Handle + ?Sized)) -> sys::Raw {
446 socket.raw_socket() as sys::Raw
447}
448
449/// A datagram socket [`Timestamped`] can drive.
450///
451/// Sockets that must see `WouldBlock` to re-arm readiness (mio on Windows)
452/// override [`Socket::try_io`]. Implemented for `std::net::UdpSocket` and,
453/// with the `mio` feature, `mio::net::UdpSocket`.
454pub trait Socket: Handle {
455 /// Runs one send or receive syscall on the socket.
456 fn try_io<R>(&self, f: impl FnOnce() -> io::Result<R>) -> io::Result<R> {
457 f()
458 }
459}
460
461impl Socket for std::net::UdpSocket {}
462
463#[cfg(feature = "mio")]
464impl Socket for mio::net::UdpSocket {
465 fn try_io<R>(&self, f: impl FnOnce() -> io::Result<R>) -> io::Result<R> {
466 mio::net::UdpSocket::try_io(self, f)
467 }
468}
469
470/// A UDP socket whose receives report the arrival time of each datagram.
471///
472/// Dereferences to the wrapped [`Socket`], so socket options and
473/// `set_nonblocking` work as usual. Its own [`send_to`](Timestamped::send_to)
474/// and [`send`](Timestamped::send) shadow the socket's to number sends for
475/// [transmit timestamps](#transmit-timestamps).
476///
477/// Every receive returns a `SystemTime` and the [`Source`] it came from. The
478/// best source is enabled automatically, and a packet missing that stamp
479/// falls back to the next one, so there is never a `None` to handle.
480///
481/// # Platforms
482///
483/// | Platform | Best source | Mechanism |
484/// |---|---|---|
485/// | Linux, Android | `Hardware` | `SO_TIMESTAMPING` with `SIOCSHWTSTAMP` on the bound interface; kernel software stamps otherwise |
486/// | Windows 10 2004+, Server 2022+ | `Kernel` | `SIO_TIMESTAMPING` + `WSARecvMsg`, performance-counter ticks converted to wall clock |
487/// | FreeBSD | `Kernel` | `SO_TIMESTAMP` with `SO_TS_CLOCK = SO_TS_REALTIME` for nanosecond stamps |
488/// | macOS, iOS, NetBSD, OpenBSD, DragonFly, illumos, Solaris, QNX | `Kernel` | `SO_TIMESTAMP`, microsecond `timeval` |
489/// | Other unix | `UserSpace` | `recvfrom` |
490///
491/// Hardware stamps need `CAP_NET_ADMIN`, a NIC with a PTP hardware clock,
492/// and that clock disciplined to the system clock (`phc2sys`). A NIC clock
493/// in TAI is recognised through the kernel's TAI offset. One in an
494/// unrelated domain fails [`Config::tolerance`] and the packet falls back to
495/// the kernel stamp, keeping the raw reading in [`Timestamp::hardware_raw`].
496///
497/// On Windows the stamp is taken where the adapter driver hands the frame
498/// to NDIS. It needs software timestamping enabled on the adapter (the
499/// `*SoftwareTimestamp` advanced property) and never appears on loopback;
500/// packets without one fall back to user space. Adapter hardware timestamps
501/// arrive as unconverted NIC ticks, fail the tolerance check, and also fall
502/// back to user space.
503///
504/// # Transmit timestamps
505///
506/// With [`Config::transmit`], [`Timestamped::tx_timestamps`] reports when
507/// each sent datagram left, matched to its send by [`Sent::id`].
508///
509/// | Platform | Best source | Which sends |
510/// |---|---|---|
511/// | Linux, Android | `Hardware` | every send on the socket |
512/// | Windows 10 2004+, Server 2022+ | `Kernel` | sends through [`Timestamped`] |
513/// | Other unix | `UserSpace` | sends through [`Timestamped`] |
514///
515/// Linux stamps every send in the kernel, including ones made through the
516/// wrapped socket directly; ids only match [`Sent::id`] if every send goes
517/// through [`Timestamped`] from one thread at a time.
518///
519/// Windows stamps where the adapter driver takes the frame from NDIS, which
520/// needs transmit timestamping on the adapter (`*SoftwareTimestamp`, see
521/// `Nic::set_tx_timestamping`). A send the driver didn't stamp, such as
522/// one over loopback, is reported with its user-space time, as is one whose
523/// stamp is still pending a second later.
524///
525/// Elsewhere the kernel has no transmit stamps, and each send is stamped
526/// when the send call returns.
527///
528/// # mio
529///
530/// With the `mio` feature, `Timestamped<S>` implements `mio::event::Source`
531/// when `S` does, and calls `mio::net::UdpSocket` through its `try_io` so
532/// readiness is re-armed on Windows. Wrap a std socket with
533/// `mio::net::UdpSocket::from_std` first. Call [`Timestamped::drain`] on
534/// each readable event; it takes everything queued without waiting.
535///
536/// ```ignore
537/// let mut socket = Timestamped::new(mio::net::UdpSocket::bind(addr)?);
538/// poll.registry().register(&mut socket, TOKEN, Interest::READABLE)?;
539///
540/// // on a readable event:
541/// socket.drain(&mut buf, |payload, r| handle(payload, r.timestamp))?;
542/// ```
543///
544/// [`Timestamped::recv_batch`] takes many queued datagrams in one call (one
545/// `recvmmsg` on Linux).
546#[derive(Debug)]
547pub struct Timestamped<S> {
548 io: S,
549 state: sys::State,
550 source: Source,
551 interface: Option<String>,
552}
553
554impl<S: Socket> Timestamped<S> {
555 /// Enables the best timestamp source available with [`Config::default`].
556 ///
557 /// Never fails: whatever can't be enabled degrades to the next source,
558 /// down to user space. [`Timestamped::source`] says what was obtained.
559 pub fn new(io: S) -> Self {
560 Self::with_config(io, Config::default())
561 }
562
563 /// Like [`Timestamped::new`] with explicit options. Never fails.
564 pub fn with_config(io: S, config: Config) -> Self {
565 let setup = sys::setup(raw(&io), &config);
566 Self {
567 io,
568 state: setup.state,
569 source: setup.source,
570 interface: setup.interface,
571 }
572 }
573
574 /// Like [`Timestamped::with_config`], but fails if kernel timestamps
575 /// can't be enabled, if the [`Hardware::Interface`] can't be
576 /// configured, or if [`Config::txtime`] or [`Config::socket_errors`]
577 /// can't be set.
578 pub fn try_with_config(io: S, config: Config) -> io::Result<Self> {
579 let setup = sys::setup(raw(&io), &config);
580 if let Some(e) = setup.kernel_error {
581 return Err(e);
582 }
583 if let (Hardware::Interface(_), Some(e)) = (&config.hardware, setup.hardware_error) {
584 return Err(e);
585 }
586 if let Some(e) = setup.txtime_error {
587 return Err(e);
588 }
589 if let Some(e) = setup.errors_error {
590 return Err(e);
591 }
592 Ok(Self {
593 io,
594 state: setup.state,
595 source: setup.source,
596 interface: setup.interface,
597 })
598 }
599
600 /// The best source configured on this socket for ordinary datagrams.
601 /// [`Source::Hardware`] only when the interface stamps every received
602 /// frame; under a narrower filter, such as the PTP-only one `ptp4l`
603 /// sets, this is [`Source::Kernel`] even though
604 /// [`Timestamped::hardware_interface`] is set and the frames the filter
605 /// matches still carry hardware stamps. A packet can also fall back to a
606 /// lesser source, e.g. a frame the NIC didn't stamp.
607 pub fn source(&self) -> Source {
608 self.source
609 }
610
611 /// The interface hardware timestamping was enabled on, if any, whatever
612 /// receive filter it ended up with.
613 pub fn hardware_interface(&self) -> Option<&str> {
614 self.interface.as_deref()
615 }
616
617 /// The wrapped socket.
618 pub fn get_ref(&self) -> &S {
619 &self.io
620 }
621
622 /// The wrapped socket.
623 pub fn get_mut(&mut self) -> &mut S {
624 &mut self.io
625 }
626
627 /// Unwraps the socket. Kernel and NIC timestamping stay enabled on it.
628 pub fn into_inner(self) -> S {
629 self.io
630 }
631
632 /// The socket's buffer use and, on Linux, drop count (`ss -m`). See
633 /// [`sockets::SocketMemory::of`].
634 #[cfg(any(
635 target_os = "linux",
636 target_os = "android",
637 target_os = "macos",
638 windows
639 ))]
640 pub fn memory(&self) -> io::Result<sockets::SocketMemory> {
641 sockets::SocketMemory::of_raw(raw(&self.io))
642 }
643
644 /// Appends every transmit timestamp ready so far to `out` and returns
645 /// how many. Never waits. Always empty without [`Config::transmit`].
646 ///
647 /// Stamps arrive shortly after each send, usually within tens of
648 /// microseconds for hardware ones. On Linux the socket signals them as an
649 /// error condition, so with mio call this when `event.is_error()` is
650 /// set, and undrained stamps count against the receive buffer. A Linux
651 /// hardware stamp read more than 10 s after its send can't be told apart
652 /// from a NIC clock in the wrong domain, and is reported as software
653 /// time. Elsewhere, call it after sending; up to 4096 unread sends are
654 /// remembered.
655 ///
656 /// On Linux this drains the whole error queue. What else is there is
657 /// kept for [`Timestamped::socket_errors`] and
658 /// [`Timestamped::txtime_errors`] when those are on, up to 4096 of
659 /// each, and discarded otherwise.
660 pub fn tx_timestamps(&self, out: &mut Vec<TxTimestamp>) -> io::Result<usize> {
661 sys::tx_timestamps(raw(&self.io), &self.state, out)
662 }
663
664 /// Sends one datagram to `to`, like `UdpSocket::send_to`.
665 pub fn send_to(&self, buf: &[u8], to: SocketAddr) -> io::Result<Sent> {
666 self.io
667 .try_io(|| sys::send(raw(&self.io), &self.state, buf, Some(to)))
668 }
669
670 /// Sends one datagram on a connected socket, like `UdpSocket::send`.
671 pub fn send(&self, buf: &[u8]) -> io::Result<Sent> {
672 self.io
673 .try_io(|| sys::send(raw(&self.io), &self.state, buf, None))
674 }
675
676 /// Sends one datagram to `to`, to leave at `at` (see [`Config::txtime`]).
677 /// Fails with `InvalidInput` without [`Config::txtime`], and with
678 /// `Unsupported` off Linux. A time the qdisc can't honour is reported
679 /// later by [`Timestamped::txtime_errors`], not here.
680 pub fn send_to_at(&self, buf: &[u8], to: SocketAddr, at: SystemTime) -> io::Result<Sent> {
681 self.io
682 .try_io(|| sys::send_at(raw(&self.io), &self.state, buf, Some(to), at))
683 }
684
685 /// Like [`Timestamped::send_to_at`] on a connected socket.
686 pub fn send_at(&self, buf: &[u8], at: SystemTime) -> io::Result<Sent> {
687 self.io
688 .try_io(|| sys::send_at(raw(&self.io), &self.state, buf, None, at))
689 }
690
691 /// Appends every timed send the qdisc has dropped since the last call to
692 /// `out` and returns how many. Never waits. Like transmit stamps, drops
693 /// are signalled as an error condition on the socket.
694 pub fn txtime_errors(&self, out: &mut Vec<TxTimeError>) -> io::Result<usize> {
695 sys::txtime_errors(raw(&self.io), &self.state, out)
696 }
697
698 /// Appends every error reported for sent datagrams since the last call
699 /// to `out` and returns how many (see [`Config::socket_errors`]).
700 /// Never waits. Transmit stamps and dropped timed sends read along the
701 /// way are kept for their own calls. Always empty off Linux, or without
702 /// [`Config::socket_errors`].
703 pub fn socket_errors(&self, out: &mut Vec<SocketError>) -> io::Result<usize> {
704 sys::socket_errors(raw(&self.io), &self.state, out)
705 }
706
707 /// Receives one datagram, like `UdpSocket::recv_from`.
708 pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<Received> {
709 self.io
710 .try_io(|| sys::recv_from(raw(&self.io), &self.state, buf, false))
711 }
712
713 /// Receives one datagram, like `UdpSocket::recv`.
714 pub fn recv(&self, buf: &mut [u8]) -> io::Result<(usize, Timestamp)> {
715 self.recv_from(buf).map(|r| (r.len, r.timestamp))
716 }
717
718 /// Receives up to `bufs.len()` datagrams, one per buffer, appending a
719 /// [`Received`] for each to `out`. Returns the count.
720 ///
721 /// Waits for the first datagram as [`Timestamped::recv_from`] does, then
722 /// takes whatever else is already queued. One `recvmmsg` call on Linux.
723 pub fn recv_batch(&self, bufs: &mut [&mut [u8]], out: &mut Vec<Received>) -> io::Result<usize> {
724 if bufs.is_empty() {
725 return Ok(0);
726 }
727 self.io
728 .try_io(|| sys::recv_batch(raw(&self.io), &self.state, bufs, out))
729 }
730
731 /// Calls `f` with the payload and metadata of every queued datagram and
732 /// returns how many there were. Never waits: an empty queue gives
733 /// `Ok(0)` even on a blocking socket. Meant for edge-triggered readiness
734 /// (mio), where each readable event must be drained to `WouldBlock`.
735 pub fn drain(&self, buf: &mut [u8], mut f: impl FnMut(&[u8], Received)) -> io::Result<usize> {
736 let mut n = 0;
737 loop {
738 match self
739 .io
740 .try_io(|| sys::recv_from(raw(&self.io), &self.state, buf, true))
741 {
742 Ok(r) => {
743 f(&buf[..r.len], r);
744 n += 1;
745 }
746 Err(e) if e.kind() == io::ErrorKind::WouldBlock => return Ok(n),
747 Err(e) => return Err(e),
748 }
749 }
750 }
751}
752
753impl<S> Deref for Timestamped<S> {
754 type Target = S;
755
756 fn deref(&self) -> &S {
757 &self.io
758 }
759}
760
761impl<S> DerefMut for Timestamped<S> {
762 fn deref_mut(&mut self) -> &mut S {
763 &mut self.io
764 }
765}
766
767#[cfg(feature = "mio")]
768impl<S: mio::event::Source> mio::event::Source for Timestamped<S> {
769 fn register(
770 &mut self,
771 registry: &mio::Registry,
772 token: mio::Token,
773 interests: mio::Interest,
774 ) -> io::Result<()> {
775 self.io.register(registry, token, interests)
776 }
777
778 fn reregister(
779 &mut self,
780 registry: &mio::Registry,
781 token: mio::Token,
782 interests: mio::Interest,
783 ) -> io::Result<()> {
784 self.io.reregister(registry, token, interests)
785 }
786
787 fn deregister(&mut self, registry: &mio::Registry) -> io::Result<()> {
788 self.io.deregister(registry)
789 }
790}
791
792#[cfg(unix)]
793impl<S: std::os::fd::AsRawFd> std::os::fd::AsRawFd for Timestamped<S> {
794 fn as_raw_fd(&self) -> std::os::fd::RawFd {
795 self.io.as_raw_fd()
796 }
797}
798
799#[cfg(unix)]
800impl<S: std::os::fd::AsFd> std::os::fd::AsFd for Timestamped<S> {
801 fn as_fd(&self) -> std::os::fd::BorrowedFd<'_> {
802 self.io.as_fd()
803 }
804}
805
806#[cfg(windows)]
807impl<S: std::os::windows::io::AsRawSocket> std::os::windows::io::AsRawSocket for Timestamped<S> {
808 fn as_raw_socket(&self) -> std::os::windows::io::RawSocket {
809 self.io.as_raw_socket()
810 }
811}
812
813#[cfg(windows)]
814impl<S: std::os::windows::io::AsSocket> std::os::windows::io::AsSocket for Timestamped<S> {
815 fn as_socket(&self) -> std::os::windows::io::BorrowedSocket<'_> {
816 self.io.as_socket()
817 }
818}
819
820/// Absolute difference between two instants on the wall clock.
821pub(crate) fn abs_diff(a: SystemTime, b: SystemTime) -> Duration {
822 a.duration_since(b).unwrap_or_else(|e| e.duration())
823}
824
825/// Builds the final [`Timestamp`] from whatever the platform offered.
826///
827/// `hardware` candidates are tried in order and the first within `tolerance`
828/// of the best software reference wins.
829pub(crate) fn resolve(
830 kernel: Option<SystemTime>,
831 hardware_raw: Option<Duration>,
832 hardware_candidates: &[SystemTime],
833 user: SystemTime,
834 tolerance: Duration,
835) -> Timestamp {
836 let reference = kernel.unwrap_or(user);
837 if let Some(&time) = hardware_candidates
838 .iter()
839 .find(|&&t| abs_diff(t, reference) <= tolerance)
840 {
841 return Timestamp {
842 time,
843 source: Source::Hardware,
844 hardware_raw,
845 };
846 }
847 match kernel {
848 Some(time) => Timestamp {
849 time,
850 source: Source::Kernel,
851 hardware_raw,
852 },
853 None => Timestamp {
854 time: user,
855 source: Source::UserSpace,
856 hardware_raw,
857 },
858 }
859}
860
861#[cfg(test)]
862mod tests {
863 use super::*;
864
865 #[test]
866 fn source_ordering_prefers_hardware() {
867 assert!(Source::Hardware > Source::Kernel);
868 assert!(Source::Kernel > Source::UserSpace);
869 }
870
871 #[test]
872 fn resolve_picks_hardware_within_tolerance() {
873 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
874 let kernel = now - Duration::from_micros(50);
875 let raw = Duration::from_secs(1_700_000_000) + Duration::from_secs(37)
876 - Duration::from_micros(80);
877 let tai = raw - Duration::from_secs(37);
878 let t = resolve(
879 Some(kernel),
880 Some(raw),
881 &[SystemTime::UNIX_EPOCH + raw, SystemTime::UNIX_EPOCH + tai],
882 now,
883 Duration::from_millis(100),
884 );
885 assert_eq!(t.source, Source::Hardware);
886 assert_eq!(t.time, SystemTime::UNIX_EPOCH + tai);
887 assert_eq!(t.hardware_raw, Some(raw));
888 }
889
890 #[test]
891 fn resolve_rejects_undisciplined_hardware_clock() {
892 let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000);
893 let kernel = now - Duration::from_micros(50);
894 let raw = Duration::from_secs(12_345);
895 let t = resolve(
896 Some(kernel),
897 Some(raw),
898 &[SystemTime::UNIX_EPOCH + raw],
899 now,
900 Duration::from_millis(100),
901 );
902 assert_eq!(t.source, Source::Kernel);
903 assert_eq!(t.time, kernel);
904 assert_eq!(t.hardware_raw, Some(raw));
905 }
906
907 #[test]
908 fn resolve_falls_back_to_user_space() {
909 let now = SystemTime::now();
910 let t = resolve(None, None, &[], now, Duration::from_millis(100));
911 assert_eq!(t.source, Source::UserSpace);
912 assert_eq!(t.time, now);
913 }
914}