Module gaea::os

Operating System backed readiness event queue.

OsQueue provides an abstraction over platform specific Operating System backed readiness event queues, such as kqueue or epoll.

Portability

Using OsQueue provides a portable interface across supported platforms as long as the caller takes the following into consideration:

Draining readiness

When using edge-triggered mode, once a readiness event is received, the corresponding operation must be performed repeatedly until it returns WouldBlock. Unless this is done, there is no guarantee that another readiness event will be delivered, even if further data is received for the Evented handle. See RegisterOption for more.

Spurious events

The Source::poll implementation may return readiness events even if the associated Evented handle is not actually ready. Given the same code, this may happen more on some platforms than others. It is important to never assume that, just because a readiness notification was received, that the associated operation will as well.

If operation fails with a WouldBlock error, then the caller should not treat this as an error and wait until another readiness event is received.

Furthermore a single call to poll may result in multiple readiness events being returned for a single Evented handle. For example, if a TCP socket becomes both readable and writable, it may be possible for a single readiness event to be returned with both readable and writable readiness OR two separate events may be returned, one with readable set and one with writable set.

Registering handles

Unless otherwise noted, it should be assumed that types implementing Evented will never become ready unless they are registered with OsQueue.

For example:

use std::thread;
use std::time::Duration;

use gaea::event;
use gaea::net::TcpStream;
use gaea::os::{OsQueue, RegisterOption};

let address = "216.58.193.100:80".parse()?;
let mut stream = TcpStream::connect(address)?;

// This actually does nothing towards connecting the TCP stream.
thread::sleep(Duration::from_secs(1));

let mut os_queue = OsQueue::new()?;

// The connect is not guaranteed to have started until it is registered at
// this point.
os_queue.register(&mut stream, event::Id(0), TcpStream::INTERESTS, RegisterOption::EDGE)?;

Timeout granularity

The timeout provided to event::Source::blocking_poll will be rounded up to the system clock granularity (usually 1ms), and kernel scheduling delays mean that the blocking interval may be overrun by a small amount.

Interrupts while polling

Interrupts (EINTR in C and io::ErrorKind::Interrupted in Rust) are not handled, they are returned as errors. In most cases however these can simply be ignored, but it's up to the user how to deal with the "error".

Implementation notes

OsQueue is backed by a readiness event queue provided by the operating system. On all platforms a call to Source::poll is mostly just a direct system call. The following system implementations back OsQueue:

OS	Selector
FreeBSD	kqueue
Linux	epoll
macOS	kqueue
NetBSD	kqueue
OpenBSD	kqueue

On all supported platforms socket operations are handled by using the system queue. Platform specific extensions (e.g. EventedFd) allow accessing other features provided by individual system selectors.

Re-exports

pub use self::signals::Signal;

pub use self::signals::SignalSet;

pub use self::signals::Signals;

Modules

signals

Module for handling signals.

Structs

Awakener	Awakener allows cross-thread waking of OsQueue.
Interests	Interests supplied when registering an Evented handle with OsQueue.
OsQueue	Readiness event queue backed by the OS.
RegisterOption	Option supplied when registering an Evented handle with OsQueue.

Traits

Evented

A handle that may be registered with OsQueue.