Trait calloop::EventSource

source · [−]
pub trait EventSource {
    type Event;
    type Metadata;
    type Ret;
    type Error: Into<Box<dyn Error + Sync + Send>>;

    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,
    { ... }
}
Expand description

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

The type of events generated by your source.

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.

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.

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

Required Methods

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.

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.

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.

Unregister your file descriptors

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

Provided Methods

Notification that a polling session is going to start

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

Notification that the current polling session ended

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

Implementations on Foreign Types

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

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

Implementors