Enum calloop::transient::TransientSource

pub enum TransientSource<T> {
    Keep(T),
    Register(T),
    Disable(T),
    Remove(T),
    None,
}

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();

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.

Variants

Keep(T)

The source should be kept in the loop.

Register(T)

The source needs to be registered with the loop.

Disable(T)

The source needs to be disabled but kept.

Remove(T)

The source needs to be removed from the loop.

None

The source has been removed from the loop and dropped (this might also be observed if there is a panic while changing states).

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. It will be appplied even if the source is ready to be removed or is disabled.

Trait Implementations

impl<T: Debug> Debug for TransientSource<T>

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

Formats the value using the given formatter.

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

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, Self::Error>

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

Process any relevant events

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

Register yourself to this poll instance

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

Re-register your file descriptors

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

Unregister your file descriptors

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

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

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

fn from(source: T) -> Self

Converts to this type from the input type.