Map scheduler ticks

How the map scheduler places maps, picks their deadlines, waits, and handles faults, registration and shutdown. Why it's built this way is on Map scheduler, and what it records on Map scheduler metrics.

Placement

Placed as	Runs
Pool	On one of Maps:PoolThreads shared threads, started when the scheduler starts. Every map the map directory opens is placed here
Dedicated	On a thread of its own, started at registration, while fewer than Maps:DedicatedThreads are in use; otherwise in the pool, with a warning. The slot frees when the map leaves

Deadlines

• The first deadline is the moment of registration plus a random 0 to one tick less a millisecond.
• The next deadline is the old one plus as many periods as it takes to pass now, read after the tick ends: one period when the tick finished in time, more when it overran. Every deadline passed over is counted as skipped.
• A pool thread takes the map whose deadline is earliest and has come, runs one tick, and puts it back. With no map queued it waits 100 ms or until woken.

Waiting

System	Waits on
Windows	A high-resolution waitable timer, together with the thread's wake and stop events. Where that timer can't be made or set, a plain timed wait on the events
Linux and the rest	The wake and stop events, with the time to the deadline as the timeout

A pool thread wakes when a map registers. A dedicated thread waits only on its own deadline and the stop event.

Faults

A tick that throws is caught, logged as an error and counted as a fault, and the map goes back on the queue at its next deadline as usual.

Registering and stopping

Call	Holds
Register	Works before or after the scheduler starts. Refused once the scheduler is stopping, and for a map already registered, including one whose unregistration waits on a tick still running
Unregister	Completes at once for an idle or unknown map, and when its current tick ends for a running one; the map never ticks again. A second call returns the same wait
Start	Starts the pool threads, once. Refused when it's already started or stopping
Stop	Starts no new tick, waits for every thread to finish the tick it's running, then completes every waiting unregistration. A second stop does nothing

Log events

Id	Level	When
7001	Error	A map's tick threw
7002	Warning	A map asked for a dedicated thread and none was free

Known edges

• The Windows timer's fallback is logged by nothing; the tick counts show it, as Map scheduler metrics describes.

Where the code lives

Piece	Path
The scheduler	Source/NexusTomorrow.Maps/Scheduling/MapScheduler.cs
The deadline queue and its rule	Source/NexusTomorrow.Maps/Scheduling/DeadlineQueue.cs
The waits	Source/NexusTomorrow.Maps/Scheduling/DeadlineWait.cs, Source/NexusTomorrow.Maps/Scheduling/WindowsDeadlineWait.cs
Tests	Tests/NexusTomorrow.Maps.Tests/Scheduling/