Skip to content

Commit edcd19f

Browse files
committed
docs: Note the second-cancel change from the reference, and the logging-lock rule
A review noted that refusing a second cancel_action while CANCELING, as the crate does, changes behavior for callers of the pure-Python Session, which accepts it and shortens the grace period to the new time limit. Say so in the cancel_action docstring, the sessions spec and the quality report. The crate can't shorten a cancel in progress. Put the rule against calling an action method while holding a lock that a logging handler takes in each action method's docstring, not only the spec, and say in the spec where the fix belongs (the crate should report acceptance and install the cancel token before logging). Say "typically" for when the 20 s cancel wait ends. Pin that a cancel from the action thread raises at once, and loosen the straight-after cancel test's bound to 8 s for slow CI runners. Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
1 parent c69d79e commit edcd19f

5 files changed

Lines changed: 60 additions & 20 deletions

File tree

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -371,6 +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 |
374375
| `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 |
375376
| `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 |
376377
| `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) |

‎rust-bindings/src/sessions/session.rs‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -730,6 +730,9 @@ impl PySession {
730730
/// wrap hook is entered. A failure after that, such as an environment
731731
/// variable that doesn't resolve, fails the action; the environment
732732
/// still counts as entered and must be exited.
733+
///
734+
/// Waits for the action thread, which logs through Python's `logging`,
735+
/// so don't call it while holding a lock that a logging handler takes.
733736
#[pyo3(signature = (*, environment, identifier=None, resolved_symtab=None, os_env_vars=None))]
734737
fn enter_environment(
735738
&self,
@@ -776,6 +779,9 @@ impl PySession {
776779
/// `READY_ENDING`, if `identifier` isn't entered, or if it isn't the
777780
/// most recently entered environment. A failure after that fails the
778781
/// action, and the environment still counts as exited.
782+
///
783+
/// Waits for the action thread, which logs through Python's `logging`,
784+
/// so don't call it while holding a lock that a logging handler takes.
779785
#[pyo3(signature = (*, identifier, resolved_symtab=None, keep_session_running=true, os_env_vars=None))]
780786
fn exit_environment(
781787
&self,
@@ -808,6 +814,9 @@ impl PySession {
808814
/// failure after that, such as a task parameter value that can't be
809815
/// coerced, fails the action.
810816
///
817+
/// Waits for the action thread, which logs through Python's `logging`,
818+
/// so don't call it while holding a lock that a logging handler takes.
819+
///
811820
/// `step_name` is surfaced as `WrappedStep.Name` to a wrapping
812821
/// environment's `onWrapTaskRun` hook (RFC 0008). It defaults to an empty
813822
/// string when the caller does not supply one.
@@ -846,6 +855,9 @@ impl PySession {
846855
/// Raises `SessionError` if the session isn't `READY`, if `command` is
847856
/// empty or blank, or if `timeout` is zero, and `ValueError` if
848857
/// `timeout` is negative, NaN or infinite.
858+
///
859+
/// Waits for the action thread, which logs through Python's `logging`,
860+
/// so don't call it while holding a lock that a logging handler takes.
849861
#[pyo3(signature = (*, command, args=None, timeout=None, os_env_vars=None, use_session_env_vars=true, log_banner_message=None))]
850862
#[allow(clippy::too_many_arguments)] // PyO3 method mirrors a kwarg-rich public signature
851863
fn run_subprocess(
@@ -906,8 +918,12 @@ impl PySession {
906918
/// `SessionError("Cannot cancel: the action has not started yet")` if
907919
/// the action hasn't installed its cancel token: at once when called
908920
/// from the action's own thread (a logging handler), and after 20 s
909-
/// otherwise, which happens only when the action thread is blocked on a
910-
/// lock the caller holds, such as a logging handler's.
921+
/// otherwise, typically because the action thread is blocked on a lock
922+
/// the caller holds, such as a logging handler's.
923+
///
924+
/// Unlike the pure-Python reference, a second cancel while one is in
925+
/// progress raises; the crate doesn't shorten the first cancel's grace
926+
/// period.
911927
#[pyo3(signature = (time_limit=None, mark_action_failed=None))]
912928
fn cancel_action(
913929
&self,
@@ -959,10 +975,6 @@ impl PySession {
959975
// through the thread-safe cancel handle, which follows the
960976
// action's own cancelation method (including cross-user
961977
// helper delivery), exactly like Session::cancel_action.
962-
// Holding the session lock means the action thread can't
963-
// write its final snapshot before the `Canceling` below, so
964-
// the snapshot can't be left reading `Canceling` after the
965-
// action has ended.
966978
// A second cancel while one is in progress: the crate's
967979
// `Session::cancel_action` refuses it, so do the same rather
968980
// than deliver it through the handle.
@@ -975,6 +987,10 @@ impl PySession {
975987
}));
976988
}
977989
}
990+
// Holding the session lock means the action thread can't
991+
// write its final snapshot before the `Canceling` below, so
992+
// the snapshot can't be left reading `Canceling` after the
993+
// action has ended.
978994
if handle.cancel(duration, mark_failed) {
979995
lock_recover(&snapshot).state = SessionState::Canceling;
980996
return Ok(());

‎specs/python-sessions-interface.md‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -225,23 +225,28 @@ it returns reaches the action, unless the action has already ended, as
225225
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
228-
`InvalidState`. If the action hasn't installed its cancel token yet,
229-
`cancel_action` raises `SessionError("Cannot cancel: the action has not
230-
started yet")`, the binding's own message: at once when called from the
231-
action's own thread (a logging handler), and after 20 s otherwise. Every
232-
error after acceptance, such as a parameter value that can't be coerced,
233-
is reported on `action_status` and doesn't raise, even when it arrives
234-
before the call returns. The crate documents those as failing the action
235-
rather than refusing the call, and the pure-Python reference reports
236-
them the same way.
228+
`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.
237240

238241
The crate runs each action on a background thread, and that thread logs
239242
through Python's `logging` (each record needs the GIL and runs the
240243
handlers). An action method waits for the crate to accept or refuse the
241244
call, and `cancel_action` waits for the action's cancel token, so don't
242245
call either while holding a lock that a logging handler takes on another
243246
thread: the action thread would wait for the lock, and the call for the
244-
action thread.
247+
action thread. The pure-Python reference logs on the caller's thread, so
248+
it has no such restriction. A fix belongs in the crate: report that it
249+
accepted a call, and install the cancel token, before logging.
245250

246251
An action that ends `FAILED`, `CANCELED` or `TIMEOUT` makes the session
247252
ending-only (`READY_ENDING`): `exit_environment` and `cleanup` still

‎src/openjd/_openjd_rs.pyi‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2221,6 +2221,9 @@ class Session:
22212221
wrap hook is entered. A failure after that, such as an environment
22222222
variable that doesn't resolve, fails the action; the environment
22232223
still counts as entered and must be exited.
2224+
2225+
Waits for the action thread, which logs through Python's `logging`,
2226+
so don't call it while holding a lock that a logging handler takes.
22242227
"""
22252228

22262229
def exit_environment(
@@ -2239,6 +2242,9 @@ class Session:
22392242
`READY_ENDING`, if `identifier` isn't entered, or if it isn't the
22402243
most recently entered environment. A failure after that fails the
22412244
action, and the environment still counts as exited.
2245+
2246+
Waits for the action thread, which logs through Python's `logging`,
2247+
so don't call it while holding a lock that a logging handler takes.
22422248
"""
22432249

22442250
def run_task(
@@ -2258,6 +2264,9 @@ class Session:
22582264
failure after that, such as a task parameter value that can't be
22592265
coerced, fails the action.
22602266
2267+
Waits for the action thread, which logs through Python's `logging`,
2268+
so don't call it while holding a lock that a logging handler takes.
2269+
22612270
`step_name` is surfaced as `WrappedStep.Name` to a wrapping
22622271
environment's `onWrapTaskRun` hook (RFC 0008). It defaults to an empty
22632272
string when the caller does not supply one.
@@ -2279,6 +2288,9 @@ class Session:
22792288
Raises `SessionError` if the session isn't `READY`, if `command` is
22802289
empty or blank, or if `timeout` is zero, and `ValueError` if
22812290
`timeout` is negative, NaN or infinite.
2291+
2292+
Waits for the action thread, which logs through Python's `logging`,
2293+
so don't call it while holding a lock that a logging handler takes.
22822294
"""
22832295

22842296
def clear_ending_only(self) -> None:
@@ -2307,8 +2319,12 @@ class Session:
23072319
`SessionError("Cannot cancel: the action has not started yet")` if
23082320
the action hasn't installed its cancel token: at once when called
23092321
from the action's own thread (a logging handler), and after 20 s
2310-
otherwise, which happens only when the action thread is blocked on a
2311-
lock the caller holds, such as a logging handler's.
2322+
otherwise, typically because the action thread is blocked on a lock
2323+
the caller holds, such as a logging handler's.
2324+
2325+
Unlike the pure-Python reference, a second cancel while one is in
2326+
progress raises; the crate doesn't shorten the first cancel's grace
2327+
period.
23122328
"""
23132329

23142330
def cleanup(self) -> None:

‎test/openjd/sessions/test_refused_calls.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -427,7 +427,7 @@ def test_straight_after_the_call_that_started_the_action(
427427
began = time.monotonic()
428428
session.cancel_action()
429429
_settle(session)
430-
assert time.monotonic() - began < 4
430+
assert time.monotonic() - began < 8
431431
status = session.action_status
432432
assert status is not None and status.state == ActionState.CANCELED
433433
assert session.state == SessionState.READY_ENDING
@@ -521,11 +521,13 @@ def test_cleanup_with_a_concurrent_call_and_logging_on(tmp_path: Path) -> None:
521521
class CancelOnBanner(logging.Handler):
522522
def emit(self, record):
523523
if "Running Task" in record.getMessage() and not results:
524+
began = time.monotonic()
524525
try:
525526
session.cancel_action()
526527
results.append("canceled")
527528
except SessionError as e:
528529
results.append(str(e))
530+
results.append(time.monotonic() - began < 0.5)
529531
logging.getLogger().addHandler(CancelOnBanner())
530532
logging.getLogger().setLevel(logging.INFO)
531533
session = Session(session_id="s", job_parameter_values={}, session_root_directory=sys.argv[1])
@@ -555,7 +557,7 @@ def test_cancel_from_the_action_thread_before_it_starts(tmp_path: Path) -> None:
555557
timeout=25,
556558
)
557559
assert result.returncode == 0, result.stderr
558-
assert result.stdout.strip() == "['Cannot cancel: the action has not started yet']"
560+
assert result.stdout.strip() == "['Cannot cancel: the action has not started yet', True]"
559561

560562

561563
_CANCEL_WHILE_THE_ACTION_THREAD_WAITS = r"""

0 commit comments

Comments
 (0)