Executing functions on the event loop
=====================================

If you need to execute a function in the context of the event loop (for example to execute it
synchronously with any callbacks or data reception) you can either use a signal or a timer. A
signal will be executed once, while a timer will be executed periodically.


Signal
------

Signals can be created using the :cpp:func:`exec<FelixClientThreadInterface::exec>` function. It
takes a callback which is going to be executed in the context of the event loop once picked up by
the event loop. The :cpp:type:`callback<FelixClientThreadInterface::UserFunction>` takes no
arguments and returns void.

.. doxygenfunction:: FelixClientThreadInterface::exec
  :no-link:
  :outline:

.. doxygentypedef:: FelixClientThreadInterface::UserFunction
  :no-link:
  :outline:


Timer
-----

Timers are sightly more involved: First you set the callback using the
:cpp:func:`callback_on_user_timer<FelixClientThreadExtension423::callback_on_user_timer>` function,
then you can start the timer using the
:cpp:func:`user_timer_start<void FelixClientThreadExtension520::user_timer_start(std::chrono::milliseconds interval)>`
function and stop it using the :cpp:func:`user_timer_stop<FelixClientThreadExtension423::user_timer_stop>`
function. The callback takes no arguments and returns void. Only one timer can be set at a time.

.. doxygenfunction:: FelixClientThreadExtension423::callback_on_user_timer
  :no-link:
  :outline:

.. doxygenfunction:: FelixClientThreadExtension520::user_timer_start(std::chrono::milliseconds interval)
  :no-link:
  :outline:

.. doxygenfunction:: FelixClientThreadExtension423::user_timer_stop
  :no-link:
  :outline:

.. doxygentypedef:: FelixClientThreadInterface::OnUserTimerCallback
  :no-link:
  :outline:


Deprecated API
--------------

Calling :cpp:func:`user_timer_start<void FelixClientThreadExtension423::user_timer_start(unsigned long interval)>`
with an integer value is deprecated. Use the overload taking a ``std::chrono::milliseconds`` instead.


Example
-------

.. code-block:: cpp
  :linenos:

  // Create a signal
  client.exec([]() { std::println("Hello from the event loop!"); });

  // Create a timer
  client.callback_on_user_timer([]() { std::println("I should be printed every second!");});
  client.user_timer_start(1000ms);