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:

Classes
struct	completed_request
	A completed request. Contains both the request and the response. More...
struct	queued_deleting_request
	A request queued for deletion in the queue. More...

Public Member Functions
	request_queue (class cluster *owner, uint32_t request_threads=8)
	constructor More...
request_queue &	add_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_queue &	post_request (std::unique_ptr< http_request > req)
	Put a http_request into the request queue. 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 cluster *	creator
	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< completed_request >	responses_out
	Completed requests queue. More...
std::vector< std::unique_ptr< 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::vector< queued_deleting_request >	responses_to_delete
	Completed requests to delete. Sorted by deletion time. More...
std::atomic< 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

owner	The creating cluster.
request_threads	The 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_threads

Number 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

(

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 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<std::unique_ptr<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<completed_request> dpp::request_queue::responses_out

protected

Completed requests queue.

responses_to_delete

std::vector<queued_deleting_request> dpp::request_queue::responses_to_delete

protected

Completed requests to delete. Sorted by deletion time.

terminating

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

protected

Set to true if the threads should terminate.