TxConfirmation Struct¶
Result of SendConfirmedAsync(CanFrame, Nullable<TimeSpan>, CancellationToken): a uniform "was this frame actually sent" answer regardless of whether the underlying adapter supports hardware TX echo (arc42 §5.3/§6.3, ADR-7; FR-RAW-030..034).
Implements IEquatable<TxConfirmation>
Remarks¶
A TxConfirmation value is only ever produced for a *resolved* outcome — the
returned Task<TxConfirmation> never completes successfully while the send is
still pending. Confirmed is true only for an actual driver-accepted send
(approximated) or an actually-matched echo frame (real); for every other outcome
(timeout, bus-off, outright rejection) Confirmed is false and
FailureReason explains why (FR-RAW-033). Explicit caller-supplied
CancellationToken cancellation is reported as task
cancellation (standard .NET convention), not as a TxConfirmation value.
Properties¶
TxConfirmation.Confirmed Property¶
True if the send was confirmed — either by a matched hardware echo, or (when the adapter has no echo capability enabled) by the driver accepting the frame. See IsApproximated to tell the two apart.
Property Value¶
TxConfirmation.FailureReason Property¶
Why the send was not confirmed; None when Confirmed is true.
Property Value¶
TxConfirmation.HostHandoffTimestamp Property¶
The host-monotonic GetTimestamp reading
taken immediately <em>before</em> the driver call -- on the echo path inside the
service's send lock; the approximated path has no such lock. Comparable with
HostTransmitTimestamp and with the demux's HostArrivalTimestamp.
Carried by exactly the results that carry HostTransmitTimestamp, and zero
on the others.
Property Value¶
Remarks¶
The other end of the driver call. HostTransmitTimestamp is where a response deadline starts, and is taken after the call -- which on an in-process bus includes the peer's answer, and on an asynchronous adapter a completion callback -- so a fast peer's response can be stamped by the demux before it. A caller deciding whether a received frame can be a response to this transmission at all needs an instant no later than the frame's wire instant: this one. On the echo path it is taken inside the lock, so no wait for another sender's driver call sits between it and the handoff.
TxConfirmation.HostTransmitTimestamp Property¶
GetTimestamp reading taken immediately
after the driver accepted the frame. Monotonic, and comparable with the
HostArrivalTimestamp the demux puts on received frames.
Which results carry it depends on the path. On the echo path, every result for a frame the driver accepted: a confirmation, a Timeout and a BusOff alike, because the driver call has returned before the echo wait begins. On the approximated path, only a confirmation: a Timeout there means the driver's asynchronous transmit had not completed, so the frame may have been handed over but there is no reading after acceptance, and the value is zero. A Rejected result carries zero on either path.
Property Value¶
Remarks¶
Timestamp answers "when was this result produced" and is a wall-clock reading; this answers "when did the frame go out", which is a different question and needs a different clock. A caller whose response deadline starts at transmission has no other way to learn that instant: by the time the returned task completes it is behind the echo wait, and reading the clock then starts the deadline late enough to let a late response pass for a punctual one (#92).
TxConfirmation.IsApproximated Property¶
True when Confirmed reflects driver acceptance rather than an actual hardware echo (FR-RAW-032) — i.e. "best-effort acknowledgment", not a guarantee the frame reached the wire. Always false when Confirmed is false.
Property Value¶
Remarks¶
"Driver acceptance" is the bus's transmit returning a positive count, and means no more
than that bus makes it mean. CanKit's QueuedCanBus returns the number of frames
it queued in process -- its own documentation says so -- so behind it an approximated
confirmation says the frame was queued, not that a driver took it.
TxConfirmation.Timestamp Property¶
UTC timestamp of when this result was produced (confirmation or failure).