Skip to main content

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}