Skip to content

Add safe retrying, deadline-bounded CV read/write#7

Merged
jaak0b merged 1 commit into
mainfrom
feature/safe-cv-programming
Jun 5, 2026
Merged

Add safe retrying, deadline-bounded CV read/write#7
jaak0b merged 1 commit into
mainfrom
feature/safe-cv-programming

Conversation

@jaak0b

@jaak0b jaak0b commented Jun 5, 2026

Copy link
Copy Markdown
Owner

Adds async CV operations that take a caller timeout and either return the result or throw — no manual event correlation.

API

  • IProgrammingControl (neutral, programming track): Task<byte> ReadCvAsync(cv, timeout), Task WriteCvAsync(cv, value, timeout).
  • IZ21CommandStation (Z21/POM): Task<byte> ReadPomCvAsync(loco, cv, timeout), Task WritePomCvAsync(loco, cv, value, timeout).
  • New neutral exceptions: CvOperationTimeoutException, CvShortCircuitException.

The existing fire-and-forget ReadCvAsync(cv) / WriteCvAsync(cv, value) + event methods are unchanged.

Behaviour

  • Retry on missing ACK until the caller's deadline (re-reads are harmless; re-writes are idempotent). Resend as soon as each LAN_X_CV_NACK arrives — no fixed interval.
  • Short circuit (LAN_X_CV_NACK_SC) aborts immediately with CvShortCircuitException (no retry).
  • Deadline elapsed throws CvOperationTimeoutException.
  • Programming-track write relies on its own confirming LAN_X_CV_RESULT (genuine decoder ACK) — no read-back.
  • POM write has no reply, so it loops write → read-back until the read-back equals the written value (needs RailCom; otherwise times out).
  • Safe ops are serialized with a SemaphoreSlim because NACK/NACK_SC carry no CV address.

Notes

  • A permanent NACK (no decoder / unreadable CV) surfaces as a timeout, not a distinct failure; MM decoders answer CV_RESULT = "finished", not "succeeded"; don't interleave the safe and fire-and-forget CV methods concurrently.
  • Z21CommandStation.Dispose now also disposes the SemaphoreSlim (overlaps the Dispose edit in the DI-fixes PR — trivial rebase).

Tests

12 new FakeTransport-driven tests (result / retry-on-NACK / short-circuit / timeout for read, write, POM read, POM write incl. read-back mismatch retry), written test-first. Full suite green: Z21.Client 665.

@jaak0b jaak0b merged commit 6d97c7c into main Jun 5, 2026
6 checks passed
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