diff --git a/include/dpp/cluster.h b/include/dpp/cluster.h index d3cfc3b693..988b9e54b9 100644 --- a/include/dpp/cluster.h +++ b/include/dpp/cluster.h @@ -52,6 +52,12 @@ namespace dpp { +/** + * @brief Pass this value into the constructor of dpp::cluster for the shard count to create a cluster with no shards. + * A cluster with no shards does not connect to a websocket, but can still use the event loop to dispatch HTTPS API + * requests to Discord. This is useful for bots that do not need to receive websocket events as it will save a lot of + * resources. + */ constexpr uint32_t NO_SHARDS = ~0U; /** diff --git a/include/dpp/sslclient.h b/include/dpp/sslclient.h index 3fe1c4c0db..896a60baf5 100644 --- a/include/dpp/sslclient.h +++ b/include/dpp/sslclient.h @@ -256,6 +256,7 @@ class DPP_EXPORT ssl_client /** * @brief Connect to a specified host and port. Throws std::runtime_error on fatal error. + * @param creator Creating cluster * @param _hostname The hostname to connect to * @param _port the Port number to connect to * @param plaintext_downgrade Set to true to connect using plaintext only, without initialising SSL. diff --git a/include/dpp/thread_pool.h b/include/dpp/thread_pool.h index 54a498c868..724ce24a54 100644 --- a/include/dpp/thread_pool.h +++ b/include/dpp/thread_pool.h @@ -30,17 +30,35 @@ namespace dpp { +/** + * @brief A work unit is a lambda executed in the thread pool + */ using work_unit = std::function; /** - * A task within a thread pool. A simple lambda that accepts no parameters and returns void. + * @brief A task within a thread pool. A simple lambda that accepts no parameters and returns void. */ struct DPP_EXPORT thread_pool_task { + /** + * @brief Task priority, lower value is higher priority + */ int priority; + /** + * @brief Work unit to execute as the task + */ work_unit function; }; +/** + * @brief Compares two thread pool tasks by priority + */ struct DPP_EXPORT thread_pool_task_comparator { + /** + * @brief Compare two tasks + * @param a first task + * @param b second task + * @return true if a > b + */ bool operator()(const thread_pool_task &a, const thread_pool_task &b) const { return a.priority > b.priority; }; @@ -51,10 +69,30 @@ struct DPP_EXPORT thread_pool_task_comparator { * into a queue, which is processed in-order by whichever thread is free. */ struct DPP_EXPORT thread_pool { + + /** + * @brief Threads that comprise the thread pool + */ std::vector threads; + + /** + * @brief Priority queue of tasks to be executed + */ std::priority_queue, thread_pool_task_comparator> tasks; + + /** + * @brief Mutex for accessing the priority queue + */ std::mutex queue_mutex; + + /** + * @brief Condition variable to notify for new tasks to run + */ std::condition_variable cv; + + /** + * @brief True if the thread pool is due to stop + */ bool stop{false}; /** @@ -63,7 +101,16 @@ struct DPP_EXPORT thread_pool { * @param num_threads number of threads in the pool */ explicit thread_pool(class cluster* creator, size_t num_threads = std::thread::hardware_concurrency()); + + /** + * @brief Destroy the thread pool + */ ~thread_pool(); + + /** + * @brief Enqueue a new task to the thread pool + * @param task task to enqueue + */ void enqueue(thread_pool_task task); }; diff --git a/include/dpp/timer.h b/include/dpp/timer.h index 8896288ffe..b5c9827ddf 100644 --- a/include/dpp/timer.h +++ b/include/dpp/timer.h @@ -75,7 +75,16 @@ struct DPP_EXPORT timer_t { timer_callback_t on_stop{}; }; +/** + * @brief Used to compare two timers next tick times in a priority queue + */ struct DPP_EXPORT timer_comparator { + /** + * @brief Compare two timers + * @param a first timer + * @param b second timer + * @return returns true if a > b + */ bool operator()(const timer_t &a, const timer_t &b) const { return a.next_tick > b.next_tick; }; diff --git a/include/dpp/wsclient.h b/include/dpp/wsclient.h index e7fc875d0a..9380d2d072 100644 --- a/include/dpp/wsclient.h +++ b/include/dpp/wsclient.h @@ -179,6 +179,7 @@ class DPP_EXPORT websocket_client : public ssl_client { /** * @brief Connect to a specific websocket server. + * @param creator Creating cluster * @param hostname Hostname to connect to * @param port Port to connect to * @param urlpath The URL path components of the HTTP request to send