Struct ResponseFuture

pub struct ResponseFuture<T> { /* private fields */ }

Future that will resolve to a Response.

Canceling a response future pre-flight

Response futures can be canceled pre-flight via ResponseFuture::set_pre_flight. This allows you to cancel requests that are no longer necessary once they have been cleared by the ratelimit queue, which may be necessary in scenarios where requests are being spammed. Refer to its documentation for more information.

Errors

Returns an ErrorType::Json error type if serializing the response body of the request failed.

Returns an ErrorType::Parsing error type if the request failed and the error in the response body could not be deserialized.

Returns an ErrorType::RequestCanceled error type if the request was canceled by the user.

Returns an ErrorType::RequestError error type if creating the request failed.

Returns an ErrorType::RequestTimedOut error type if the request timed out. The timeout value is configured via ClientBuilder::timeout.

Returns an ErrorType::Response error type if the request failed.

Returns an ErrorType::ServiceUnavailable error type if the Discord API is unavailable.

Implementations

impl<T> ResponseFuture<T>

pub fn set_pre_flight( &mut self, pre_flight: Box<dyn FnOnce() -> bool + Send + 'static>, ) -> bool

Set a function to call after clearing the ratelimiter but prior to sending the request to determine if the request is still valid.

This function will be a no-op if the request has failed, has already passed the ratelimiter, or if there is no ratelimiter configured.

Returns whether the pre flight function was set.

Examples

Delete a message, but immediately before sending the request check if the request should still be sent:

use std::{
    collections::HashSet,
    env,
    future::IntoFuture,
    sync::{Arc, Mutex},
};
use twilight_http::{error::ErrorType, Client};
use twilight_model::id::Id;

let channel_id = Id::new(1);
let message_id = Id::new(2);

let channels_ignored = {
    let mut map = HashSet::new();
    map.insert(channel_id);

    Arc::new(Mutex::new(map))
};

let client = Client::new(env::var("DISCORD_TOKEN")?);
let mut req = client.delete_message(channel_id, message_id).into_future();

let channels_ignored_clone = channels_ignored.clone();
req.set_pre_flight(Box::new(move || {
    // imagine you have some logic here to external state that checks
    // whether the request should still be performed
    let channels_ignored = channels_ignored_clone.lock().expect("channels poisoned");

    !channels_ignored.contains(&channel_id)
}));

// the pre-flight check will cancel the request
assert!(matches!(
    req.await.unwrap_err().kind(),
    ErrorType::RequestCanceled,
));

Trait Implementations

impl<T: Unpin> Future for ResponseFuture<T>

type Output = Result<Response<T>, Error>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.