Skip to main content

Crate fast_talker

Crate fast_talker 

Source
Expand description

§fast-talker

Low-latency networking helpers: receive timestamps, NIC and thread tuning, and the counters that show where packets are lost. Everything uses direct syscalls; nothing shells out.

ModuleWhat it doesReplacesPlatforms
TimestampedUDP receive with hardware, kernel or user-space arrival times, per-datagram drop counts, send timestamps, send errors (Linux), sends timed to leave at a given instant (Linux)all
tcpTCP reads and sends with timestamps (queued, sent, acknowledged) and connection healthss -tiall
nicInterfaces and their addresses, NIC counters, rings, coalescing, flow control, queues, EEE, NAPI and IRQ placement, PTP clock offset, flow steering, ETF qdiscip addr, ethtool, ip -s link, tcLinux, macOS, Windows
countersKernel protocol counters with interval deltasnstat -azLinux, macOS, Windows
socketsSockets created with their options applied before bind or connect; socket queues, buffer use and drops; socket options for latencyss -m, setsockoptLinux, macOS, Windows
rtThread priority and CPU placement, memory residency, idle and timer controlchrt, taskset, mlockallLinux, macOS, Windows
irqInterrupt affinity and handler threads/proc/irq/*Linux
latencyAllocation-free latency histogram, request/reply round-trip matchingall
clockA device’s own timestamps mapped to host time through receive stampsall
multicastGroup membership by interface name, source-specific joins, sending interface, hops, loopbackLinux, macOS, Windows
monitorLow-priority background thread feeding loss counters and TCP health to a callbackLinux, macOS, Windows
planDeclarative interface configuration (TOML with serde), with drift checkingLinux, Windows; compiles on macOS, where most settings are Unsupported
optionsOption lists a library can accept from its own users, applied per platformLinux, macOS, Windows
sys_checkRead-only checks of kernel, CPU isolation, power and PTP clock sync, and of the privileges setup needsLinux, macOS, Windows

Linux has everything. macOS and Windows get what they support; each module’s docs list what’s available where.

§Receive with arrival timestamps

use fast_talker::Timestamped;
use std::net::UdpSocket;

let socket = Timestamped::new(UdpSocket::bind("0.0.0.0:5005")?);
let mut buf = [0u8; 1500];
let r = socket.recv_from(&mut buf)?;
println!(
    "{} bytes from {}, {:?} stamp, {:?} ago, {:?} dropped so far",
    r.len, r.from, r.timestamp.source, r.timestamp.elapsed(), r.drops
);

The best available stamp is enabled automatically (NIC hardware on Linux, kernel on macOS, Windows and the BSDs, user space otherwise). A packet missing it falls back to the next best. On Linux that turns on hardware timestamping for the interface the socket is bound to, a NIC-wide setting that stays on after the socket closes; set Config::hardware to Hardware::Off, or start from Config::kernel_only(), to leave the NIC alone. Timestamped derefs to the wrapped socket, works with mio (feature mio), and has recv_batch for batched receives. With Config::socket_errors, Timestamped::socket_errors reports ICMP and local errors for sent datagrams on Linux.

§Create a socket with its options

use fast_talker::{options::{Rules, SocketOption}, sockets};

let options = [
    SocketOption::RecvBuffer(8 << 20),
    SocketOption::BindDevice("eth0".into()),
    SocketOption::WinCpuAffinity(3),
];
let allow = |o: &SocketOption| !matches!(o, SocketOption::Dscp(_));
let (socket, report) =
    sockets::bind_udp("0.0.0.0:5005".parse().unwrap(), &options, &Rules::portable(&allow))?;
for a in &report.adjusted {
    eprintln!("{a}"); // RecvBuffer(8388608) took effect as RecvBuffer(212992): capped by ...
}

bind_udp and connect_tcp apply every option to the unbound socket, so the ones that only work or only matter there (WinCpuAffinity, ReuseAddress, BindDevice, TCP buffer sizes) take effect. Each Report lists what was applied, what the platform adjusted (a buffer capped by net.core.rmem_max, a real-time priority clamped on macOS), and what was skipped. A Report holds the guards that keep some settings in force, so it stays on the thread that made it; report.summary() copies the lists into a ReportSummary, which is Send and Clone for handing to another thread or storing in a handle. nic::interfaces() lists interfaces with their addresses, nic::on_link(ip) finds the one on a device’s subnet, and nic::source_for(ip) the local address a device should send to.

§Map a device’s clock to host time

clock::DeviceClock pairs the counter a device stamps its packets with and the kernel’s receive stamp of each packet. It unwraps a counter with a known modulus, keeps the smallest offset over a sliding window, holds back stamps that claim a packet arrived before it was sent (a corrupted counter), and can fit a drifting device clock, also for packets tens of seconds apart. Feed it each packet once, with that packet’s own receive stamp.

§Pin a receive path

On Linux, pin the NIC’s NAPI thread and interrupt and the socket reader, and keep the CPUs out of deep idle:

use fast_talker::{irq, nic::Nic, rt::{self, CpuDmaLatency, Scheduler, Thread}};

let nic = Nic::open("eth0")?;
nic.set_eee(false)?;
nic.set_threaded_napi(true)?;
irq::set_all_affinity(&[0, 1, 2, 3, 4, 5])?;
for napi in nic.napis()? {
    napi.pin(&[7], Scheduler::Fifo(90))?;
}
rt::lock_memory()?;
let _idle = CpuDmaLatency::request(std::time::Duration::ZERO)?;
std::thread::spawn(|| {
    Thread::current().pin(&[7], Scheduler::Fifo(80)).unwrap();
    rt::prefault_stack(256 * 1024);
    // receive loop
});

The rt docs give the Windows and macOS equivalent of each step; examples/realtime.rs does the full setup on all three.

A socket’s SO_BUSY_POLL only spins a blocking receive on that socket. A thread that waits in epoll_wait (mio’s Poll::poll) still sleeps until the interrupt unless the epoll instance busy-polls too, which Linux 6.9 allows. sockets::epoll_busy_poll_from reads the LinuxBusyPoll, LinuxPreferBusyPoll and LinuxBusyPollBudget options off a socket’s option list and sockets::set_epoll_busy_poll gives them to the poll, so one declaration covers both:

use fast_talker::{options::SocketOption, sockets};
use std::os::fd::AsFd;

let options = [SocketOption::LinuxBusyPoll(10_000), SocketOption::LinuxPreferBusyPoll(true)];
let poll = mio::Poll::new()?;
if let Some(p) = sockets::epoll_busy_poll_from(&options) {
    sockets::set_epoll_busy_poll(poll.registry().as_fd(), &p)?;
}

§Measure real-time noise

On Linux, noise does what rtla osnoise, rtla timerlat and rtla hwnoise do, as a background thread for the length of a run: hist triggers count every interrupt, softirq and context switch on the CPUs that run a busy-polling thread (nothing is added to those CPUs), timerlat measures what a thread of a given priority waits on the others, and the sink gets log2 histograms once a second. Needs root and the tracers built in; Noise::capabilities() says what the kernel has.

use fast_talker::{noise::{Noise, NoiseConfig, PassiveConfig, TimerlatConfig}, options::ThreadOption};
use std::time::Duration;

let noise = Noise::start(
    NoiseConfig {
        instance: "my-run".into(),
        passive: Some(PassiveConfig { cpus: vec![1, 2], wakeups_of: vec!["my-rt-thread".into()] }),
        timerlat: Some(TimerlatConfig {
            cpus: vec![3, 4],
            reader_thread: vec![ThreadOption::RtPriority(80)],
            stop_at: Some(Duration::from_micros(500)),
            ..TimerlatConfig::default()
        }),
        ..NoiseConfig::default()
    },
    |report| println!("{report:?}"),
)?;
// ... the run ...
noise.stop();

§Watch for loss

use fast_talker::monitor::{Config, Monitor, WatchedSocket};

let socket = std::net::UdpSocket::bind("10.0.0.1:5000")?;
let _monitor = Monitor::start(
    Config {
        interfaces: vec!["eth0".into()],
        sockets: vec![WatchedSocket::new("rx", &socket)?],
        ..Config::default()
    },
    |sample| {
        if sample.has_loss() {
            eprintln!("loss: {sample:?}");
        }
    },
)?;

The monitor samples on its own low-priority thread. Its default reads were checked against 16 mainline NIC drivers for contention with the packet path. examples/drops.rs does the same by hand; examples/nic_report.rs prints what an interface’s driver supports.

§Features

FeatureDefaultEnables
monitoryesmonitor (and plan, options)
planyesplan
optionsyesoptions
sys-checkyessys_check
serdenoSerialize/Deserialize for plans, options, checks and flow rules
mionomio::event::Source for Timestamped, which can wrap a mio::net::UdpSocket
pyo3noDuck-typed Python conversions for the option types and reports, and a shared apply_process_options (py); enables options

The only other dependencies are libc and windows-sys.

§Options from Python

With pyo3, ThreadOption, ProcessOption, SocketOption and the rt types they carry convert from plain Python values, so every extension module built on fast-talker takes the same configuration without sharing a Python class. Take py::ThreadOptions (or ProcessOptions, SocketOptions) as an argument:

ⓘ
#[pyfunction]
#[pyo3(signature = (thread = None))]
fn connect(thread: fast_talker::py::ThreadOptions) -> PyResult<()> {
    let options = thread.0;
    // Hand `options` to the network thread, which calls
    // ThreadOption::apply_all(&options, &Rules::default()).
    Ok(())
}

Python callers can then write any of:

connect(None)
connect(("rt_priority", 80))
connect([("cpu_affinity", [7]), ("rt_priority", 80), "win_disable_power_throttling"])
connect({"cpu_affinity": 7, "rt_priority": 80, "macos_qos": "user_interactive"})
connect([{"kind": "unix_scheduler", "value": ("fifo", 80)}])
connect([{"kind": "macos_time_constraint", "period_us": 1000, "computation_us": 200, "constraint_us": 500}])

@dataclass
class Opt:
    kind: str
    value: object = None

connect([Opt("RtPriority", 80), Opt("win-priority", "time_critical")])

class Net(Enum):
    RT_PRIORITY = 80
    CPU_AFFINITY = (6, 7)

connect(list(Net))
connect(ThreadConfig(80, 3))  # anything with `priority` and `cpu_affinity`

Names ignore case, _, - and spaces. Mappings, (name, value) pairs, objects with kind/type and value attributes (dataclasses, attrs, pydantic, named tuples, SimpleNamespace) and Enum members all work; a tagged mapping with keys it doesn’t use is refused rather than half read. Bad input raises TypeError or ValueError naming the value, the accepted shapes and the closest valid name. Converting back to Python gives {"kind": "rt_priority", "value": 80} dicts, which convert back unchanged. py/fast_talker_options.pyi has type stubs (ThreadOptionsLike, SchedulerLike, …) to copy into a module’s stubs.

Process-wide options are the application’s to choose. py::register(m) adds apply_process_options(options, *, strict=False) and the ProcessGuard it returns to an extension module, so every module built on fast-talker offers the same call. ProcessGuard.__module__ is the module’s name; a package that re-exports an extension module mydriver._core calls py::register_as(m, "mydriver") instead:

with mydriver.apply_process_options([("linux_cpu_dma_latency", 0), "lock_memory"]) as guard:
    print(guard.applied, guard.skipped)
    ...  # settings held until the block ends

A Report and a ReportSummary convert to {"applied": [...], "adjusted": [...], "skipped": [...]} (ReportDict, ThreadReportDict, … in the stubs).

The tests for this embed Python: cargo test --features pyo3 finds python3 on PATH; set PYO3_PYTHON to use another interpreter, and put pydantic and attrs on PYTHONPATH to cover them too.

§Tests

cargo test runs the unit tests and the tests against the real OS (loopback, TCP, multicast). The sim_* tests run each platform’s backend against a simulated host and NIC; they need cargo-snare and run with cargo snare test, which plain cargo test leaves out. tests/tuning.rs changes a real NIC on Linux: it skips itself without root and takes the NIC from FAST_TALKER_TEST_NIC.

§Migrating from 0.2

  • Every function taking a socket takes &impl fast_talker::Handle, implemented for anything with a raw descriptor (AsRawFd / AsRawSocket), Timestamped and TimestampedStream included. Code split by #[cfg(unix)] / #[cfg(windows)] only to name AsFd or AsSocket can be one function. multicast::Handle is now fast_talker::Handle (still re-exported from multicast), with raw_socket() in place of raw().
  • Socket and tcp::Stream require Handle instead of AsRawFd / AsRawSocket; implementations need no change.
  • Report has a new public field, adjusted. Code building Rules by hand for a library’s users can use Rules::portable(&allow), and Rules::first_rejected or Rules::check to validate before applying. kind_name() gives an option’s snake-case name.
  • Config has a new field, socket_errors; struct literals need ..Config::default() (or Config::kernel_only()).
  • Reading transmit stamps no longer discards ICMP errors from the error queue when Config::socket_errors is on; they wait for Timestamped::socket_errors.
  • SocketOption::apply_all on an already bound socket fails WinCpuAffinity with InvalidInput instead of the OS’s EINVAL; create the socket with sockets::bind_udp or sockets::connect_tcp.
  • On macOS, a RecvBuffer or SendBuffer above kern.ipc.maxsockbuf is set to the limit and reported in Report::adjusted, where it could fail with ENOBUFS before.
  • A type that kept a copy of a Report’s lists to send between threads can be options::ReportSummary, from Report::summary(); it converts to the same Python dict.
  • DeviceClock holds back a packet whose offset falls more than DeviceClock::outlier_gate (1 ms by default) below the mapping, until three in a row agree, so a host clock stepped back is followed after three packets instead of one. With fit_drift the mapping follows the lower convex hull of the window minima instead of a least-squares line. to_host maps any time SystemTime holds, before 1970 and after 2554 included.
  • nic::source_for no longer answers with the peer’s own address when connecting leaves the local address unspecified; it fails with AddrNotAvailable when no other address shares the peer’s subnet.
  • In the Python stubs, the TypeVar is _OptionDict and the *Name literals are declared TypeAlias; recopy the file. The extension module’s ProcessGuard.__module__ is no longer "fast_talker".

§Minimum Rust version

1.88.

§Not covered

  • Async runtimes. For a tokio socket with hardware transmit stamps, see timestamped-socket from the Pendulum project.
  • io_uring setup (IORING_SETUP_DEFER_TASKRUN, IORING_REGISTER_NAPI); that belongs in the crate driving the ring.

§License

Apache-2.0; see LICENSE.

Re-exports§

pub use sys_check::sys_check;

Modules§

clock
Mapping a device’s own timestamps to host time.
counters
Kernel protocol counters, as nstat -az shows them.
irq
Hardware interrupt affinity and handler threads: what writing /proc/irq/<n>/smp_affinity_list and running chrt on irq/<n>-* threads does by hand.
latency
A fixed-size latency histogram cheap enough to record into from a real-time thread: no allocation, no locks, a few instructions per sample.
monitor
A low-priority background thread that samples NIC, protocol and socket loss counters on an interval and hands each sample to a callback, for logging and telemetry.
multicast
Multicast membership and sending options beyond std’s: joining by interface name for IPv4 and IPv6 alike, source-specific membership, the sending interface, hop limit and loopback, and on Linux, keeping groups the socket never joined out of it.
nic
Network interface statistics and tuning, the programmatic equivalent of ethtool -S/-i/-g/-G/-c/-C/-a/-A/-l/-L and ip -s link.
noise
Real-time noise telemetry: what rtla osnoise, rtla timerlat and rtla hwnoise measure, as a background thread that hands aggregated numbers to a sink for the length of a run.
options
Real-time setup as a list of options, for crates built on fast-talker that let their users pick the setup.
plan
Declarative interface setup, applied at startup and checked for drift afterwards.
py
Python conversions for the options types, for extension modules that take real-time setup from Python.
rt
Real-time process and thread setup: CPU placement, scheduling priority, memory residency and timer/idle behaviour.
sockets
Per-socket queue depth, buffer use and drops: ss -uamn / ss -tamn (netstat -an on macOS and Windows) as an API.
sys_check
Read-only checks of the kernel, CPU isolation, frequency, idle and power settings, services that would undo interrupt placement, and whether this process is allowed to do the setup (Check::privileges).
tcp
TCP with receive, send and acknowledgement timestamps, and connection health.

Structs§

Config
Socket timestamping options.
Received
One received datagram.
Sent
One datagram sent with Timestamped::send_to or Timestamped::send.
SocketError
An error the network or the local stack reported for a datagram this socket sent, from Timestamped::socket_errors or sockets::socket_errors. Linux only.
Timestamp
When one datagram arrived or left.
Timestamped
A UDP socket whose receives report the arrival time of each datagram.
TxTimeError
A timed send the qdisc dropped, from Timestamped::txtime_errors.
TxTimestamp
When one sent datagram left, from Timestamped::tx_timestamps.

Enums§

ErrorOrigin
Where a SocketError came from.
Hardware
Whether to ask the network interface for hardware timestamps.
Source
Where a packet’s timestamp was taken. Ordered from least to most accurate, so a.max(b) is the better of two sources.
TxTime
How Timestamped::send_at treats its time.
TxTimeErrorKind
Why a timed send was dropped.

Traits§

Handle
Anything holding an open socket, on every platform.
Socket
A datagram socket Timestamped can drive.

Type Aliases§

RawSocket
A socket’s raw handle: a file descriptor on unix, a SOCKET on Windows.