Skip to content

Perf/ticker wheel - #1672

Draft
nightNR wants to merge 2 commits into
Sphereserver:devfrom
nightNR:perf/ticker-wheel
Draft

nightNR wants to merge 2 commits into
Sphereserver:devfrom
nightNR:perf/ticker-wheel

Conversation

@nightNR

@nightNR nightNR commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Description

Problem. CWorldTicker keeps every pending object timer (TIMER, decay, spawns, memory items, spell effects, ...) and the periodic tick of every awake character in sorted std::vectors. In every tick with at least one add or remove request the whole vector is rebuilt: removed entries are copied out, added ones are std::merged in, and expired ones are erased from the front. On a live shard awake NPCs reschedule every tick, so the rebuild runs in practically every tick and costs O(total timers), even though almost all timers are just waiting. With many timers this dominates the tick time.

Change. The timers are scheduled by a timing wheel (src/game/CTickWheel.h):

  • slots of 25 ms covering a window of TimerWheelSlots slots (new sphere.ini setting, default 131072, about 55 minutes; rounded up to a power of 2, clamped to 256..4194304, read at startup, the slot count and window length are logged);
  • timers beyond the window wait in an overflow list, scanned a little each tick with a cursor and moved to the wheel before they expire;
  • the link lives inside the object (intrusive), so adding, removing or rescheduling a timer is O(1) and never allocates;
  • each tick only visits the slots elapsed since the previous one;
  • the entries collected in a tick are sorted by expiration time, then by insertion order, so timers expiring in the same tick still fire in a deterministic order.
operation before (sorted vectors) after (wheel)
add / reschedule O(1) queued, then O(N + C log C) rebuild in the tick O(1), no allocation
remove / cancel O(1) queued, then part of the O(N) rebuild O(1)
tick O(N + C log C) whenever anything changed O(k log k) for the k expired timers + elapsed slots + a slice of the overflow list
memory 2 vectors of N entries + the rebuild copy fixed slot array (8 bytes per slot, x2 wheels: ~2 MB by default) + a hook in each object

(N = pending timers, C = add/remove requests in the tick, k = timers expiring in the tick.)

Benchmarks (Release, Windows, NetworkThreads=0, client logged in, 45 s runs, Tick() time summed over 10 s windows):

scenario metric before wheel
200,000 items with a long timer + 300 live NPCs Tick() per 10 s ~440 ms ~83 ms
average tick ~1.8 ms ~0.35 ms
CPU per 45 s 2.59 s 0.75 s
memory 280 MB 288 MB
same + 20,000 items constantly rescheduling (~9,000 @Timer scripts/s) Tick() per 10 s ~4.3 s ~3.6 s
CPU per 45 s 18.3 s 15.2 s
memory 298 MB 309 MB
500 items with timers + 300 NPCs Tick() per 10 s ~40 ms within noise

With many timers the tick is about 5x faster and uses about 3x less CPU. Under heavy script load (scripts take ~85 % of the tick) it still saves about 16 % of the tick time and 17 % of the CPU. In a small world the difference is within the measurement noise (picking the expired timers is only 5-10 % of the tick there). The machine is noisy (up to 2x between runs of the same binary), so the numbers above compare runs of the same batch.


Type of Change

  • Bug fix
  • New feature
  • Performance improvement
  • Refactoring
  • Documentation update
  • Build / CI change
  • Other (please describe)

Related Issues

Addresses item P1 of the performance audit in #1671 (world timers rebuilt every tick).

Alternative implementation of the same change: #1673 (ordered container, perf/ticker-tree). Only one of the two should be merged; see "Alternative" below.


Testing

  • Tested on a clean SphereServer instance with latest ScriptPack
  • No regressions in existing functionality
  • Added or updated tests (if applicable)

Unit tests (tests/src/t_CTickWheel.cpp, doctest, -DUNIT_TESTING=ON): 25/25 test cases, 3,601,519 assertions, 0 warnings on Linux GCC and Clang (Nightly). They cover slot count normalization, the expiry boundary and the order of equal timeouts, the overflow list (each timer fires in the first tick after its time, never earlier), the clock going back or jumping over many revolutions, sleeping entries, Clear(), removal or rescheduling while the overflow scan is in progress (with the removed entry's memory overwritten), and a randomized comparison (2 wheel sizes x 40 seeds x 3000 ticks of random add, cancel, reschedule, sleep and clock moves) where every collected batch, including its order, must match a reference ordered container. A mutant without the cursor fix in the overflow scan is caught by two test cases.

In-game tests on a clean instance with the latest ScriptPack and a real client, Debug builds (all asserts active), before vs after. Every timer checks it fires not early, not more than 500 ms late, not twice, not after being removed or cancelled, and in order where required. 24 scenarios: ordering (also through the overflow list), equal due times, removal before/after firing, cancel and re-arm, self-rescheduling and self-removal from @Timer, TIMERMS=0, TIMER/TIMERD units, negative timers, a stress test of 1000 timers with random removals and reschedules, equipped items, NPC periodic ticks with chars killed/removed during the tick, contained timers, decay, CAN_O_NOSLEEP in sleeping sectors, spawns, items moved between ground/backpack/equipped while a timer is pending.

run before wheel (131072 slots) wheel (256 slots)
24 scenarios, world clock 0 24/24 24/24 24/24
24 scenarios, world clock 1 h (sectors really sleep) 24/24 24/24 24/24
24 scenarios, ItemTimers=1 24/24 24/24 -
server frozen for 8 s and 3 s (longer than one 256-slot revolution) pass pass pass
world save, stop, restart with 40 pending timers pass pass pass

No error, assert or crash in any run. Lateness and the behavior of the informational scenarios (sleeping sectors, containers, dupe) are identical before and after.


Checklist

  • Code compiles successfully (MSVC Windows Debug/Release; GCC and Clang Linux Nightly with 0 warnings)
  • Changes follow the project's coding style
  • No unrelated code was modified
  • Documentation updated where necessary (sphere.ini, Changelog.txt)
  • This PR does not introduce breaking changes (or they are documented)

No script-visible change: timers fire at the same times. The only difference is the order of timers with exactly the same expiration time: before it was arbitrary (sorted by object pointer), now it is the order they were set.


Alternative: ordered container (#1673)

The other PR keeps the same scheduling model but replaces the sorted vectors with a std::multimap; each object keeps its own node and reuses it when rescheduled. O(log N) insert, and the tick only looks at the front of the container.

tree (#1673) wheel (this PR)
add / remove O(log N) / O(1) amortized, node reused O(1) / O(1), no allocation
tick O(k) O(k log k) + elapsed slots + overflow slice
Tick() per 10 s, 200k timers ~75 ms ~83 ms
CPU per 45 s, 200k timers 0.88 s 0.75 s
timer add/remove per 10 s, 200k timers 5-8 ms ~2.5 ms
Tick() per 10 s, heavy rescheduling ~4.0 s ~3.6 s
timer add/remove per 10 s, heavy rescheduling 50-93 ms 6-7 ms
CPU per 45 s, heavy rescheduling 15.8 s 15.2 s
memory, 200k timers 300 MB 288 MB

Tree pros:

  • simpler, uses a standard container, less new code to review;
  • no window, no overflow list, no new sphere.ini setting;
  • no fixed memory for the slot array;
  • ordering is exact by construction.

Tree cons:

  • O(log N) insert into a large tree: under heavy rescheduling the add/remove cost is about 10x the wheel's, and it loses most of its advantage over the current code;
  • one tree node per object, kept for reuse: 12-13 MB more memory than the wheel at 200k timers;
  • more CPU than the wheel in every measured scenario.

Wheel cons:

  • more code (the wheel, the overflow list and its incremental scan) and a new setting;
  • ~2 MB of fixed memory for the slots at the default size;
  • timers beyond the window (~55 minutes by default) go through the overflow list.

The wheel is faster or equal in every scenario; the tree never beats it. The tree is the simpler option if reviewability matters more than the last 10-15 %.


Additional Notes

  • Pre-existing behavior kept on purpose, found by the tests (same before and after, and in the tree variant): timers expired in the same tick are collected first and then run without rechecking the object. So if the @Timer of A removes B, or sets B's timer to later, and B expired in the same tick, B's @Timer still runs (on an object being deleted), and the new timeout is cleared afterwards (the reschedule is lost). Fixing it changes script-visible behavior, so it is left for a separate PR; the wheel already keeps the data needed for that check.
  • All benchmarks use NetworkThreads=0: with NetworkThreads=1 the current code (also without this PR) crashes intermittently in CNetworkOutput (purecall / access violation), about 3 runs out of 15.

The timers of the objects and the periodic ticks of the characters were kept
in sorted vectors, rebuilt every tick from queued add/erase requests. With many
timers this dominated the tick time.

Use a timing wheel instead (CTickWheel): slots of 25 ms covering a window of
TimerWheelSlots slots (sphere.ini, default 131072, ~55 minutes), plus an
overflow list for later timers, scanned incrementally and moved to the wheel
before they expire. The link lives inside the object, so adding, removing or
rescheduling a timer is O(1) and never allocates. Each tick only visits the
slots elapsed since the previous one. The entries collected in a tick are
sorted by expiration time, then by insertion order, the same order given by
the previous sorted container.
Check the slot count normalization, the expiration boundary and the order of
entries expiring at the same time, the window boundary, time jumps around one
revolution, the clock not moving, going back or negative, very far timers,
many entries in one slot, and the overflow entries firing on time.

Game-like cases: entries removed before expiring, or removed and rescheduled
while the overflow scan is in progress (with the memory of the removed entry
overwritten, as for a deleted item), timers set again from their own tick or
changed while pending, sleeping objects, clear and reuse.

A randomized test compares every collected batch, including its order, with a
reference ordered container.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant