.. _ex_cpu_st:

tmc::ex_cpu_st
-----------------------------------------------------------------------------------
``ex_cpu_st`` is a single-threaded executor. It behaves the same as an ``ex_cpu`` with ``.set_thread_count(1)``.
However, it has better round-trip latency and better internal execution performance,
as it does not need the thread tracking and synchronization systems that are present in the multi-threaded executor.

This single-threaded executor may be useful to manage communication with certain systems that require all calls to come from the same thread (e.g. SDL/OpenGL).

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_``.

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

.. code-block:: cpp

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

  int main() {
    // Run async_main on the global (multi-threaded) ex_cpu
    tmc::cpu_executor().init();
    return tmc::async_main([]() -> tmc::task<int> {
    
      // Configure and run a single-threaded executor
      tmc::ex_cpu_st single_threaded_exec;
      single_threaded_exec.init();
    
      // This child task will be executed on single_threaded_exec
      co_await tmc::spawn(some_task()).run_on(single_threaded_exec);
      // After it completes, the main task will resume back on the global ex_cpu

      co_return 0;
    }());
  }

API Reference
-----------------------------------------------------------------------------------
.. doxygenclass:: tmc::ex_cpu_st
   :members: