Trait calloop::EventSource
source · 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<'_>) { ... }
}
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 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.
Required Associated Types§
sourcetype Metadata
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.
Provided Associated Constants§
sourceconst NEEDS_EXTRA_LIFECYCLE_EVENTS: bool = false
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 Methods§
sourcefn process_events<F>(
&mut self,
readiness: Readiness,
token: Token,
callback: F,
) -> Result<PostAction, Self::Error>
fn process_events<F>( &mut self, readiness: Readiness, token: Token, callback: F, ) -> Result<PostAction, Self::Error>
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.
sourcefn register(
&mut self,
poll: &mut Poll,
token_factory: &mut TokenFactory,
) -> Result<()>
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.
sourcefn reregister(
&mut self,
poll: &mut Poll,
token_factory: &mut TokenFactory,
) -> Result<()>
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.
sourcefn unregister(&mut self, poll: &mut Poll) -> Result<()>
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§
sourcefn before_sleep(&mut self) -> Result<Option<(Readiness, Token)>>
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
sourcefn before_handle_events(&mut self, events: EventIterator<'_>)
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§
Implementations on Foreign Types§
source§impl<T: EventSource> EventSource for &mut T
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>
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<()>
const NEEDS_EXTRA_LIFECYCLE_EVENTS: bool = T::NEEDS_EXTRA_LIFECYCLE_EVENTS
fn before_sleep(&mut self) -> Result<Option<(Readiness, Token)>>
fn before_handle_events(&mut self, events: EventIterator<'_>)
source§impl<T: EventSource> EventSource for Box<T>
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.