D++ (DPP)
C++ Discord API Bot Library
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...

+ Collaboration diagram for dpp::request_queue:

Public Member Functions

 request_queue (class cluster *owner, uint32_t request_threads=8)
 constructor More...
 
request_queueadd_request_threads (uint32_t request_threads)
 Add more request threads to the library at runtime. More...
 
uint32_t get_request_thread_count () const
 Get the request thread count. More...
 
 ~request_queue ()
 Destroy the request queue object. Side effects: Joins and deletes queue threads. More...
 
request_queuepost_request (http_request *req)
 Put a http_request into the request queue. You should ALWAYS "new" an object to pass to here – don't submit an object that's on the stack! More...
 
bool is_globally_ratelimited () const
 Returns true if the bot is currently globally rate limited. More...
 

Protected Member Functions

void out_loop ()
 Outbound queue thread loop. More...
 

Protected Attributes

class clustercreator
 The cluster that owns this request_queue. More...
 
std::shared_mutex out_mutex
 Outbound queue mutex thread safety. More...
 
std::thread * out_thread
 Outbound queue thread Note that although there are many 'in queues', which handle the HTTP requests, there is only ever one 'out queue' which dispatches the results to the caller. This is to simplify thread management in bots that use the library, as less mutexing and thread safety boilerplate is required. More...
 
std::condition_variable out_ready
 Outbound queue condition. Signalled when there are requests completed to call callbacks for. More...
 
std::queue< std::pair< http_request_completion_t *, http_request * > > responses_out
 Completed requests queue. More...
 
std::vector< in_thread * > requests_in
 A vector of inbound request threads forming a pool. There are a set number of these defined by a constant in queues.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 thread 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 threads in the pool. These are few and far between. More...
 
std::multimap< time_t, std::pair< http_request_completion_t *, http_request * > > responses_to_delete
 Completed requests to delete. More...
 
bool terminating
 Set to true if the threads should terminate. More...
 
bool globally_ratelimited
 True if globally rate limited - makes the entire request thread wait. More...
 
uint64_t globally_limited_for
 How many seconds we are globally rate limited for. More...
 
uint32_t in_thread_pool_size
 Number of request threads in the thread pool. More...
 

Friends

class in_thread
 Required so in_thread can access these member variables. More...
 

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 two threads, one to make outbound HTTP requests and push the returned results into a queue, and the second to call the callback methods with these results. They are separated so that 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().

Constructor & Destructor Documentation

◆ request_queue()

dpp::request_queue::request_queue ( class cluster owner,
uint32_t  request_threads = 8 
)

constructor

Parameters
ownerThe creating cluster.
request_threadsThe number of http request threads to allocate to the threadpool. By default eight threads are allocated. Side effects: Creates threads for the queue

◆ ~request_queue()

dpp::request_queue::~request_queue ( )

Destroy the request queue object. Side effects: Joins and deletes queue threads.

Member Function Documentation

◆ add_request_threads()

request_queue& dpp::request_queue::add_request_threads ( uint32_t  request_threads)

Add more request threads to the library at runtime.

Note
You should do this at a quiet time when there are few requests happening. This will reorganise the hashing used to place requests into the thread pool so if you do this while the bot is busy there is a small chance of receiving "429 rate limited" errors.
Parameters
request_threadsNumber of threads to add. It is not possible to scale down at runtime.
Returns
reference to self

◆ get_request_thread_count()

uint32_t dpp::request_queue::get_request_thread_count ( ) const

Get the request thread count.

Returns
uint32_t number of request threads 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

◆ out_loop()

void dpp::request_queue::out_loop ( )
protected

Outbound queue thread loop.

◆ post_request()

request_queue& dpp::request_queue::post_request ( http_request req)

Put a http_request into the request queue. You should ALWAYS "new" an object to pass to here – don't submit an object that's on the stack!

Note
Will use a simple hash function to determine which of the 'in queues' to place this request onto.
Parameters
reqrequest to add
Returns
reference to self

Friends And Related Function Documentation

◆ in_thread

friend class in_thread
friend

Required so in_thread can access these member variables.

Member Data Documentation

◆ creator

class cluster* dpp::request_queue::creator
protected

The cluster that owns this request_queue.

◆ globally_limited_for

uint64_t dpp::request_queue::globally_limited_for
protected

How many seconds we are globally rate limited for.

Note
Only if globally_ratelimited is true.

◆ globally_ratelimited

bool dpp::request_queue::globally_ratelimited
protected

True if globally rate limited - makes the entire request thread wait.

◆ in_thread_pool_size

uint32_t dpp::request_queue::in_thread_pool_size
protected

Number of request threads in the thread pool.

◆ out_mutex

std::shared_mutex dpp::request_queue::out_mutex
protected

Outbound queue mutex thread safety.

◆ out_ready

std::condition_variable dpp::request_queue::out_ready
protected

Outbound queue condition. Signalled when there are requests completed to call callbacks for.

◆ out_thread

std::thread* dpp::request_queue::out_thread
protected

Outbound queue thread Note that although there are many 'in queues', which handle the HTTP requests, there is only ever one 'out queue' which dispatches the results to the caller. This is to simplify thread management in bots that use the library, as less mutexing and thread safety boilerplate is required.

◆ requests_in

std::vector<in_thread*> dpp::request_queue::requests_in
protected

A vector of inbound request threads forming a pool. There are a set number of these defined by a constant in queues.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 thread 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 threads in the pool. These are few and far between.

◆ responses_out

std::queue<std::pair<http_request_completion_t*, http_request*> > dpp::request_queue::responses_out
protected

Completed requests queue.

◆ responses_to_delete

std::multimap<time_t, std::pair<http_request_completion_t*, http_request*> > dpp::request_queue::responses_to_delete
protected

Completed requests to delete.

◆ terminating

bool dpp::request_queue::terminating
protected

Set to true if the threads should terminate.

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