pollio 0.1.3

A small native event poller abstraction over epoll and kqueue
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

use crate::EventObject;
use std::io;
use std::os::fd::RawFd;

/// Platform-agnostic interface for registering file descriptors and waiting for readiness.
///
/// The concrete implementation is [`OsPoller`](crate::OsPoller), which maps to `epoll` on Linux
/// and `kqueue` on macOS.
pub trait Poller {
    /// Create a new OS poller instance.
    fn new() -> io::Result<Self>
    where
        Self: Sized;

    /// Register `event` for **read** readiness.
    ///
    /// The FD and [`EventKind`](crate::EventKind) are packed into the kernel user-data field so
    /// they round-trip when [`wait`](Self::wait) returns.
    fn add(&self, event: EventObject) -> io::Result<()>;

    /// Remove `fd` from the poller.
    fn delete(&self, fd: RawFd) -> io::Result<()>;

    /// Block until at least one registered FD is readable, or the timeout elapses.
    ///
    /// Returns a slice of ready [`EventObject`]s, backed by a buffer owned by the poller and
    /// reused across calls. An empty slice means the call timed out with no events. The slice is
    /// only valid until the next call to `wait`.
    ///
    /// # Timeout
    ///
    /// | Value | Behavior |
    /// |-------|----------|
    /// | `-1`  | Block indefinitely |
    /// | `0`   | Poll without blocking |
    /// | `> 0` | Timeout in milliseconds |
    fn wait(&mut self, timeout_ms: i32) -> io::Result<&[EventObject]>;
}