Trait calloop::EventSource

pub trait EventSource {
    type Event;
    type Metadata;
    type Ret;
    type Error: Into<Box<dyn Error + Sync + Send>>;

    // Required methods
    fn process_events<F>(
        &mut self,
        readiness: Readiness,
        token: Token,
        callback: F
    ) -> Result<PostAction, Self::Error>
       where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret;
    fn register(
        &mut self,
        poll: &mut Poll,
        token_factory: &mut TokenFactory
    ) -> Result<()>;
    fn reregister(
        &mut self,
        poll: &mut Poll,
        token_factory: &mut TokenFactory
    ) -> Result<()>;
    fn unregister(&mut self, poll: &mut Poll) -> Result<()>;

    // Provided methods
    fn pre_run<F>(&mut self, _callback: F) -> Result<()>
       where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret { ... }
    fn post_run<F>(&mut self, _callback: F) -> Result<()>
       where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret { ... }
}

Trait representing an event source

This is the trait you need to implement if you wish to create your own calloop-compatible event sources.

The 3 associated types define the type of closure the user will need to provide to process events for your event source.

The process_events method will be called when one of the FD you registered is ready, with the associated readiness and token.

The register, reregister and unregister methods are plumbing to let your source register itself with the polling system. See their documentation for details.

In case your event source needs to do some special processing before or after a polling session occurs (to prepare the underlying source for polling, and cleanup after that), you can override the pre_run and post_run, that do nothing by default. Depending on the underlying events, process_events may be invoked once, several times, or none at all between pre_run and post_run are called, but when it is invoked, it’ll always be between those two.

Required Associated Types

type Event

The type of events generated by your source.

type Metadata

Some metadata of your event source

This is typically useful if your source contains some internal state that the user may need to interact with when processing events. The user callback will receive a &mut Metadata reference.

Set to () if not needed.

type Ret

The return type of the user callback

If the user needs to return some value back to your event source once its processing is finshed (to indicate success or failure for example), you can specify it using this type.

Set to () if not needed.

type Error: Into<Box<dyn Error + Sync + Send>>

The error type returned from process_events() (not the user callback!).

Required Methods

fn process_events<F>( &mut self, readiness: Readiness, token: Token, callback: F ) -> Result<PostAction, Self::Error>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

Process any relevant events

This method will be called every time one of the FD you registered becomes ready, including the readiness details and the associated token.

Your event source will then do some processing of the file descriptor(s) to generate events, and call the provided callback for each one of them.

You should ensure you drained the file descriptors of their events, especially if using edge-triggered mode.

fn register( &mut self, poll: &mut Poll, token_factory: &mut TokenFactory ) -> Result<()>

Register yourself to this poll instance

You should register all your relevant file descriptors to the provided Poll using its Poll::register method.

If you need to register more than one file descriptor, you can change the sub_id field of the Token to differentiate between them.

fn reregister( &mut self, poll: &mut Poll, token_factory: &mut TokenFactory ) -> Result<()>

Re-register your file descriptors

Your should update the registration of all your relevant file descriptor to the provided Poll using its Poll::reregister, if necessary.

fn unregister(&mut self, poll: &mut Poll) -> Result<()>

Unregister your file descriptors

You should unregister all your file descriptors from this Poll using its Poll::unregister method.

Provided Methods

fn pre_run<F>(&mut self, _callback: F) -> Result<()>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

Notification that a polling session is going to start

You can generate events from this method as you would from process_events.

fn post_run<F>(&mut self, _callback: F) -> Result<()>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

Notification that the current polling session ended

You can generate events from this method as you would from process_events.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<T: EventSource> EventSource for &mut T

Blanket implementation for exclusive references to event sources. EventSource is not an object safe trait, so this does not include trait objects.

type Event = <T as EventSource>::Event

type Metadata = <T as EventSource>::Metadata

type Ret = <T as EventSource>::Ret

type Error = <T as EventSource>::Error

fn process_events<F>( &mut self, readiness: Readiness, token: Token, callback: F ) -> Result<PostAction, Self::Error>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

fn register( &mut self, poll: &mut Poll, token_factory: &mut TokenFactory ) -> Result<()>

fn reregister( &mut self, poll: &mut Poll, token_factory: &mut TokenFactory ) -> Result<()>

fn unregister(&mut self, poll: &mut Poll) -> Result<()>

fn pre_run<F>(&mut self, callback: F) -> Result<()>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

fn post_run<F>(&mut self, callback: F) -> Result<()>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

impl<T: EventSource> EventSource for Box<T>

Blanket implementation for boxed event sources. EventSource is not an object safe trait, so this does not include trait objects.

type Event = <T as EventSource>::Event

type Metadata = <T as EventSource>::Metadata

type Ret = <T as EventSource>::Ret

type Error = <T as EventSource>::Error

fn process_events<F>( &mut self, readiness: Readiness, token: Token, callback: F ) -> Result<PostAction, Self::Error>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

fn register( &mut self, poll: &mut Poll, token_factory: &mut TokenFactory ) -> Result<()>

fn reregister( &mut self, poll: &mut Poll, token_factory: &mut TokenFactory ) -> Result<()>

fn unregister(&mut self, poll: &mut Poll) -> Result<()>

fn pre_run<F>(&mut self, callback: F) -> Result<()>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

fn post_run<F>(&mut self, callback: F) -> Result<()>

where F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,

Implementors

impl EventSource for Signals

type Event = Event

type Metadata = ()

type Ret = ()

type Error = SignalError

impl EventSource for Timer

type Event = Instant

type Metadata = ()

type Ret = TimeoutAction

type Error = Error

impl<F, E> EventSource for Generic<F, E>

where F: AsRawFd, E: Into<Box<dyn Error + Send + Sync>>,

type Event = Readiness

type Metadata = F

type Ret = Result<PostAction, E>

type Error = E

impl<T> EventSource for Channel<T>

type Event = Event<T>

type Metadata = ()

type Ret = ()

type Error = ChannelError

impl<T: EventSource> EventSource for TransientSource<T>

type Event = <T as EventSource>::Event

type Metadata = <T as EventSource>::Metadata

type Ret = <T as EventSource>::Ret

type Error = <T as EventSource>::Error