Struct twilight_standby::Standby

pub struct Standby { /* private fields */ }

The Standby struct, used by the main event loop to process events and by tasks to wait for an event.

Refer to the crate-level documentation for more information.

Using Standby in multiple tasks

To use a Standby instance in multiple tasks, consider wrapping it in an std::sync::Arc or std::rc::Rc.

Examples

Timeouts

Futures can be timed out by passing the future returned by Standby to functions such as tokio::time::timeout:

use std::time::Duration;
use twilight_model::gateway::event::{Event, EventType};
use twilight_standby::Standby;

let standby = Standby::new();
let future = standby.wait_for_event(|event: &Event| event.kind() == EventType::Ready);
let event = tokio::time::timeout(Duration::from_secs(1), future).await?;

Implementations

impl Standby

pub fn new() -> Self

Create a new instance of Standby.

Once a Standby has been created it must process gateway events via process. Awaiting an event can start via methods such as wait_for and wait_for_message_stream.

pub fn process(&self, event: &Event) -> ProcessResults

Process an event, calling any bystanders that might be waiting on it.

Returns statistics about matched Standby calls and how they were processed. For example, by using ProcessResults::matched you can determine how many calls were sent an event.

When a bystander checks to see if an event is what it’s waiting for, it will receive the event by cloning it.

This function must be called when events are received in order for futures returned by methods to fulfill.

pub fn wait_for<F: Fn(&Event) -> bool + Send + Sync + 'static>( &self, guild_id: Id<GuildMarker>, check: impl Into<Box<F>> ) -> WaitForGuildEventFuture

Wait for an event in a certain guild.

To wait for multiple guild events matching the given predicate use wait_for_stream.

Examples

Wait for a BanAdd event in guild 123:

use futures_util::future;
use twilight_model::{
    gateway::event::{Event, EventType},
    id::Id,
};
use twilight_standby::Standby;

let standby = Standby::new();

let guild_id = Id::new(123);

let reaction = standby
    .wait_for(guild_id, |event: &Event| event.kind() == EventType::BanAdd)
    .await?;

Errors

The returned future resolves to a Canceled error if the associated Standby instance is dropped.

pub fn wait_for_stream<F: Fn(&Event) -> bool + Send + Sync + 'static>( &self, guild_id: Id<GuildMarker>, check: impl Into<Box<F>> ) -> WaitForGuildEventStream

Wait for a stream of events in a certain guild.

To wait for only one guild event matching the given predicate use wait_for.

Examples

Wait for multiple BanAdd events in guild 123:

use futures_util::stream::StreamExt;
use twilight_model::{
    gateway::event::{Event, EventType},
    id::Id,
};
use twilight_standby::Standby;

let standby = Standby::new();

let guild_id = Id::new(123);

let mut stream =
    standby.wait_for_stream(guild_id, |event: &Event| event.kind() == EventType::BanAdd);

while let Some(event) = stream.next().await {
    if let Event::BanAdd(ban) = event {
        println!("user {} was banned in guild {}", ban.user.id, ban.guild_id);
    }
}

Errors

The returned stream ends when the associated Standby instance is dropped.

pub fn wait_for_event<F: Fn(&Event) -> bool + Send + Sync + 'static>( &self, check: impl Into<Box<F>> ) -> WaitForEventFuture

Wait for an event not in a certain guild. This must be filtered by an event type.

To wait for multiple events matching the given predicate use wait_for_event_stream.

Examples

Wait for a Ready event for shard 5:

use futures_util::future;
use twilight_model::gateway::event::{Event, EventType};
use twilight_standby::Standby;

let standby = Standby::new();

let ready = standby
    .wait_for_event(|event: &Event| {
        if let Event::Ready(ready) = event {
            ready.shard.map_or(false, |id| id.number() == 5)
        } else {
            false
        }
    })
    .await?;

Errors

The returned future resolves to a Canceled error if the associated Standby instance is dropped.

pub fn wait_for_event_stream<F: Fn(&Event) -> bool + Send + Sync + 'static>( &self, check: impl Into<Box<F>> ) -> WaitForEventStream

Wait for a stream of events not in a certain guild. This must be filtered by an event type.

To wait for only one event matching the given predicate use wait_for_event.

Examples

Wait for multiple Ready events on shard 5:

use futures_util::stream::StreamExt;
use twilight_model::gateway::event::{Event, EventType};
use twilight_standby::Standby;

let standby = Standby::new();

let mut events = standby.wait_for_event_stream(|event: &Event| {
    if let Event::Ready(ready) = event {
        ready.shard.map_or(false, |id| id.number() == 5)
    } else {
        false
    }
});

while let Some(event) = events.next().await {
    println!("got event with type {:?}", event.kind());
}

Errors

The returned stream ends when the associated Standby instance is dropped.

pub fn wait_for_message<F: Fn(&MessageCreate) -> bool + Send + Sync + 'static>( &self, channel_id: Id<ChannelMarker>, check: impl Into<Box<F>> ) -> WaitForMessageFuture

Wait for a message in a certain channel.

To wait for multiple messages matching the given predicate use wait_for_message_stream.

Examples

Wait for a message in channel 123 by user 456 with the content “test”:

use futures_util::future;
use twilight_model::{gateway::payload::incoming::MessageCreate, id::Id};
use twilight_standby::Standby;

let standby = Standby::new();

let author_id = Id::new(456);
let channel_id = Id::new(123);

let message = standby
    .wait_for_message(channel_id, move |event: &MessageCreate| {
        event.author.id == author_id && event.content == "test"
    })
    .await?;

Errors

The returned future resolves to a Canceled error if the associated Standby instance is dropped.

pub fn wait_for_message_stream<F: Fn(&MessageCreate) -> bool + Send + Sync + 'static>( &self, channel_id: Id<ChannelMarker>, check: impl Into<Box<F>> ) -> WaitForMessageStream

Wait for a stream of message in a certain channel.

To wait for only one message matching the given predicate use wait_for_message.

Examples

Wait for multiple messages in channel 123 by user 456 with the content “test”:

use futures_util::stream::StreamExt;
use twilight_model::{gateway::payload::incoming::MessageCreate, id::Id};
use twilight_standby::Standby;

let standby = Standby::new();

let author_id = Id::new(456);
let channel_id = Id::new(123);

let mut messages = standby.wait_for_message_stream(channel_id, move |event: &MessageCreate| {
    event.author.id == author_id && event.content == "test"
});

while let Some(message) = messages.next().await {
    println!("got message by {}", message.author.id);
}

Errors

The returned stream ends when the associated Standby instance is dropped.

pub fn wait_for_reaction<F: Fn(&ReactionAdd) -> bool + Send + Sync + 'static>( &self, message_id: Id<MessageMarker>, check: impl Into<Box<F>> ) -> WaitForReactionFuture

Wait for a reaction on a certain message.

To wait for multiple reactions matching the given predicate use wait_for_reaction_stream.

Examples

Wait for a reaction on message 123 by user 456:

use futures_util::future;
use twilight_model::{gateway::payload::incoming::ReactionAdd, id::Id};
use twilight_standby::Standby;

let standby = Standby::new();

let message_id = Id::new(123);
let user_id = Id::new(456);

let reaction = standby
    .wait_for_reaction(message_id, move |event: &ReactionAdd| {
        event.user_id == user_id
    })
    .await?;

Errors

The returned future resolves to a Canceled error if the associated Standby instance is dropped.

pub fn wait_for_reaction_stream<F: Fn(&ReactionAdd) -> bool + Send + Sync + 'static>( &self, message_id: Id<MessageMarker>, check: impl Into<Box<F>> ) -> WaitForReactionStream

Wait for a stream of reactions on a certain message.

To wait for only one reaction matching the given predicate use wait_for_reaction.

Examples

Wait for multiple reactions on message 123 with unicode reaction “🤠”:

use futures_util::stream::StreamExt;
use twilight_model::{
    channel::message::ReactionType,
    gateway::payload::incoming::ReactionAdd,
    id::Id,
};
use twilight_standby::Standby;

let standby = Standby::new();

let message_id = Id::new(123);

let mut reactions = standby.wait_for_reaction_stream(message_id, |event: &ReactionAdd| {
    matches!(&event.emoji, ReactionType::Unicode { name } if name == "🤠")
});

while let Some(reaction) = reactions.next().await {
    println!("got a reaction by {}", reaction.user_id);
}

Errors

The returned stream ends when the associated Standby instance is dropped.

pub fn wait_for_component<F: Fn(&Interaction) -> bool + Send + Sync + 'static>( &self, message_id: Id<MessageMarker>, check: impl Into<Box<F>> ) -> WaitForComponentFuture

Wait for a component on a certain message.

Returns a Canceled error if the Standby struct was dropped.

If you need to wait for multiple components matching the given predicate, use wait_for_component_stream.

Examples

Wait for a component on message 123 by user 456:

use futures_util::future;
use twilight_model::{application::interaction::Interaction, id::Id};
use twilight_standby::Standby;

let standby = Standby::new();
let message_id = Id::new(123);

let component = standby
    .wait_for_component(message_id, |event: &Interaction| {
        event.author_id() == Some(Id::new(456))
    })
    .await?;

pub fn wait_for_component_stream<F: Fn(&Interaction) -> bool + Send + Sync + 'static>( &self, message_id: Id<MessageMarker>, check: impl Into<Box<F>> ) -> WaitForComponentStream

Wait for a stream of components on a certain message.

Returns a Canceled error if the Standby struct was dropped.

If you need to wait for only one component matching the given predicate, use wait_for_component.

Examples

Wait for multiple button components on message 123 with a custom_id of “Click”:

use futures_util::stream::StreamExt;
use twilight_model::{
    application::interaction::{Interaction, InteractionData},
    id::Id,
};
use twilight_standby::Standby;

let standby = Standby::new();
let message_id = Id::new(123);

let mut components = standby.wait_for_component_stream(message_id, |event: &Interaction| {
    if let Some(InteractionData::MessageComponent(data)) = &event.data {
        data.custom_id == "Click".to_string()
    } else {
        false
    }
});

while let Some(component) = components.next().await {
    println!("got a component by {}", component.author_id().unwrap());
}

Trait Implementations

impl Debug for Standby

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

Formats the value using the given formatter.

impl Default for Standby

fn default() -> Standby

Returns the “default value” for a type.