Skip to content

Safe (retrying, deadline-bounded) CV read/write#8

Merged
jaak0b merged 5 commits into
mainfrom
Release/7.0.3
Jun 5, 2026
Merged

Safe (retrying, deadline-bounded) CV read/write#8
jaak0b merged 5 commits into
mainfrom
Release/7.0.3

Conversation

@jaak0b

@jaak0b jaak0b commented Jun 5, 2026

Copy link
Copy Markdown
Owner

Adds safe, async CV programming methods that retry on a missing decoder acknowledgement and either return the value / succeed or throw a dedicated timeout exception, with a follow-up hardening pass from code review.

New API

  • IProgrammingControl.ReadCvAsync(cv, timeout) / WriteCvAsync(cv, value, timeout) — programming track.
  • IZ21CommandStation.ReadPomCvAsync(loco, cv, timeout) / WritePomCvAsync(loco, cv, value, timeout) — POM (main line; POM write verifies via RailCom read-back).
  • CvOperationTimeoutException, CvShortCircuitException.
  • Z21Options.CvRetryDelay (default 50 ms) — backoff between NACK retries.

Behaviour

  • Retries on LAN_X_CV_NACK until the caller's deadline; aborts immediately on LAN_X_CV_NACK_SC.
  • A permanent NACK (absent / unreadable decoder, no RailCom) surfaces as a timeout.
  • Operations are serialized by a semaphore; the fire-and-forget CV overloads now fail fast if invoked while a safe operation is in progress (NACKs carry no address and would be misattributed).

Hardening (review fixes)

  • Send and wait are both bounded by the deadline (Task.WaitAsync), so a stalled transport cannot outlive the timeout.
  • Cancellation is only mapped to a timeout when it is the deadline; unrelated OperationCanceledExceptions propagate.
  • Dispose() is idempotent and cancels in-flight operations (surfaced as ObjectDisposedException); lock release tolerates disposal.
  • Timeout arguments are validated.

Tests

17 unit tests for the safe CV flow (results, NACK retries, short circuit, timeouts, POM read-back, timeout validation, concurrency guard, dispose). Full solution green: 697 passed, hardware smoke tests skipped.

@jaak0b jaak0b merged commit a54f84e into main Jun 5, 2026
6 checks passed
@jaak0b jaak0b mentioned this pull request Jun 5, 2026
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