Struct TransientSource

pub struct TransientSource<T> { /* private fields */ }

Available on crate feature wayland and Linux only.

A TransientSource wraps a Calloop event source and manages its registration. A user of this type only needs to perform the usual Calloop calls (process_events() and *register()) and the return value of process_events().

Rather than needing to check for the full set of PostAction values returned from process_events(), you can just check for Continue or Reregister and pass that back out through your own process_events() implementation. In your registration functions, you then only need to call the same function on this type ie. register() inside register() etc.

For example, say you have a source that contains a channel along with some other logic. If the channel’s sending end has been dropped, it needs to be removed from the loop. So to manage this, you use this in your struct:

struct CompositeSource {
   // Event source for channel.
   mpsc_receiver: TransientSource<calloop::channel::Channel<T>>,

   // Any other fields go here...
}

To create the transient source, you can simply use the Into implementation:

let (sender, source) = channel();
let mpsc_receiver: TransientSource<Channel> = source.into();

(If you want to start off with an empty TransientSource, you can just use Default::default() instead.)

TransientSource implements EventSource and passes through process_events() calls, so in the parent’s process_events() implementation you can just do this:

fn process_events<F>(
    &mut self,
    readiness: calloop::Readiness,
    token: calloop::Token,
    callback: F,
) -> Result<calloop::PostAction, Self::Error>
where
    F: FnMut(Self::Event, &mut Self::Metadata) -> Self::Ret,
{
    let channel_return = self.mpsc_receiver.process_events(readiness, token, callback)?;

    // Perform other logic here...

    Ok(channel_return)
}

Note that:

• You can call process_events() on the TransientSource<Channel> even if the channel has been unregistered and dropped. All that will happen is that you won’t get any events from it.

• The PostAction returned from process_events() will only ever be PostAction::Continue or PostAction::Reregister. You will still need to combine this with the result of any other sources (transient or not).

Once you return channel_return from your process_events() method (and assuming it propagates all the way up to the event loop itself through any other event sources), the event loop might call reregister() on your source. All your source has to do is:

fn reregister(
    &mut self,
    poll: &mut calloop::Poll,
    token_factory: &mut calloop::TokenFactory,
) -> crate::Result<()> {
    self.mpsc_receiver.reregister(poll, token_factory)?;

    // Other registration actions...

    Ok(())
}

The TransientSource will take care of updating the registration of the inner source, even if it actually needs to be unregistered or initially registered.

Replacing or removing TransientSources

Not properly removing or replacing TransientSources can cause spurious wakeups of the event loop, and in some cases can leak file descriptors or fail to free entries in Calloop’s internal data structures. No unsoundness or undefined behaviour will result, but leaking file descriptors can result in errors or panics.

If you want to remove a source before it returns PostAction::Remove, use the TransientSource::remove() method. If you want to replace a source with another one, use the TransientSource::replace() method. Either of these may be called at any time during processing or from outside the event loop. Both require either returning PostAction::Reregister from the process_event() call that does this, or reregistering the event source some other way eg. via the top-level loop handle.

If, instead, you directly assign a new source to the variable holding the TransientSource, the inner source will be dropped before it can be unregistered. For example:

self.mpsc_receiver = Default::default();
self.mpsc_receiver = new_channel.into();

Implementations

impl<T> TransientSource<T>

pub fn map<F, U>(&mut self, f: F) -> Option<U>

where F: FnOnce(&mut T) -> U,

Apply a function to the enclosed source, if it exists and is not about to be removed.

pub fn is_none(&self) -> bool

Returns true if there is no wrapped event source.

pub fn remove(&mut self)

Removes the wrapped event source from the event loop and this wrapper.

If this is called from outside of the event loop, you will need to wake up the event loop for any changes to take place. If it is called from within the event loop, you must return PostAction::Reregister from your own event source’s process_events(), and the source will be unregistered as needed after it exits.

pub fn replace(&mut self, new: T)

Replace the currently wrapped source with the given one. No more events will be generated from the old source after this point. The old source will not be dropped immediately, it will be kept so that it can be deregistered.

If this is called from outside of the event loop, you will need to wake up the event loop for any changes to take place. If it is called from within the event loop, you must return PostAction::Reregister from your own event source’s process_events(), and the sources will be registered and unregistered as needed after it exits.

Trait Implementations

impl<T> Debug for TransientSource<T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Default for TransientSource<T>

where T: Default,

fn default() -> TransientSource<T>

Returns the “default value” for a type.

impl<T> EventSource for TransientSource<T>

where T: EventSource,

type Event = <T as EventSource>::Event

The type of events generated by your source.

type Metadata = <T as EventSource>::Metadata

Some metadata of your event source

type Ret = <T as EventSource>::Ret

The return type of the user callback

type Error = <T as EventSource>::Error

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

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

where F: FnMut(<TransientSource<T> as EventSource>::Event, &mut <TransientSource<T> as EventSource>::Metadata) -> <TransientSource<T> as EventSource>::Ret,

Process any relevant events

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

Register yourself to this poll instance

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

Re-register your file descriptors

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

Unregister your file descriptors

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

fn before_sleep(&mut self) -> Result<Option<(Readiness, Token)>, Error>

Notification that a single poll is about to begin

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

impl<T> From<T> for TransientSource<T>

where T: EventSource,

fn from(source: T) -> TransientSource<T>

Converts to this type from the input type.