tlbmc/g3doc/components/scheduler.md

# TaskScheduler Engine

<!--*
# Document freshness: For more information, see go/fresh-source.
freshness: { owner: 'tlbmc-dev' reviewed: '2026-08-17' }
*-->

## Purpose & Overview

The `TaskScheduler` is a high-precision asynchronous task scheduling engine
managing concurrent event execution, recurring sensor polling, and background
collector tasks over a dedicated `boost::asio::io_context` thread
(`async_executor_thread_`). It utilizes an `executor_work_guard` to maintain
continuous event loop execution regardless of active task volume.

## Core Classes

### `TaskScheduler`

The central orchestrator managing the dedicated execution thread and supervising
active tasks via a thread-safe registry (`id_to_async_tasks_`).

#### `TaskScheduler::Options`

Defines default operational thresholds:

*   `cleanup_tasks_period`: The interval for background eviction checks,
    defaulting to **10 seconds** (kept at this duration to avoid overloading the
    scheduling loop).
*   `default_task_timeout`: The maximum duration allowed before a task is
    considered unresponsive, defaulting to **60 seconds** (aligning with
    standard client-side Redfish request timeouts).

### `Task`

Wraps a single scheduled action's execution state around an underlying
`boost::asio::steady_timer`.

*   **`Run()`**: Executes the assigned task payload and updates internal
    timestamps (`last_run_time`, `wait_times`).
*   **`ScheduleNextRun()`**: Arms the `steady_timer` for the next iteration. It
    calculates expiration delay by deducting previous execution overhead
    (`last_execution_duration_`) from the base period.
*   **`OnDone()` (Task Completion & Acknowledgement)**: Periodic tasks require
    explicit invocation of the `OnDone()` acknowledgement callback upon
    completing their work. This signals execution termination, triggers the
    calculation of `last_execution_duration_`, and ensures the subsequent
    iteration is scheduled correctly to maintain precise periodicity.
*   **`Cancel()`**: Flags the task as cancelled (`cancelled_ = true`) and aborts
    active timer operations.
*   **`SetPeriod()`**: Cancels current waits and dynamically adjusts the
    scheduling interval (`period_`).

### `TimeInfo`

Captures granular timing diagnostics:

*   `last_scheduled_time`: Timestamp when the next execution was scheduled.
*   `last_run_time`: Timestamp of the most recent execution completion.
*   `wait_times`: A circular buffer logging historical execution latencies.

## Execution & Scheduling APIs

*   **`ScheduleAsync()`**: Schedules a recurring task (`TaskMode::kPeriodic`)
    with an initial delay matching the target period
    (`ExecutionMode::kRunAfterScheduling`).
*   **`RunAndScheduleAsync()`**: Triggers initial execution immediately
    (`ExecutionMode::kRunImmediately`), and then schedules subsequent recurring
    executions based on the period.
*   **`ScheduleOneShotAsync()`**: Schedules a task to run exactly once
    (`TaskMode::kOnce`) after the specified delay. Its internal completion
    handler automatically invokes cancellation upon execution.

## Inactive Task Eviction & Metrics

### `CleanupInactiveTasks()`

Runs periodically to track execution timestamps exceeding task timeouts and
purging dangling tasks. By comparing elapsed time since `last_run_time` against
configured task timeouts, it evicts stalled operations (`Cancel()`).

### `GetSchedulingAccuracyPercentage()`

Evaluates timing precision by computing task lateness ratios:

*   Compares each task's `average_wait_time` against its assigned `period`.
*   Applies a proportional inaccuracy penalty for durations exceeding the target
    window.
*   Aggregates these values across the task population to return a high-level
    scheduling accuracy metric (0% to 100%).

## Code References

*   Header:
    [scheduler.h](http://google3/third_party/milotic/external/cc/tlbmc/scheduler/scheduler.h)
*   Implementation:
    [scheduler.cc](http://google3/third_party/milotic/external/cc/tlbmc/scheduler/scheduler.cc)