diff --git a/include/osquery/dispatcher.h b/include/osquery/dispatcher.h index 6e8977d0..2050713a 100644 --- a/include/osquery/dispatcher.h +++ b/include/osquery/dispatcher.h @@ -15,60 +15,143 @@ namespace osquery { -// kDefaultThreadPoolSize represents the amount of threads that the thread pool -// will be created with if not otherwise specified +/// The amount of threads that the thread pool will be created with if another +/// value is not specified on the command-line. extern const int kDefaultThreadPoolSize; -// Dispatcher is a singleton that exposes the osqueryd work dispatcher and -// thread -// pool +/// Dispatcher is a singleton which can be used to coordinate the parallel +/// execution of asynchronus tasks across an application. Interally, Dispatcher +/// is back by the Apache Thrift thread pool. class Dispatcher { public: - // getInstance returns a singleton instance of Dispatcher. + /// @brief the primary way to access the Dispatcher singleton. + /// + /// osquery::Dispatcher::getInstance() provides access to the Dispatcher + /// singleton. + /// + /// \code{.cpp} + /// auto dispatch = osquery::Dispatcher::getInstance(); + /// \endcode + /// + /// @retern a shared pointer to an instance of osquery::Dispatch. static std::shared_ptr getInstance(); - // add a task to the dispatcher + /// @brief add a task to the dispatcher. + /// + /// Adding tasks to the Dispatcher's thread pool requires you to create a + /// "runnable" class which publicly implements Apache Thrift's Runnable + /// class. Create a shared pointer to the class and you're all set to + /// schedule work. + /// + /// \code{.cpp} + /// class TestRunnable : public apache::thrift::concurrency::Runnable { + /// public: + /// int* i; + /// TestRunnable(int* i) : i(i) {} + /// virtual void run() { ++*i; } + /// }; + /// + /// auto dispatch = osquery::Dispatcher::getInstance(); + /// int i = 5; + /// dispatch->add(std::make_shared(&i); + /// while (dispatch->totalTaskCount() > 0) {} + /// assert(i == 6); + /// \endcode + /// + /// @param task a C++11 std shared pointer to an instance of a class which + /// publically inherrits from `apache::thrift::concurrency::Runnable`. + /// + /// @return an instance of osquery::Status, indicating the success or failure + /// of the operation. Status add(std::shared_ptr task); - // getter for the thread manager instance. + /// @brief Getter for the underlying thread manager instance. + /// + /// Use this getter if you'd like to perform some operations which the + /// Dispatcher API doesn't support, but you are certain are supported by the + /// backing Apache Thrift thread manager. + /// + /// Use this method with caution, as it only exists to allow developers to + /// iterate quickly in the event that the pragmatic decision to access the + /// underlying thread manager has been determined to be neccessary. + /// + /// \code{.cpp} + /// auto t = osquery::Dispatcher::getInstance()->getThreadManager(); + /// \endcode + /// + /// @return a shared pointer to the Apache Thrift `ThreadManager` instance + /// which is currently being used to orchestrate multi-threaded operations. std::shared_ptr getThreadManager(); - // Joins the thread manager. This is the same as stop, except that it will - // block until all the workers have finished their work. At that point - // the ThreadManager will transition into the STOPPED state. + /// @brief Joins the thread manager. + /// + /// This is the same as stop, except that it will block until all the workers + /// have finished their work. At that point the ThreadManager will transition + /// into the STOPPED state. void join(); - // get the current state of the thread manager + /// @brief Get the current state of the thread manager. + /// + /// @return an Apache Thrift STATE enum. apache::thrift::concurrency::ThreadManager::STATE state() const; - // add a worker thread + /// @brief Add a worker thread. + /// + /// Use this method to add an additional thread to the thread pool. + /// + /// @param value is a size_t indicating how many additional worker threads + /// should be added to the thread group. If not parameter is supplied, one + /// worker thread is added. + /// + /// @see osquery::Dispatcher::removeWorker void addWorker(size_t value = 1); - // remove a worker thread + /// @brief Remove a worker thread. + /// + /// Use this method to remove a thread from the thread pool. + /// + /// @param value is a size_t indicating how many additional worker threads + /// should be removed from the thread group. If not parameter is supplied, + /// one worker thread is removed. + /// + /// @see osquery::Dispatcher::addWorker void removeWorker(size_t value = 1); - // Gets the current number of idle worker threads + /// @brief Gets the current number of idle worker threads. + /// + /// @return the number of idle worker threads. size_t idleWorkerCount() const; - // Gets the current number of total worker threads + /// @brief Gets the current number of total worker threads. + /// + /// @return the current number of total worker threads. size_t workerCount() const; - // Gets the current number of pending tasks + /// @brief Gets the current number of pending tasks. + /// + /// @return the current number of pending tasks. size_t pendingTaskCount() const; - // Gets the current number of pending and executing tasks + /// @brief Gets the current number of pending and executing tasks. + /// + /// @return the current number of pending and executing tasks. size_t totalTaskCount() const; - // Gets the maximum pending task count. 0 indicates no maximum + /// @brief Gets the maximum pending task count. 0 indicates no maximum. + /// + /// @return the maximum pending task count. 0 indicates no maximum. size_t pendingTaskCountMax() const; - // Gets the number of tasks which have been expired without being run. + /// @brief Gets the number of tasks which have been expired without being + /// run. + /// + /// @return he number of tasks which have been expired without being run. size_t expiredTaskCount() const; private: - // since instances of Dispatcher should only be created via getInstance(), - // Dispatcher's constructor is private + /// since instances of Dispatcher should only be created via getInstance(), + /// Dispatcher's constructor is private. Dispatcher(); private: