NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

Docs / Modules / Scheduler

Scheduler

The NightMare Scheduler uses one timing engine for both operator command jobs and direct C++ callbacks.

The public singleton is:

gScheduler

A job has independent dimensions:

clock
    Wall
    Monotonic

repeat
    one-shot
    recurring

target
    std::string command
    callback

scope
    MANAGED
    USER

The Scheduler itself can run in:

TASK
MANUAL

Capacity#

The current maximum number of jobs is:

Scheduler::MaxJobs == 30

IDs are global within the Scheduler and begin at 1.

Labels are unique within a scope.

This means these can coexist:

MANAGED  nm.telemetry.system
USER     nm.telemetry.system

MANAGED jobs#

C++ jobs are MANAGED by default.

Examples:

gScheduler.after("startup-check", callback, 5000);

gScheduler.everyMonotonic(
    "sensor-poll",
    callback,
    1000);

Framework jobs also use MANAGED scope.

Current examples include telemetry publication and pending identity-cleanup retry.

USER jobs#

USER jobs are created by the JOB command family.

Examples:

JOB AFTER once 5000 "PING"
JOB EVERY hourly WALL 3600 "INFO PUBLISH"

The command surface can only see USER jobs.

Therefore:

JOB LIST
JOB DELETE
JOB CLEAR

cannot enumerate or remove MANAGED jobs.

Command jobs#

A command job stores a std::string and executes it through:

handleNightMareCommand(...)

with command source:

NM_CMD_SRC_JOB

Example:

gScheduler.after(
    "reconnect",
    "NETWORK TRANSPORT SET MQTT",
    5000);

C++ command jobs default to MANAGED scope.

An explicit scope may be supplied:

gScheduler.after(
    "user-like-job",
    "PING",
    5000,
    SchedulerJobScope::USER);

Normally only the JOB command implementation should create USER jobs.

Callback jobs#

A callback is:

using SchedulerCallback = void (*)();

Supported:

void poll()
{
    // ...
}

gScheduler.timer("poll", poll, 1000);

and non-capturing lambdas:

gScheduler.timer(
    "poll",
    []() {
        // ...
    },
    1000);

Not supported:

int value = 1;

gScheduler.timer(
    "poll",
    [value]() {
        // capturing lambda: not a function pointer
    },
    1000);

Callback jobs are always MANAGED.

Exactly one execution target#

Every job must contain exactly one of:

command
callback

Never both.

Never neither.

The Scheduler rejects an invalid target configuration.

Wall clock#

Wall-clock deadlines use Unix seconds.

Use:

gScheduler.atWall(label, command, epochSeconds);
gScheduler.atWall(label, callback, epochSeconds);

Example:

gScheduler.atWall(
    "midnight-task",
    callback,
    1790000000);

Wall jobs do not execute until NightMare wall time is valid.

One-shot monotonic delay#

Use:

gScheduler.after(label, command, delayMs);
gScheduler.after(label, callback, delayMs);

Example:

gScheduler.after(
    "startup-check",
    callback,
    5000);

The deadline is calculated from the current millis() value.

Recurring wall interval#

Use:

gScheduler.everyWall(label, command, intervalSeconds);
gScheduler.everyWall(label, callback, intervalSeconds);

Example:

gScheduler.everyWall(
    "hourly",
    callback,
    3600);

The interval is in seconds.

Wall recurring jobs require valid wall time before their first due time can be established/executed.

Recurring monotonic interval#

Use:

gScheduler.everyMonotonic(label, command, intervalMs);
gScheduler.everyMonotonic(label, callback, intervalMs);

Example:

gScheduler.everyMonotonic(
    "poll",
    callback,
    1000);

The interval is in milliseconds.

timer()#

timer() is the convenience form for a recurring monotonic callback:

gScheduler.timer(
    "poll",
    callback,
    1000);

Its first execution is one interval from the time it is scheduled.

setTimeout()#

setTimeout() creates a one-shot monotonic callback with an internally generated label:

gScheduler.setTimeout(callback, 5000);

Use an explicitly labeled after() job when later removal by a stable label matters.

Persistence#

Only jobs satisfying all of these persist:

active
Wall clock
std::string command target

Therefore:

Job Persists
atWall(..., command, ...) yes
everyWall(..., command, ...) yes
after(..., command, ...) no
everyMonotonic(..., command, ...) no
any callback job no

This is intentional.

A function pointer is runtime firmware state.

A monotonic deadline only has meaning within the current boot.

Persistence file#

Persisted jobs are stored in:

/jobs.json

Each persisted job includes its scope.

Entries without a valid current scope are not imported through a backwards-compatibility path.

Storage availability#

The Scheduler initializes persistent storage through PersistentSettings.

A persisted job cannot be added while Scheduler storage is unavailable.

Runtime-only jobs can still be represented independently of persistent wall-job storage.

The Scheduler retries storage initialization periodically.

Run mode#

Start the Scheduler explicitly with:

gScheduler.begin(SchedulerRunMode::TASK);

or:

gScheduler.begin(SchedulerRunMode::MANUAL);

The first successful begin() fixes the selected mode.

A later begin() requesting the other mode fails instead of silently changing execution ownership.

Calling begin() again with the same mode is allowed.

TASK mode#

In TASK mode the Scheduler creates its own FreeRTOS task.

Current defaults are:

poll interval:   100 ms
stack size:      8192 bytes
priority:        1

The task repeatedly calls:

gScheduler.tick();

Applications using startNightMareESP() normally do not need to manage this directly.

MANUAL mode#

In MANUAL mode no Scheduler task is created.

The application must service:

gScheduler.tick();

The standard framework lifecycle already does this from:

tickNightMareESP();

when:

NM_SCHEDULER_OWN_TASK == 0

Direct tick()#

tick() is public and can also be used directly for cooperative/manual execution.

The Scheduler uses a recursive mutex plus a dispatching_ guard to prevent overlapping dispatch inside the Scheduler itself.

Choosing TASK mode and then also manually driving tick() is application-level misuse; the standard tickNightMareESP() path avoids that by only ticking in MANUAL mode.

Dispatch behavior#

At each tick, the Scheduler snapshots the highest job ID that existed when dispatch began.

Jobs created by a running callback/command are therefore not immediately executed in the same dispatch pass.

Before executing a due target, the Scheduler updates/removes the job state.

Then it temporarily releases the job lock while the command/callback runs.

This allows a callback to interact with the Scheduler without deadlocking the job table.

One-shot persisted jobs#

For a persisted one-shot wall command, removal from persisted storage happens before the target is executed.

If saving that removal fails, the live job is restored and execution is skipped so the Scheduler does not claim a persisted job was consumed when the storage record still says otherwise.

Recurring scheduling#

After a recurring job runs, the next deadline is based on the current tick time:

Wall:
    wallNow + interval

Monotonic:
    monotonicNow + interval

The Scheduler does not attempt to replay every missed interval after a long pause.

Remove#

Remove a MANAGED job by label:

gScheduler.remove("sensor-poll");

or ID:

gScheduler.remove(id);

The default scope is MANAGED.

Remove a USER job explicitly:

gScheduler.remove(
    id,
    SchedulerJobScope::USER);

For persisted jobs, removal is transactional: if saving the new persisted list fails, the job is restored.

Clear#

Clear one scope:

gScheduler.clear(SchedulerJobScope::USER);

or:

gScheduler.clear(SchedulerJobScope::MANAGED);

Clearing one scope preserves persisted jobs from the other scope.

JOB CLEAR always uses USER.

List#

std::string json =
    gScheduler.list(SchedulerJobScope::USER);

Listing is scope-specific.

The returned JSON describes active jobs and current clock state.

Callback jobs are reported as callback targets; function-pointer addresses are not part of the public listing.

JOB command mapping#

The operator command family maps to Scheduler calls as follows:

JOB AT
    wall one-shot std::string command

JOB AFTER
    monotonic one-shot std::string command

JOB EVERY ... WALL
    wall recurring std::string command

JOB EVERY ... MONO
    monotonic recurring std::string command

JOB LIST
    USER list

JOB DELETE
    USER remove

JOB CLEAR
    USER clear

See Commands for exact command syntax.

Last updated · Edit this page on GitHub