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

pub trait Source<ES, E> where
    ES: Sink, {
    fn max_timeout(&self) -> Option<Duration>;

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

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

A readiness event source that can be polled for events.

Implementing event source

The trait has two generic parameters: ES and E. ES must implement event::Sink, this should always be a generic parameter to ensure that any event sink can be used with the event source. E should also remain generic but a trait bound From<MyError> should be added, this way poll can return a single error from multiple event sources. The example below shows how this works.

use std::time::Duration;

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

/// Our event source that implements `event::Source`.
struct MyEventSource(Vec<Event>);

/// The error returned by our even source implementation.
struct SourceError;

impl<ES, E> event::Source<ES, E> for MyEventSource
    where ES: event::Sink, // We keep the event sink generic to support all
                           // kinds of event sinks.
          E: From<SourceError>, // We add this bound to allow use to convert
                                // `SourceError` into the generic error `E`.
{
    fn max_timeout(&self) -> Option<Duration> {
        if !self.0.is_empty() {
            // If we have an event ready we don't want to block.
            Some(Duration::from_millis(0))
        } else {
            // If we don't have any events we don't have a preference about
            // blocking times.
            None
        }
    }

    fn poll(&mut self, event_sink: &mut ES) -> Result<(), E> {
        match poll_events(event_sink) {
            Ok(()) => Ok(()),
            // We need explicitly call `into()` to convert our error into
            // the generic error. Note that this isn't required when using
            // `?` (the try operator).
            Err(err) => Err(err.into()),
        }
    }
}

#[derive(Debug)]
struct MyError;

// Implementing `From` for `MyError` allows us to use it as an error in our call
// to poll below.
impl From<SourceError> for MyError {
    fn from(_err: SourceError) -> MyError {
        MyError
    }
}

// Now we can use our event source with `MyError` as error type.
let mut my_source = MyEventSource(Vec::new());
let mut events = Vec::new();
poll(&mut [&mut my_source], &mut events, None)

Required methods

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

The duration until the next event will be available.

This is used by poll to determine what timeout to use in a blocking call. For example if we have a queue of timers, of which the next one expires in one second, we don't want to block for more then one second and thus we should return Some(1 second) to ensure that. Otherwise we'll overrun the timer by nine seconds.

If the duration until the next available event is unknown None should be returned.

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

Poll for readiness events.

Any available readiness events must be added to event_sink. This method may not block.

Some implementation of event::Sinks have a limited available capacity. This method may not add more events then event::Sink::capacity_left returns, iff it returns a capacity limit. Available events that don't fit in the event sink in a single call to poll should remain in the source and should be added to the event sink in future calls to poll.

Loading content...

Provided methods

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

A blocking poll for readiness events.

This is the same as Source::poll and all requirements of that method apply to this method as well. Different to poll is that this method may block up to timeout duration, if one is provided, or block forever if no timeout is provided (assuming something wakes up the poll source).

The default implementation simply calls poll, thus it doesn't actually block.

Loading content...

Implementations on Foreign Types

impl<S, ES, E, '_> Source<ES, E> for &'_ mut S where
    S: Source<ES, E>,
    ES: Sink, [src]

Loading content...

Implementors

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

impl<ES, E> Source<ES, E> for Queue where
    ES: Sink, [src]

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

impl<ES, E> Source<ES, E> for Timers where
    ES: Sink, [src]

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

Loading content...