docs: strip task-tracking IDs from code comments and fill missing XML docs
Tracking IDs are review bookkeeping that rots in shipped source; the rationale they tagged is kept. Comment-only change (CommentChecker 458 -> 16 false positives).
This commit is contained in:
@@ -43,7 +43,7 @@ public sealed class WorkerPipeSession
|
||||
|
||||
// The transport the reader and writer share, when this session was handed one to own. Null for
|
||||
// the reader/writer constructors, whose callers keep ownership of whatever streams they built the
|
||||
// pair over. Owning it is what lets teardown close the handle (WRK-31): on net48 a pipe read
|
||||
// pair over. Owning it is what lets teardown close the handle: on net48 a pipe read
|
||||
// parked in the kernel cannot be cancelled, only unblocked by disposal.
|
||||
private readonly Stream? _transportStream;
|
||||
|
||||
@@ -175,7 +175,7 @@ public sealed class WorkerPipeSession
|
||||
|
||||
// Closing the transport is what actually ends a pipe read parked in the kernel: on net48
|
||||
// NamedPipeClientStream.ReadAsync ignores its CancellationToken, so the message loop's
|
||||
// cancellation can never reach one (WRK-31). It is deliberately the LAST teardown step,
|
||||
// cancellation can never reach one. It is deliberately the LAST teardown step,
|
||||
// because in the ordinary case every frame this session will ever write has been written
|
||||
// AND flushed by the time control reaches here: WorkerFrameWriter.WriteAsync signals only
|
||||
// after both, and each exit path awaits its final write before unwinding — the shutdown
|
||||
@@ -563,7 +563,7 @@ public sealed class WorkerPipeSession
|
||||
/// task eventually faults, so a task nobody is awaiting any more can never reach the
|
||||
/// finalizer with an unobserved exception. Mirrors the shape
|
||||
/// <c>WorkerFrameWriter.ObserveAbandonedFault</c> uses for frames a cancelled caller stops
|
||||
/// awaiting (NEXT-04). Faulting is the only outcome that runs the continuation, and the
|
||||
/// awaiting. Faulting is the only outcome that runs the continuation, and the
|
||||
/// continuation is scheduled inline, so this costs nothing on the ordinary path.
|
||||
/// </summary>
|
||||
/// <param name="task">Task that may fault after its awaiter has walked away.</param>
|
||||
@@ -614,7 +614,7 @@ public sealed class WorkerPipeSession
|
||||
}
|
||||
|
||||
// Submit the whole drained batch through the writer's batch entry point under one lock
|
||||
// acquisition so the burst pays a single flush instead of one per event (WRK-25). Events
|
||||
// acquisition so the burst pays a single flush instead of one per event. Events
|
||||
// are the low-priority frame class: the writer holds them behind any pending control frame
|
||||
// (reply, fault, heartbeat, shutdown ack) so those are not delayed behind an event backlog,
|
||||
// and intra-batch order is preserved.
|
||||
@@ -634,7 +634,7 @@ public sealed class WorkerPipeSession
|
||||
when (exception.ErrorCode == WorkerFrameProtocolErrorCode.MessageTooLarge)
|
||||
{
|
||||
// A single oversized event surfaces from the batch's awaited completions; the death is
|
||||
// still IPC-30's structured, event-naming fault. Map the rejection back to the first
|
||||
// still the structured, event-naming fault. Map the rejection back to the first
|
||||
// event in batch order whose envelope overshoots the negotiated maximum — the same
|
||||
// frame the writer rejected first.
|
||||
await FaultOnOversizedEventAsync(
|
||||
@@ -665,8 +665,8 @@ public sealed class WorkerPipeSession
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Ends the session on an event that cannot be framed, but deliberately and diagnosably
|
||||
/// (IPC-30). An event above the negotiated frame maximum is undeliverable end to end — the
|
||||
/// Ends the session on an event that cannot be framed, but deliberately and diagnosably.
|
||||
/// An event above the negotiated frame maximum is undeliverable end to end — the
|
||||
/// pipe maximum sits only an envelope reserve above the public gRPC cap — so dropping it
|
||||
/// would silently make the event stream unfaithful, and synthesizing a placeholder is barred
|
||||
/// by the no-synthesized-events rule. Instead the worker records which event blocked (never
|
||||
@@ -869,7 +869,7 @@ public sealed class WorkerPipeSession
|
||||
/// overshot the frame maximum. The fallback itself is a handful of bytes, so it fits any
|
||||
/// sane negotiated maximum; the only way it can also throw <c>MessageTooLarge</c> is a
|
||||
/// pathologically tiny negotiated maximum below the gateway's validation floor — the
|
||||
/// pre-existing WRK-24 gap, which adds the negotiated-max lower bound that makes this
|
||||
/// pre-existing gap, which adds the negotiated-max lower bound that makes this
|
||||
/// unreachable. Until then, a defensive swallow keeps the "no diagnostics command is
|
||||
/// session-fatal" invariant true even in that degenerate config: the correlation goes
|
||||
/// unanswered and the gateway's own per-command timeout covers it, but the session lives.
|
||||
@@ -1028,7 +1028,7 @@ public sealed class WorkerPipeSession
|
||||
/// <c>MxCommandReply</c> does not stop at the pipe: the gateway returns it verbatim through
|
||||
/// <c>Invoke</c>, where the public gRPC send cap applies, and the gateway's validator
|
||||
/// couples the two limits so the pipe maximum never exceeds the gRPC cap by more than two
|
||||
/// reserves (IPC-33). Subtracting both therefore keeps the packed events at or below the
|
||||
/// reserves. Subtracting both therefore keeps the packed events at or below the
|
||||
/// gRPC cap and leaves the wrapper — correlation id, protocol status, kind, the
|
||||
/// <c>drain_events</c> length prefix and, in the truncated case, the
|
||||
/// <c>DiagnosticMessage</c> — a full reserve of margin under it. Budgeting against the pipe
|
||||
@@ -1246,8 +1246,8 @@ public sealed class WorkerPipeSession
|
||||
_activeCommandTasks.Add(commandTask);
|
||||
}
|
||||
|
||||
// WRK-33: every other discarded task in this file is wrapped with ObserveFaultWhenever
|
||||
// (NEXT-04 discipline) so a fault reaching the finalizer unobserved is impossible. This
|
||||
// Every other discarded task in this file is wrapped with ObserveFaultWhenever
|
||||
// (the fault-observation discipline) so a fault reaching the finalizer unobserved is impossible. This
|
||||
// wrapper task was the one exception — ObserveCommandTaskAsync only swallows
|
||||
// OperationCanceledException, so any other exception escaping ProcessCommandAsync's own
|
||||
// catch path (e.g. a future edit, or a failure past TryWriteFaultAsync's narrow filter)
|
||||
@@ -1380,7 +1380,7 @@ public sealed class WorkerPipeSession
|
||||
if ((!string.IsNullOrEmpty(snapshot.CurrentCommandCorrelationId) || snapshot.StaCallInProgress)
|
||||
&& staleFor <= _sessionOptions.HeartbeatStuckCeiling)
|
||||
{
|
||||
// A command is in flight, or an STA call outside the dispatcher (the alarm poll, WRK-27) is
|
||||
// A command is in flight, or an STA call outside the dispatcher (the alarm poll) is
|
||||
// executing, and we are still within the defensive suppression ceiling — the STA is busy
|
||||
// doing that work, not hung. The next MarkActivity() in StaRuntime.ProcessQueuedCommands
|
||||
// will refresh LastActivityUtc once the work returns, at which point this branch stops
|
||||
@@ -1402,7 +1402,7 @@ public sealed class WorkerPipeSession
|
||||
// the StaHung fault just sent. Without this the heartbeat loop keeps
|
||||
// advertising a non-faulted state that contradicts the fault.
|
||||
_state = WorkerState.Faulted;
|
||||
// WRK-34: CommandMethod is a method-name field, not a correlation-id field, so a
|
||||
// CommandMethod is a method-name field, not a correlation-id field, so a
|
||||
// consumer reading it (dashboard, gateway logs) shouldn't see a bare correlation id
|
||||
// there. Use a stable label and carry the stuck command's correlation id (if any) in
|
||||
// the diagnostic message instead.
|
||||
|
||||
Reference in New Issue
Block a user