Struct ResponseFuture 

pub struct ResponseFuture<T>(/* private fields */);

Future that completes when a Response is received.

Rate limits

Requests that exceed a rate limit are automatically and immediately retried until they succeed or fail with another error. If configured without a RateLimiter, care must be taken that an external service intercepts and delays these retry requests.

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::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.

Implementations

impl<T> ResponseFuture<T>

pub fn set_pre_flight<P>(&mut self, predicate: P) -> bool

where P: Fn() -> bool + Send + 'static,

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::{Client, error::ErrorType};
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(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.