.. _ex_cpu:

tmc::ex_cpu
-----------------------------------------------------------------------------------
``ex_cpu`` is the primary executor of TooManyCooks. It provides a high-performance work-stealing thread pool with the option for multiple priority levels.

It is recommended to use a single instance of ``ex_cpu`` for general work submission across your entire application. This maximizes the efficiency of the work-stealing architecture.
However, you can create additional ``ex_cpu`` 's if your application requires it. For example, a separate single-threaded executor may be useful to process calls to certain external libraries.

You must call ``.init()`` on each executor instance before you use it. Before calling ``init()``, you may configure it by calling any of the member functions that begin with ``set_``.

A global instance of ``ex_cpu`` is available from ``tmc::cpu_executor()``.
This is provided as a convenience so that you can access the executor without needing to explicitly inject it.
However, if you don't want to use the global instance, just don't ``init()`` it, and it won't consume any resources.

Usage Example
-----------------------------------------------------------------------------------

.. code-block:: cpp

  #define TMC_IMPL
  #include "tmc/all_headers.hpp"

  int main() {
    // Configure and init the global CPU executor
    tmc::cpu_executor().set_thread_count(8).set_priority_count(1).init();

    return tmc::async_main(main_task());
  }

.. code-block:: cpp

  #define TMC_IMPL
  #include "tmc/all_headers.hpp"

  int main() {
    // Create a standalone instance of the CPU executor
    tmc::ex_cpu my_executor;
    my_executor.set_thread_count(8).set_priority_count(1).init();

    tmc::post_waitable(my_executor, main_task()).wait();
  }

API Reference
-----------------------------------------------------------------------------------
.. doxygenfunction:: tmc::cpu_executor

.. doxygenclass:: tmc::ex_cpu
   :members: