Module trace 

Tracing

The trace feature enables a number of callbacks that can be used to track the lifecycle of tasks and/or executors.

The passed IDs are only guaranteed to be unique for the duration of time the item is valid. If a task ends, and is re-spawned, it MAY or MAY NOT have the same ID. While a task is active, the id will not change. For executors, the same applies, but the IDs will be stable for practical embedded programs.

Callbacks can be used by enabling the trace feature, implementing the Trace trait, and registering the implementation with the trace_impl! macro. All callbacks must be implemented.

Task Tracing lifecycle

┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
       │(1)                                            │
│      │
  ╔════▼════╗ (2) ┌─────────┐ (3) ┌─────────┐          │
│ ║ SPAWNED ║────▶│ WAITING │────▶│ RUNNING │
  ╚═════════╝     └─────────┘     └─────────┘          │
│                 ▲         ▲     │    │    │
                  │           (4)      │    │(6)       │
│                 │(7)      └ ─ ─ ┘    │    │
                  │                    │    │          │
│             ┌──────┐             (5) │    │  ┌─────┐
              │ IDLE │◀────────────────┘    └─▶│ END │ │
│             └──────┘                         └─────┘
  ┌──────────────────────┐                             │
└ ┤ Task Trace Lifecycle │─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  └──────────────────────┘

1. A task is spawned, task_new is called
2. A task is enqueued for the first time, task_ready_begin is called
3. A task is polled, task_exec_begin is called
4. WHILE a task is polled, the task is re-awoken, and task_ready_begin is called. The task does not IMMEDIATELY move state, until polling is complete and the RUNNING state is exited. task_exec_end is called when polling is complete, marking the transition to WAITING
5. Polling is complete, task_exec_end is called
6. The task has completed, and task_end is called
7. A task is awoken, task_ready_begin is called

Executor Tracing lifecycle

┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
      │(1)                                             │
│     │
  ╔═══▼══╗   (2)     ┌────────────┐  (3)  ┌─────────┐  │
│ ║ IDLE ║──────────▶│ SCHEDULING │──────▶│ POLLING │
  ╚══════╝           └────────────┘       └─────────┘  │
│     ▲              │            ▲            │
      │      (5)     │            │  (4)       │       │
│     └──────────────┘            └────────────┘
  ┌──────────────────────────┐                         │
└ ┤ Executor Trace Lifecycle │─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  └──────────────────────────┘

1. The executor is started (no associated trace)
2. A task on this executor is awoken. task_ready_begin is called when this occurs, and poll_start is called when the executor actually begins running
3. The executor has decided a task to poll. task_exec_begin is called
4. The executor finishes polling the task. task_exec_end is called
5. The executor has finished polling tasks. executor_idle is called

Idle

executor_idle only means that a single executor has run out of work. With multiple executors (e.g. a thread-mode executor plus one or more interrupt executors), an interrupt executor going idle returns to the preempted lower-priority context, which keeps running. The current thread/core is only idle when its thread-mode executor reaches its sleep site, at which point idle is called. In multi-core chips, or when using threads under std or an RTOS, this does not mean the entire system is idle.

Traits

Trace

Executor trace hooks.