[−][src]Trait gaea::event::Sink

pub trait Sink {
    fn capacity_left(&self) -> Capacity;

    fn add(&mut self, event: Event);

    fn extend<I>(&mut self, events: I)
    where
        I: Iterator<Item = Event>,
    { ... }
}

An event sink to which events can be added.

event::Sink is passed as an argument to poll and will be used to receive any new readiness events received since the last poll. Usually, a single event::Sink is created and reused on each call to poll.

See poll for more documentation on polling.

Why a trait?

A possible question that might arise is: "why is this a trait and not a concrete type?" The answer is flexibility. Previously it was a vector, but most users actually have there own data structure with runnable processes, green threads, Futures, etc. This meant that event::Sink was often an intermediate storage used to receive events only to mark processes as runnable and run them later.

Using a trait removes the need for this intermediate storage and allows users to direct mark processes as runnable inside there own data structure.

Examples

An implementation of event::Sink for an array.

use gaea::{event, Event, Queue, Ready, poll};

const EVENTS_SIZE: usize = 32;

/// Our `event::Sink` implementation.
struct MyEvents([Option<Event>; EVENTS_SIZE]);

impl event::Sink for MyEvents {
    fn capacity_left(&self) -> event::Capacity {
        let limit = self.0.iter().position(Option::is_some).unwrap_or(EVENTS_SIZE);
        event::Capacity::Limited(limit)
    }

    fn add(&mut self, event: Event) {
        let index = self.0.iter().position(Option::is_none).unwrap();
        self.0[index] = Some(event);
    }
}

// An event source, with some events.
let mut queue = Queue::new();
let event1 = Event::new(event::Id(0), Ready::READABLE);
queue.add(event1);
let event2 = Event::new(event::Id(1), Ready::WRITABLE);
queue.add(event2);

// Poll the source.
let mut events = MyEvents([None; EVENTS_SIZE]);
poll(&mut [&mut queue], &mut events, None)?;
assert_eq!(events.0[0], Some(event1));
assert_eq!(events.0[1], Some(event2));

Required methods

fn capacity_left(&self) -> Capacity

Capacity left in the event sink.

This must return the available capacity left, not total capacity.

Notes

If this returns Capacity::Limited and the capacity left is incorrect it may cause missing events.

fn add(&mut self, event: Event)

Add a single event.

Loading content...

Provided methods

fn extend<I>(&mut self, events: I) where
    I: Iterator<Item = Event>, 

Extend with multiple events.

Loading content...

Implementations on Foreign Types

impl<'a, ES> Sink for &'a mut ES where
    ES: Sink, [src]

impl Sink for Vec<Event>[src]

Loading content...

Implementors

Loading content...