Skip to content

Keep the world timers in an ordered container - #1673

Draft
nightNR wants to merge 1 commit into
Sphereserver:devfrom
nightNR:perf/ticker-tree
Draft

nightNR wants to merge 1 commit into
Sphereserver:devfrom
nightNR:perf/ticker-tree

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 kept in a std::multimap ordered by expiration time (src/game/CTimedObject.h, src/game/CWorldTicker.cpp):

  • every object stores the iterator of its own entry, so adding, removing or rescheduling it needs no search: O(log N) insert, O(1) amortized removal;
  • when an entry is removed or expires, its node is extracted and kept in the object, and reused when the timer is set again, so after the first timer of an object no allocation happens;
  • each tick only visits the expired entries from the head of the container;
  • timers expiring in the same tick still fire ordered by expiration time, then by insertion order;
  • no new setting, no limit on how far in the future a timer can be.
operation before (sorted vectors) after (ordered container)
add / reschedule O(1) queued, then O(N + C log C) rebuild in the tick O(log N), node reused
remove / cancel O(1) queued, then part of the O(N) rebuild O(1) amortized
tick O(N + C log C) whenever anything changed O(k) for the k expired timers
memory 2 vectors of N entries + the rebuild copy one tree node per object with a timer (kept for reuse)

(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 tree
200,000 items with a long timer + 300 live NPCs Tick() per 10 s ~440 ms ~75 ms
average tick ~1.8 ms ~0.3 ms
CPU per 45 s 2.59 s 0.88 s
memory 280 MB 300 MB
same + 20,000 items constantly rescheduling (~9,000 @Timer scripts/s) Tick() per 10 s ~4.3 s ~4.0 s
timer add/remove per 10 s ~3 ms 50-93 ms
CPU per 45 s 18.3 s 15.8 s
memory 298 MB 321 MB
500 items with timers + 300 NPCs Tick() per 10 s ~40 ms ~45-85 ms (noise)

With many timers the tick is about 6x faster and uses about 3x less CPU. Under heavy script load (scripts take ~85 % of the tick) the gain is small: about 7 % of the tick time and 14 % of the CPU. Most of the tick is scripts there, and the O(log N) inserts into a tree of ~220k nodes (50-93 ms per 10 s) cost more than the queued adds of the old code (~3 ms). In a small world the difference is within the measurement noise. 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: #1672 (timing wheel, perf/ticker-wheel). 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)

No new unit tests: the container is a standard std::multimap, the logic around it is the same entry bookkeeping as before. The randomized unit test of #1672 uses an ordered container with the same semantics as its reference model.

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, 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 tree
24 scenarios, world clock 0 24/24 24/24
24 scenarios, world clock 1 h (sectors really sleep) 24/24 24/24
server frozen for 8 s and 3 s pass pass
world save, stop, restart with 40 pending timers pass, max 143 ms late pass, max 143 ms late

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)
  • Changes follow the project's coding style
  • No unrelated code was modified
  • Documentation updated where necessary (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: timing wheel ( #1672 )

The other PR replaces the sorted vectors with a timing wheel: 25 ms slots over a window of TimerWheelSlots slots (new sphere.ini setting, default ~55 minutes), an overflow list for later timers, intrusive O(1) add/remove.

tree (this PR) wheel ( #1672 )
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: a standard container, about 170 lines added against about 440 for the wheel (which also adds src/game/CTickWheel.h), easier to review and maintain;
  • no window, no overflow list, no new sphere.ini setting to tune;
  • no fixed memory for the slot array;
  • ordering is exact by construction, no batch sort needed.

Tree cons:

  • O(log N) insert: under heavy rescheduling the add/remove cost is about 10x the wheel's, and it keeps only a small advantage over the current code there;
  • 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;
  • no dedicated unit tests.

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; this PR is the simpler option if reviewability matters more than the last 10-15 % (and much more under heavy rescheduling).


Additional Notes

  • Pre-existing behavior kept on purpose, found by the tests (same before and after, and in the wheel 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.
  • 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 std::multimap ordered by expiration time instead. Every object stores the
iterator of its own entry, so adding, removing or rescheduling it doesn't need
any search, and the node is extracted and reused when it's rescheduled, so it
doesn't allocate either. Each tick only visits the expired entries from the
head. Entries expiring in the same tick still fire ordered by expiration time,
then by insertion order.
@nightNR nightNR mentioned this pull request Nov 19, 2026
6 of 12 tasks
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