docs(quic): what ~ClientQUIC lets finish before it closes
The README and the consumer notes say that a reply sent on a stream let go just before deleting the connection still arrives, and the agent notes add the gotcha with the test that guards it, and count 39 tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
4876ff14a8
commit
79a2f12629
GPG key ID:
2937E59CDCC1BCFB
3 changed files with 5 additions and 4 deletions
|
|
@ -83,7 +83,7 @@ A route map is `std::unordered_map<std::string, std::function<HTTPResponse(const
|
||||||
- `OpenStream(unidirectional = false)` returns a `QUICStream` whose start msquic has queued (it starts asynchronously, whatever the interface comment says), or throws `QUICException` when it cannot be opened; `GetStreamId()` throws until the stream has started, so call it once the stream has carried data. `SendDatagram(buffer, size)` is best effort within the path MTU (about 1200 bytes on the open internet) and throws `QUICException` when msquic refuses it. `OnStream(callback(QUICStream))` receives the streams the peer opens; streams that arrived before it was set are queued and delivered when it is, so setting it after the constructor returns is fine. `OnDatagram(callback(std::vector<char>))`; without one, datagrams queue for `RecieveDatagramSync()`, which blocks and throws `QUICClosedException` when the connection closes first. A datagram that arrives before `OnDatagram` is set goes to that queue, never to the callback: a server that sets `OnDatagram` in `connectCallback` can miss one sent right after the handshake (`tests/ShouldSendRecieveQUICDatagram` sleeps 200 ms for it). Both callbacks run as pool tasks. `Stop()` initiates a clean shutdown and returns. `GetHandle()` is the msquic `HQUIC`.
|
- `OpenStream(unidirectional = false)` returns a `QUICStream` whose start msquic has queued (it starts asynchronously, whatever the interface comment says), or throws `QUICException` when it cannot be opened; `GetStreamId()` throws until the stream has started, so call it once the stream has carried data. `SendDatagram(buffer, size)` is best effort within the path MTU (about 1200 bytes on the open internet) and throws `QUICException` when msquic refuses it. `OnStream(callback(QUICStream))` receives the streams the peer opens; streams that arrived before it was set are queued and delivered when it is, so setting it after the constructor returns is fine. `OnDatagram(callback(std::vector<char>))`; without one, datagrams queue for `RecieveDatagramSync()`, which blocks and throws `QUICClosedException` when the connection closes first. A datagram that arrives before `OnDatagram` is set goes to that queue, never to the callback: a server that sets `OnDatagram` in `connectCallback` can miss one sent right after the handshake (`tests/ShouldSendRecieveQUICDatagram` sleeps 200 ms for it). Both callbacks run as pool tasks. `Stop()` initiates a clean shutdown and returns. `GetHandle()` is the msquic `HQUIC`.
|
||||||
- **`OnClosed(callback())`** fires once when the connection has shut down for any reason but its own destruction: the peer closed it, the idle timeout or a transport error ended it, or `Stop()`. It runs on msquic's worker thread, after the handle is closed, and deleting this `ClientQUIC` from inside it is safe, which is what it is for; if the connection had already closed when `OnClosed` was called (the peer went before `connectCallback` ran), it runs as a pool task instead, never inside `OnClosed`. Inside it: nothing that blocks, no `*Sync` call, no deleting a *different* `ClientQUIC` (its destructor waits on msquic workers, this one perhaps among them), no throwing. `std::stop_callback` rules: once `~ClientQUIC` has begun it never starts, and the destructor waits for a run already under way on another thread, so never destroy a `ClientQUIC` while holding a lock the callback takes, or the two deadlock. Calling it again replaces the callback, an empty one unregisters, and once it has fired later calls do nothing. Two owners deleting one `ClientQUIC` (the callback and a shutdown path) is still a double delete: keep peers in a map under a mutex, and let whoever removes one delete it, outside the lock.
|
- **`OnClosed(callback())`** fires once when the connection has shut down for any reason but its own destruction: the peer closed it, the idle timeout or a transport error ended it, or `Stop()`. It runs on msquic's worker thread, after the handle is closed, and deleting this `ClientQUIC` from inside it is safe, which is what it is for; if the connection had already closed when `OnClosed` was called (the peer went before `connectCallback` ran), it runs as a pool task instead, never inside `OnClosed`. Inside it: nothing that blocks, no `*Sync` call, no deleting a *different* `ClientQUIC` (its destructor waits on msquic workers, this one perhaps among them), no throwing. `std::stop_callback` rules: once `~ClientQUIC` has begun it never starts, and the destructor waits for a run already under way on another thread, so never destroy a `ClientQUIC` while holding a lock the callback takes, or the two deadlock. Calling it again replaces the callback, an empty one unregisters, and once it has fired later calls do nothing. Two owners deleting one `ClientQUIC` (the callback and a shutdown path) is still a double delete: keep peers in a map under a mutex, and let whoever removes one delete it, outside the lock.
|
||||||
- **`QUICStream`** is move-only, with `connection`, `canSend`, `canReceive` (a unidirectional stream has one of them false) and the msquic `handle`. `SendSync(buffer, size, finish = false)` blocks until msquic has taken the buffer, throws `QUICClosedException` when the stream or connection was closed before that send completed and `QUICException` when msquic refused it outright; `finish` closes the send side after it (the peer's `RecieveUntilCloseSync` returns). `RecieveSync()` waits for at least one byte and throws `QUICClosedException` once the peer closed its side and the buffer is drained; `RecieveUntilCloseSync()`; `RecieveUntilFullSync(n)` takes exactly `n` or throws and leaves what arrived for the next receive. `SendAsync(buffer, size, finish, onSent(bool))` holds no thread natively: it copies the buffer, hands the copy to msquic and returns, and msquic's `SEND_COMPLETE` fires `onSent` exactly once on the msquic worker, `true` once msquic took the whole buffer (buffered or acknowledged, not a receipt from the peer's application), `false` when the stream or connection closed first; sends queue in call order, from any thread and from inside callbacks, never waiting for one another; a send msquic never took (closed stream, moved-from wrapper) reports `false` from a pool task, never inside `SendAsync`; `onSent` must not block (no `*Sync` call: it would wait for the worker it runs on) or throw, and still fires after the wrapper is destroyed, whose `Stop()` lets the sends already made go out before the FIN. `BytesInFlight()` and `SendsInFlight()` count what `SendAsync`/`SendSync` handed msquic that has not completed: how far behind the peer is, so a server can drop a follower past a cap. **`OnRecieve(onData(std::span<const char>), onEnd(bool clean))`** receives without a thread: `onData` gets each run of bytes as it arrives (the span is valid for the call only), `onEnd` fires once after the last of them, `true` for the peer's FIN, `false` for a reset by either side or a connection that went first. Bytes that arrived before the call are delivered by it, on the calling thread, before it returns (with the end, if that came too); afterwards the callbacks run on the msquic worker. No two callbacks of one stream, `onSent` included, ever run at once. Inside them: `SendAsync`, `Abort`, the in-flight counters, destroying or moving the wrapper; never a `*Sync` call (it waits for the worker it runs on), `~ClientQUIC`, anything that blocks, or a throw. Destroying the wrapper or `Stop()` unregisters both, `std::stop_callback`-style: neither runs once it returns, it waits for one running on another thread (so never destroy a stream under a lock its callbacks take), and an `onEnd` not yet delivered never is. To reach the stream from its own callbacks, hold it in a `shared_ptr` and capture a `weak_ptr`. Once per stream (a second call throws `QUICException`), not mixed with the `Recieve*` calls, which then get nothing; a stream that cannot receive, or a closed one, gets `onEnd(false)` at once. **`Abort(errorCode = 0)`** resets both directions with a 62-bit application error code, from any thread or from inside `onData` (a byte cap): sends msquic has not taken yet report `false` (those already in its send buffer reported `true` and are discarded by the reset), no `onData` follows, `onEnd(false)` does; `RecieveAsync`, `RecieveUntilCloseAsync` and `RecieveUntilFullAsync(n, ...)` give a closed stream an empty chunk and an early close what arrived, never an exception. A default-constructed `QUICStream` behaves as closed. `PrependReceived(bytes)` pushes bytes back for the next receive (a demuxer that peeked a prefix); `GetStreamId()` throws `QUICException` before the stream has started; `Stop()` shuts both directions down (the send side with a FIN, the receive side abortively, else a peer holding its side open keeps the handle alive), completes asynchronously, and is what the destructor calls.
|
- **`QUICStream`** is move-only, with `connection`, `canSend`, `canReceive` (a unidirectional stream has one of them false) and the msquic `handle`. `SendSync(buffer, size, finish = false)` blocks until msquic has taken the buffer, throws `QUICClosedException` when the stream or connection was closed before that send completed and `QUICException` when msquic refused it outright; `finish` closes the send side after it (the peer's `RecieveUntilCloseSync` returns). `RecieveSync()` waits for at least one byte and throws `QUICClosedException` once the peer closed its side and the buffer is drained; `RecieveUntilCloseSync()`; `RecieveUntilFullSync(n)` takes exactly `n` or throws and leaves what arrived for the next receive. `SendAsync(buffer, size, finish, onSent(bool))` holds no thread natively: it copies the buffer, hands the copy to msquic and returns, and msquic's `SEND_COMPLETE` fires `onSent` exactly once on the msquic worker, `true` once msquic took the whole buffer (buffered or acknowledged, not a receipt from the peer's application), `false` when the stream or connection closed first; sends queue in call order, from any thread and from inside callbacks, never waiting for one another; a send msquic never took (closed stream, moved-from wrapper) reports `false` from a pool task, never inside `SendAsync`; `onSent` must not block (no `*Sync` call: it would wait for the worker it runs on) or throw, and still fires after the wrapper is destroyed, whose `Stop()` lets the sends already made go out before the FIN. `BytesInFlight()` and `SendsInFlight()` count what `SendAsync`/`SendSync` handed msquic that has not completed: how far behind the peer is, so a server can drop a follower past a cap. **`OnRecieve(onData(std::span<const char>), onEnd(bool clean))`** receives without a thread: `onData` gets each run of bytes as it arrives (the span is valid for the call only), `onEnd` fires once after the last of them, `true` for the peer's FIN, `false` for a reset by either side or a connection that went first. Bytes that arrived before the call are delivered by it, on the calling thread, before it returns (with the end, if that came too); afterwards the callbacks run on the msquic worker. No two callbacks of one stream, `onSent` included, ever run at once. Inside them: `SendAsync`, `Abort`, the in-flight counters, destroying or moving the wrapper; never a `*Sync` call (it waits for the worker it runs on), `~ClientQUIC`, anything that blocks, or a throw. Destroying the wrapper or `Stop()` unregisters both, `std::stop_callback`-style: neither runs once it returns, it waits for one running on another thread (so never destroy a stream under a lock its callbacks take), and an `onEnd` not yet delivered never is. To reach the stream from its own callbacks, hold it in a `shared_ptr` and capture a `weak_ptr`. Once per stream (a second call throws `QUICException`), not mixed with the `Recieve*` calls, which then get nothing; a stream that cannot receive, or a closed one, gets `onEnd(false)` at once. **`Abort(errorCode = 0)`** resets both directions with a 62-bit application error code, from any thread or from inside `onData` (a byte cap): sends msquic has not taken yet report `false` (those already in its send buffer reported `true` and are discarded by the reset), no `onData` follows, `onEnd(false)` does; `RecieveAsync`, `RecieveUntilCloseAsync` and `RecieveUntilFullAsync(n, ...)` give a closed stream an empty chunk and an early close what arrived, never an exception. A default-constructed `QUICStream` behaves as closed. `PrependReceived(bytes)` pushes bytes back for the next receive (a demuxer that peeked a prefix); `GetStreamId()` throws `QUICException` before the stream has started; `Stop()` shuts both directions down (the send side with a FIN, the receive side abortively, else a peer holding its side open keeps the handle alive), completes asynchronously, and is what the destructor calls.
|
||||||
- Lifetimes: `~ClientQUIC` first destroys peer streams nobody claimed, then shuts the connection down and closes it, waiting up to 5 s for every stream on it to finish closing and then up to 1 s (a round trip, when the peer answers) for the shutdown to complete, so the peer is sent the close and hears of it at once, not at its idle timeout. A connection whose peer is already gone, or one still in its handshake, can take that whole second. Streams may outlive their connection, dead; destroy or `Stop()` them first when you can. msquic has two process-wide registrations here, one for clients and one for listeners and the peers they accept, each closed by a static destructor at exit, and each close blocks until every connection and stream handle opened under it is closed: an accepted peer you never deleted holds the listener's until the idle timeout, two minutes by default. Delete or `Stop()` what you own before `main` returns, or end with `std::_Exit` after flushing, as the library's own tests do.
|
- Lifetimes: `~ClientQUIC` first destroys peer streams nobody claimed, then lets the streams already stopped finish (up to 1 s, a round trip when the peer answers), so a reply sent with `SendAsync(..., finish = true)` on a stream let go just before still arrives, then shuts the connection down, which aborts any stream still open, and closes it, waiting up to 5 s for every stream on it to finish closing and then up to 1 s (a round trip, when the peer answers) for the shutdown to complete, so the peer is sent the close and hears of it at once, not at its idle timeout. A connection whose peer is already gone, or one still in its handshake, can take that whole second. Streams may outlive their connection, dead; destroy or `Stop()` them first when you can. msquic has two process-wide registrations here, one for clients and one for listeners and the peers they accept, each closed by a static destructor at exit, and each close blocks until every connection and stream handle opened under it is closed: an accepted peer you never deleted holds the listener's until the idle timeout, two minutes by default. Delete or `Stop()` what you own before `main` returns, or end with `std::_Exit` after flushing, as the library's own tests do.
|
||||||
|
|
||||||
**`ListenerQUIC(port, alpn, QUICServerCredentials, connectCallback(ClientQUIC*), concurrentClientLimit, totalClientLimit)`** listens on every address of both families and throws `QUICException` when it cannot. **`ListenerQUIC(bindAddress, port, alpn, ...)`**, same arguments after the address, listens on one: numeric only (`127.0.0.1` or `::1` for this machine alone, `0.0.0.0` or `::` for every address of one family; `localhost` throws `QUICException`). msquic still binds the UDP port on every address and drops, at its own layer, a connection sent to another one: the client fails within milliseconds with `QUIC_STATUS_ALPN_NEG_FAILURE` (0x5c) and connectCallback never hears of it. A listener on `127.0.0.1` is not reachable through `::1`, so its clients dial `127.0.0.1`, not `localhost`. `Port()` is the UDP port it bound: pass port 0 to let msquic pick a free one and read it back (still valid after `Stop()`, 0 on a moved-from listener). The callback's `ClientQUIC*` is heap-allocated and yours: set `OnStream` / `OnDatagram` on it, keep it as long as the connection should live, `Stop()` or `delete` it to shut the connection down, and `delete` it in any case, since only that frees it (a connection the peer or the idle timeout ended has its msquic handle closed for it, but the object stays): `OnClosed` says when, and `peer->OnClosed([peer] { delete peer; })` in the callback is the whole of it for a server that keeps no other reference. `ListenSyncSync()` runs the accept loop on the calling thread and the callback there; `ListenSyncAsync()` runs the callback as a pool task; `ListenAsyncSync()` and `ListenAsyncAsync()` run the loop on a thread of their own, the second with the callback on the pool. `Stop()` stops accepting; the destructor stops, joins, and deletes peers accepted but not yet handed out. `totalClientLimit` ends the hand-off loop after that many connections (later ones queue until the listener is destroyed); `concurrentClientLimit` is stored and not enforced.
|
**`ListenerQUIC(port, alpn, QUICServerCredentials, connectCallback(ClientQUIC*), concurrentClientLimit, totalClientLimit)`** listens on every address of both families and throws `QUICException` when it cannot. **`ListenerQUIC(bindAddress, port, alpn, ...)`**, same arguments after the address, listens on one: numeric only (`127.0.0.1` or `::1` for this machine alone, `0.0.0.0` or `::` for every address of one family; `localhost` throws `QUICException`). msquic still binds the UDP port on every address and drops, at its own layer, a connection sent to another one: the client fails within milliseconds with `QUIC_STATUS_ALPN_NEG_FAILURE` (0x5c) and connectCallback never hears of it. A listener on `127.0.0.1` is not reachable through `::1`, so its clients dial `127.0.0.1`, not `localhost`. `Port()` is the UDP port it bound: pass port 0 to let msquic pick a free one and read it back (still valid after `Stop()`, 0 on a moved-from listener). The callback's `ClientQUIC*` is heap-allocated and yours: set `OnStream` / `OnDatagram` on it, keep it as long as the connection should live, `Stop()` or `delete` it to shut the connection down, and `delete` it in any case, since only that frees it (a connection the peer or the idle timeout ended has its msquic handle closed for it, but the object stays): `OnClosed` says when, and `peer->OnClosed([peer] { delete peer; })` in the callback is the whole of it for a server that keeps no other reference. `ListenSyncSync()` runs the accept loop on the calling thread and the callback there; `ListenSyncAsync()` runs the callback as a pool task; `ListenAsyncSync()` and `ListenAsyncAsync()` run the loop on a thread of their own, the second with the callback on the pool. `Stop()` stops accepting; the destructor stops, joins, and deletes peers accepted but not yet handed out. `totalClientLimit` ends the hand-off loop after that many connections (later ones queue until the listener is destroyed); `concurrentClientLimit` is stored and not enforced.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -28,7 +28,7 @@ Partitions and what they own:
|
||||||
- `:URL`: `URL`, an absolute URL as RFC 3986 reads it (`Parse`), the resolution of a reference against it (`Resolve`, RFC 3986 §5.2, dot segments removed), the recomposition, and the pieces a request is built from. Inline, native only; what `ClientHTTP1::Fetch` follows a Location with.
|
- `:URL`: `URL`, an absolute URL as RFC 3986 reads it (`Parse`), the resolution of a reference against it (`Resolve`, RFC 3986 §5.2, dot segments removed), the recomposition, and the pieces a request is built from. Inline, native only; what `ClientHTTP1::Fetch` follows a Location with.
|
||||||
- `:HTTP1`: the RFC 9112 codec, inline: `SerializeRequest`, `SerializeResponse`, `SerializeContinue`, `MessageParser`, `MessageLimits`, `HTTP1ProtocolError`, and the framing it refuses to guess at.
|
- `:HTTP1`: the RFC 9112 codec, inline: `SerializeRequest`, `SerializeResponse`, `SerializeContinue`, `MessageParser`, `MessageLimits`, `HTTP1ProtocolError`, and the framing it refuses to guess at.
|
||||||
- `:ClientHTTP1`, `:ListenerHTTP1`: HTTP/1.1 over a `ByteStream&`. The listener is a `ListenerTCP` with a thread per accepted connection; the client keeps one pooled connection with a replay-once rule, and `ClientHTTP1::Fetch` is the URL fetch that follows redirects by RFC 9110 §15.4 with a client per hop (`FetchOptions`, `FetchResult`, `FetchStop`).
|
- `:ClientHTTP1`, `:ListenerHTTP1`: HTTP/1.1 over a `ByteStream&`. The listener is a `ListenerTCP` with a thread per accepted connection; the client keeps one pooled connection with a replay-once rule, and `ClientHTTP1::Fetch` is the URL fetch that follows redirects by RFC 9110 §15.4 with a client per hop (`FetchOptions`, `FetchResult`, `FetchStop`).
|
||||||
- `:ClientQUIC`: `ClientQUIC` and `QUICStream` for both ends of a connection, `QUICSettings`, both QUIC credential structs, `QUICException`, `QUICClosedException`. The native unit holds the process-wide `MsQuicRuntime` (API table and registration, closed by a static destructor at exit), the stream registry with its refcounted handles, a `SendRequest` per send carrying its own outcome, the per-stream delivery of `OnRecieve`'s and `SendAsync`'s callbacks (whichever thread finds nobody delivering runs what is ready; the rest queue and return), the `CloseNotice` behind `OnClosed`, and the drain in `~ClientQUIC` (streams, then the connection's own `SHUTDOWN_COMPLETE`).
|
- `:ClientQUIC`: `ClientQUIC` and `QUICStream` for both ends of a connection, `QUICSettings`, both QUIC credential structs, `QUICException`, `QUICClosedException`. The native unit holds the process-wide `MsQuicRuntime` (API table and registration, closed by a static destructor at exit), the stream registry with its refcounted handles, a `SendRequest` per send carrying its own outcome, the per-stream delivery of `OnRecieve`'s and `SendAsync`'s callbacks (whichever thread finds nobody delivering runs what is ready; the rest queue and return), the `CloseNotice` behind `OnClosed`, and the drain in `~ClientQUIC` (the streams already stopped, then every stream, then the connection's own `SHUTDOWN_COMPLETE`).
|
||||||
- `:ListenerQUIC`: the msquic listener, its four `Listen*` variants, the self-signed certificate's on-disk cache (per user under `$XDG_CACHE_HOME/crafter-network/quic-cert/`, behind a lock; the OpenSSL work is module-internal functions of `:TLS`), `ComputeCertificateHashSHA256`, `GetSelfSignedCertificatePath`.
|
- `:ListenerQUIC`: the msquic listener, its four `Listen*` variants, the self-signed certificate's on-disk cache (per user under `$XDG_CACHE_HOME/crafter-network/quic-cert/`, behind a lock; the OpenSSL work is module-internal functions of `:TLS`), `ComputeCertificateHashSHA256`, `GetSelfSignedCertificatePath`.
|
||||||
- `:HTTP3`: QUIC varints, HTTP/3 frames, the QPACK static table, Huffman decoding, the control-stream preludes and the WebTransport stream prefixes. Native only: it throws for protocol errors.
|
- `:HTTP3`: QUIC varints, HTTP/3 frames, the QPACK static table, Huffman decoding, the control-stream preludes and the WebTransport stream prefixes. Native only: it throws for protocol errors.
|
||||||
- `:ClientHTTP`, `:ListenerHTTP`: HTTP/3 on `:ClientQUIC` and `:ListenerQUIC`. The listener demuxes every bidirectional stream into an HTTP/3 request or a WebTransport data stream and accepts extended CONNECT when `wtRoutes` is non-empty.
|
- `:ClientHTTP`, `:ListenerHTTP`: HTTP/3 on `:ClientQUIC` and `:ListenerQUIC`. The listener demuxes every bidirectional stream into an HTTP/3 request or a WebTransport data stream and accepts extended CONNECT when `wtRoutes` is non-empty.
|
||||||
|
|
@ -51,7 +51,7 @@ crafter-build # native: TCP, TLS, HTTP/1.1, QUI
|
||||||
crafter-build --no-quic # native without QUIC, HTTP/3, WebTransport and msquic
|
crafter-build --no-quic # native without QUIC, HTTP/3, WebTransport and msquic
|
||||||
crafter-build --local # Crafter.Thread from ../Crafter.Thread
|
crafter-build --local # Crafter.Thread from ../Crafter.Thread
|
||||||
crafter-build --target=wasm32-wasip1 # the browser library
|
crafter-build --target=wasm32-wasip1 # the browser library
|
||||||
crafter-build test # the suite, native: 38 tests
|
crafter-build test # the suite, native: 39 tests
|
||||||
crafter-build test 'Should*HTTP1' # a name glob
|
crafter-build test 'Should*HTTP1' # a name glob
|
||||||
crafter-build test --no-quic # the TCP, URL, TLS and HTTP/1.1 tests plus ShouldBuildWithoutQUIC: 19
|
crafter-build test --no-quic # the TCP, URL, TLS and HTTP/1.1 tests plus ShouldBuildWithoutQUIC: 19
|
||||||
crafter-build test --list
|
crafter-build test --list
|
||||||
|
|
@ -123,6 +123,7 @@ Decided deliberately; change them only with the maintainer's say-so.
|
||||||
- **`:TLS` declares module-internal functions** (`MakeWebTransportCertificatePem`, `CertificatePairExpiry`, `EncodePkcs12`, `CertificateSha256`) without `export`: `:ListenerQUIC` imports `:TLS` for them so libssl stays behind one partition, and a consumer never sees them.
|
- **`:TLS` declares module-internal functions** (`MakeWebTransportCertificatePem`, `CertificatePairExpiry`, `EncodePkcs12`, `CertificateSha256`) without `export`: `:ListenerQUIC` imports `:TLS` for them so libssl stays behind one partition, and a consumer never sees them.
|
||||||
- **msquic's registration is closed by a static destructor that waits for every handle.** A test that returns from `main` with an accepted peer alive waits two minutes, the idle timeout; the tests `_Exit`. The exception, `ShouldSurviveConnectionChurn`, exists because a leaked stream handle once hung that close forever (`fix(quic)` in `git log`, with the `SHUTDOWN_ON_FAIL` story).
|
- **msquic's registration is closed by a static destructor that waits for every handle.** A test that returns from `main` with an accepted peer alive waits two minutes, the idle timeout; the tests `_Exit`. The exception, `ShouldSurviveConnectionChurn`, exists because a leaked stream handle once hung that close forever (`fix(quic)` in `git log`, with the `SHUTDOWN_ON_FAIL` story).
|
||||||
- **Callbacks the interfaces say run "on the msquic worker" run as pool tasks**: `ClientQUIC::OnStream` and `OnDatagram` both enqueue. What arrives before a handler is set is queued: streams are delivered on `OnStream`; datagrams go to `RecieveDatagramSync`'s queue and never to a later `OnDatagram`. `OnClosed`, the native `QUICStream::SendAsync` callback and `OnRecieve`'s callbacks are the exceptions: they do run on the worker, `OnClosed` inside `SHUTDOWN_COMPLETE` after the handle is closed (a pool task only when set after the close), `onSent` inside the send's `SEND_COMPLETE` (a pool task only for a send msquic never took), `onData`/`onEnd` inside `RECEIVE` and the shutdown events (on the caller's thread for what `OnRecieve` finds waiting), so that none depends on a pool the host shares. A blocking call inside any of them stalls every connection on that worker.
|
- **Callbacks the interfaces say run "on the msquic worker" run as pool tasks**: `ClientQUIC::OnStream` and `OnDatagram` both enqueue. What arrives before a handler is set is queued: streams are delivered on `OnStream`; datagrams go to `RecieveDatagramSync`'s queue and never to a later `OnDatagram`. `OnClosed`, the native `QUICStream::SendAsync` callback and `OnRecieve`'s callbacks are the exceptions: they do run on the worker, `OnClosed` inside `SHUTDOWN_COMPLETE` after the handle is closed (a pool task only when set after the close), `onSent` inside the send's `SEND_COMPLETE` (a pool task only for a send msquic never took), `onData`/`onEnd` inside `RECEIVE` and the shutdown events (on the caller's thread for what `OnRecieve` finds waiting), so that none depends on a pool the host shares. A blocking call inside any of them stalls every connection on that worker.
|
||||||
|
- **`~ClientQUIC` lets the streams already stopped finish, up to 1 s, before `ConnectionShutdown`,** which aborts every stream and whatever msquic had not sent of it: a server that replied with `SendAsync(..., finish = true)`, let the stream go and deleted the connection lost the reply every time in `ShouldFinishStoppedStreamsQUIC` before. Streams count as finishing from `QUICStream::Stop` (a stream that can send) to `SHUTDOWN_COMPLETE`, in the registry's `finishing`.
|
||||||
- **`~ClientQUIC` waits for the connection's `SHUTDOWN_COMPLETE`, up to 1 s, before `ConnectionClose`.** msquic sends `CONNECTION_CLOSE` from a `FLUSH_SEND` it queues while processing `ConnectionShutdown` and ignores once `ShutdownComplete` is set; a close queued right behind the shutdown completed it silently, and the peer only timed the connection out (`fix(quic)` in `git log`, `ShouldTellPeerOfCloseQUIC`). So a destructor on an msquic worker thread (inside a stream callback) blocks that second and then some; only `OnClosed`'s, which has nothing left to close, is free.
|
- **`~ClientQUIC` waits for the connection's `SHUTDOWN_COMPLETE`, up to 1 s, before `ConnectionClose`.** msquic sends `CONNECTION_CLOSE` from a `FLUSH_SEND` it queues while processing `ConnectionShutdown` and ignores once `ShutdownComplete` is set; a close queued right behind the shutdown completed it silently, and the peer only timed the connection out (`fix(quic)` in `git log`, `ShouldTellPeerOfCloseQUIC`). So a destructor on an msquic worker thread (inside a stream callback) blocks that second and then some; only `OnClosed`'s, which has nothing left to close, is free.
|
||||||
- **`ListenerQUIC::ListenAsync*` run the accept loop on a `std::thread`**, not the pool as their comments say, and `ListenerHTTP::Listen` is `ListenSyncAsync` underneath, so a `ListenerHTTP`'s per-connection setup is a pool task. A saturated pool delays a new connection's SETTINGS; the early streams are buffered meanwhile (`ShouldNotDropEarlyStreams`).
|
- **`ListenerQUIC::ListenAsync*` run the accept loop on a `std::thread`**, not the pool as their comments say, and `ListenerHTTP::Listen` is `ListenSyncAsync` underneath, so a `ListenerHTTP`'s per-connection setup is a pool task. A saturated pool delays a new connection's SETTINGS; the early streams are buffered meanwhile (`ShouldNotDropEarlyStreams`).
|
||||||
- **A `ClientQUIC` against an HTTP/3 server must drain the server's unidirectional streams** (control, QPACK encoder and decoder) with an `OnStream` reader, or they back up and msquic may abort the connection. `ClientHTTP` does it; a hand-rolled WebTransport client (`ShouldEchoWebTransport`) does it itself.
|
- **A `ClientQUIC` against an HTTP/3 server must drain the server's unidirectional streams** (control, QPACK encoder and decoder) with an `OnStream` reader, or they back up and msquic may abort the connection. `ClientHTTP` does it; a hand-rolled WebTransport client (`ShouldEchoWebTransport`) does it itself.
|
||||||
|
|
|
||||||
|
|
@ -121,7 +121,7 @@ Crafter::ListenerQUIC listener("127.0.0.1", 0, "myproto/1", creds, [](Crafter::C
|
||||||
|
|
||||||
Keep the callback short: it runs on the msquic worker, so no `*Sync` call and no deleting a *different* connection from inside it. If the connection had already closed when `OnClosed` was called, it fires as a pool task instead, never inside `OnClosed`. Once `~ClientQUIC` has begun it never fires, and the destructor waits for one already running on another thread, as `std::stop_callback` does, so don't destroy a connection while holding a lock its callback takes. A client-side `ClientQUIC` has `OnClosed` too.
|
Keep the callback short: it runs on the msquic worker, so no `*Sync` call and no deleting a *different* connection from inside it. If the connection had already closed when `OnClosed` was called, it fires as a pool task instead, never inside `OnClosed`. Once `~ClientQUIC` has begun it never fires, and the destructor waits for one already running on another thread, as `std::stop_callback` does, so don't destroy a connection while holding a lock its callback takes. A client-side `ClientQUIC` has `OnClosed` too.
|
||||||
|
|
||||||
`~ClientQUIC` waits, up to 1 s and about a round trip when the peer is there, for its close to reach the peer, so a server learns of a client that went away at once rather than at its idle timeout.
|
`~ClientQUIC` waits, up to 1 s and about a round trip when the peer is there, for its close to reach the peer, so a server learns of a client that went away at once rather than at its idle timeout. Before that it lets the streams already stopped finish, bounded the same way: a reply sent with `SendAsync(..., finish = true)` on a stream that was then let go still arrives when the connection is deleted right after.
|
||||||
|
|
||||||
#### Sending without a thread
|
#### Sending without a thread
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue