lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
myxce/.kiro/specs/scheduler-sim-discrete-clock/requirements.md
Rongsong Shen dcf54387ae
docs(spec): libxce-alloc-preason-equality review fixes; new scheduler-sim-discrete-clock spec 
libxce-alloc-preason-equality (requirements, design, tasks; not yet approved):
- alloc_eq compares `from` and excludes only instid; the scheduler stamps
  `from` with the deciding session's start, the same clock reading that
  is recorded as beginRound, so a replay reproduces it.
- every comparator takes an optional char** why: a malloc'd description
  of the first difference, owned and freed by the caller; --sim-verify
  mismatch lines print it (resolves bug-1881).
- job_preason_eq is new full-match behavior, not a relocation (bug-1845
  keeps the simulator main-reason-only); the three white-box test files
  switch to it and keep their sim_verify.c include.
- alloc_eq stays separate from merge_job_alloc()'s same_alloc_slot()
  (bug-1863), which does match on instid.

scheduler-sim-discrete-clock (initialized): remove --sim-speed so the
simulator clock moves only at recorded timestamps and a replayed
session_start equals the recorded beginRound exactly.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 08:50:07 +00:00

2.2 KiB
Raw Blame History

Requirements Document

Project Description (Input)

Who has the problem: operators and engineers who replay scheduler recordings with xce_scheduler --sim / --sim-verify or the simulation REPL, and the libxce-alloc-preason-equality work, which needs a replay to reproduce values derived from a session's start time bit-for-bit.

Current situation: the simulator is already event-driven: sim_loop.c never sleeps, and it jumps the virtual clock with sim_advance_virtual_clock() to each recorded event timestamp and to each recorded session's beginRound. --sim-speed (default 1, help text "1=real-time") does not pace anything. It only scales how far the clock drifts with real elapsed time between those jumps (xce_core_now() = virtual_clock_base + elapsed_real * speed_num / speed_den). So at the default speed, every clock reading in a replay (core->session_start, the --sim-record beginRound, decision timestamps, REPL position) depends on how fast the host happens to run. For example, a replayed session's session_start lands slightly after the recorded beginRound. Only --sim-speed 0 is deterministic. The REPL exposes the same knob as its speed parameter.

What should change: make the simulator a pure discrete-event simulation. Remove --sim-speed, the REPL speed parameter, and the simulator's use of speed_num/speed_den, so the virtual clock moves only when the replay reaches a recorded event or round timestamp and never drifts with real time. Guarantee that a replayed session's core->session_start equals the recorded ReplaySession beginRound exactly, so values derived from it (for example xce_alloc_t.from, spec libxce-alloc-preason-equality Requirement 4.3) reproduce under --sim-verify. Amend the scheduler-core spec where it defines the speed modes (Req 5 AC 3 mode table, AC 13 simulation startup). Expected touch points: main.c CLI, sim.c sim_set_virtual_clock(), sim_loop.c, repl_params.c/repl_info.c, core_clock.c/core.h, about 20 scheduler tests that set a speed, and src/docs/deployment.md. Normal-mode (live) scheduling is unchanged.

Requirements