Trait StreamExt

pub trait StreamExt: Stream {
    // Provided method
    fn next_event(
        &mut self,
        wanted_event_types: EventTypeFlags,
    ) -> NextEvent<'_, Self>
       where Self: Unpin { ... }
}

An extension trait for the [Stream] trait.

If you need utilities from multiple StreamExt traits, underscore import this one.

Provided Methods

fn next_event( &mut self, wanted_event_types: EventTypeFlags, ) -> NextEvent<'_, Self>

where Self: Unpin,

Consumes and returns the next wanted Event in the stream or None if the stream is finished.

next_event() takes a EventTypeFlags which is then passed along to parse. Unwanted event types are skipped.

Close messages are always considered wanted and map onto Event::GatewayClose.

Equivalent to:

async fn next_event(&mut self, wanted_event_types: EventTypeFlags) -> Option<Result<Event, ReceiveMessageError>>

Note that because next_event doesn’t take ownership over the stream, the [Stream] type must be Unpin. If you want to use next with a !Unpin stream, you’ll first have to pin the stream. This can be done by boxing the stream using Box::pin or pinning it to the stack using pin!.

Cancel safety

This method is cancel safe. The returned future only holds onto a reference to the underlying stream, so dropping it will never lose a value.

Example

use twilight_gateway::{Event, EventTypeFlags, StreamExt as _};

while let Some(item) = shard.next_event(EventTypeFlags::all()).await {
    let Ok(event) = item else {
        tracing::warn!(source = ?item.unwrap_err(), "error receiving event");

        continue;
    };

    match event {
        Event::Ready(_) => tracing::info!("ready!"),
        _ => {}
    }
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<St> StreamExt for St

where St: Stream<Item = Result<Message, ReceiveMessageError>> + ?Sized,