Struct twilight_standby::Standby
source · pub struct Standby { /* private fields */ }
Expand description
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§
source§impl Standby
impl Standby
sourcepub fn new() -> Self
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
.
sourcepub fn process(&self, event: &Event) -> ProcessResults
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.
sourcepub fn wait_for<F: Fn(&Event) -> bool + Send + Sync + 'static>(
&self,
guild_id: Id<GuildMarker>,
check: impl Into<Box<F>>
) -> WaitForGuildEventFuture ⓘ
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.
sourcepub fn wait_for_stream<F: Fn(&Event) -> bool + Send + Sync + 'static>(
&self,
guild_id: Id<GuildMarker>,
check: impl Into<Box<F>>
) -> WaitForGuildEventStream
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.
sourcepub fn wait_for_event<F: Fn(&Event) -> bool + Send + Sync + 'static>(
&self,
check: impl Into<Box<F>>
) -> WaitForEventFuture ⓘ
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.
sourcepub fn wait_for_event_stream<F: Fn(&Event) -> bool + Send + Sync + 'static>(
&self,
check: impl Into<Box<F>>
) -> WaitForEventStream
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.
sourcepub fn wait_for_message<F: Fn(&MessageCreate) -> bool + Send + Sync + 'static>(
&self,
channel_id: Id<ChannelMarker>,
check: impl Into<Box<F>>
) -> WaitForMessageFuture ⓘ
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.
sourcepub fn wait_for_message_stream<F: Fn(&MessageCreate) -> bool + Send + Sync + 'static>(
&self,
channel_id: Id<ChannelMarker>,
check: impl Into<Box<F>>
) -> WaitForMessageStream
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.
sourcepub fn wait_for_reaction<F: Fn(&ReactionAdd) -> bool + Send + Sync + 'static>(
&self,
message_id: Id<MessageMarker>,
check: impl Into<Box<F>>
) -> WaitForReactionFuture ⓘ
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.
sourcepub fn wait_for_reaction_stream<F: Fn(&ReactionAdd) -> bool + Send + Sync + 'static>(
&self,
message_id: Id<MessageMarker>,
check: impl Into<Box<F>>
) -> WaitForReactionStream
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.
sourcepub fn wait_for_component<F: Fn(&Interaction) -> bool + Send + Sync + 'static>(
&self,
message_id: Id<MessageMarker>,
check: impl Into<Box<F>>
) -> WaitForComponentFuture ⓘ
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?;
sourcepub fn wait_for_component_stream<F: Fn(&Interaction) -> bool + Send + Sync + 'static>(
&self,
message_id: Id<MessageMarker>,
check: impl Into<Box<F>>
) -> WaitForComponentStream
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());
}