Skip to content

Commit 33de403

Browse files
committed
docs: Say a second cancel in the reference shortens the grace period to at most its time limit
Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
1 parent ee82118 commit 33de403

2 files changed

Lines changed: 12 additions & 12 deletions

File tree

‎reports/sessions-bindings-quality-evaluation-report.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -371,7 +371,7 @@ counted as test-suite failures.
371371
|---|---|---|---|
372372
| `run_task` while session not READY | `RuntimeError("Session must be in the READY state to run a task.")` | `SessionError("Session must be in READY state, current: RUNNING")` (the crate's message; a `RuntimeError`) | ⚠ message change |
373373
| `run_task` / `enter_environment` on a `READY_ENDING` session | `RuntimeError("Session must be in the READY state ...")` | `SessionError("Session must be in READY state, current: READY_ENDING")`, a `RuntimeError`; nothing changes | ⚠ message change (the crate's) |
374-
| `cancel_action` while a cancel is in progress | accepted; shortens the grace period to the new `time_limit` | `SessionError("Session must be in RUNNING state, current: CANCELING")`, the crate's refusal; the crate can't shorten a cancel in progress | ⚠ behavior change |
374+
| `cancel_action` while a cancel is in progress | accepted; shortens the remaining grace period to at most the new `time_limit` | `SessionError("Session must be in RUNNING state, current: CANCELING")`, the crate's refusal; the crate can't shorten a cancel in progress | ⚠ behavior change |
375375
| `Session.clear_ending_only()` | not in reference | takes a `READY_ENDING` session back to `READY`, as the crate's `clear_ending_only` does | ⚠ binding-only API |
376376
| `WindowsSessionUser(...)` when the process user can't be looked up | `get_process_user()` raises | raises `RuntimeError("Could not determine the process user: ...")` (before, treated as "not the process user") | ⚠ class change |
377377
| `cancel_action` when nothing is running | `RuntimeError("No actions are running")` | `SessionError("Session must be in RUNNING state, current: READY")` | ⚠ class+message change (the crate's) |

‎specs/python-sessions-interface.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -226,17 +226,17 @@ one that fails before its subprocess starts can: then it raises the
226226
crate's `InvalidState`. A zero `time_limit` terminates at once. A second
227227
`cancel_action` while the session is `CANCELING` raises the crate's
228228
`InvalidState`; the pure-Python reference accepts it and shortens the
229-
grace period to its `time_limit`, which the crate can't do. If the
230-
action hasn't installed its cancel token yet, `cancel_action` raises
231-
`SessionError("Cannot cancel: the action has not started yet")`, the
232-
binding's own message: at once when called from the action's own thread
233-
(a logging handler), and after 20 s otherwise, typically because the
234-
action thread is blocked on a lock the caller holds. Every error after
235-
acceptance, such as a parameter value that can't be coerced, is reported
236-
on `action_status` and doesn't raise, even when it arrives before the
237-
call returns. The crate documents those as failing the action rather
238-
than refusing the call, and the pure-Python reference reports them the
239-
same way.
229+
remaining grace period to at most its `time_limit`, which the crate
230+
can't do. If the action hasn't installed its cancel token yet,
231+
`cancel_action` raises `SessionError("Cannot cancel: the action has not
232+
started yet")`, the binding's own message: at once when called from the
233+
action's own thread (a logging handler), and after 20 s otherwise,
234+
typically because the action thread is blocked on a lock the caller
235+
holds. Every error after acceptance, such as a parameter value that
236+
can't be coerced, is reported on `action_status` and doesn't raise, even
237+
when it arrives before the call returns. The crate documents those as
238+
failing the action rather than refusing the call, and the pure-Python
239+
reference reports them the same way.
240240

241241
The crate runs each action on a background thread, and that thread logs
242242
through Python's `logging` (each record needs the GIL and runs the

0 commit comments

Comments
 (0)