Skip to content

fix(scheduling): make ScheduledAgentTask start/stop atomic state transitions (issue #215) - #370

Open
konlue wants to merge 2 commits into
agentic-ai-java:mainfrom
konlue:fix/issue215-scheduled-task-atomic-lifecycle
Open

konlue wants to merge 2 commits into
agentic-ai-java:mainfrom
konlue:fix/issue215-scheduled-task-atomic-lifecycle

Conversation

@konlue

@konlue konlue commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Describe what this PR does / why we need it

Issue #215 reports that ScheduledAgentTask.start/stop compose their lifecycle from two independent volatile flags with no atomic transition. This PR replaces the flag pair with a single CAS-able lifecycle state and closes all four windows it exposes, with deterministic latch-driven regression tests.

Root cause

Four concrete defects fall out of the flag pair. Two concurrent starts can both pass the started guard and each publish a schedule, leaving two live schedulings for one task. A stop racing with an in-flight start can finish before the future is published, so the late future is never cancelled and keeps triggering. A stop followed by a start succeeds: stopped plays no role in the start guard, resurrecting a stopped task. And a start whose scheduling throws leaves the task registered forever, since the registration happens in the constructor but nothing releases it on failure.

The fix

The task now holds one AtomicReference over a package-private ScheduleState (NEW, STARTING, RUNNING, STOPPING, STOPPED, FAILED). start() claims NEW → STARTING up front, so a concurrent or repeated start is rejected while the first is still publishing the schedule. After the schedule is published, STARTING → RUNNING must win; if stop() took the state during the window, the just-published future is cancelled instead of left live and the start fails. A scheduling failure moves to FAILED, releases the registration, and propagates the original exception, so a failed start strands nothing. stop() funnels through a single-winner transition to STOPPING — concurrent and repeated stops are no-ops — then cancels the future, unregisters, notifies, and lands on STOPPED. The stop semantics are unchanged: cancel(false) only, so in-flight executions are still not interrupted. No new listener events and no public API growth; isStarted/isStopped keep their previous observable semantics (started history is retained after stop).

Testing

The new ScheduledAgentTaskAtomicStartStopTest gates the scheduler publication with latches for deterministic interleaving: a first start blocked inside the publication window makes a concurrent second start fail with exactly one schedule published (red before: two schedules, no exception); a start after stop is rejected with no new schedule (red before: it scheduled again); a start whose scheduling throws unregisters and propagates (red before: registration left behind); a stop during the STARTING window cancels the late-published future and ends STOPPED (red before: the future stayed live and start succeeded); and the full state walk NEW → STARTING → RUNNING → STOPPING → STOPPED is asserted through a package-private observation point. The scheduling package is 19/19 green with the #214/#216 regressions untouched, checkstyle and spring-javaformat are clean. The module's 8 pre-existing failures on this baseline (skills prompt template, file store Windows path, prompt template line endings) are unrelated and unchanged.

Fixes #215

@konlue
konlue force-pushed the fix/issue215-scheduled-task-atomic-lifecycle branch from 00523e4 to 31be3f3 Compare November 15, 2026 03:39

@yuluo-yx yuluo-yx left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isStarted() no longer preserves started history: reproduced new task -> stop() without any start() call, yet isStarted() returns true. STARTING is also reported as started before scheduling succeeds. Preserve whether start actually succeeded and add regression coverage for stopping a never-started task.

…sitions (issue agentic-ai-java#215)

start/stop composed their lifecycle from independent volatile
started/stopped flags, so the transitions were not atomic: two
concurrent starts could both pass the guard and publish two schedules,
a stop racing with the schedule publication could miss the future
published afterwards, a stop followed by start resurrected the stopped
task, and a failed start left the registration behind.

The lifecycle is now a single CAS-able state (NEW, STARTING, RUNNING,
STOPPING, STOPPED, FAILED). start() claims NEW->STARTING up front, so a
second start is rejected while the first is still publishing; a stop
winning the STARTING window makes the late future cancelled instead of
live; a scheduling failure releases the registration and lands in
FAILED. stop() is idempotent through a single winner transition. The
derived isStarted/isStopped keep their previous observable semantics,
and all existing lifecycle/ownership tests pass unchanged.

Deterministic interleaving tests gate the scheduler publication with
latches: double start schedules once, start after stop is rejected,
failed start unregisters, stop during start cancels the late future.
…gentic-ai-java#215 review)

isStarted() derived from the lifecycle state reported started=true for a
task that was only stopped (NEW -> STOPPED), and during STARTING before
the schedule was published. isStarted() now reads a monotonic
start-succeeded projection, set once when the STARTING -> RUNNING
transition succeeds and never reset, so it answers whether a start
actually succeeded while the state machine remains the single source of
transitions. Regression test covers stopping a never-started task.
@konlue
konlue force-pushed the fix/issue215-scheduled-task-atomic-lifecycle branch from 31be3f3 to 2fc28c9 Compare November 17, 2026 15:54
@konlue

konlue commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

@yuluo-yx Fixed and pushed (2fc28c9, branch rebased onto the current main first — it picked up the merged #216 work cleanly).

Root cause: my derived isStarted() read the lifecycle state itself, so "being in a non-NEW, non-FAILED state" answered the wrong question — a task stopped without ever starting (NEW → STOPPED) reported started, and STARTING reported started before any schedule was published. Your reproduction is exact.

Fix: isStarted() now reads a separate monotonic projection, startSucceeded, set once when the STARTING → RUNNING transition succeeds and never reset. It answers "did a start actually succeed" independently of where the state machine currently is: NEW, STARTING, FAILED, and a never-started STOPPED all report false; a task that reached RUNNING keeps reporting started after a later stop (the history semantics the previous tests rely on). The lifecycle state machine itself is unchanged and stays the single source of transitions — the projection participates in no transition.

Regression coverage: a new test stops a never-started task and asserts isStarted() stays false while isStopped() is true (red before the fix: started reported true). The full state-walk test still asserts started=true once RUNNING was reached and after the subsequent stop. argi-workflow-graph-core scheduling is 23/23 green after the rebase (including the merged #216 mutex tests), checkstyle and format clean.

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.

[BUG][OPT-24] 为定时任务 start/stop 建立原子生命周期边界

2 participants