Struct twilight_standby::Standby

pub struct Standby(_);

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.

Cloning

Standby internally wraps its data within an Arc. This means that standby can be cloned and passed around tasks and threads cheaply.

Implementations

impl Standby

pub fn new() -> Self

Create a new instance of Standby.

pub fn process(&self, event: &Event)

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

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: GuildId,
    check: impl Into<Box<F>>
) -> WaitForGuildEventFuture

Wait for an event in a certain guild.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::{EventType, Event},
    id::GuildId,
};
use twilight_standby::Standby;

let standby = Standby::new();

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

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

Wait for a stream of events in a certain guild.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::{EventType, Event},
    id::GuildId,
};
use twilight_standby::Standby;

let standby = Standby::new();

let mut stream = standby.wait_for_stream(GuildId(123), |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);
    }
 }

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.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::{EventType, Event};
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(|[id, _]| id == 5).unwrap_or(false)
    } else {
        false
    }
}).await?;

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.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::{EventType, Event};
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(|[id, _]| id == 5).unwrap_or(false)
    } else {
        false
    }
});

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

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

Wait for a message in a certain channel.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::MessageCreate, id::{ChannelId, UserId}};
use twilight_standby::Standby;

let standby = Standby::new();

let message = standby.wait_for_message(ChannelId(123), |event: &MessageCreate| {
    event.author.id == UserId(456) && event.content == "test"
}).await?;

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

Wait for a stream of message in a certain channel.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::MessageCreate, id::{ChannelId, UserId}};
use twilight_standby::Standby;

let standby = Standby::new();

let mut messages = standby.wait_for_message_stream(ChannelId(123), |event: &MessageCreate| {
    event.author.id == UserId(456) && event.content == "test"
});

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

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

Wait for a reaction on a certain message.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::ReactionAdd, id::{MessageId, UserId}};
use twilight_standby::Standby;

let standby = Standby::new();

let reaction = standby.wait_for_reaction(MessageId(123), |event: &ReactionAdd| {
    event.user_id == UserId(456)
}).await?;

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

Wait for a stream of reactions on a certain message.

Returns a Canceled error if the Standby struct was dropped.

If you need 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::ReactionType,
    gateway::payload::ReactionAdd,
    id::{MessageId, UserId},
};
use twilight_standby::Standby;

let standby = Standby::new();

let mut reactions = standby.wait_for_reaction_stream(MessageId(123), |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);
}

Trait Implementations

impl Clone for Standby

pub fn clone(&self) -> Standby

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Standby

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

Formats the value using the given formatter.

impl Default for Standby

pub fn default() -> Standby

Returns the "default value" for a type.