| D++ (DPP) C++ Discord API Bot Library

Search
Loading...
Searching...
No Matches
dpp::request_queue Class Reference

The request_queue class manages rate limits and marshalls HTTP requests that have been built as http_request objects. More...

`#include <queues.h>`

Collaboration diagram for dpp::request_queue:
[legend]

## Classes

struct | completed_request
| A completed request. Contains both the request and the response. More...

## Public Member Functions

| request_queue (class cluster *owner, uint32_t request_concurrency=8)
| constructor
| ~request_queue ()
| Destroy the request queue object. Side effects: Ends and deletes concurrency timers.
size_t | get_active_request_count () const
| Returns the number of active requests on this queue.
uint32_t | get_request_queue_count () const
| Get the request queue concurrency count.
bool | is_globally_ratelimited () const
| Returns true if the bot is currently globally rate limited.
request_queue & | post_request (std::unique_ptr< http_request > req)
| Put a http_request into the request queue.

## Public Attributes

class cluster * | creator
| The cluster that owns this request_queue.
time_t | globally_limited_until
| When we are globally rate limited until (unix epoch).
std::atomic< bool > | globally_ratelimited
| True if globally rate limited.
uint32_t | in_queue_pool_size
| Number of request queues in the pool. This is the direct size of the requests_in vector.
std::vector< std::unique_ptr< request_concurrency_queue > > | requests_in
| A vector of timers forming a pool.
std::atomic< bool > | terminating
| Set to true if the timers should terminate. When this is set to true no further requests are accepted to the queues.

## Friends

class | request_concurrency_queue
| Required so request_concurrency_queue can access these member variables.

## Detailed Description

The request_queue class manages rate limits and marshalls HTTP requests that have been built as http_request objects.

It ensures asynchronous delivery of events and queueing of requests.

It will spawn multiple timers to make outbound HTTP requests and then call the callbacks of those requests on completion within the dpp::thread_pool for the cluster. If the user decides to take a long time processing a reply in their callback it won't affect when other requests are sent, and if a HTTP request takes a long time due to latency, it won't hold up user processing.

There are usually two request_queue objects in each dpp::cluster, one of which is used internally for the various REST methods to Discord such as sending messages, and the other used to support user REST calls via dpp::cluster::request(). They are separated so that the one for user requests can be specifically configured to never ever send the Discord token unless it is explicitly placed into the request, for security reasons.

## Constructor & Destructor Documentation

## ◆ request_queue()

dpp::request_queue::request_queue | ( | class cluster * | owner,
|  | uint32_t | request_concurrency = 8 )

constructor

Parameters

  owner | The creating cluster.

  request_concurrency

  The number of http request queues to allocate. Each request queue is a dpp::timer which ticks every second looking for new requests to run. The timer will hold back requests if we are waiting as to comply with rate limits. Adding a request to this class will cause the queue it is placed in to run immediately but this cannot override rate limits. By default eight concurrency queues are allocated. Side effects: Creates timers for the queue

## ◆ ~request_queue()

dpp::request_queue::~request_queue | ( |  | ) |

Destroy the request queue object. Side effects: Ends and deletes concurrency timers.

## Member Function Documentation

## ◆ get_active_request_count()

size_t dpp::request_queue::get_active_request_count | ( |  | ) | const

Returns the number of active requests on this queue.

Returns
  Total number of active requests

## ◆ get_request_queue_count()

uint32_t dpp::request_queue::get_request_queue_count | ( |  | ) | const

Get the request queue concurrency count.

Returns
  uint32_t number of request queues that are active

## ◆ is_globally_ratelimited()

bool dpp::request_queue::is_globally_ratelimited | ( |  | ) | const

Returns true if the bot is currently globally rate limited.

Returns
  true if globally rate limited

## ◆ post_request()

request_queue & dpp::request_queue::post_request | ( | std::unique_ptr< http_request > | req | ) |

Put a http_request into the request queue.

Note
  Will use a simple hash function to determine which of the 'in queues' to place this request onto.

Parameters

  req | request to add

Returns
  reference to self

## Friends And Related Symbol Documentation

## ◆ request_concurrency_queue

friend class request_concurrency_queue

friend

Required so request_concurrency_queue can access these member variables.

## Member Data Documentation

## ◆ creator

class cluster* dpp::request_queue::creator

The cluster that owns this request_queue.

## ◆ globally_limited_until

time_t dpp::request_queue::globally_limited_until

When we are globally rate limited until (unix epoch).

Note
  Only valid if globally_rate limited is true. If we are globally rate limited, queues in this class will not process requests until the current unix epoch time is greater than this time.

## ◆ globally_ratelimited

std::atomic<bool> dpp::request_queue::globally_ratelimited

True if globally rate limited.

When globally rate limited the concurrency queues associated with this request queue will not process any requests in their timers until the global rate limit expires.

## ◆ in_queue_pool_size

uint32_t dpp::request_queue::in_queue_pool_size

Number of request queues in the pool. This is the direct size of the requests_in vector.

## ◆ requests_in

std::vector<std::unique_ptr<request_concurrency_queue> > dpp::request_queue::requests_in

A vector of timers forming a pool.

There are a set number of these defined by a constant in cluster.cpp. A request is always placed on the same element in this vector, based upon its url, so that two conditions are satisfied:

1) Any requests for the same ratelimit bucket are handled by the same concurrency queue in the pool so that they do not create unnecessary 429 errors, 2) Requests for different endpoints go into different buckets, so that they may be requested in parallel A global ratelimit event pauses all timers in the pool. These are few and far between.

## ◆ terminating

std::atomic<bool> dpp::request_queue::terminating

Set to true if the timers should terminate. When this is set to true no further requests are accepted to the queues.

D++ Library version 9.0.13 D++ Library version 9.0.12 D++ Library version 9.0.11 D++ Library version 9.0.10 D++ Library version 9.0.9 D++ Library version 9.0.8 D++ Library version 9.0.7 D++ Library version 9.0.6 D++ Library version 9.0.5 D++ Library version 9.0.4 D++ Library version 9.0.3 D++ Library version 9.0.2 D++ Library version 9.0.1 D++ Library version 9.0.0 D++ Library version 1.0.2 D++ Library version 1.0.1 D++ Library version 1.0.0