.. _aw_enter_exit:

Advanced - enter()/exit()
-----------------------------------------------------------------------------------
When ``tmc::enter(Executor)`` is called, the task will be resumed on Executor, and it will return a scope object that captures the current executor and priority.
This can be used to later ``exit()`` the scope and return to the previous executor and priority.

.. code-block:: cpp

  // assume we start on the cpu executor here
  auto scope = co_await tmc::enter(other_exec);
  // do something on the other executor
  co_await scope.exit();
  // we are back on the cpu executor now, with our original priority

Further customizations can be applied to the ``enter()`` and ``exit()`` calls.

The ``enter()`` awaitable supports :literal_ref:`with_priority()<with_priority>`.
The ``exit()`` awaitable supports :literal_ref:`resume_on()<resume_on>` and :literal_ref:`with_priority()<with_priority>`.

Examples:

.. code-block:: cpp

  // assume we start on the cpu executor here, at priority 0
  auto scope = co_await tmc::enter(other_exec).with_priority(1);
  // we are now running on other_exec, at priority 1
  co_await scope.exit().resume_on(third_exec).with_priority(2);
  // we are now running on third_exec, at priority 2

API Reference
-----------------------------------------------------------------------------------
.. doxygenfunction:: tmc::enter(E&)
.. doxygenfunction:: tmc::enter(E*)

.. doxygenclass:: tmc::aw_ex_scope_enter
  :members:
   
.. doxygenclass:: tmc::aw_ex_scope_exit
  :members: