.. _theory:

**********************
A bit of theory
**********************

This section explains the core concepts behind neSmiK's region annotation system.

.. _theory_nesting:

Nesting of regions
=====================

neSmiK supports two modes of region nesting. The way you structure your annotations determines which backends can properly process them.

.. _properly_nested:

Properly Nested
----------------

In properly nested mode, regions must form a strict call stack hierarchy. Each ``region_start`` must be matched by a corresponding ``region_stop`` in the reverse order of start calls.

**Example:**

.. code-block:: cpp

    nesmik::region_start("outer");
    // ... work ...
    nesmik::region_start("inner");
    // ... work ...
    nesmik::region_stop("inner");   // Must stop "inner" before "outer"
    nesmik::region_stop("outer");

This is the **recommended** mode, as it works with all backends.

.. _not_properly_nested:

Not Properly Nested
--------------------

In this mode, regions can be started and stopped in any order. Regions may overlap or be stopped in a different order than they were started.

**Example:**

.. code-block:: cpp

    nesmik::region_start("region_a");
    nesmik::region_start("region_b");
    nesmik::region_stop("region_a");  // Stops "a" while "b" is still open
    nesmik::region_stop("region_b");

.. warning::

    Not all backends support non-properly nested regions. If you encounter issues, try restructuring your annotations to use properly nested regions.