Trait EventSource

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

    const NEEDS_EXTRA_LIFECYCLE_EVENTS: bool = false;

    // 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 before_sleep(&mut self) -> Result<Option<(Readiness, Token)>> { ... }
    fn before_handle_events(&mut self, events: EventIterator<'_>) { ... }
}

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 NEEDS_EXTRA_LIFECYCLE_EVENTS to true. For all sources for which that constant is true, the methods before_sleep and before_handle_events will be called. before_sleep is called before the polling system performs a poll operation. before_handle_events is called before any process_events methods have been called. This means that during process_events you can assume that all cleanup has occured on all sources.

Provided Associated Constants

const NEEDS_EXTRA_LIFECYCLE_EVENTS: bool = false

Whether this source needs to be sent the EventSource::before_sleep and EventSource::before_handle_events notifications. These are opt-in because they require more expensive checks, and almost all sources will not need these notifications

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 before_sleep(&mut self) -> Result<Option<(Readiness, Token)>>

Notification that a single poll is about to begin

Use this to perform operations which must be done before polling, but which may conflict with other event handlers. For example, if polling requires a lock to be taken

If this returns Ok(Some), this will be treated as an event arriving in polling, and your event handler will be called with the returned Token and Readiness. Polling will however still occur, but with a timeout of 0, so additional events from this or other sources may also be handled in the same iterations. The returned Token must belong to this source

fn before_handle_events(&mut self, events: EventIterator<'_>)

Notification that polling is complete, and EventSource::process_events will be called with the given events for this source. The iterator may be empty, which indicates that no events were generated for this source

Please note, the iterator excludes any synthetic events returned from EventSource::before_sleep

Use this to perform a cleanup before event handlers with arbitrary code may run. This could be used to drop a lock obtained in EventSource::before_sleep

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.

const NEEDS_EXTRA_LIFECYCLE_EVENTS: bool = T::NEEDS_EXTRA_LIFECYCLE_EVENTS

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 before_sleep(&mut self) -> Result<Option<(Readiness, Token)>>

fn before_handle_events(&mut self, events: EventIterator<'_>)

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.

const NEEDS_EXTRA_LIFECYCLE_EVENTS: bool = T::NEEDS_EXTRA_LIFECYCLE_EVENTS

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 before_sleep(&mut self) -> Result<Option<(Readiness, Token)>>

fn before_handle_events(&mut self, events: EventIterator<'_>)

Implementors

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: AsFd, E: Into<Box<dyn Error + Send + Sync>>,

type Event = Readiness

type Metadata = NoIoDrop<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