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.
| Module | What it does | Replaces | Platforms |
|---|---|---|---|
Timestamped | UDP 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 | |
tcp | TCP reads and sends with timestamps (queued, sent, acknowledged) and connection health | ss -ti | all |
nic | Interfaces and their addresses, NIC counters, rings, coalescing, flow control, queues, EEE, NAPI and IRQ placement, PTP clock offset, flow steering, ETF qdisc | ip addr, ethtool, ip -s link, tc | Linux, macOS, Windows |
counters | Kernel protocol counters with interval deltas | nstat -az | Linux, macOS, Windows |
sockets | Sockets created with their options applied before bind or connect; socket queues, buffer use and drops; socket options for latency | ss -m, setsockopt | Linux, macOS, Windows |
rt | Thread priority and CPU placement, memory residency, idle and timer control | chrt, taskset, mlockall | Linux, macOS, Windows |
irq | Interrupt affinity and handler threads | /proc/irq/* | Linux |
latency | Allocation-free latency histogram, request/reply round-trip matching | all | |
clock | A device’s own timestamps mapped to host time through receive stamps | all | |
multicast | Group membership by interface name, source-specific joins, sending interface, hops, loopback | Linux, macOS, Windows | |
monitor | Low-priority background thread feeding loss counters and TCP health to a callback | Linux, macOS, Windows | |
plan | Declarative interface configuration (TOML with serde), with drift checking | Linux, Windows; compiles on macOS, where most settings are Unsupported | |
options | Option lists a library can accept from its own users, applied per platform | Linux, macOS, Windows | |
sys_check | Read-only checks of kernel, CPU isolation, power and PTP clock sync, and of the privileges setup needs | Linux, 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
| Feature | Default | Enables |
|---|---|---|
monitor | yes | monitor (and plan, options) |
plan | yes | plan |
options | yes | options |
sys-check | yes | sys_check |
serde | no | Serialize/Deserialize for plans, options, checks and flow rules |
mio | no | mio::event::Source for Timestamped, which can wrap a mio::net::UdpSocket |
pyo3 | no | Duck-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 endsA 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),TimestampedandTimestampedStreamincluded. Code split by#[cfg(unix)]/#[cfg(windows)]only to nameAsFdorAsSocketcan be one function.multicast::Handleis nowfast_talker::Handle(still re-exported frommulticast), withraw_socket()in place ofraw(). Socketandtcp::StreamrequireHandleinstead ofAsRawFd/AsRawSocket; implementations need no change.Reporthas a new public field,adjusted. Code buildingRulesby hand for a library’s users can useRules::portable(&allow), andRules::first_rejectedorRules::checkto validate before applying.kind_name()gives an option’s snake-case name.Confighas a new field,socket_errors; struct literals need..Config::default()(orConfig::kernel_only()).- Reading transmit stamps no longer discards ICMP errors from the error
queue when
Config::socket_errorsis on; they wait forTimestamped::socket_errors. SocketOption::apply_allon an already bound socket failsWinCpuAffinitywithInvalidInputinstead of the OS’sEINVAL; create the socket withsockets::bind_udporsockets::connect_tcp.- On macOS, a
RecvBufferorSendBufferabovekern.ipc.maxsockbufis set to the limit and reported inReport::adjusted, where it could fail withENOBUFSbefore. - A type that kept a copy of a
Report’s lists to send between threads can beoptions::ReportSummary, fromReport::summary(); it converts to the same Python dict. DeviceClockholds back a packet whose offset falls more thanDeviceClock::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. Withfit_driftthe mapping follows the lower convex hull of the window minima instead of a least-squares line.to_hostmaps any timeSystemTimeholds, before 1970 and after 2554 included.nic::source_forno longer answers with the peer’s own address when connecting leaves the local address unspecified; it fails withAddrNotAvailablewhen no other address shares the peer’s subnet.- In the Python stubs, the
TypeVaris_OptionDictand the*Nameliterals are declaredTypeAlias; recopy the file. The extension module’sProcessGuard.__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-socketfrom 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 -azshows them. - irq
- Hardware interrupt affinity and handler threads: what writing
/proc/irq/<n>/smp_affinity_listand runningchrtonirq/<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/-Landip -s link. - noise
- Real-time noise telemetry: what
rtla osnoise,rtla timerlatandrtla hwnoisemeasure, 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
optionstypes, 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 -anon 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_toorTimestamped::send. - Socket
Error - An error the network or the local stack reported for a datagram this
socket sent, from
Timestamped::socket_errorsorsockets::socket_errors. Linux only. - Timestamp
- When one datagram arrived or left.
- Timestamped
- A UDP socket whose receives report the arrival time of each datagram.
- TxTime
Error - A timed send the qdisc dropped, from
Timestamped::txtime_errors. - TxTimestamp
- When one sent datagram left, from
Timestamped::tx_timestamps.
Enums§
- Error
Origin - Where a
SocketErrorcame 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_attreats its time. - TxTime
Error Kind - Why a timed send was dropped.
Traits§
- Handle
- Anything holding an open socket, on every platform.
- Socket
- A datagram socket
Timestampedcan drive.
Type Aliases§
- RawSocket
- A socket’s raw handle: a file descriptor on unix, a
SOCKETon Windows.