Struct Driver 

pub struct Driver { /* private fields */ }

A completion-style I/O driver for one thread. See the module docs.

A driver is not Send: create it on the thread that runs it (io_uring’s single-issuer mode requires that). Its Waker is Send + Sync.

Implementations

impl Driver

pub fn new(cfg: &DriverConfig) -> Result<Driver>

Creates a driver. With Backend::IoUring it probes the kernel and falls back to epoll when io_uring is missing, disabled or too old (Driver::fallback_reason says why). Asking for a back end this OS doesn’t have is an Unsupported error.

pub fn backend(&self) -> Backend

The back end in use.

pub fn fallback_reason(&self) -> Option<&str>

Why the requested back end was replaced, if it was, or which of its optional features the kernel lacks (io_uring set-up flags or registered files, each dropped on its own).

pub fn waker(&self) -> Waker

A handle that wakes this driver from any thread.

pub fn listen(&mut self, socket: Socket, key: u64) -> Result<Id>

Registers a listening socket and starts accepting on it. Accepted connections arrive as Event::Accepted with key.

pub fn stream(&mut self, socket: Socket, key: u64) -> Result<Id>

Registers a connected, non-blocking stream socket. Nothing is received until Driver::recv turns receiving on.

pub fn udp(&mut self, socket: Socket, key: u64) -> Result<Id>

Registers a bound UDP socket. Datagrams arrive as Event::Datagram once Driver::recv turns receiving on.

pub fn udp_large( &mut self, socket: Socket, key: u64, buf_size: usize, ) -> Result<Id>

Registers a bound UDP socket that receives into buf_size-byte buffers of the driver’s own (instead of the stock given with Driver::provide), for a socket with GRO on: a buffer then takes a whole batch of datagrams (up to 64 KiB, cut by RecvMeta::segment_size). Give the buffers of its Event::Datagrams back with Driver::provide; the driver keeps a few for reuse.

pub fn recv(&mut self, id: Id, on: bool)

Turns receiving on or off for a stream or UDP socket. Turning it off is backpressure: the driver stops taking data, so the kernel’s receive window closes. A few Data events already under way may still arrive after it is turned off.

pub fn send(&mut self, id: Id, buf: OutBuf)

Queues a buffer to send on a stream. It is written at the start of the next turn, after everything queued before it.

pub fn send_to(&mut self, id: Id, msgs: &[Transmit<'_>]) -> Result<usize>

Sends datagrams on a UDP socket at once, without queueing. Returns how many were handed to the kernel; WouldBlock means the socket buffer is full and nothing was sent.

pub fn close(&mut self, id: Id)

Closes a socket. Queued and in-flight sends are discarded (their buffers come back as Event::Sent), then Event::Closed is reported. Flush first for a graceful close.

pub fn socket(&self, id: Id) -> Option<&Socket>

The socket behind id, for addresses and options.

pub fn provide(&mut self, buf: Vec<u8>)

Gives the driver a receive buffer (an empty Vec with spare capacity). The driver keeps it until data arrives and then hands it back in an event. A buffer of the size given to Driver::udp_large goes back to the large stock.

pub fn buffers_wanted(&self) -> usize

How many more receive buffers the driver would like (to reach its target stock).

pub fn set_buffer_target(&mut self, n: usize)

Sets how many receive buffers the driver keeps in stock (io_uring: at most the ring size).

pub fn flush_now(&mut self, id: Id)

Writes a stream’s queued output now, where that costs no extra system call (epoll and kqueue write each socket with its own call anyway; io_uring batches its submissions and IOCP posts them, so there this does nothing). The results come with the next turn (K4).

pub fn trim_buffers(&mut self, keep: usize)

Frees spare receive buffers down to keep and lets the stock grow again from small (an idle loop after a burst; buffers lent to an io_uring ring stay).

pub fn turn( &mut self, timeout: Option<Duration>, out: &mut Vec<Event>, ) -> Result<()>

Flushes queued sends, waits for I/O up to timeout (None waits until something happens or a Waker fires; zero only polls) and appends what happened to out. Returns at once when events are already pending.

pub fn stats(&self) -> DriverStats

System call and event counters.

pub fn len(&self) -> usize

Registered sockets (listeners, streams and UDP sockets, including ones closing).

pub fn is_empty(&self) -> bool

Whether no socket is registered.

Trait Implementations

impl Debug for Driver

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.