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:
@@ -521,7 +521,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
/// Control-frame completion decoupling. The boundary flush is charged per class run, not per
|
||||
/// control frame: a pass carrying nothing but control frames still pays exactly one flush. Flushing
|
||||
/// after every control frame
|
||||
/// would reinstate the syscall-per-heartbeat cost WRK-12 removed.
|
||||
/// would reinstate the syscall-per-heartbeat cost the earlier per-frame flush design incurred.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
@@ -592,7 +592,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Verifies a per-frame rejection does not burn a sequence number (WRK-23). The sequence is a
|
||||
/// Verifies a per-frame rejection does not burn a sequence number. The sequence is a
|
||||
/// diagnostic counter, so a gap breaks nothing functionally — but an operator correlating a pipe
|
||||
/// capture reads a gap as a lost frame and chases a bug that does not exist, and the gap-free
|
||||
/// guarantee the concurrent-write test asserts would otherwise only hold until the first
|
||||
@@ -664,7 +664,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
|
||||
/// <summary>
|
||||
/// Verifies a negotiated frame maximum below the worker floor is rejected as
|
||||
/// <c>InvalidConfiguration</c> (WRK-24), and that exactly the floor is adopted. The floor matches
|
||||
/// <c>InvalidConfiguration</c> and that exactly the floor is adopted. The floor matches
|
||||
/// the gateway's own <c>GatewayOptionsValidator.MinimumMaxMessageBytes</c>, so the worker never
|
||||
/// rejects a value the gateway's validator accepts, yet a nonsensical tiny value faults at the
|
||||
/// handshake instead of leaving a session that fails every later frame.
|
||||
@@ -684,7 +684,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-22 / IPC-26. A <c>WriteAsync</c> cancelled while it waits for the write lock must never
|
||||
/// A <c>WriteAsync</c> cancelled while it waits for the write lock must never
|
||||
/// have its frame written by the next lock-holder. Writer A holds the lock mid-write (blocked in
|
||||
/// the stream); an event write is queued and then cancelled; when A is released and a later
|
||||
/// control frame drains, the wire carries A's frame and the control frame only — the cancelled
|
||||
@@ -727,7 +727,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// NEXT-04. A frame claimed by the draining lock-holder before its caller's cancellation lands
|
||||
/// A frame claimed by the draining lock-holder before its caller's cancellation lands
|
||||
/// is abandoned — the cancelled caller never awaits its completion. If the wire write then
|
||||
/// faults, the tombstone path's fault-observing continuation must still observe the exception
|
||||
/// so it never surfaces as <see cref="TaskScheduler.UnobservedTaskException"/>.
|
||||
@@ -791,7 +791,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-22 / IPC-26, the review's shutdown scenario. A cancelled event frame queued before a
|
||||
/// Shutdown scenario: a cancelled event frame queued before a
|
||||
/// shutdown-ack control frame must not trail the ack on the wire: the tombstone rule plus the
|
||||
/// control-before-event scheduler keeps the ack the last frame written.
|
||||
/// </summary>
|
||||
@@ -830,9 +830,9 @@ public sealed class WorkerFrameProtocolTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-25. The batch entry point enqueues a whole event burst under one lock acquisition and
|
||||
/// The batch entry point enqueues a whole event burst under one lock acquisition and
|
||||
/// drains it together, so N events cost exactly one flush and reach the wire in batch order with
|
||||
/// monotonic sequences — the coalescing WRK-12 shipped, now on the event hot path.
|
||||
/// monotonic sequences — the flush coalescing now on the event hot path.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
[Fact]
|
||||
@@ -868,7 +868,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-25. Control-before-event still holds mid-batch: a control frame queued while a batch is
|
||||
/// Control-before-event still holds mid-batch: a control frame queued while a batch is
|
||||
/// draining jumps ahead of the batch's remaining events.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
@@ -1223,7 +1223,7 @@ public sealed class WorkerFrameProtocolTests
|
||||
|
||||
// A MemoryStream whose first write blocks until released and whose second write blocks until
|
||||
// released and then throws, so a test can abandon a claimed frame by cancellation and fault its
|
||||
// wire write afterwards (NEXT-04).
|
||||
// wire write afterwards.
|
||||
private sealed class SecondWriteFaultingGatedStream : MemoryStream
|
||||
{
|
||||
private readonly SemaphoreSlim _firstRelease = new SemaphoreSlim(0);
|
||||
@@ -1235,6 +1235,8 @@ public sealed class WorkerFrameProtocolTests
|
||||
private readonly string _faultMessage;
|
||||
private int _writeCount;
|
||||
|
||||
/// <summary>Initializes a new instance of the <see cref="SecondWriteFaultingGatedStream"/> class.</summary>
|
||||
/// <param name="faultMessage">The message of the exception thrown by the second write.</param>
|
||||
public SecondWriteFaultingGatedStream(string faultMessage)
|
||||
{
|
||||
_faultMessage = faultMessage;
|
||||
|
||||
@@ -20,7 +20,7 @@ public sealed class WorkerPipeSessionTests
|
||||
private const string SessionId = "session-1";
|
||||
private const string Nonce = "nonce-secret";
|
||||
|
||||
// Byte-heavy drain fixture (WRK-21). 10,000 events at ~1.7 KiB each is ~17 MB of queue — far
|
||||
// Byte-heavy drain fixture. 10,000 events at ~1.7 KiB each is ~17 MB of queue — far
|
||||
// more than one frame — so DrainEvents must truncate.
|
||||
//
|
||||
// Two limits below are harness accommodations, not properties of the fix. PipePair runs both
|
||||
@@ -559,7 +559,7 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The WRK-21 repro. A queue full of byte-heavy events (large string values — the payload
|
||||
/// The repro for the oversized drain reply. A queue full of byte-heavy events (large string values — the payload
|
||||
/// profile this gateway exists for) used to make <c>DrainEvents max_events = 0</c> build a
|
||||
/// reply above the negotiated frame maximum: the writer rejected the frame, the exception
|
||||
/// unwound the session, and the already-dequeued events were gone. The drain is now
|
||||
@@ -703,7 +703,7 @@ public sealed class WorkerPipeSessionTests
|
||||
{
|
||||
// The lowest Worker.MaxMessageBytes GatewayOptionsValidator permits: the public gRPC floor
|
||||
// (1024) plus the 64 KiB envelope-overhead reserve. The naive budget — frame max less the
|
||||
// two reserves the DrainEvents budget subtracts (IPC-33) — would be negative here; the
|
||||
// two reserves the DrainEvents budget subtracts — would be negative here; the
|
||||
// floored budget is half of the frame max (~33 KiB).
|
||||
const uint validatorFloorFrameMax = 1024 + (64 * 1024);
|
||||
using CancellationTokenSource cancellation = new(TimeSpan.FromSeconds(60));
|
||||
@@ -761,7 +761,7 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Verifies the control-reply write seam is not session-fatal on size (WRK-21 backstop). The
|
||||
/// Verifies the control-reply write seam is not session-fatal on size (the drain backstop). The
|
||||
/// reply builders size their payloads, so this path needs a deliberately budget-blind drain
|
||||
/// to reach — but that is the point: a future command or a sizing bug must degrade to an
|
||||
/// error reply for that correlation, never to a dead session.
|
||||
@@ -859,7 +859,7 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// IPC-30. An event above the negotiated frame maximum is undeliverable end to end (the pipe
|
||||
/// 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 the session stays
|
||||
/// fatal by design — but the death must be structured: a WorkerFault naming the event, with
|
||||
/// no value payload in it, before the process exits. Silently dropping the event or
|
||||
@@ -915,7 +915,7 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-31, the other side of the invariant. The graceful path leaves the message loop
|
||||
/// The other side of the transport-ownership invariant. The graceful path leaves the message loop
|
||||
/// through its <c>return</c> after the shutdown ack, with that iteration's read already
|
||||
/// awaited — so there is no abandoned read for teardown to account for. Pinning this keeps
|
||||
/// the new disposal-and-observe step a pure no-op on the path production takes every time a
|
||||
@@ -955,7 +955,7 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-31. The session now owns and closes the transport rather than leaving it to
|
||||
/// The session now owns and closes the transport rather than leaving it to
|
||||
/// <c>WorkerPipeClient</c>'s <c>using</c>, because the read it unblocks has to be observed
|
||||
/// while the session still holds it. This asserts the closure actually happens on the
|
||||
/// session's own timeline: the gateway end of the pipe must see disconnection while
|
||||
@@ -1250,7 +1250,7 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-27. An STA call outside the command dispatcher (the alarm poll) advertises itself on
|
||||
/// An STA call outside the command dispatcher (the alarm poll) advertises itself on
|
||||
/// the heartbeat snapshot's <c>StaCallInProgress</c> flag, and the watchdog grants it the same
|
||||
/// grace-to-ceiling suppression as a dispatched command: stale STA activity within the ceiling
|
||||
/// does not fault while the flag is set, but stale activity beyond the ceiling faults anyway.
|
||||
@@ -1340,8 +1340,8 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-25. The event drain loop submits a whole drained batch through the writer's batch entry
|
||||
/// point, so a burst of 128 events costs one flush, not 128 — the assertion the WRK-12
|
||||
/// The event drain loop submits a whole drained batch through the writer's batch entry
|
||||
/// point, so a burst of 128 events costs one flush, not 128 — the assertion the
|
||||
/// tracking claim needed to actually hold on the event hot path.
|
||||
/// </summary>
|
||||
/// <returns>A task that represents the asynchronous operation.</returns>
|
||||
@@ -1413,7 +1413,7 @@ public sealed class WorkerPipeSessionTests
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WRK-24. A GatewayHello negotiating a frame maximum below the worker floor faults at the
|
||||
/// A GatewayHello negotiating a frame maximum below the worker floor faults at the
|
||||
/// handshake with a fault frame rather than being adopted — mirroring the above-ceiling
|
||||
/// handshake behavior — so a nonsensical tiny value never leaves a session that fails every
|
||||
/// later frame. No message loop is entered.
|
||||
@@ -2338,7 +2338,7 @@ public sealed class WorkerPipeSessionTests
|
||||
public sealed class AbandonedPipeReadTeardownTests
|
||||
{
|
||||
/// <summary>
|
||||
/// WRK-31. A fault exit unwinds the message loop while its frame read is still pending,
|
||||
/// A fault exit unwinds the message loop while its frame read is still pending,
|
||||
/// and on net48 nothing can cancel that read — <c>NamedPipeClientStream.ReadAsync</c>
|
||||
/// ignores the token, so only closing the handle ends it. The session must therefore
|
||||
/// dispose the transport itself and account for the read that disposal unblocks: the
|
||||
|
||||
Reference in New Issue
Block a user