Struct gaea::os::OsQueue

pub struct OsQueue { /* fields omitted */ }

Readiness event queue backed by the OS.

This queue allows a program to monitor a large number of Evented handles, waiting until one or more become "ready" for some class of operations; e.g. reading or writing. An Evented type is considered ready if it is possible to immediately perform a corresponding operation; e.g. read or write.

To use this queue an Evented handle must first be registered using the register method, supplying an associated id, readiness interests and polling option. The associated id is used to associate a readiness event with an Evented handle. The readiness interests defines which specific operations on the handle to monitor for readiness. And the final argument, RegisterOption, defines how to deliver the readiness events, see RegisterOption for more information.

See to module documentation for information.

Methods

impl OsQueue

pub fn new() -> Result<OsQueue>

Create a new OS backed readiness event queue.

This function will make a syscall to the operating system to create the system selector. If this syscall fails it will return the error.

Examples

use std::io;
use std::time::Duration;

use gaea::os::OsQueue;
use gaea::poll;

// Create a new OS backed readiness event queue.
let mut os_queue = OsQueue::new()?;

// Create an event sink.
let mut events = Vec::new();

// Poll the queue for new readiness events.
// But since no `Evented` handles have been registered we'll receive no
// events.
poll::<_, io::Error>(&mut [&mut os_queue], &mut events, Some(Duration::from_millis(500)))?;

pub fn register<E: ?Sized>(
    &mut self,
    handle: &mut E,
    id: Id,
    interests: Interests,
    opt: RegisterOption
) -> Result<()> where
    E: Evented, 

Register an Evented handle with the OsQueue.

Once registered, the Evented handle will be monitored for readiness state changes. When it notices a state change, it will return a readiness event for the handle the next time the queue is polled.

Arguments

handle: This is the handle that the OsQueue should monitor for readiness state changes.

id: The caller picks a id to associate with the handle. When poll returns an event for the handle, this id is included. This allows the caller to map the event to its handle. The id associated with the Evented handle can be changed at any time by calling reregister.

interests: Specifies which operations OsQueue should monitor for readiness. OsQueue will only return readiness events for operations specified by this argument. If a socket is registered with readable interests and the socket becomes writable, no event will be returned from poll. The readiness interests for an Evented handle can be changed at any time by calling reregister. Most types that implemented Evented have a associated constant named INTERESTS which provide a sane interest for that type, e.g. TcpStream interests are readable and writable.

opt: Specifies the registration option. Just like the interests and id, the option can be changed for an Evented handle at any time by calling reregister.

Notes

Unless otherwise specified, the caller should assume that once an Evented handle is registered with a OsQueue instance, it is bound to that OsQueue for the lifetime of the Evented handle. This remains true even if the Evented handle is deregistered.

Examples

use std::io;

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

// Create a new `OsQueue` as well a containers for the events.
let mut os_queue = OsQueue::new()?;
let mut events = Vec::new();

// Create a TCP connection. `TcpStream` implements the `Evented` trait.
let address = "216.58.193.100:80".parse()?;
let mut stream = TcpStream::connect(address)?;

// Register the connection with queue.
os_queue.register(&mut stream, event::Id(0), TcpStream::INTERESTS, RegisterOption::EDGE)?;

// Run the event loop.
loop {
    poll::<_, io::Error>(&mut [&mut os_queue], &mut events, None)?;

    for event in events.drain(..) {
        if event.id() == event::Id(0) {
            // The TCP connection is (likely) ready for use.
        }
    }
}

pub fn reregister<E: ?Sized>(
    &mut self,
    handle: &mut E,
    id: Id,
    interests: Interests,
    opt: RegisterOption
) -> Result<()> where
    E: Evented, 

Re-register an Evented handle with OsQueue.

Re-registering an Evented handle allows changing the details of the registration. Specifically, it allows updating the associated id, interests, and opt specified in previous register and reregister calls.

The reregister arguments fully override the previous values. In other words, if a socket is registered with readable interest and the call to reregister specifies only writable, then read interest is no longer monitored for the handle.

The Evented handle must have previously been registered with this OsQueue otherwise the call to reregister may return an error.

See the register documentation for details about the function arguments.

Examples

use std::io;

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

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

// Create a TCP connection. `TcpStream` implements the `Evented` trait.
let address = "216.58.193.100:80".parse()?;
let mut stream = TcpStream::connect(address)?;

// Register the connection with `OsQueue`, only with readable interest.
os_queue.register(&mut stream, event::Id(0), Interests::READABLE, RegisterOption::EDGE)?;

// Reregister the connection specifying a different id and write interest
// instead. `RegisterOption::EDGE` must be specified even though that value
// is not being changed.
os_queue.reregister(&mut stream, event::Id(2), Interests::WRITABLE, RegisterOption::EDGE)?;

// Run the event loop.
loop {
    poll::<_, io::Error>(&mut [&mut os_queue], &mut events, None)?;

    for event in events.drain(..) {
        if event.id() == event::Id(2) {
            // The TCP connection is (likely) ready for use.
        } else if event.id() == event::Id(0) {
            // We won't receive events with the old id anymore.
            unreachable!();
        }
    }
}

pub fn deregister<E: ?Sized>(&mut self, handle: &mut E) -> Result<()> where
    E: Evented, 

Deregister an Evented handle from OsQueue.

When an Evented handle is deregistered, the handle will no longer be monitored for readiness state changes. Unlike disabling handles with oneshot, deregistering clears up any internal resources needed to track the handle.

A handle can be registered again using register after it has been deregistered; however, it must be passed back to the same OsQueue.

Notes

Calling reregister after deregister may be work on some platforms but not all. To properly re-register a handle after deregistering use register, this works on all platforms.

Examples

use std::io;
use std::time::Duration;

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

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

// Create a TCP connection. `TcpStream` implements the `Evented` trait.
let address = "216.58.193.100:80".parse()?;
let mut stream = TcpStream::connect(address)?;

// Register the connection with `OsQueue`.
os_queue.register(&mut stream, event::Id(0), TcpStream::INTERESTS, RegisterOption::EDGE)?;

// Do stuff with the connection etc.

// Deregister it so the resources can be cleaned up.
os_queue.deregister(&mut stream)?;

// Set a timeout because we shouldn't receive any events anymore.
poll::<_, io::Error>(&mut [&mut os_queue], &mut events, Some(Duration::from_millis(100)))?;
assert!(events.is_empty());

Trait Implementations

impl<ES, E> Source<ES, E> for OsQueue where
    ES: Sink,
    E: From<Error>, 

fn max_timeout(&self) -> Option<Duration>

The duration until the next event will be available.

fn poll(&mut self, event_sink: &mut ES) -> Result<(), E>

Poll for readiness events.

fn blocking_poll(
    &mut self,
    event_sink: &mut ES,
    timeout: Option<Duration>
) -> Result<(), E>

A blocking poll for readiness events.

impl Debug for OsQueue

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

Formats the value using the given formatter.