From 7f441ef939b6f3b7239a3fdcdc6518a9a3b58924 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 22:12:13 -0700 Subject: [PATCH 01/11] quest(m1/refresh/core): claim Co-Authored-By: Claude Opus 5.5 From 39907ea596f6c9815176b64abbf749a33363b5e1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:24:42 -0700 Subject: [PATCH 02/11] feat(net)!: track demand reports the wanted group, with refresh on join `track::Demand::wanted()` replaces `used`/`unused`: `None` while nobody consumes the track, `Some(n)` while consumers want group `n` or later. `track::Info::refresh` is the ratio of a group's bytes after its first frame to the first frame past which a join asks for the group after the newest. IETF DYNAMIC_GROUPS maps onto `refresh: Some(0)`, a downstream NEW_GROUP_REQUEST counts as a join, and the upstream driver asks when `wanted` passes the largest group. JS, moq-ffi, and the bindings follow. Co-Authored-By: Claude Opus 5.5 --- dart/moq/MIGRATE.md | 7 + dart/moq/test/moq_test.dart | 3 +- dart/moq_ffi/lib/src/moq.dart | 86 ++- doc/concept/standard.md | 12 +- go/wrapper/MIGRATE.md | 7 + go/wrapper/json/json_test.go | 29 +- go/wrapper/moq_test.go | 19 +- go/wrapper/publish.go | 22 +- go/wrapper/records.go | 13 +- js/e2ee/src/e2ee.test.ts | 12 +- js/net/MIGRATE.md | 8 + js/net/src/bandwidth.ts | 4 +- js/net/src/broadcast.test.ts | 9 +- js/net/src/broadcast.ts | 6 +- js/net/src/group.ts | 8 + js/net/src/ietf/subscriber.test.ts | 28 +- js/net/src/ietf/subscriber.ts | 16 +- js/net/src/integration.test.ts | 18 +- js/net/src/internal.ts | 5 + js/net/src/lite/subscriber.ts | 6 +- js/net/src/track.test.ts | 123 +++- js/net/src/track.ts | 84 ++- js/net/src/util/demand.ts | 9 + js/publish/src/broadcast.ts | 2 +- kt/moq/MIGRATE.md | 7 + .../kotlin/dev/moq/SmokeTest.kt | 6 +- py/moq-rs/MIGRATE.md | 7 + py/moq-rs/moq/_records.py | 9 +- py/moq-rs/moq/publish.py | 19 +- py/moq-rs/tests/test_local.py | 26 +- py/moq-rs/tests/test_server.py | 4 +- quest/m1/refresh/README.md | 1 - quest/m1/refresh/core.md | 72 --- quest/m1/refresh/json.md | 10 +- quest/m1/refresh/lite.md | 8 +- quest/m1/refresh/video.md | 4 - rs/moq-archive/src/reader/mod.rs | 13 +- rs/moq-audio/src/encode/capture.rs | 22 +- rs/moq-audio/src/encode/producer.rs | 20 +- rs/moq-boy/src/main.rs | 20 +- rs/moq-c/src/publish.rs | 62 +- rs/moq-cli/tests/integration/listen.rs | 10 +- rs/moq-e2ee/src/tests.rs | 14 +- rs/moq-ffi/MIGRATE.md | 8 + rs/moq-ffi/src/bench.rs | 1 + rs/moq-ffi/src/demand.rs | 44 +- rs/moq-ffi/src/producer.rs | 11 +- rs/moq-ffi/src/test.rs | 63 +- rs/moq-flate/src/stream/mod.rs | 2 +- rs/moq-gst/src/source/imp.rs | 13 +- rs/moq-hls/src/server/routes.rs | 8 +- rs/moq-json/src/snapshot/mod.rs | 9 +- rs/moq-json/src/stream/mod.rs | 9 +- rs/moq-mux/src/container/consumer.rs | 3 +- rs/moq-net/Cargo.toml | 4 +- rs/moq-net/MIGRATE.md | 18 + rs/moq-net/benches/new-group.rs | 36 -- rs/moq-net/benches/origin.rs | 4 +- rs/moq-net/benches/refresh.rs | 55 ++ rs/moq-net/benches/session.rs | 4 +- rs/moq-net/src/fuzz.rs | 41 -- rs/moq-net/src/ietf/mod.rs | 2 - rs/moq-net/src/ietf/new_group.rs | 144 ----- rs/moq-net/src/ietf/publisher.rs | 204 +++---- rs/moq-net/src/ietf/subscriber.rs | 307 ++++------ rs/moq-net/src/lite/publisher.rs | 22 +- rs/moq-net/src/lite/subscriber.rs | 9 +- rs/moq-net/src/model/broadcast.rs | 16 +- rs/moq-net/src/model/group.rs | 15 + rs/moq-net/src/model/mod.rs | 3 - rs/moq-net/src/model/origin.rs | 24 +- rs/moq-net/src/model/resume.rs | 7 +- rs/moq-net/src/model/subscription.rs | 76 +-- rs/moq-net/src/model/track.rs | 550 +++++++++++------- rs/moq-net/src/model/track/demand.rs | 86 +-- rs/moq-net/src/util.rs | 12 + .../tests/integration/announce_to_serve.rs | 4 +- .../tests/integration/dial_split_horizon.rs | 2 +- rs/moq-net/tests/integration/fetch_only.rs | 2 +- rs/moq-net/tests/integration/finite_relay.rs | 2 +- .../tests/integration/history_groups.rs | 4 +- .../tests/integration/idle_cancel_refetch.rs | 2 +- .../tests/integration/late_lower_group.rs | 2 +- .../tests/integration/received_rewind.rs | 2 +- rs/moq-net/tests/integration/rejoin.rs | 22 +- rs/moq-net/tests/integration/request_caps.rs | 2 +- rs/moq-net/tests/integration/session_close.rs | 4 +- .../tests/integration/subscribe_ranges.rs | 2 +- .../tests/integration/subscribe_tracks.rs | 2 +- .../integration/subscription_end_integrity.rs | 6 +- rs/moq-net/tests/integration/support/mod.rs | 19 + .../tests/integration/track_info_cancel.rs | 11 +- .../tests/integration/track_stream_demand.rs | 42 +- .../tests/integration/unannounce_release.rs | 4 +- rs/moq-net/tests/loom.rs | 25 +- rs/moq-rtc/src/egress.rs | 7 +- rs/moq-stats/src/produce.rs | 12 +- rs/moq-tokio/tests/integration/broadcast.rs | 4 +- rs/moq-tokio/tests/integration/main.rs | 12 + .../integration/subscription_end_integrity.rs | 2 +- rs/moq-tokio/tests/integration/unannounce.rs | 4 +- rs/moq-transcode/src/lib.rs | 16 +- rs/moq-transcode/src/rung.rs | 12 +- rs/moq-video/src/capture/wgc.rs | 2 +- rs/moq-video/src/encode/producer.rs | 14 +- swift/MIGRATE.md | 7 + swift/Sources/Moq/Track.swift | 18 +- swift/Tests/MoqTests/SmokeTests.swift | 12 +- test/interop/clients/rust/tail.rs | 3 +- 109 files changed, 1518 insertions(+), 1446 deletions(-) create mode 100644 js/net/src/util/demand.ts delete mode 100644 quest/m1/refresh/core.md delete mode 100644 rs/moq-net/benches/new-group.rs create mode 100644 rs/moq-net/benches/refresh.rs delete mode 100644 rs/moq-net/src/ietf/new_group.rs diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 965ea3b1cd6..2d48666f428 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`TrackDemand.isUsed()`, `used()`, and `unused()` are gone. +`wanted()` returns null while nobody subscribes, otherwise the group subscribers want next, and `wantedChanged()` waits for it to change (the first call returns at once). +Loop on `wantedChanged()` until it returns non-null where you awaited `used()`, and null where you awaited `unused()`. +`TrackInfo` gains `refresh`. `GroupDemand` is unchanged. + ### Subscriptions carry group ranges (#5732) `Subscription.groupStart` and `groupEnd` are replaced by `ranges`, a list of `Range` whose ends are an `Anchor` (an absolute group and frame, or a count of groups before the latest), and an optional `order`. diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 9a10f776e71..e268f30d191 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -196,7 +196,8 @@ void main() { // Routed subscriptions pull their source lazily when the consumer is first read. final nextGroup = consumer.nextGroup(); - await track.demand().used().timeout(timeout); + final demand = track.demand(); + while (await demand.wantedChanged().timeout(timeout) == null) {} final producer = track.appendGroup(); producer.writeFrame( diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 3f990238d98..35ce09c6268 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,7 +8,9 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; + import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -2636,10 +2638,12 @@ class FfiConverterMoqRoute { class MoqTrackInfo { final int priority; final int? maxAgeUs; + final int? refresh; final int? timescale; MoqTrackInfo({ this.priority = 127, this.maxAgeUs = null, + this.refresh = null, this.timescale = null, }); } @@ -2661,6 +2665,11 @@ class FfiConverterMoqTrackInfo { ); final maxAgeUs = maxAgeUs_lifted.value; new_offset += maxAgeUs_lifted.bytesRead; + final refresh_lifted = FfiConverterOptionalUInt32.read( + Uint8List.view(buf.buffer, new_offset), + ); + final refresh = refresh_lifted.value; + new_offset += refresh_lifted.bytesRead; final timescale_lifted = FfiConverterOptionalUInt64.read( Uint8List.view(buf.buffer, new_offset), ); @@ -2670,6 +2679,7 @@ class FfiConverterMoqTrackInfo { MoqTrackInfo( priority: priority, maxAgeUs: maxAgeUs, + refresh: refresh, timescale: timescale, ), new_offset - buf.offsetInBytes, @@ -2680,6 +2690,7 @@ class FfiConverterMoqTrackInfo { final total_length = FfiConverterUInt8.allocationSize(value.priority) + FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) + + FfiConverterOptionalUInt32.allocationSize(value.refresh) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + 0; final buf = Uint8List(total_length); @@ -2697,6 +2708,10 @@ class FfiConverterMoqTrackInfo { value.maxAgeUs, Uint8List.view(buf.buffer, new_offset), ); + new_offset += FfiConverterOptionalUInt32.write( + value.refresh, + Uint8List.view(buf.buffer, new_offset), + ); new_offset += FfiConverterOptionalUInt64.write( value.timescale, Uint8List.view(buf.buffer, new_offset), @@ -2707,6 +2722,7 @@ class FfiConverterMoqTrackInfo { static int allocationSize(MoqTrackInfo value) { return FfiConverterUInt8.allocationSize(value.priority) + FfiConverterOptionalUInt64.allocationSize(value.maxAgeUs) + + FfiConverterOptionalUInt32.allocationSize(value.refresh) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + 0; } @@ -8463,10 +8479,9 @@ class FfiConverterMoqGroupDemand { } abstract class MoqTrackDemandInterface { - bool isUsed(); String name(); - Future unused(); - Future used(); + int? wanted(); + Future wantedChanged(); } final _MoqTrackDemandFinalizer = Finalizer>((ptr) { @@ -8500,47 +8515,37 @@ class MoqTrackDemand implements MoqTrackDemandInterface { rustCall((status) => uniffi_moq_ffi_fn_free_moqtrackdemand(_ptr, status)); } - bool isUsed() { + String name() { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqtrackdemand_is_used( + (status) => uniffi_moq_ffi_fn_method_moqtrackdemand_name( uniffiClonePointer(), status, ), - FfiConverterBool.lift, + FfiConverterString.lift, null, ); } - String name() { + int? wanted() { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqtrackdemand_name( + (status) => uniffi_moq_ffi_fn_method_moqtrackdemand_wanted( uniffiClonePointer(), status, ), - FfiConverterString.lift, + FfiConverterOptionalUInt64.lift, null, ); } - Future unused() { + Future wantedChanged() { return uniffiRustCallAsync( - () => - uniffi_moq_ffi_fn_method_moqtrackdemand_unused(uniffiClonePointer()), - ffi_moq_ffi_rust_future_poll_void, - ffi_moq_ffi_rust_future_complete_void, - ffi_moq_ffi_rust_future_free_void, - (_) {}, - moqExceptionErrorHandler, - ); - } - - Future used() { - return uniffiRustCallAsync( - () => uniffi_moq_ffi_fn_method_moqtrackdemand_used(uniffiClonePointer()), - ffi_moq_ffi_rust_future_poll_void, - ffi_moq_ffi_rust_future_complete_void, - ffi_moq_ffi_rust_future_free_void, - (_) {}, + () => uniffi_moq_ffi_fn_method_moqtrackdemand_wanted_changed( + uniffiClonePointer(), + ), + ffi_moq_ffi_rust_future_poll_rust_buffer, + ffi_moq_ffi_rust_future_complete_rust_buffer, + ffi_moq_ffi_rust_future_free_rust_buffer, + FfiConverterOptionalUInt64.lift, moqExceptionErrorHandler, ); } @@ -15540,10 +15545,10 @@ external void uniffi_moq_ffi_fn_free_moqtrackdemand( Pointer uniffiStatus, ); -@Native, Pointer)>( +@Native, Pointer)>( assetId: _uniffiAssetId, ) -external int uniffi_moq_ffi_fn_method_moqtrackdemand_is_used( +external RustBuffer uniffi_moq_ffi_fn_method_moqtrackdemand_name( Pointer ptr, Pointer uniffiStatus, ); @@ -15551,18 +15556,13 @@ external int uniffi_moq_ffi_fn_method_moqtrackdemand_is_used( @Native, Pointer)>( assetId: _uniffiAssetId, ) -external RustBuffer uniffi_moq_ffi_fn_method_moqtrackdemand_name( +external RustBuffer uniffi_moq_ffi_fn_method_moqtrackdemand_wanted( Pointer ptr, Pointer uniffiStatus, ); @Native Function(Pointer)>(assetId: _uniffiAssetId) -external Pointer uniffi_moq_ffi_fn_method_moqtrackdemand_unused( - Pointer ptr, -); - -@Native Function(Pointer)>(assetId: _uniffiAssetId) -external Pointer uniffi_moq_ffi_fn_method_moqtrackdemand_used( +external Pointer uniffi_moq_ffi_fn_method_moqtrackdemand_wanted_changed( Pointer ptr, ); @@ -17989,17 +17989,14 @@ external int uniffi_moq_ffi_checksum_method_moqgroupdemand_unused(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqgroupdemand_used(); -@Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqtrackdemand_is_used(); - @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqtrackdemand_name(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqtrackdemand_unused(); +external int uniffi_moq_ffi_checksum_method_moqtrackdemand_wanted(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqtrackdemand_used(); +external int uniffi_moq_ffi_checksum_method_moqtrackdemand_wanted_changed(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqflatesnapshotproducer_finish(); @@ -18652,16 +18649,13 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqgroupdemand_used() != 16710) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqtrackdemand_is_used() != 62559) { - throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); - } if (uniffi_moq_ffi_checksum_method_moqtrackdemand_name() != 14603) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqtrackdemand_unused() != 32953) { + if (uniffi_moq_ffi_checksum_method_moqtrackdemand_wanted() != 13310) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqtrackdemand_used() != 18944) { + if (uniffi_moq_ffi_checksum_method_moqtrackdemand_wanted_changed() != 29509) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqflatesnapshotproducer_finish() != diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 8e926905673..10097f9520a 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -30,9 +30,9 @@ subset drops. What a peer actually observes against this implementation: - **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later. - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 17, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. -- **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority and delivery timeouts; Rust also renews request tokens and relays `NEW_GROUP_REQUEST` (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. +- **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. - **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. -- **Dynamic groups.** A Rust relay advertises `DYNAMIC_GROUPS` only where the original publisher did, and carries `NEW_GROUP_REQUEST` (draft 15 and later) back to it: on the `SUBSCRIBE` that opens the upstream subscription, or in a `REQUEST_UPDATE` once it is established. Requests from every subscriber of a track coalesce, so one that names an existing group or that an outstanding request already covers goes no further. A request for 0 goes upstream as 0, unless another subscriber's request past the newest group held answers it too. The next group the relay receives answers every request it held, so new groups never send one again. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. Local publishers never advertise `DYNAMIC_GROUPS`; on their tracks a `SUBSCRIBE`'s request is ignored and an update carrying one ends the subscription with `UPDATE_FAILED`. moq-lite hops do not carry requests yet. +- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. moq-lite hops do not carry requests yet. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. @@ -99,6 +99,14 @@ choices. They follow the product model. but do not drop objects or reset subgroups. Latency enforcement uses presentation time instead of wall-clock delivery deadlines. +- **A relay judges `NEW_GROUP_REQUEST` instead of forwarding it.** + [Draft 22 §9.20.19](https://www.ietf.org/archive/id/draft-ietf-moq-transport-22.html#section-9.20.19) + says a relay forwards it toward the publisher. Here every hop treats it as a + join under the track's refresh ratio, against its own cache, and asks upstream + only when the ratio calls for a new group. Every hop caches the same groups, so + each reaches the same answer, and a request against a group still small enough + to join is dropped rather than refreshed for every subscriber. + - **Rendezvous waits are capped at zero.** A `SUBSCRIBE` with a positive `RENDEZVOUS_TIMEOUT` gets `TIMEOUT` immediately if no publisher exists; absent or zero still gets `DOES_NOT_EXIST`. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 8689478554b..b532b261ec9 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`TrackDemand.IsUsed`, `Used`, and `Unused` are gone. +`Wanted()` returns nil while nobody subscribes, otherwise the group subscribers want next, and `WantedChanged(ctx)` waits for it to change (the first call returns at once). +Loop on `WantedChanged` until it returns non-nil where you called `Used`, and nil where you called `Unused`. +`TrackInfo` gains `Refresh`. `GroupDemand` is unchanged. + ### Subscriptions carry group ranges (#5732) `Subscription.GroupStart` and `GroupEnd` are replaced by `Ranges`, a slice of `Range` whose ends are `AnchorAbsolute` or `AnchorRelative` (an absolute group and frame, or a count of groups before the latest), and an optional `Order`. diff --git a/go/wrapper/json/json_test.go b/go/wrapper/json/json_test.go index f5b62f6c9ce..978901bfe30 100644 --- a/go/wrapper/json/json_test.go +++ b/go/wrapper/json/json_test.go @@ -144,8 +144,8 @@ func TestDemand(t *testing.T) { if name := snapshotDemand.Name(); name != "status" { t.Fatalf("Name = %q, want status", name) } - if snapshotDemand.IsUsed() { - t.Fatal("IsUsed before any subscriber") + if wanted := snapshotDemand.Wanted(); wanted != nil { + t.Fatalf("Wanted = %d before any subscriber", *wanted) } snapshotConsumer, err := moqjson.NewSnapshotConsumer(subscribeTrack(ctx, t, consumer, "status"), moqjson.ConsumerOptions{}) @@ -156,26 +156,39 @@ func TestDemand(t *testing.T) { if err != nil { t.Fatal(err) } - if err := snapshotDemand.Used(ctx); err != nil { + if err := untilWanted(ctx, snapshotDemand, true); err != nil { t.Fatal(err) } - if err := streamDemand.Used(ctx); err != nil { + if err := untilWanted(ctx, streamDemand, true); err != nil { t.Fatal(err) } snapshotConsumer.Cancel() streamConsumer.Cancel() - if err := snapshotDemand.Unused(ctx); err != nil { + if err := untilWanted(ctx, snapshotDemand, false); err != nil { t.Fatal(err) } - if err := streamDemand.Unused(ctx); err != nil { + if err := untilWanted(ctx, streamDemand, false); err != nil { t.Fatal(err) } if err := snapshot.Finish(); err != nil { t.Fatal(err) } - if err := snapshotDemand.Used(ctx); !errors.Is(err, moq.ErrClosed) { - t.Fatalf("Used after Finish = %v, want ErrClosed", err) + if err := untilWanted(ctx, snapshotDemand, true); !errors.Is(err, moq.ErrClosed) { + t.Fatalf("untilWanted after Finish = %v, want ErrClosed", err) + } +} + +// untilWanted blocks until some subscriber wants the track, or none does. +func untilWanted(ctx context.Context, demand *moq.TrackDemand, wanted bool) error { + for { + next, err := demand.WantedChanged(ctx) + if err != nil { + return err + } + if (next != nil) == wanted { + return nil + } } } diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 4ecce1054db..02858ed518e 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -1261,8 +1261,8 @@ func TestUsedCancelKeepsTheTrack(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) defer cancel() - if err := demand.Used(ctx); !errors.Is(err, context.DeadlineExceeded) { - t.Fatalf("Used error = %v, want context.DeadlineExceeded", err) + if err := untilWanted(ctx, demand, true); !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("untilWanted error = %v, want context.DeadlineExceeded", err) } readCtx, readCancel := context.WithTimeout(context.Background(), testTimeout) @@ -1273,7 +1273,7 @@ func TestUsedCancelKeepsTheTrack(t *testing.T) { t.Fatal(err) } defer consumer.Cancel() - if err := demand.Used(readCtx); err != nil { + if err := untilWanted(readCtx, demand, true); err != nil { t.Fatal(err) } @@ -1596,3 +1596,16 @@ func timedInfo() *moq.TrackInfo { scale := uint64(1_000_000) return &moq.TrackInfo{Priority: 127, Timescale: &scale} } + +// untilWanted blocks until some subscriber wants the track, or none does. +func untilWanted(ctx context.Context, demand *moq.TrackDemand, wanted bool) error { + for { + next, err := demand.WantedChanged(ctx) + if err != nil { + return err + } + if (next != nil) == wanted { + return nil + } + } +} diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index ed3e814ca66..172a43dc645 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -149,7 +149,7 @@ func (r *TrackRequest) Abort(errorCode uint16) error { return r.inner.Abort(errorCode) } -// TrackDemand watches whether a published track has subscribers. +// TrackDemand watches the group a published track's subscribers want next. // // It is weak: holding it neither keeps the track open nor locks the producer, so // a wait can park here while the producer keeps publishing. Waits return @@ -163,19 +163,15 @@ func (d *TrackDemand) Name() string { return d.inner.Name() } -// IsUsed reports whether the track has at least one active subscriber right now. -func (d *TrackDemand) IsUsed() bool { - return d.inner.IsUsed() +// Wanted is the group subscribers want next, or nil while nobody subscribes. A +// value past the newest group asks for a new group now, typically a keyframe. +func (d *TrackDemand) Wanted() *uint64 { + return d.inner.Wanted() } -// Used blocks until the track has at least one active subscriber. -func (d *TrackDemand) Used(ctx context.Context) error { - return d.inner.Used(ctx) -} - -// Unused blocks until the track has no active subscribers. -func (d *TrackDemand) Unused(ctx context.Context) error { - return d.inner.Unused(ctx) +// WantedChanged blocks until Wanted changes and returns it. The first call returns at once. +func (d *TrackDemand) WantedChanged(ctx context.Context) (*uint64, error) { + return d.inner.WantedChanged(ctx) } // TrackProducer writes arbitrary byte payloads with no codec required. @@ -183,7 +179,7 @@ type TrackProducer struct { inner *ffi.MoqTrackProducer } -// Demand returns a watch-only handle to the track's name and whether it has subscribers. +// Demand returns a watch-only handle to the track's name and the group its subscribers want. func (t *TrackProducer) Demand() (*TrackDemand, error) { inner, err := t.inner.Demand() if err != nil { diff --git a/go/wrapper/records.go b/go/wrapper/records.go index 803415176eb..b0059cf0ba3 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -109,12 +109,15 @@ func subscriptionFFI(s *Subscription) (*ffi.MoqSubscription, error) { } // TrackInfo holds publisher-side track properties: priority, how long a -// non-latest group is cached (nil for no limit), and the timescale in ticks per -// second (nil means untimed on both publish and receive). A zero Priority is -// the least urgent; set 127 for the midpoint a nil TrackInfo uses. +// non-latest group is cached (nil for no limit), how many times its first frame +// a group's later bytes may grow before a joining subscriber asks for a new group +// (nil never asks), and the timescale in ticks per second (nil means untimed on +// both publish and receive). A zero Priority is the least urgent; set 127 for the +// midpoint a nil TrackInfo uses. type TrackInfo struct { Priority uint8 MaxAge *time.Duration + Refresh *uint32 Timescale *uint64 } @@ -123,11 +126,11 @@ func trackInfoFFI(info *TrackInfo) (*ffi.MoqTrackInfo, error) { return nil, nil } maxAge, err := optMicros("max age", info.MaxAge) - return &ffi.MoqTrackInfo{Priority: info.Priority, MaxAgeUs: maxAge, Timescale: info.Timescale}, err + return &ffi.MoqTrackInfo{Priority: info.Priority, MaxAgeUs: maxAge, Refresh: info.Refresh, Timescale: info.Timescale}, err } func trackInfoFromFFI(info ffi.MoqTrackInfo) TrackInfo { - return TrackInfo{Priority: info.Priority, MaxAge: optFromMicros(info.MaxAgeUs), Timescale: info.Timescale} + return TrackInfo{Priority: info.Priority, MaxAge: optFromMicros(info.MaxAgeUs), Refresh: info.Refresh, Timescale: info.Timescale} } // ConnectionStats holds transport metrics for a session (RTT, bandwidth, byte diff --git a/js/e2ee/src/e2ee.test.ts b/js/e2ee/src/e2ee.test.ts index aad6ec21673..d19d5334176 100644 --- a/js/e2ee/src/e2ee.test.ts +++ b/js/e2ee/src/e2ee.test.ts @@ -382,7 +382,7 @@ test("grouped authentication failure ends the track", async () => { test("grouped failure wakes pending reads and releases demand", async () => { const p = await pair("video"); const demand = p.net.demand(); - expect(demand.used.peek()).toBe(true); + expect(demand.wanted.peek()).toBeDefined(); // One authentic frame, then silence. The group and the track stay open. const open = new NetGroup.Producer(0); @@ -408,7 +408,7 @@ test("grouped failure wakes pending reads and releases demand", async () => { expect(await failure(nextGroup)).toBe("authentication"); expect(await failure(datagram)).toBe("authentication"); - expect(demand.used.peek()).toBe(false); + expect(demand.wanted.peek()).toBeUndefined(); expect(badDemand.used.peek()).toBe(false); expect(open.demand().used.peek()).toBe(false); expect(p.net.closed.peek()).toBeUndefined(); @@ -473,8 +473,8 @@ test("closing the track consumer releases demand while a group is held", async ( const group = await recvGroup(p.consumer); p.consumer.close(); - await demand.unused(); - expect(demand.used.peek()).toBe(false); + // The unsubscribe lands on the next microtask. + while (demand.wanted.peek() !== undefined) await Promise.resolve(); // The held group is not failed by the unsubscribe: it ends after what it holds, as in @moq/net. expect(await readText(group)).toBe("ok"); @@ -495,11 +495,11 @@ test("a bad datagram stays an event and keeps demand", async () => { const frame = good.readFrame(); expect(await p.consumer.recvDatagram()).toEqual({ kind: "authentication", sequence: 1 }); - expect(demand.used.peek()).toBe(true); + expect(demand.wanted.peek()).toBeDefined(); await p.producer.insertDatagram(2, ms(3), text("next")); expect(datagramText(await p.consumer.recvDatagram())).toBe("next"); - expect(demand.used.peek()).toBe(true); + expect(demand.wanted.peek()).toBeDefined(); await open.writeFrame(ms(4), text("still")); expect(decoder.decode((await frame)?.plaintext)).toBe("still"); diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 36a3e004aed..762bed1e04f 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,14 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`Track.Demand.used` and `unused()` are gone. +`demand.wanted` is a `Getter`: `undefined` while nobody subscribes, otherwise the group subscribers want next. +Watch it where you watched `used`, comparing against `undefined`, and wait for it to become `undefined` where you awaited `unused()`. +`Track.Info.refresh` opts a track in to new groups on join. +Broadcast and group demand keep `used` and `unused()`. + ### Track readers follow `largest()` instead of reading `latest()` (#5725) `latest()` on `Track.Subscriber` and `Track.Ordered` is gone, and `Subscriber.largest()` is no longer a synchronous buffered snapshot. diff --git a/js/net/src/bandwidth.ts b/js/net/src/bandwidth.ts index d6884f728b6..f8382d0d773 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -93,7 +93,7 @@ function wantsOf(entries: readonly Entry[]): Want[] { const wants: Want[] = []; for (const entry of entries) { if (entry.demand.closed.peek() !== undefined) continue; - if (!entry.demand.used.peek()) continue; + if (entry.demand.wanted.peek() === undefined) continue; wants.push({ id: entry.id, priority: entry.priority, max: entry.max }); } return wants; @@ -162,7 +162,7 @@ export class Allocator implements Handle { if (this.#estimate) effect.get(this.#estimate); const entries = effect.get(this.#entries); for (const entry of entries) { - effect.get(entry.demand.used); + effect.get(entry.demand.wanted); effect.get(entry.demand.closed); } this.#publish(); diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 773fb35b94f..8f15ca10df6 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -7,6 +7,7 @@ import { TrackSequences } from "./internal.ts"; import { textFrame } from "./mock.ts"; import { Timescale, Timestamp } from "./time.ts"; import type { Request as TrackRequest } from "./track.ts"; +import { unwanted } from "./util/demand.ts"; import { wireOf } from "./wire.ts"; // The public API mints consumers internally (Producer.consume, the wire layers); tests act @@ -282,7 +283,7 @@ test("an info lookup joining a subscription's request stays demand after the sub // Flush every pending notification, so only the lookup is left holding demand. subscriber.close(); await new Promise((resolve) => setTimeout(resolve, 0)); - expect(request.demand().used.peek()).toBe(false); + expect(request.demand().wanted.peek()).toBeUndefined(); expect(demand.used.peek()).toBe(true); request.accept({ timescale: Timescale.MILLI }); @@ -784,12 +785,12 @@ test("broadcast demand watches static and pending tracks rather than broadcast h const request = await pulled; if (!request) throw new Error("expected request"); const requested = request.demand(); - expect(requested.used.peek()).toBe(true); + expect(requested.wanted.peek()).toBeDefined(); first.close(); await Promise.resolve(); expect(demand.used.peek()).toBe(true); second.close(); - await requested.unused(); + await unwanted(requested); await demand.unused(); expect(demand.used.peek()).toBe(false); request.reject(); @@ -824,7 +825,7 @@ test("a pending track info query counts as broadcast demand", async () => { const request = await pending; if (!request) throw new Error("expected request"); // Nobody subscribes to the queried track itself. - expect(request.demand().used.peek()).toBe(false); + expect(request.demand().wanted.peek()).toBeUndefined(); request.accept({ timescale: Timescale.MILLI, priority: 2 }); expect((await info).priority).toBe(2); await demand.unused(); diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 0cf432ad284..3dab4121a7b 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -80,13 +80,13 @@ function watchDemand(state: BroadcastState, producer: track.Producer, lookups?: const used = state.closed.peek() === undefined && demand.closed.peek() === undefined && - ((lookups?.pending ?? 0) > 0 || demand.used.peek()); + ((lookups?.pending ?? 0) > 0 || demand.wanted.peek() !== undefined); if (active === used) return; state.active += used ? 1 : -1; active = used; state.used.set(state.active > 0); }; - const disposeUsed = demand.used.subscribe(update); + const disposeUsed = demand.wanted.subscribe(update); if (lookups) lookups.changed = update; const disposeClosed = demand.closed.subscribe(() => { if (demand.closed.peek() === undefined) return; @@ -221,7 +221,7 @@ async function resolveTrackInfo(state: BroadcastState, name: string, hold?: Abor let answered = false; let ended = false; const release = () => { - if (lookups.opened && lookups.pending === 0 && !producer.demand().used.peek()) producer.close(); + if (lookups.opened && lookups.pending === 0 && producer.demand().wanted.peek() === undefined) producer.close(); }; info.then( () => { diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 08ffa4ab5db..16788478ca4 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -196,6 +196,14 @@ export class Producer { group.#admits.push(admit); }; hooks.groupStart = (group) => (group.#state.total.peek() > 0 ? group.#state.timestamp : undefined); + hooks.overRefresh = (group, ratio) => { + const state = group.#state; + const first = state.frames.peek()[0]; + // Without its first frame the cache cannot measure the group, so it asks for nothing. + if (state.start !== 0 || first === undefined) return false; + const head = first.payload.byteLength; + return state.cacheBytes - head > head * ratio; + }; hooks.limitGroup = (group, frames) => { // A closed group takes no more frames, but one already past the cap still // contradicts the end. diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 2c9ce400b7b..c0ef4c69bb4 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -11,6 +11,7 @@ import { Reader, Stream } from "../stream.ts"; import { Tail } from "../tail.ts"; import { Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; +import * as demandUtil from "../util/demand.ts"; import { ControlStreamAdapter, NativeSession } from "./adapter.ts"; import type * as Cluster from "./cluster.ts"; import { Connection } from "./connection.ts"; @@ -1238,22 +1239,24 @@ test.each(["acceptance", "timeout"])("returning demand preserves pending setup u let returned: track.Subscriber | undefined; const resumed = Promise.withResolvers(); const waiting = Promise.withResolvers(); + const unwanted = demandUtil.unwanted; + const unwantedSpy = spyOn(demandUtil, "unwanted"); const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { const producer = pending(request); const demand = producer.demand(); - const unused = demand.unused.bind(demand); let returnedOnce = false; - spyOn(demand, "unused").mockImplementation(async () => { + unwantedSpy.mockImplementation(async (watched) => { + if (watched !== demand) return unwanted(watched); if (returnedOnce) { waiting.resolve(); - return unused(); + return unwanted(demand); } returnedOnce = true; - await unused(); - const peek = demand.used.peek.bind(demand.used); + await unwanted(demand); + const peek = demand.wanted.peek.bind(demand.wanted); // Return after the watcher checks demand, before its result crosses the // promise race to the setup continuation. No real-time sleeps are involved. - const observed = spyOn(demand.used, "peek").mockImplementationOnce(() => { + const observed = spyOn(demand.wanted, "peek").mockImplementationOnce(() => { const used = peek(); observed.mockRestore(); queueMicrotask(() => { @@ -1269,6 +1272,7 @@ test.each(["acceptance", "timeout"])("returning demand preserves pending setup u // Restore real timers even if an injection promise outlives the test. onTestFinished(() => { captured.mockRestore(); + unwantedSpy.mockRestore(); opening.mockRestore(); first.close(); returned?.close(); @@ -1311,15 +1315,16 @@ test("setup abandonment closes before a queued viewer can attach", async () => { const broadcast = subscriber.consume(Path.from("room")); const pending = hooks.pendingTrackProducer; const resumed = Promise.withResolvers(); + const unwanted = demandUtil.unwanted; + const unwantedSpy = spyOn(demandUtil, "unwanted"); const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { const producer = pending(request); const demand = producer.demand(); - const unused = demand.unused.bind(demand); - spyOn(demand, "unused").mockImplementationOnce(async () => { - await unused(); - const peek = demand.used.peek.bind(demand.used); + unwantedSpy.mockImplementationOnce(async (watched) => { + await unwanted(watched); + const peek = demand.wanted.peek.bind(demand.wanted); let checks = 0; - const observed = spyOn(demand.used, "peek").mockImplementation(() => { + const observed = spyOn(demand.wanted, "peek").mockImplementation(() => { const used = peek(); // The first check is the watcher; the second is the setup loop's // final check. A queued viewer must see that cancellation committed. @@ -1337,6 +1342,7 @@ test("setup abandonment closes before a queued viewer can attach", async () => { // Runner timeouts do not unwind an async test parked on the injection promise. onTestFinished(() => { captured.mockRestore(); + unwantedSpy.mockRestore(); first.close(); returned?.close(); broadcast.close(); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 99dc5daa2a5..9c5672485de 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -26,6 +26,7 @@ import type { Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { Deadline, requestOptions } from "../util/deadline.ts"; +import { unwanted } from "../util/demand.ts"; import { LIMITS, type Limits, SlotMap, Slots } from "../util/limits.ts"; import { overrideBroadcastWire, wireOf } from "../wire.ts"; import type { Session } from "./adapter.ts"; @@ -724,12 +725,12 @@ export class Subscriber { const waitAbandoned = async (): Promise => { // An info-only lookup attaches no subscriber yet still waits on SUBSCRIBE_OK for // the track info, so only demand that arrived and then left is abandonment. - while (!demand.used.peek() && demand.closed.peek() === undefined) { - await Signal.race(demand.used, demand.closed); + while (demand.wanted.peek() === undefined && demand.closed.peek() === undefined) { + await Signal.race(demand.wanted, demand.closed); } for (;;) { - await demand.unused(); - if (demand.closed.peek() !== undefined || !demand.used.peek()) return null; + await unwanted(demand); + if (demand.closed.peek() !== undefined || demand.wanted.peek() === undefined) return null; } }; @@ -746,7 +747,7 @@ export class Subscriber { trackAlias = result.alias; break; } - if (demand.closed.peek() === undefined && demand.used.peek()) continue; + if (demand.closed.peek() === undefined && demand.wanted.peek() !== undefined) continue; throw abandoned; } console.debug(`subscribe ok: id=${requestId} broadcast=${broadcast} track=${request.name}`); @@ -834,8 +835,9 @@ export class Subscriber { let terminal = localEnded; const demand = producer.demand(); for (;;) { - const reason = await race([done, demand.unused().then(() => idle)]); - if (reason === idle && demand.closed.peek() === undefined && demand.used.peek()) continue; + const reason = await race([done, unwanted(demand).then(() => idle)]); + if (reason === idle && demand.closed.peek() === undefined && demand.wanted.peek() !== undefined) + continue; terminal = reason; break; } diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index ba8edce3d2d..1a344a5d3d1 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -1404,12 +1404,12 @@ async function runSubscriberTeardown(protocol: string, version?: number) { expect(await sub.readString()).toBe("hello"); // The publisher now has a live downstream reader for the track. - await waitUntil(() => video.demand().used.peek()); + await waitUntil(() => video.demand().wanted.peek() !== undefined); // Closing the only subscriber must tear the wire subscription down, so demand drops on the // publisher rather than the relay serving groups to nobody. sub.close(); - await waitUntil(() => !video.demand().used.peek()); + await waitUntil(() => video.demand().wanted.peek() === undefined); broadcast.close(); remote.close(); @@ -1455,11 +1455,11 @@ test("integration: ietf draft-14 subscriber teardown on last unsubscribe", async const remote = wireOf(client).consume(Path.from("test")); const sub = remote.track("video").subscribe().ordered(); expect(await sub.readString()).toBe("hello"); - await waitUntil(() => served?.demand().used.peek() === true); + await waitUntil(() => served?.demand().wanted.peek() !== undefined); // Closing the subscriber sends Unsubscribe and tears the subscription down, so demand drops. sub.close(); - await waitUntil(() => served?.demand().used.peek() === false); + await waitUntil(() => served?.demand().wanted.peek() === undefined); broadcast.close(); await serving; @@ -1528,17 +1528,17 @@ test("integration: lite fan-out keeps the upstream until the last subscriber lea const b = remote.track("video").subscribe().ordered(); expect(await a.readString()).toBe("hello"); expect(await b.readString()).toBe("hello"); - await waitUntil(() => video.demand().used.peek()); + await waitUntil(() => video.demand().wanted.peek() !== undefined); // Closing one leaves the shared upstream serving the other. a.close(); video.writeFrame(textFrame("more")); expect(await b.readString()).toBe("more"); - expect(video.demand().used.peek()).toBe(true); + expect(video.demand().wanted.peek()).toBeDefined(); // The last close tears it down. b.close(); - await waitUntil(() => !video.demand().used.peek()); + await waitUntil(() => video.demand().wanted.peek() === undefined); broadcast.close(); remote.close(); @@ -1565,10 +1565,10 @@ test("integration: lite re-subscribe re-opens the upstream after each teardown", video.writeFrame(textFrame(`hello-${i}`)); const sub = remote.track("video").subscribe().ordered(); expect(await sub.readString()).toBe(`hello-${i}`); - await waitUntil(() => video.demand().used.peek()); + await waitUntil(() => video.demand().wanted.peek() !== undefined); sub.close(); - await waitUntil(() => !video.demand().used.peek()); + await waitUntil(() => video.demand().wanted.peek() === undefined); } broadcast.close(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 6869b62baef..7e18f0cce39 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -312,6 +312,8 @@ export const hooks: { admitGroupStart: (group: GroupProducer, admit: (start: Timestamp) => () => void) => void; /** Return a group producer's first timestamp, if it already holds a frame. */ groupStart: (group: GroupProducer) => Timestamp | undefined; + /** Whether a group's bytes after its first frame exceed `ratio` times the first frame. */ + overRefresh: (group: GroupProducer, ratio: number) => boolean; /** Keep a mirror of a group accepted unverified below its track's eviction watermark out of media-time expiry. */ unverifyGroup: (group: GroupConsumer) => void; /** Return a group's first timestamp, retained even after its first frame is read. */ @@ -404,6 +406,9 @@ export const hooks: { groupStart: () => { throw new Error("group.ts not loaded"); }, + overRefresh: () => { + throw new Error("group.ts not loaded"); + }, unverifyGroup: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 292af1ef8bc..a4f5cab34a6 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -20,6 +20,7 @@ import * as Time from "../time.ts"; import type * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { Deadline, REQUEST_TIMEOUT_MS, requestOptions } from "../util/deadline.ts"; +import { unwanted } from "../util/demand.ts"; import { LIMITS, type Limits, SlotMap, Slots } from "../util/limits.ts"; import { overrideBroadcastWire, wireOf } from "../wire.ts"; import { @@ -784,8 +785,9 @@ export class Subscriber { const idle = Symbol("idle"); const demand = producer.demand(); for (;;) { - const reason = await race([done, demand.unused().then(() => idle)]); - if (reason === idle && demand.closed.peek() === undefined && demand.used.peek()) continue; + const reason = await race([done, unwanted(demand).then(() => idle)]); + if (reason === idle && demand.closed.peek() === undefined && demand.wanted.peek() !== undefined) + continue; break; } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index a5a9aea56da..893d425c23f 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -1,11 +1,13 @@ import { expect, setSystemTime, spyOn, test } from "bun:test"; import { Manual, Milli, Nano } from "@moq/clock"; +import { Producer as BroadcastProducer } from "./broadcast.ts"; import { ProtocolViolation, TimestampMismatch, TooFarBehind } from "./error.ts"; import { Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; import { Timescale, Timestamp } from "./time.ts"; import { infoDefaults, type Subscription, Producer as TrackProducer } from "./track.ts"; +import { unwanted } from "./util/demand.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); @@ -39,25 +41,25 @@ test("priority reads the committed info and is the midpoint before accept", () = expect(producer.priority).toBe(60); }); -test("used reflects subscriber demand and unused resolves when the last one leaves", async () => { +test("wanted reflects subscriber demand and clears when the last one leaves", async () => { const producer = new TrackProducer("test"); // No subscribers: no demand. - expect(producer.demand().used.peek()).toBe(false); + expect(producer.demand().wanted.peek()).toBeUndefined(); const a = producer.subscribe(); const b = producer.subscribe().ordered(); - expect(producer.demand().used.peek()).toBe(true); + expect(producer.demand().wanted.peek()).toBeDefined(); - // Closing one of two keeps demand, so unused() stays pending. + // Closing one of two keeps demand. a.close(); - expect(producer.demand().used.peek()).toBe(true); + expect(producer.demand().wanted.peek()).toBeDefined(); - // Closing the last subscriber drops demand; unused() resolves. The consumer wire awaits this + // Closing the last subscriber drops demand. The consumer wire awaits this // to tear an idle upstream down. b.close(); - await producer.demand().unused(); - expect(producer.demand().used.peek()).toBe(false); + await unwanted(producer.demand()); + expect(producer.demand().wanted.peek()).toBeUndefined(); }); test("a producer never self-closes on zero demand: a publisher keeps serving new subscribers", async () => { @@ -66,9 +68,9 @@ test("a producer never self-closes on zero demand: a publisher keeps serving new // Demand comes and goes... const a = producer.subscribe(); a.close(); - await producer.demand().unused(); + await unwanted(producer.demand()); - // ...but the producer stays open (only the wire acts on `unused`, not the producer itself), + // ...but the producer stays open (only the wire acts on unwanted demand, not the producer), // so a publisher writing to a track nobody is watching is unaffected. expect(producer.closed.peek()).toBeUndefined(); @@ -76,17 +78,17 @@ test("a producer never self-closes on zero demand: a publisher keeps serving new producer.writeFrame(textFrame("still here")); const b = producer.subscribe().ordered(); expect(await b.readString()).toBe("still here"); - expect(producer.demand().used.peek()).toBe(true); + expect(producer.demand().wanted.peek()).toBeDefined(); }); -test("unused() resolves immediately when there was never any demand", async () => { +test("unwanted resolves immediately when there was never any demand", async () => { const producer = new TrackProducer("video"); - // No subscriber was ever attached; unused() must not hang. - await producer.demand().unused(); - expect(producer.demand().used.peek()).toBe(false); + // No subscriber was ever attached; the wait must not hang. + await unwanted(producer.demand()); + expect(producer.demand().wanted.peek()).toBeUndefined(); }); -test("used stays true across churn while at least one subscriber remains", async () => { +test("wanted stays set across churn while at least one subscriber remains", async () => { const producer = new TrackProducer("video"); const a = producer.subscribe(); @@ -94,12 +96,95 @@ test("used stays true across churn while at least one subscriber remains", async for (let i = 0; i < 20; i++) { const t = producer.subscribe(); t.close(); - expect(producer.demand().used.peek()).toBe(true); + expect(producer.demand().wanted.peek()).toBeDefined(); } a.close(); - await producer.demand().unused(); - expect(producer.demand().used.peek()).toBe(false); + await unwanted(producer.demand()); + expect(producer.demand().wanted.peek()).toBeUndefined(); +}); + +// Append a group of a 3 byte first frame and a `delta` byte delta to an untimed track. +function refreshGroup(producer: TrackProducer, delta: number): void { + const group = producer.appendGroup(); + group.writeFrame({ payload: enc.encode("key") }); + if (delta > 0) group.writeFrame({ payload: new Uint8Array(delta) }); + group.close(); +} + +test("the first subscriber of a track with no group wants group 0", () => { + const producer = new TrackProducer("test").accept({ refresh: 1 }); + expect(producer.demand().wanted.peek()).toBeUndefined(); + const subscriber = producer.subscribe(); + expect(producer.demand().wanted.peek()).toBe(0); + subscriber.close(); +}); + +test("a join over the refresh ratio wants the group after the newest", () => { + for (const [delta, wanted] of [ + [0, 0], + [3, 0], + [4, 1], + ]) { + const producer = new TrackProducer("test").accept({ refresh: 1 }); + refreshGroup(producer, delta); + const subscriber = producer.subscribe(); + expect(producer.demand().wanted.peek()).toBe(wanted); + subscriber.close(); + } +}); + +test("joins coalesce until the wanted group lands", () => { + const producer = new TrackProducer("test").accept({ refresh: 1 }); + refreshGroup(producer, 4); + const subscribers = [producer.subscribe(), producer.subscribe()]; + expect(producer.demand().wanted.peek()).toBe(1); + + // Group 1 answers it, and a join under its ratio asks nothing more. + refreshGroup(producer, 0); + subscribers.push(producer.subscribe()); + expect(producer.demand().wanted.peek()).toBe(1); + + refreshGroup(producer, 4); + subscribers.push(producer.subscribe()); + expect(producer.demand().wanted.peek()).toBe(3); + for (const subscriber of subscribers) subscriber.close(); +}); + +test("joins without refresh ask for no group", () => { + const producer = new TrackProducer("test").accept({}); + refreshGroup(producer, 1000); + const subscriber = producer.subscribe(); + expect(producer.demand().wanted.peek()).toBe(0); + subscriber.close(); +}); + +test("a fixed start is no join", () => { + const producer = new TrackProducer("test").accept({ refresh: 1 }); + refreshGroup(producer, 4); + const subscriber = producer.subscribe({ groups: { start: { included: 0 } } }); + expect(producer.demand().wanted.peek()).toBe(0); + subscriber.close(); +}); + +test("a replacement wants the group past its predecessor", () => { + const broadcast = new BroadcastProducer(); + const first = broadcast.createTrack("test"); + first.writeGroup(new GroupProducer(7)); + first.close(); + + const second = broadcast.createTrack("test"); + const subscriber = second.subscribe(); + expect(second.demand().wanted.peek()).toBe(8); + subscriber.close(); + broadcast.close(); +}); + +test("refresh must be a u32 ratio", () => { + expect(() => infoDefaults({ refresh: -1 })).toThrow(RangeError); + expect(() => infoDefaults({ refresh: 0.5 })).toThrow(RangeError); + expect(() => infoDefaults({ refresh: 2 ** 32 })).toThrow(RangeError); + expect(infoDefaults({ refresh: 0 }).refresh).toBe(0); }); test("appendDatagram shares the group sequence counter", () => { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index fa75702e863..40cfca85d63 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -94,6 +94,14 @@ export interface Info { maxAge?: Milli; /** Tie-break priority between subscriptions of equal subscriber priority (`0..=255`, higher first). Defaults to `127`. */ priority: number; + /** + * How many times its first frame a group's later bytes may grow before a joining + * subscriber asks for a new group, or omitted to never ask. A join against a newest group + * whose bytes after its first frame exceed this many times the first frame moves + * {@link Demand.wanted} past it, so a late joiner never downloads much more than a + * snapshot or keyframe. `0` asks on any join after a delta. An integer in `0..2^32`. + */ + refresh?: number; } // Normalize a duration for the wire, which carries it as an unsigned varint. @@ -126,9 +134,17 @@ export function infoDefaults(info: Partial = {}): Info { timescale: info.timescale == null ? undefined : Timescale(info.timescale), maxAge: info.maxAge === undefined ? undefined : wireMillis("maxAge", info.maxAge), priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), + refresh: info.refresh == null ? undefined : refreshRatio(info.refresh), }; } +function refreshRatio(value: number): number { + if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) { + throw new RangeError(`refresh must be an integer in 0..2^32: ${value}`); + } + return value; +} + /** An explicitly included or excluded group sequence. */ export type Bound = { included: number; excluded?: never } | { excluded: number; included?: never }; @@ -542,8 +558,13 @@ let ordered_: { recvDatagram(subscriber: Subscriber): Promise; }; +// Whether a subscription joins at the live edge rather than resuming from a fixed group. +function joinsLive(subscription: Subscription | undefined): boolean { + return subscription?.groups?.start === undefined && subscription?.groups?.end === undefined; +} + // Constructs a Demand from within this module; assigned in the class's static block. -let makeDemand: (name: string, used: Getter, state: TrackState) => Demand; +let makeDemand: (name: string, wanted: Getter, state: TrackState) => Demand; /** * A watch-only view of a track's subscriber demand, from {@link Producer.demand} or {@link Request.demand}. Mirrors the @@ -557,29 +578,28 @@ export class Demand { /** The track name. */ readonly name: string; - #used: Getter; + #wanted: Getter; #state: TrackState; - private constructor(name: string, used: Getter, state: TrackState) { + private constructor(name: string, wanted: Getter, state: TrackState) { this.name = name; - this.#used = used; + this.#wanted = wanted; this.#state = state; } static { - makeDemand = (name, used, state) => new Demand(name, used, state); - } - - /** Whether the track currently has any subscribers. Watch it (`effect.get` / `.peek()`) to follow demand. */ - get used(): Getter { - return this.#used; + makeDemand = (name, wanted, state) => new Demand(name, wanted, state); } - /** Resolves once the track has no subscribers (or has closed). Await it to react to demand ending. */ - async unused(): Promise { - while (this.#used.peek() && this.#state.closed.peek() === undefined) { - await Signal.race(this.#used, this.#state.closed); - } + /** + * The group subscribers want: `undefined` while nobody subscribes, otherwise the sequence + * the next group should have at least. A publisher opens a group whenever it passes its + * largest. The first subscriber of a track with no group wants `0`, and a join judged by + * {@link Info.refresh} wants the group after the newest. It never goes back. Watch it + * (`effect.get` / `.peek()`) to follow demand. + */ + get wanted(): Getter { + return this.#wanted; } /** Settles once the track closes: `null` on a clean close, or the abort {@link Error}. */ @@ -656,8 +676,10 @@ export class Producer { // One independent downstream state per live subscriber. #sinks = new Set(); - // Whether any subscriber is currently attached, watched through {@link demand}. - #used = new Signal(false); + // The group subscribers want while any is attached, watched through {@link demand}. + #wanted = new Signal(undefined); + // The lowest group they want; raised by a join over the refresh ratio, never lowered. + #floor = 0; #demand: Demand; #largestSeen?: Location; // The largest group's content may still grow: it has not closed cleanly, and it is not a @@ -666,7 +688,7 @@ export class Producer { constructor(name: string) { this.name = name; - this.#demand = makeDemand(name, this.#used, this.#state); + this.#demand = makeDemand(name, this.#wanted, this.#state); } static { @@ -687,6 +709,8 @@ export class Producer { } if (own.bound && (!previous || previous.sequence < own.bound.sequence)) sequence.bound = own.bound; producer.#sequence = sequence; + // A replacement's subscribers want the group past what earlier producers wrote. + if (sequence.next > producer.#received) producer.#want(sequence.next); if (producer.#state.closed.peek() !== undefined) return; own.holders--; sequence.holders++; @@ -796,6 +820,23 @@ export class Producer { return this.#demand; } + // A subscriber joined at the live edge: ask for a new group when the newest one's bytes + // after its first frame exceed the refresh ratio times the first frame. + #join(): void { + const ratio = this.#state.info.peek()?.refresh; + const latest = this.#state.latest; + if (ratio === undefined || latest === undefined) return; + const group = this.#cached.get(latest)?.group; + if (group && hooks.overRefresh(group, ratio)) this.#want(latest + 1); + } + + // Raise the wanted floor, reporting it while anyone subscribes. + #want(group: number): void { + if (group <= this.#floor) return; + this.#floor = group; + if (this.#sinks.size > 0) this.#wanted.set(group); + } + // Register a downstream sink: seed its info, replay the retained window, and (while // the track is open) mirror future groups into it. A late subscriber to a closed // track still drains the buffered groups before seeing the end. @@ -808,8 +849,9 @@ export class Producer { const closed = this.#state.closed.peek(); if (closed === undefined) { + if (joinsLive(sink.update.peek())) this.#join(); this.#sinks.add(sink); - this.#used.set(true); + this.#wanted.set(this.#floor); // Forward subscription updates from the sink's Subscriber to the producer's own // state, which the wire layer (or the serving application) watches. @@ -827,8 +869,8 @@ export class Producer { this.#sinks.delete(sink); this.#updateSubscription(); // Update demand: once the last subscriber leaves, the consumer wire (watching - // {@link Demand.unused}) tears the upstream down instead of downloading to nobody. - this.#used.set(this.#sinks.size > 0); + // {@link Demand.wanted}) tears the upstream down instead of downloading to nobody. + this.#wanted.set(this.#sinks.size > 0 ? this.#floor : undefined); // A closed track leaves a sink's buffered mirrors readable; they age out // with the cache, so a stale consumer can't pin them. if (this.#state.closed.peek() !== undefined) { diff --git a/js/net/src/util/demand.ts b/js/net/src/util/demand.ts new file mode 100644 index 00000000000..4157274408f --- /dev/null +++ b/js/net/src/util/demand.ts @@ -0,0 +1,9 @@ +import { Signal } from "@moq/signals"; +import type { Demand } from "../track.ts"; + +/** Resolve once no subscriber wants the track, or it closed. */ +export async function unwanted(demand: Demand): Promise { + while (demand.wanted.peek() !== undefined && demand.closed.peek() === undefined) { + await Signal.race(demand.wanted, demand.closed); + } +} diff --git a/js/publish/src/broadcast.ts b/js/publish/src/broadcast.ts index 06f03d1ddcc..40c60d031f6 100644 --- a/js/publish/src/broadcast.ts +++ b/js/publish/src/broadcast.ts @@ -432,7 +432,7 @@ export class Broadcast { }); } inner.run((demand) => { - demand.set(signal, demand.get(served.demand().used) ? served : undefined); + demand.set(signal, demand.get(served.demand().wanted) !== undefined ? served : undefined); }); } }); diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 2552722b9e0..663e2aab715 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`TrackDemand.isUsed()`, `used()`, and `unused()` are gone. +`wanted()` returns null while nobody subscribes, otherwise the group subscribers want next, and `wantedChanged()` waits for it to change (the first call returns at once). +Loop on `wantedChanged()` until it returns non-null where you called `used()`, and null where you called `unused()`. +`TrackInfo` gains `refresh`. `GroupDemand` is unchanged. + ### Subscriptions carry group ranges (#5732) `Subscription.groupStart` and `groupEnd` are replaced by `ranges`, a list of `Range` whose ends are `AnchorAbsolute` or `AnchorRelative` (an absolute group and frame, or a count of groups before the latest), and an optional `order`. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 1b22b33f62f..81252df3c56 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -428,12 +428,12 @@ class SmokeTest { val producer = SnapshotProducer(broadcast, broadcast.publishTrack("status", null), config) val demand: TrackDemand = producer.demand() assertEquals("status", demand.name()) - assertEquals(false, demand.isUsed()) + assertEquals(null, demand.wanted()) val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null), config) - demand.used() + while (demand.wantedChanged() == null) {} consumer.cancel() - demand.unused() + while (demand.wantedChanged() != null) {} } } diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 980942e7d1e..4f2e44aea3d 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`TrackDemand.is_used()`, `used()`, and `unused()` are gone. +`wanted()` returns `None` while nobody subscribes, otherwise the group subscribers want next, and `await wanted_changed()` waits for it to change (the first call returns at once). +Loop on `wanted_changed()` until it returns non-`None` where you awaited `used()`, and `None` where you awaited `unused()`. +`TrackInfo` gains `refresh`. `GroupDemand` is unchanged. + ### Subscriptions carry group ranges (#5732) `Subscription.group_start` and `group_end` are replaced by `ranges`, a list of `Range` whose ends are an `Anchor` (an absolute group and frame, or a count of groups before the latest), and an optional `order`. diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index 861430b86c5..a065d3f7255 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -121,18 +121,22 @@ class TrackInfo: """Publisher-side track properties, mirroring moq-net's ``track::Info``. ``priority`` defaults to 127, the middle of the range. ``max_age`` is how long the - publisher caches a non-latest group, ``None`` for no limit. ``timescale`` is ticks - per second: ``None`` means the track is untimed, on both publish and receive. + publisher caches a non-latest group, ``None`` for no limit. ``refresh`` is how many + times its first frame a group's later bytes may grow before a joining subscriber + asks for a new group, ``None`` to never ask. ``timescale`` is ticks per second: + ``None`` means the track is untimed, on both publish and receive. """ priority: int = 127 max_age: timedelta | None = None + refresh: int | None = None timescale: int | None = None def _ffi(self) -> MoqTrackInfo: return MoqTrackInfo( priority=self.priority, max_age_us=_opt_us(self.max_age, "max_age"), + refresh=self.refresh, timescale=self.timescale, ) @@ -141,6 +145,7 @@ def _from_ffi(info: MoqTrackInfo) -> TrackInfo: return TrackInfo( priority=info.priority, max_age=None if info.max_age_us is None else _from_us(info.max_age_us), + refresh=info.refresh, timescale=info.timescale, ) diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 2406b7d7670..5812b10994f 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -63,7 +63,7 @@ def abort(self, error_code: int) -> None: class TrackDemand: - """A watch-only handle to whether a published track has subscribers. + """A watch-only handle to the group a published track's subscribers want next. Returned by a producer's ``demand()``. Weak: holding it neither keeps the track open nor locks the producer, so a wait can park here while the @@ -79,17 +79,16 @@ def name(self) -> str: """The name of the track this watches.""" return self._inner.name() - def is_used(self) -> bool: - """Whether the track has at least one active subscriber right now.""" - return self._inner.is_used() + def wanted(self) -> int | None: + """The group subscribers want next, or None while nobody subscribes. - async def used(self) -> None: - """Wait until the track has at least one active subscriber.""" - await self._inner.used() + A value past the newest group asks for a new group now, typically a keyframe. + """ + return self._inner.wanted() - async def unused(self) -> None: - """Wait until the track has no active subscribers.""" - await self._inner.unused() + async def wanted_changed(self) -> int | None: + """Wait for ``wanted`` to change and return it. The first call returns at once.""" + return await self._inner.wanted_changed() class TrackProducer: diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index c8bbdc650ed..c5263f35a01 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -14,6 +14,12 @@ FROM_GROUP_0 = [moq.Range(start=cast(moq.Anchor, moq.Anchor.ABSOLUTE(group=0, frame=0)))] +async def until_wanted(demand: moq.TrackDemand, wanted: bool = True) -> None: + """Wait until some subscriber wants the track, or none does.""" + while (await demand.wanted_changed() is not None) != wanted: + pass + + def create_announced(origin: moq.OriginProducer, path: str) -> moq.BroadcastProducer: broadcast = origin.create_broadcast(path) broadcast.announce() @@ -516,23 +522,23 @@ async def test_json_producers_report_demand(): snapshot_demand = snapshot.demand() stream_demand = stream.demand() assert snapshot_demand.name == "status" - assert not snapshot_demand.is_used() + assert snapshot_demand.wanted() is None consumer = broadcast.consume() snapshot_consumer = moq.json.SnapshotConsumer(await consumer.subscribe_track("status"), compression=True) stream_consumer = moq.json.StreamConsumer(await consumer.subscribe_track("events")) - await asyncio.wait_for(snapshot_demand.used(), timeout=5.0) - await asyncio.wait_for(stream_demand.used(), timeout=5.0) - assert snapshot_demand.is_used() + await asyncio.wait_for(until_wanted(snapshot_demand), timeout=5.0) + await asyncio.wait_for(until_wanted(stream_demand), timeout=5.0) + assert snapshot_demand.wanted() == 0 snapshot_consumer.cancel() stream_consumer.cancel() - await asyncio.wait_for(snapshot_demand.unused(), timeout=5.0) - await asyncio.wait_for(stream_demand.unused(), timeout=5.0) + await asyncio.wait_for(until_wanted(snapshot_demand, False), timeout=5.0) + await asyncio.wait_for(until_wanted(stream_demand, False), timeout=5.0) snapshot.finish() with pytest.raises(moq.Error.Closed): # type: ignore[attr-defined] - await asyncio.wait_for(snapshot_demand.used(), timeout=5.0) + await asyncio.wait_for(until_wanted(snapshot_demand), timeout=5.0) async def test_dynamic_track_request(): @@ -546,7 +552,7 @@ async def test_dynamic_track_request(): request = await asyncio.wait_for(dynamic.requested_track(), timeout=5.0) assert request.name == "events" demand = request.demand() - assert demand.is_used() + assert demand.wanted() is not None # Accept the request as a raw track (which unblocks the subscribe), then write. track = request.accept() @@ -559,12 +565,12 @@ async def test_dynamic_track_request(): assert frame.payload == payload track_consumer.cancel() - await asyncio.wait_for(demand.unused(), timeout=5.0) + await asyncio.wait_for(until_wanted(demand, False), timeout=5.0) track.finish() broadcast.close() del track with pytest.raises(moq.Error.Closed): # type: ignore[attr-defined] - await asyncio.wait_for(demand.used(), timeout=5.0) + await asyncio.wait_for(until_wanted(demand), timeout=5.0) async def test_media_subscribe_refuses_a_non_rendition(): diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index d7c7edff3e6..568e2fd5ac7 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -473,7 +473,9 @@ async def drain(reader: moq.TrackConsumer) -> None: consumer = await asyncio.wait_for(consume.request_broadcast("live"), timeout=5.0) reader = await asyncio.wait_for(consumer.subscribe_track("data"), timeout=5.0) reading.append(asyncio.create_task(drain(reader))) - await asyncio.wait_for(track.demand().used(), timeout=5.0) + demand = track.demand() + while await asyncio.wait_for(demand.wanted_changed(), timeout=5.0) is None: + pass raise ZeroDivisionError("boom") # The error exits the context without draining, but the session is over. assert session is not None diff --git a/quest/m1/refresh/README.md b/quest/m1/refresh/README.md index 0ba2a0e10e9..708e994f19d 100644 --- a/quest/m1/refresh/README.md +++ b/quest/m1/refresh/README.md @@ -62,7 +62,6 @@ Work owned by this README, after the children land: ## Required -- [Core](/quest/m1/refresh/core.md) - `track::Info::refresh` and `Demand::wanted` in Rust, JS, and moq-ffi; each hop evaluates the ratio on a join; IETF dynamic groups map onto it - [Lite wire](/quest/m1/refresh/lite.md) - lite-07 TRACK_INFO advertises the ratio and SUBSCRIBE_UPDATE carries the wanted group, so a join at any relay reaches the origin - [moq-json](/quest/m1/refresh/json.md) - snapshot and window groups roll on a qualifying join, reading the ratio from the track; `delta_ratio` and `op_ratio` become `deltas` and `ops` switches in every binding - [Video](/quest/m1/refresh/video.md) - video publishers advertise refresh and force a keyframe on demand, keeping the encoder's max GOP diff --git a/quest/m1/refresh/core.md b/quest/m1/refresh/core.md deleted file mode 100644 index 6fda8b7127f..00000000000 --- a/quest/m1/refresh/core.md +++ /dev/null @@ -1,72 +0,0 @@ -# [L] Refresh in the track model - -## Goal - -A Rust or JS publisher sets `track::Info::refresh` and awaits -`track::Demand::wanted`, which reports `None` while unused and `Some(n)` -when consumers want group `n` or later. A local join against a group whose -bytes after the first frame exceed `refresh` times the first frame moves -`n` past the largest group. `used()` and `unused()` are gone everywhere, -including moq-ffi and the binding wrappers. IETF tracks advertising -DYNAMIC_GROUPS and downstream NEW_GROUP_REQUESTs use the same path. - -## Plan - -Decided 2026-10-16 (see the [epic](/quest/m1/refresh/README.md)). - -- **API (Rust).** `track::Info::refresh: Option`, documented as the - delta-to-first-frame byte ratio past which a join asks for a new group. - `track::Demand::wanted() -> Option`, with `wanted_changed().await` - and `poll_wanted_changed`, following the `subscription_changed` pattern. - Delete `Demand::used`, `unused`, `is_used`, `poll_used`, and - `poll_unused`, and migrate every caller (about 30 Rust files, including - moq-audio, moq-mux, moq-gst, moq-hls, moq-boy, and moq-cli). -- **API (JS).** `track.Info.refresh` and `demand.wanted: Getter` replace `demand.used` and `unused()`. Migrate js/publish, - js/json, js/flate, and the other callers. -- **moq-ffi and bindings.** moq-ffi's `Demand` (`rs/moq-ffi/src/demand.rs`) - follows, as do moq-c, the py, swift, kt, go, and dart wrappers, `cpp/moq`, - `cpp/obs/src`, `doc/lib/*`, and `doc/bin/obs.md`. `MoqTrackInfo` gains `refresh`, beside `max_age_us`. - Because json producers read the ratio from the track, a binding could not - otherwise publish a refreshing json track (revised in the #5734 review). -- **Semantics.** - - The first consumer of a track with no group yields `Some(0)`. A paused - producer resumes on `Some` and opens a group when `n` passes its - largest. - - On a join, if the newest group's bytes after its first frame exceed - `refresh` times the first frame, `wanted` becomes `Some(largest + 1)`. - Otherwise the join reads the current group and nothing changes. A - request on a group under the ratio is dropped, not deferred. - - A pending `n` clears when `append_group` or `create_group` reaches it. - Further joins coalesce into it until then, which is the IETF - "outstanding until Largest Group grows" rule. - - The model measures bytes from the group's existing cache accounting, - with no app knowledge. It assumes a group's first frame is its - independent start, which is the moq-lite meaning of a group. - - `Subscription` stays subscriber-settable only and gains no request - field, so a subscriber cannot express an explicit request. -- **IETF mapping.** Replace #5708's crate-private `dynamic_groups` and - `Subscription::new_group`: - - DYNAMIC_GROUPS=1 on ingress becomes `refresh: Some(0)`. - - `refresh.is_some()` advertises DYNAMIC_GROUPS=1 on egress. - - A downstream NEW_GROUP_REQUEST counts as a join under the ratio, even - at a relay. This is a deliberate deviation from draft-22 §9.20.19, - which says a relay MUST forward it. Decided 2026-10-16 in the #5734 - review: the ratio is the point of refresh, and every hop's cache holds - the same group. Document it under deviations in - `doc/concept/standard.md`. - - The upstream IETF driver sends NEW_GROUP_REQUEST when `wanted` passes - the largest group. - - Keep #5708's suppression and teardown tests passing. -- **Tests.** Model tests under simulated time cover the first consumer, - unused, a join under the ratio, a join over it, coalesced joins, clearing - on append, `refresh: None`, and a replaced producer. A benchmark sweeps - tracks against subscribers per track, so the join check stays on the - touched track. -- Add a `MIGRATE.md` entry in each affected package for the `Demand` - break, and update `doc/concept/standard.md` for the IETF mapping. - -Public API: breaking (`Demand` in Rust, JS, moq-ffi, and every binding; -`track::Info::refresh` and `MoqTrackInfo::refresh` added). Wire: none in this quest. IETF fields are -interpreted as described above. diff --git a/quest/m1/refresh/json.md b/quest/m1/refresh/json.md index 836325a2bba..afd9086fc12 100644 --- a/quest/m1/refresh/json.md +++ b/quest/m1/refresh/json.md @@ -60,7 +60,7 @@ revised in the #5734 review. that cannot forward requests, so a joiner there downloads at most up to the caps. - This works locally without wire support: a local subscriber's join - drives `wanted` through [core](/quest/m1/refresh/core.md) alone. + drives `wanted` through the track model alone. - **In-repo users follow:** the hang and moq-mux catalog producers (`deltas: false`), `js/publish` catalog, moq-stats, the moq-room and `js/room` chat windows, the moq-hls and moq-archive tests, benches, and @@ -68,8 +68,8 @@ revised in the #5734 review. keep deltas. - **Bindings.** Replace `delta_ratio` with `deltas` in moq-ffi (`rs/moq-ffi/src/json.rs`), moq-c, the py, swift, go, kt, and dart wrappers, and - `doc/lib/*`. The ratio reaches them through `MoqTrackInfo::refresh` from - [core](/quest/m1/refresh/core.md), and the moq-ffi driver above refreshes + `doc/lib/*`. The ratio reaches them through `MoqTrackInfo::refresh`, and + the moq-ffi driver above refreshes their producers with no wrapper change. Update the moq-json and `@moq/json` READMEs and add an entry to each affected package's `MIGRATE.md`. - moq-flate is unchanged. Its snapshot mode already opens a group per @@ -88,10 +88,6 @@ Public API: breaking (`delta_ratio` and `op_ratio` replaced by `deltas` and and Rust `Producer::refresh` / `poll_refresh` added; bindings gain no refresh method because moq-ffi drives it internally). Wire: none. -## Required - -- [Core](/quest/m1/refresh/core.md) - `Demand::wanted` and `track::Info::refresh` - ## Related - [JSON window timestamps](/quest/m1/json-window-timestamps.md) - touches the same window code diff --git a/quest/m1/refresh/lite.md b/quest/m1/refresh/lite.md index 4388acfdd15..8ed29cc630e 100644 --- a/quest/m1/refresh/lite.md +++ b/quest/m1/refresh/lite.md @@ -42,9 +42,5 @@ relay reaches the origin's `wanted`, a join under it does not, and concurrent joins send one SUBSCRIBE_UPDATE. Use simulated time. Run `just test interop --all`. -Public API: none beyond [core](/quest/m1/refresh/core.md). Wire: two new -lite-07 fields. - -## Required - -- [Core](/quest/m1/refresh/core.md) - the model signal and ratio this carries +Public API: none beyond `Demand::wanted` and `track::Info::refresh`. Wire: two +new lite-07 fields. diff --git a/quest/m1/refresh/video.md b/quest/m1/refresh/video.md index 7b01910dff6..1ad728911c4 100644 --- a/quest/m1/refresh/video.md +++ b/quest/m1/refresh/video.md @@ -42,7 +42,3 @@ covers a ratio crossing within 500 ms of the previous keyframe. Public API: set by the open decision above, either an encoder or rendition config field for the ratio, or none for a fixed default. Wire: none. - -## Required - -- [Core](/quest/m1/refresh/core.md) - `Demand::wanted` and `track::Info::refresh` diff --git a/rs/moq-archive/src/reader/mod.rs b/rs/moq-archive/src/reader/mod.rs index 17b899d98e8..7658a572e41 100644 --- a/rs/moq-archive/src/reader/mod.rs +++ b/rs/moq-archive/src/reader/mod.rs @@ -478,7 +478,7 @@ async fn serve_track(shared: Arc>, request: track::Req let timescale = info.timescale; let dynamic = request.dynamic(); - let demand = dynamic.demand(); + let mut demand = dynamic.demand(); let _producer = request.accept(info); let mut groups = kio::Tasks::new(); @@ -493,9 +493,14 @@ async fn serve_track(shared: Arc>, request: track::Req Poll::Pending => break, } } - match groups.poll(waiter).is_ready() && demand.poll_unused(waiter).is_ready() { - true => Poll::Ready(()), - false => Poll::Pending, + if groups.poll(waiter).is_pending() { + return Poll::Pending; + } + // Drain the changes so the waiter stays registered, then read where demand settled. + while let Poll::Ready(Ok(Some(_))) = demand.poll_wanted_changed(waiter) {} + match demand.wanted() { + None => Poll::Ready(()), + Some(_) => Poll::Pending, } }) .await diff --git a/rs/moq-audio/src/encode/capture.rs b/rs/moq-audio/src/encode/capture.rs index 8a7e2e41df3..d9ed42b978b 100644 --- a/rs/moq-audio/src/encode/capture.rs +++ b/rs/moq-audio/src/encode/capture.rs @@ -793,21 +793,23 @@ trait Demand { impl Demand for moq_net::track::Demand { async fn used(&mut self) -> bool { - match moq_net::track::Demand::used(self).await { - Ok(()) => true, - Err(err) => { - log_track_ended(err); - false - } - } + until_wanted(self, true).await } async fn unused(&mut self) -> bool { - match moq_net::track::Demand::unused(self).await { - Ok(()) => true, + until_wanted(self, false).await + } +} + +/// Wait until some subscriber wants the track, or none does. +async fn until_wanted(demand: &mut moq_net::track::Demand, wanted: bool) -> bool { + loop { + match demand.wanted_changed().await { + Ok(next) if next.is_some() == wanted => return true, + Ok(_) => {} Err(err) => { log_track_ended(err); - false + return false; } } } diff --git a/rs/moq-audio/src/encode/producer.rs b/rs/moq-audio/src/encode/producer.rs index 9410af9f6ab..f9da91b58b6 100644 --- a/rs/moq-audio/src/encode/producer.rs +++ b/rs/moq-audio/src/encode/producer.rs @@ -595,24 +595,32 @@ mod tests { ..Options::default() }; let mut producer = Producer::new(&mut broadcast, catalog, Input::default(), &options).unwrap(); - let demand = producer.demand(); + let mut demand = producer.demand(); assert_eq!(demand.name(), "audio"); - assert!(!demand.is_used()); + assert_eq!(demand.wanted(), None); let subscriber = consumer.track("audio").unwrap().subscribe(None).await.unwrap(); - tokio::time::timeout(Duration::from_secs(1), demand.used()) + let wanted = async { + while demand.wanted_changed().await?.is_none() {} + moq_net::Result::Ok(()) + }; + tokio::time::timeout(Duration::from_secs(1), wanted) .await .expect("subscription demand") .unwrap(); - assert!(demand.is_used()); + assert_eq!(demand.wanted(), Some(0)); drop(subscriber); drop(consumer); - tokio::time::timeout(Duration::from_secs(1), demand.unused()) + let unwanted = async { + while demand.wanted_changed().await?.is_some() {} + moq_net::Result::Ok(()) + }; + tokio::time::timeout(Duration::from_secs(1), unwanted) .await .expect("subscription released") .unwrap(); - assert!(!demand.is_used()); + assert_eq!(demand.wanted(), None); producer.finish().unwrap(); drop(producer); diff --git a/rs/moq-boy/src/main.rs b/rs/moq-boy/src/main.rs index b9bcb741f9d..390f9e3da46 100644 --- a/rs/moq-boy/src/main.rs +++ b/rs/moq-boy/src/main.rs @@ -121,12 +121,19 @@ struct Session { location: Option, } +/// Wait until some viewer wants the track, or none does. +async fn until_wanted(demand: &moq_net::track::Demand, wanted: bool) -> moq_net::Result<()> { + let mut demand = demand.clone(); + while demand.wanted_changed().await?.is_some() != wanted {} + Ok(()) +} + impl Session { /// Monitor a single track's subscription state. /// Sets the flag when a viewer subscribes, clears it when all unsubscribe. async fn run_track_monitor(&self, name: &str, track: &moq_net::track::Demand, flag: &AtomicBool) { loop { - if track.used().await.is_err() { + if until_wanted(track, true).await.is_err() { break; } tracing::info!("resuming {name}: viewer subscribed"); @@ -134,7 +141,7 @@ impl Session { self.paused.store(false, Ordering::Release); self.resume.1.notify_all(); - if track.unused().await.is_err() { + if until_wanted(track, false).await.is_err() { break; } tracing::info!("pausing {name}: no viewers"); @@ -147,7 +154,10 @@ impl Session { async fn run_pause_monitor(&self) { loop { // Wait for BOTH tracks to become unused. - let (v, a) = tokio::join!(self.video_track.unused(), self.audio_track.unused()); + let (v, a) = tokio::join!( + until_wanted(&self.video_track, false), + until_wanted(&self.audio_track, false) + ); if v.is_err() || a.is_err() { break; } @@ -156,8 +166,8 @@ impl Session { // Wait for EITHER track to become used. tokio::select! { - Err(_) = self.video_track.used() => break, - Err(_) = self.audio_track.used() => break, + Err(_) = until_wanted(&self.video_track, true) => break, + Err(_) = until_wanted(&self.audio_track, true) => break, else => {}, } tracing::info!("resuming emulation: viewer connected"); diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 03754bd3542..e5cdbb9764e 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -500,53 +500,39 @@ impl Publish { pub(crate) async fn run_demand( callback: OnStatus, - demand: moq_net::track::Demand, + mut demand: moq_net::track::Demand, mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { - // Neither handle exposes the current state, only the level-triggered waits, and exactly - // one of them is ready at any instant: racing them is the read. Close is ignored until - // that seed is delivered, so a watcher closed before its first poll still reports USED - // or UNUSED before the terminal. An application dropping its producer ends the watcher; it - // does not keep the track alive and reports the close as clean. - let mut used = tokio::select! { - res = demand.used() => match res { - Ok(()) => true, - Err(moq_net::Error::Dropped) => return Ok(()), - Err(err) => return Err(err.into()), - }, - res = demand.unused() => match res { - Ok(()) => false, + // The first change is the current state. Close is ignored until it is delivered, so a + // watcher closed before its first poll still reports USED or UNUSED before the terminal. + // An application dropping its producer ends the watcher; it does not keep the track + // alive and reports the close as clean. + let mut used = None; + loop { + let next = match used { + None => demand.wanted_changed().await, + Some(_) => tokio::select! { + biased; + _ = &mut close => return Ok(()), + res = demand.wanted_changed() => res, + }, + }; + let next = match next { + Ok(wanted) => wanted.is_some(), Err(moq_net::Error::Dropped) => return Ok(()), Err(err) => return Err(err.into()), - }, - }; - - loop { - let state = if used { + }; + // A join that only moves the wanted group is no edge here. + if used == Some(next) { + continue; + } + used = Some(next); + let state = if next { moq_demand::MOQ_DEMAND_USED } else { moq_demand::MOQ_DEMAND_UNUSED }; callback.call(state as i32); - - // A flip between the report and this wait resolves it immediately, so no edge is - // lost; a double flip collapses into nothing, which is what a level signal means. - let flipped = async { - if used { - demand.unused().await - } else { - demand.used().await - } - }; - tokio::select! { - biased; - _ = &mut close => return Ok(()), - res = flipped => match res { - Ok(()) => used = !used, - Err(moq_net::Error::Dropped) => return Ok(()), - Err(err) => return Err(err.into()), - }, - } } } diff --git a/rs/moq-cli/tests/integration/listen.rs b/rs/moq-cli/tests/integration/listen.rs index a7fd53e58ee..55a39e9bea4 100644 --- a/rs/moq-cli/tests/integration/listen.rs +++ b/rs/moq-cli/tests/integration/listen.rs @@ -159,10 +159,12 @@ async fn an_export_stage_ending_during_drain_waits_for_every_session() { .established() .await .unwrap(); - tokio::time::timeout(TIMEOUT, catalog.demand().used()) - .await - .unwrap() - .unwrap(); + let mut demand = catalog.demand(); + let wanted = async { + while demand.wanted_changed().await?.is_none() {} + moq_net::Result::Ok(()) + }; + tokio::time::timeout(TIMEOUT, wanted).await.unwrap().unwrap(); let mut legacy = moq_tokio::connect::Config::default(); legacy.version = vec!["moq-lite-03".parse().unwrap()]; let legacy = legacy diff --git a/rs/moq-e2ee/src/tests.rs b/rs/moq-e2ee/src/tests.rs index e8ebd078fd4..7454c8f0f3a 100644 --- a/rs/moq-e2ee/src/tests.rs +++ b/rs/moq-e2ee/src/tests.rs @@ -530,11 +530,11 @@ fn reserved_track_serves_on_demand() { protected.producer.generation().name("audio").unwrap().as_str() ); let demand = request.demand(); - assert!(!demand.is_used()); + assert!(!demand.wanted().is_some()); let subscribing = protected.consumer.subscribe("audio", subscribe_all()).unwrap(); assert!(subscribing.poll_ok(&kio::Waiter::noop()).is_pending()); - assert!(demand.is_used()); + assert!(demand.wanted().is_some()); let mut audio = request.accept(timed()); let mut reader = resolve(&subscribing).unwrap(); @@ -752,7 +752,7 @@ impl Parked { fn grouped_failure_wakes_pending_reads_and_releases_demand() { let mut pair = pair("video"); let demand = pair.net.demand(); - assert!(demand.is_used()); + assert!(demand.wanted().is_some()); // One authentic frame, then silence. The group and the track stay open. let name: Name = pair.net.name().parse().unwrap(); @@ -800,7 +800,7 @@ fn grouped_failure_wakes_pending_reads_and_releases_demand() { assert!(frame.woken(), "parked frame read was not woken"); assert!(track.woken(), "parked group and datagram reads were not woken"); assert!( - !demand.is_used(), + !demand.wanted().is_some(), "track demand stayed live after authentication failure" ); assert!(!bad_demand.is_used(), "failed group demand stayed live"); @@ -844,7 +844,7 @@ fn dropping_track_releases_demand_while_group_is_held() { let mut group = recv_group(&mut pair.consumer); drop(pair.consumer); - assert!(!demand.is_used(), "a held group kept the track subscription"); + assert!(!demand.wanted().is_some(), "a held group kept the track subscription"); // The held group is not failed by the unsubscribe. assert_eq!(read_frame(&mut group).plaintext, &b"ok"[..]); @@ -878,14 +878,14 @@ fn bad_datagram_stays_an_event_and_keeps_demand() { frame.poll(|waiter| good.poll_read_frame(waiter)), Poll::Pending )); - assert!(demand.is_used()); + assert!(demand.wanted().is_some()); pair.producer.insert_datagram(1, ms(3), b"next").unwrap(); match recv_datagram(&mut pair.consumer) { Event::Datagram(d) => assert_eq!(&d.plaintext[..], b"next"), other => panic!("{other:?}"), } - assert!(demand.is_used()); + assert!(demand.wanted().is_some()); } #[test] diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index e75eb72a719..7501ead7149 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,14 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`MoqTrackDemand::is_used`, `used`, and `unused` are gone. +`wanted()` returns null while nobody subscribes, otherwise the group subscribers want next, and `wanted_changed()` waits for it to change (the first call returns at once). +Loop on `wanted_changed()` until it returns non-null where you awaited `used()`, and null where you awaited `unused()`. +`MoqTrackInfo` gains `refresh`, the ratio past which a joining subscriber asks for a new group. +`MoqGroupDemand` is unchanged. + ### Subscriptions carry group ranges (#5732) `MoqSubscription::group_start` and `group_end` are replaced by `ranges`, a list of `MoqRange { start, end }` whose ends are `MoqAnchor::Absolute { group, frame }` or `MoqAnchor::Relative { groups }`, and an optional `order`. diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index 3c4d3910d95..86b0d8e58c0 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -242,6 +242,7 @@ async fn rust_ffi() { let timed = MoqTrackInfo { priority: 127, max_age_us: None, + refresh: None, timescale: Some(1_000_000), }; let tracks: Vec<_> = (0..case.publishers) diff --git a/rs/moq-ffi/src/demand.rs b/rs/moq-ffi/src/demand.rs index 5bd689e1532..f06fa74d663 100644 --- a/rs/moq-ffi/src/demand.rs +++ b/rs/moq-ffi/src/demand.rs @@ -1,10 +1,10 @@ -//! Watching whether anyone still wants a published track or a requested group. +//! Watching what subscribers want of a published track, or whether a requested group is still wanted. use std::sync::Arc; use crate::error::MoqError; -/// A watch-only handle to a published track's subscriber demand. +/// A watch-only handle to the group a published track's subscribers want next. /// /// Weak: holding it neither keeps the track open nor locks the producer it came from, so a wait /// can park here while the producer keeps publishing. Waits fail with `Closed` once the track is @@ -12,11 +12,14 @@ use crate::error::MoqError; #[derive(uniffi::Object)] pub struct MoqTrackDemand { inner: moq_net::track::Demand, + // The watcher `wanted_changed` advances, kept apart so concurrent waits queue in turn. + changes: Arc>, } impl MoqTrackDemand { pub(crate) fn new(inner: moq_net::track::Demand) -> Arc { - Arc::new(Self { inner }) + let changes = Arc::new(tokio::sync::Mutex::new(inner.clone())); + Arc::new(Self { inner, changes }) } pub(crate) fn inner(&self) -> &moq_net::track::Demand { @@ -31,21 +34,32 @@ impl MoqTrackDemand { self.inner.name().to_string() } - /// Whether the track has at least one active consumer right now, without waiting. - pub fn is_used(&self) -> bool { - self.inner.is_used() + /// The group subscribers want next: null while nobody consumes the track, otherwise the + /// sequence the next group should have at least. A value past the newest group asks for a + /// new group now, typically a keyframe. + pub fn wanted(&self) -> Option { + self.inner.wanted() } - /// Wait until the track has at least one active consumer. - pub async fn used(&self) -> Result<(), MoqError> { - let demand = self.inner.clone(); - crate::ffi::detached(async move { gone(demand.used().await) }).await + /// Wait for `wanted` to change and return the new value. The first call returns at once. + pub async fn wanted_changed(&self) -> Result, MoqError> { + let changes = self.changes.clone(); + crate::ffi::detached(async move { gone(changes.lock().await.wanted_changed().await) }).await } +} - /// Wait until the track has no active consumers. - pub async fn unused(&self) -> Result<(), MoqError> { - let demand = self.inner.clone(); - crate::ffi::detached(async move { gone(demand.unused().await) }).await +#[cfg(test)] +impl MoqTrackDemand { + /// Wait until some subscriber wants the track. + pub(crate) async fn until_wanted(&self) -> Result<(), MoqError> { + while self.wanted_changed().await?.is_none() {} + Ok(()) + } + + /// Wait until no subscriber wants the track. + pub(crate) async fn until_unwanted(&self) -> Result<(), MoqError> { + while self.wanted_changed().await?.is_some() {} + Ok(()) } } @@ -95,7 +109,7 @@ impl MoqGroupDemand { /// /// That is how a finished track or request ends, which a demand watcher expects, not the internal /// failure `Dropped` means to a consumer. An aborted track or rejected request keeps its reason. -fn gone(result: Result<(), moq_net::Error>) -> Result<(), MoqError> { +fn gone(result: Result) -> Result { match result { Err(moq_net::Error::Dropped) => Err(MoqError::Closed), result => Ok(result?), diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 9e30534e81a..e0798506645 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -23,6 +23,11 @@ pub struct MoqTrackInfo { /// [`MoqSubscription::max_delay_us`](crate::consumer::MoqSubscription::max_delay_us). #[uniffi(default = None)] pub max_age_us: Option, + /// How many times its first frame a group's later bytes may grow before a joining + /// subscriber asks for a new group, or null to never ask. See + /// [`MoqTrackDemand::wanted`](crate::demand::MoqTrackDemand::wanted). + #[uniffi(default = None)] + pub refresh: Option, /// Per-frame timescale in ticks per second, or null for an untimed track. #[uniffi(default = None)] pub timescale: Option, @@ -32,7 +37,9 @@ impl TryFrom for moq_net::track::Info { type Error = MoqError; fn try_from(info: MoqTrackInfo) -> Result { - let mut out = moq_net::track::Info::default().with_priority(info.priority); + let mut out = moq_net::track::Info::default() + .with_priority(info.priority) + .with_refresh(info.refresh); if let Some(us) = info.max_age_us { out = out.with_max_age(std::time::Duration::from_micros(us)); } @@ -66,6 +73,7 @@ impl TryFrom<&moq_net::track::Info> for MoqTrackInfo { Ok(Self { priority: info.priority, max_age_us, + refresh: info.refresh, timescale: info.timescale.map(|timescale| timescale.as_u64()), }) } @@ -698,6 +706,7 @@ mod metadata_tests { let info = MoqTrackInfo { priority: 0, max_age_us, + refresh: None, timescale: None, }; let model = moq_net::track::Info::try_from(info).unwrap(); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 001a0c66161..b36c36930db 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -33,6 +33,7 @@ fn timed_info() -> MoqTrackInfo { MoqTrackInfo { priority: 127, max_age_us: None, + refresh: None, timescale: Some(1_000_000), } } @@ -537,13 +538,13 @@ async fn raw_track_activity() { assert_eq!(demand.name(), "status"); let consumer = track.consume(None).unwrap(); - tokio::time::timeout(TIMEOUT, demand.used()) + tokio::time::timeout(TIMEOUT, demand.until_wanted()) .await .expect("timed out waiting for raw track to become used") .unwrap(); drop(consumer); - tokio::time::timeout(TIMEOUT, demand.unused()) + tokio::time::timeout(TIMEOUT, demand.until_unwanted()) .await .expect("timed out waiting for raw track to become unused") .unwrap(); @@ -603,7 +604,7 @@ async fn raw_audio_activity() { ) .await .unwrap(); - tokio::time::timeout(TIMEOUT, audio.demand().unwrap().used()) + tokio::time::timeout(TIMEOUT, audio.demand().unwrap().until_wanted()) .await .expect("timed out waiting for raw audio to become used") .unwrap(); @@ -621,7 +622,7 @@ async fn raw_audio_activity() { assert_eq!(first.timestamp_us, FIRST_TIMESTAMP_US); drop(subscription); - tokio::time::timeout(TIMEOUT, audio.demand().unwrap().unused()) + tokio::time::timeout(TIMEOUT, audio.demand().unwrap().until_unwanted()) .await .expect("timed out waiting for raw audio to become unused") .unwrap(); @@ -635,7 +636,7 @@ async fn raw_audio_activity() { ) .await .unwrap(); - tokio::time::timeout(TIMEOUT, audio.demand().unwrap().used()) + tokio::time::timeout(TIMEOUT, audio.demand().unwrap().until_wanted()) .await .expect("timed out waiting for raw audio to become used again") .unwrap(); @@ -859,6 +860,7 @@ async fn raw_track_datagram_roundtrip() { Some(MoqTrackInfo { priority: 0, max_age_us: None, + refresh: None, timescale: Some(1_000_000), }), ) @@ -889,6 +891,7 @@ async fn raw_track_info_reports_publisher_properties() { let info = MoqTrackInfo { priority: 7, max_age_us: Some(2_500_000), + refresh: Some(2), timescale: Some(90_000), }; let track = broadcast.publish_track("status".into(), Some(info)).unwrap(); @@ -897,6 +900,7 @@ async fn raw_track_info_reports_publisher_properties() { let got = consumer.info().unwrap(); assert_eq!(got.priority, 7); assert_eq!(got.max_age_us, Some(2_500_000)); + assert_eq!(got.refresh, Some(2)); assert_eq!(got.timescale, Some(90_000)); } @@ -960,6 +964,7 @@ async fn data_writes_preserve_optional_timestamps() { Some(MoqTrackInfo { priority: 127, max_age_us: None, + refresh: None, timescale: timestamp_us.map(|_| 1_000_000), }), ) @@ -1151,29 +1156,29 @@ async fn json_demand() { let stream_demand = stream.demand().unwrap(); assert_eq!(snapshot_demand.name(), "status"); assert_eq!(stream_demand.name(), "events"); - assert!(!snapshot_demand.is_used()); + assert!(!snapshot_demand.wanted().is_some()); let snapshot_consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "status").await, snapshot_config).unwrap(); let stream_consumer = MoqJsonStreamConsumer::new(&*subscribe(&broadcast, "events").await, stream_config).unwrap(); - tokio::time::timeout(TIMEOUT, snapshot_demand.used()) + tokio::time::timeout(TIMEOUT, snapshot_demand.until_wanted()) .await .expect("timed out waiting for the json snapshot to become used") .unwrap(); - tokio::time::timeout(TIMEOUT, stream_demand.used()) + tokio::time::timeout(TIMEOUT, stream_demand.until_wanted()) .await .expect("timed out waiting for the json stream to become used") .unwrap(); - assert!(snapshot_demand.is_used()); + assert!(snapshot_demand.wanted().is_some()); drop(snapshot_consumer); drop(stream_consumer); - tokio::time::timeout(TIMEOUT, snapshot_demand.unused()) + tokio::time::timeout(TIMEOUT, snapshot_demand.until_unwanted()) .await .expect("timed out waiting for the json snapshot to become unused") .unwrap(); - tokio::time::timeout(TIMEOUT, stream_demand.unused()) + tokio::time::timeout(TIMEOUT, stream_demand.until_unwanted()) .await .expect("timed out waiting for the json stream to become unused") .unwrap(); @@ -1182,8 +1187,8 @@ async fn json_demand() { stream.finish().unwrap(); assert!(matches!(snapshot.demand(), Err(MoqError::Closed))); assert!(matches!(stream.demand(), Err(MoqError::Closed))); - assert!(matches!(snapshot_demand.used().await, Err(MoqError::Closed))); - assert!(matches!(stream_demand.used().await, Err(MoqError::Closed))); + assert!(matches!(snapshot_demand.until_wanted().await, Err(MoqError::Closed))); + assert!(matches!(stream_demand.until_wanted().await, Err(MoqError::Closed))); } /// A demand handle waits without the producer, and fails once the track is gone. @@ -1205,7 +1210,7 @@ async fn demand_handle_outlives_finish() { assert_eq!(media_demand.name(), media.demand().unwrap().name()); let consumer = track.consume(None).unwrap(); - tokio::time::timeout(TIMEOUT, track_demand.used()) + tokio::time::timeout(TIMEOUT, track_demand.until_wanted()) .await .expect("timed out waiting for the raw track to become used") .unwrap(); @@ -1214,10 +1219,10 @@ async fn demand_handle_outlives_finish() { track.finish().unwrap(); drop(track); media.finish().unwrap(); - let track_err = tokio::time::timeout(TIMEOUT, track_demand.used()) + let track_err = tokio::time::timeout(TIMEOUT, track_demand.until_wanted()) .await .expect("timed out waiting for the finished raw track"); - let media_err = tokio::time::timeout(TIMEOUT, media_demand.used()) + let media_err = tokio::time::timeout(TIMEOUT, media_demand.until_wanted()) .await .expect("timed out waiting for the finished media track"); assert!(matches!(track_err, Err(MoqError::Closed)), "{track_err:?}"); @@ -1322,20 +1327,20 @@ async fn track_request_demand_survives_accept() { let request = dynamic.requested_track().await.unwrap(); let demand = request.demand().unwrap(); assert_eq!(demand.name(), "events"); - assert!(demand.is_used()); + assert!(demand.wanted().is_some()); let track = request.accept(None).unwrap(); assert!(matches!(request.demand(), Err(MoqError::Closed))); let consumer = subscribe.await.unwrap().unwrap(); - demand.used().await.unwrap(); + demand.until_wanted().await.unwrap(); consumer.cancel(); - demand.unused().await.unwrap(); + demand.until_unwanted().await.unwrap(); let consumer = track.consume(None).unwrap(); - demand.used().await.unwrap(); + demand.until_wanted().await.unwrap(); consumer.cancel(); - demand.unused().await.unwrap(); + demand.until_unwanted().await.unwrap(); drop(track); broadcast.close().unwrap(); - assert!(matches!(demand.used().await, Err(MoqError::Closed))); + assert!(matches!(demand.until_wanted().await, Err(MoqError::Closed))); } #[tokio::test] @@ -1348,7 +1353,7 @@ async fn track_request_demand_ends_on_rejection() { let demand = request.demand().unwrap(); request.abort(404).unwrap(); assert!(subscribe.await.unwrap().is_err()); - assert!(demand.used().await.is_err()); + assert!(demand.until_wanted().await.is_err()); assert!(matches!(request.demand(), Err(MoqError::Closed))); } @@ -2303,13 +2308,13 @@ async fn media_track_activity_and_name() { assert!(catalog.audio.contains_key(&track_name)); let track_consumer = broadcast_consumer.subscribe_track(track_name, None).await.unwrap(); - tokio::time::timeout(TIMEOUT, media.demand().unwrap().used()) + tokio::time::timeout(TIMEOUT, media.demand().unwrap().until_wanted()) .await .expect("timed out waiting for media track to become used") .unwrap(); drop(track_consumer); - tokio::time::timeout(TIMEOUT, media.demand().unwrap().unused()) + tokio::time::timeout(TIMEOUT, media.demand().unwrap().until_unwanted()) .await .expect("timed out waiting for media track to become unused") .unwrap(); @@ -2979,12 +2984,12 @@ async fn video_raw_publish_consume() { assert_eq!(video.demand().unwrap().name(), "camera"); let local_consumer = broadcast.consume().unwrap(); let demand_consumer = local_consumer.subscribe_track("camera".into(), None).await.unwrap(); - tokio::time::timeout(TIMEOUT, video.demand().unwrap().used()) + tokio::time::timeout(TIMEOUT, video.demand().unwrap().until_wanted()) .await .expect("timed out waiting for video demand") .unwrap(); drop(demand_consumer); - tokio::time::timeout(TIMEOUT, video.demand().unwrap().unused()) + tokio::time::timeout(TIMEOUT, video.demand().unwrap().until_unwanted()) .await .expect("timed out waiting for video demand to clear") .unwrap(); @@ -4269,7 +4274,7 @@ async fn raw_read_frame_terminal_cancel_releases_demand() { let consumer = track.consume(None).unwrap(); let demand = track.demand().unwrap(); - tokio::time::timeout(TIMEOUT, demand.used()) + tokio::time::timeout(TIMEOUT, demand.until_wanted()) .await .expect("timed out waiting for the subscriber") .unwrap(); @@ -4293,7 +4298,7 @@ async fn raw_read_frame_terminal_cancel_releases_demand() { Ok(None) => panic!("cancelled read returned EOF"), } - tokio::time::timeout(TIMEOUT, demand.unused()) + tokio::time::timeout(TIMEOUT, demand.until_unwanted()) .await .expect("timed out waiting for demand to drop") .unwrap(); diff --git a/rs/moq-flate/src/stream/mod.rs b/rs/moq-flate/src/stream/mod.rs index 731785e901d..1a24503c91b 100644 --- a/rs/moq-flate/src/stream/mod.rs +++ b/rs/moq-flate/src/stream/mod.rs @@ -317,7 +317,7 @@ mod test { "compression={compression}" ); assert!(refused(producer.append(huge.clone())), "compression={compression}"); - assert!(producer.demand().is_used(), "a refusal must not end the track"); + assert!(producer.demand().wanted().is_some(), "a refusal must not end the track"); producer.append(&b"second"[..]).unwrap(); producer.finish().unwrap(); diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index ecaf7c293d1..abe64f42670 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -1954,14 +1954,13 @@ mod session_tests { // has: that edge says the session reconciled the removal, which a fixed beat can only // guess at. Answering before it lands is a pump that legitimately goes live, so the // wait is what the assertion below is about. + let mut demand = request.demand(); + let unwanted = async { + while demand.wanted_changed().await?.is_some() {} + moq_net::Result::Ok(()) + }; super::RUNTIME - .block_on(async { - tokio::time::timeout( - Duration::from_secs(10), - moq_net::kio::wait(|waiter| request.demand().poll_unused(waiter)), - ) - .await - }) + .block_on(async { tokio::time::timeout(Duration::from_secs(10), unwanted).await }) .expect("the cancelled pump never dropped its subscription") .expect("the pending request is still open"); diff --git a/rs/moq-hls/src/server/routes.rs b/rs/moq-hls/src/server/routes.rs index 3f746a30378..69d0e0cc2d6 100644 --- a/rs/moq-hls/src/server/routes.rs +++ b/rs/moq-hls/src/server/routes.rs @@ -809,11 +809,15 @@ mod tests { let mut cursor = rendition.segments(); let mut next = std::pin::pin!(cursor.next()); // Waiting for its first segment, the cursor subscribes before any media exists. - let demand = track.demand(); + let mut demand = track.demand(); + let wanted = async { + while demand.wanted_changed().await?.is_none() {} + moq_net::Result::Ok(()) + }; tokio::time::timeout(TIMEOUT, async { tokio::select! { _ = next.as_mut() => panic!("{version}: a segment before any media"), - used = demand.used() => used.expect("track open"), + wanted = wanted => wanted.expect("track open"), } }) .await diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 547f350e14d..8f51bc3e2de 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -187,16 +187,13 @@ mod test { fn demand_follows_subscribers() { let (producer, consumer) = producer(Config::default()); let demand = producer.demand(); - let waiter = kio::Waiter::noop(); - assert!(matches!(demand.poll_used(&waiter), Poll::Ready(Ok(())))); + assert_eq!(demand.wanted(), Some(0)); drop(consumer); - assert!(matches!(demand.poll_unused(&waiter), Poll::Ready(Ok(())))); - assert!(demand.poll_used(&waiter).is_pending()); + assert_eq!(demand.wanted(), None); let _consumer = producer.consume(); - assert!(matches!(demand.poll_used(&waiter), Poll::Ready(Ok(())))); - assert!(demand.poll_unused(&waiter).is_pending()); + assert_eq!(demand.wanted(), Some(0)); } /// Drain every value currently available from a plaintext consumer without blocking. diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index 1241bea79bb..7dcfb0d8472 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -126,16 +126,13 @@ mod test { fn demand_follows_subscribers() { let (producer, consumer) = producer(Config::default()); let demand = producer.demand(); - let waiter = kio::Waiter::noop(); - assert!(matches!(demand.poll_used(&waiter), Poll::Ready(Ok(())))); + assert_eq!(demand.wanted(), Some(0)); drop(consumer); - assert!(matches!(demand.poll_unused(&waiter), Poll::Ready(Ok(())))); - assert!(demand.poll_used(&waiter).is_pending()); + assert_eq!(demand.wanted(), None); let _consumer = producer.consume(); - assert!(matches!(demand.poll_used(&waiter), Poll::Ready(Ok(())))); - assert!(demand.poll_unused(&waiter).is_pending()); + assert_eq!(demand.wanted(), Some(0)); } fn compressed() -> Config { diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index fe26ab0ec30..068c28a9df9 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -2230,7 +2230,8 @@ mod tests { let source = moq_net::broadcast::Info::new().produce(); let mut track = source.create_track("video", info.clone()).unwrap(); route.requested_broadcast().await.unwrap().accept(&source); - track.demand().used().await.unwrap(); + let mut demand = track.demand(); + while demand.wanted_changed().await.unwrap().is_none() {} if sequence == 1 { assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); } diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index cb2a5a3cf0e..bfe0b6f1632 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -166,11 +166,9 @@ name = "request-ids" harness = false required-features = ["fuzz"] -# Uses the hidden fuzz module to reach the crate-private NEW_GROUP_REQUEST. [[bench]] -name = "new-group" +name = "refresh" harness = false -required-features = ["fuzz"] # Uses the hidden fuzz module to observe source selection without public API. [[bench]] diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index bdcf4edb0b6..1c68f9c1987 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,24 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`track::Demand::used`, `unused`, `is_used`, `poll_used`, and `poll_unused` are gone. +`wanted()` returns `None` while nobody consumes the track and `Some(n)` while consumers want group `n` or later; open a group whenever `n` passes your largest. +`wanted_changed().await` (or `poll_wanted_changed`) returns it at once on the first call, then on each change, and errors once the track closes. +A clone of a `Demand` watches on its own. + +```rust +// Before +demand.used().await?; +demand.unused().await?; +// After +while demand.wanted_changed().await?.is_none() {} +while demand.wanted_changed().await?.is_some() {} +``` + +`track::Info::refresh` opts a track in to new groups on join: set it with `Info::with_refresh(ratio)`. + ### Track readers follow `largest()` instead of reading `latest()` (#5725) `latest()` on `track::{Producer, Consumer, Subscriber, Ordered}` is gone. diff --git a/rs/moq-net/benches/new-group.rs b/rs/moq-net/benches/new-group.rs deleted file mode 100644 index 633239feb9a..00000000000 --- a/rs/moq-net/benches/new-group.rs +++ /dev/null @@ -1,36 +0,0 @@ -//! A downstream NEW_GROUP_REQUEST reaching a relay's upstream subscription: one -//! subscriber raises its request and the track's upstream driver reads the aggregate. -//! Swept over tracks and subscribers per track, so a cost that grows with the relay's -//! other tracks instead of the touched track's subscribers shows up as a slope. -//! -//! The request is crate-private, so this reaches it through the hidden `fuzz` module. -//! -//! Run with `cargo bench -p moq-net --features fuzz --bench new-group`. - -use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; -use moq_net::fuzz::NewGroups; - -const TRACKS: [usize; 3] = [1, 100, 1_000]; -const SUBSCRIBERS: [usize; 3] = [1, 10, 100]; - -fn request(c: &mut Criterion) { - let mut group = c.benchmark_group("new_group/request"); - for tracks in TRACKS { - for subscribers in SUBSCRIBERS { - let mut relay = NewGroups::new(tracks, subscribers); - let mut value = 0; - group.bench_function(BenchmarkId::new(format!("{tracks}x"), subscribers), |b| { - b.iter(|| { - // A higher value every time, so the aggregate always changes. - value += 1; - let seen = relay.request(tracks / 2, subscribers / 2, value); - assert_eq!(seen, Some(value)); - }) - }); - } - } - group.finish(); -} - -criterion_group!(benches, request); -criterion_main!(benches); diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index df226650408..461dc9185ab 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -1178,7 +1178,7 @@ impl Generation { async fn announce(&self, epoch: &Epoch) { self.route(epoch); for track in &self.tracks { - moq_clock::timeout(COPY_WAIT, track.demand().used()) + moq_clock::timeout(COPY_WAIT, support::wanted(track.demand())) .await .expect("route swap did not splice") .expect("replacement track closed"); @@ -1344,7 +1344,7 @@ async fn resume_overlap(readers: usize, retained: usize, routes: usize) -> Resum for _ in 1..routes { generations.push(generation(&mut (0..retained).rev())); let (_, latest) = generations.last().unwrap(); - moq_clock::timeout(COPY_WAIT, latest.demand().used()) + moq_clock::timeout(COPY_WAIT, support::wanted(latest.demand())) .await .expect("route swap did not splice") .expect("replacement track closed"); diff --git a/rs/moq-net/benches/refresh.rs b/rs/moq-net/benches/refresh.rs new file mode 100644 index 00000000000..51043b072e4 --- /dev/null +++ b/rs/moq-net/benches/refresh.rs @@ -0,0 +1,55 @@ +//! A join judged by the track's refresh ratio, then the group it asked for: swept over +//! tracks and subscribers per track. The judgment reads only the joined track's newest +//! group, so a cost that grows with the other tracks or the joined track's audience +//! shows up as a slope. +//! +//! Run with `cargo bench -p moq-net --bench refresh`. + +use bytes::Bytes; +use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; +use moq_net::{broadcast, track}; + +const TRACKS: [usize; 3] = [1, 100, 1_000]; +const SUBSCRIBERS: [usize; 3] = [1, 10, 100]; + +/// Append a group whose delta outweighs its first frame. +fn refreshable(track: &track::Producer) { + let mut group = track.append_group().unwrap(); + group.write_frame(None, Bytes::from_static(b"key")).unwrap(); + group.write_frame(None, Bytes::from_static(b"delta")).unwrap(); + group.finish().unwrap(); +} + +fn join(c: &mut Criterion) { + let mut group = c.benchmark_group("refresh/join"); + for tracks in TRACKS { + for subscribers in SUBSCRIBERS { + let broadcast = broadcast::Info::default().produce(); + let info = track::Info::default().with_refresh(1); + let producers: Vec<_> = (0..tracks) + .map(|i| broadcast.create_track(format!("bench{i}"), info.clone()).unwrap()) + .collect(); + let _audience: Vec> = producers + .iter() + .map(|track| (0..subscribers).map(|_| track.subscribe(None)).collect()) + .collect(); + let track = &producers[tracks / 2]; + let demand = track.demand(); + refreshable(track); + let mut latest = 0; + group.bench_function(BenchmarkId::new(format!("{tracks}x"), subscribers), |b| { + b.iter(|| { + let joined = track.subscribe(None); + assert_eq!(demand.wanted(), Some(latest + 1)); + drop(joined); + refreshable(track); + latest += 1; + }) + }); + } + } + group.finish(); +} + +criterion_group!(benches, join); +criterion_main!(benches); diff --git a/rs/moq-net/benches/session.rs b/rs/moq-net/benches/session.rs index 9edebb67b78..46dc6df305f 100644 --- a/rs/moq-net/benches/session.rs +++ b/rs/moq-net/benches/session.rs @@ -988,10 +988,10 @@ impl ChurnRoom { let track = self.broadcasts[session].track(&format!("churn{session}")).unwrap(); let subscriber = track.subscribe(None).await.unwrap(); // The relay saw the request, rather than a cached track answering it locally. - self.churn[session].demand().used().await.unwrap(); + support::wanted(self.churn[session].demand()).await.unwrap(); drop(subscriber); drop(track); - self.churn[session].demand().unused().await.unwrap(); + support::unwanted(self.churn[session].demand()).await.unwrap(); } start.elapsed() } diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index be45262c4c6..d007dcad3d1 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -1284,47 +1284,6 @@ impl RequestValidity { } } -/// A relay's tracks, each with its downstream subscribers, for the private -/// NEW_GROUP_REQUEST benchmark. -pub struct NewGroups { - tracks: Vec<(track::Producer, Vec, Option)>, - _broadcast: broadcast::Producer, -} - -impl NewGroups { - /// `tracks` tracks of `subscribers` subscribers each, none of them asking for a group. - pub fn new(tracks: usize, subscribers: usize) -> Self { - let broadcast = broadcast::Producer::new(broadcast::Info::default()); - let tracks = (0..tracks) - .map(|i| { - let track = broadcast.create_track(format!("{i}"), None).unwrap(); - let subscribers = (0..subscribers).map(|_| track.subscribe(None)).collect(); - (track, subscribers, None) - }) - .collect(); - Self { - tracks, - _broadcast: broadcast, - } - } - - /// One subscriber of one track asks for `value`, returning the request its upstream - /// subscription now sees, or `None` if that did not change. - pub fn request(&mut self, track: usize, subscriber: usize, value: u64) -> Option { - let (producer, subscribers, asked) = &mut self.tracks[track]; - subscribers[subscriber] - .update(track::Subscription { - new_group: crate::model::NewGroup::new(value, None), - ..Default::default() - }) - .unwrap(); - match producer.poll_new_group(asked, &kio::Waiter::noop()) { - std::task::Poll::Ready(Ok(new_group)) => new_group.map(|new_group| new_group.value), - _ => None, - } - } -} - #[cfg(test)] mod tests { use super::*; diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index 47abf6a4bd8..af1f7162312 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -26,8 +26,6 @@ pub mod hidden; mod location; pub mod message; mod namespace; -#[cfg(feature = "async")] -mod new_group; mod object; pub mod peer; mod priority; diff --git a/rs/moq-net/src/ietf/new_group.rs b/rs/moq-net/src/ietf/new_group.rs deleted file mode 100644 index fda92e72ddb..00000000000 --- a/rs/moq-net/src/ietf/new_group.rs +++ /dev/null @@ -1,144 +0,0 @@ -//! A relay's NEW_GROUP_REQUEST forwarding (moq-transport draft-15 section 9.2.1.12 through -//! draft-22 section 9.20.19, unchanged across them). -//! -//! Downstream subscribers' requests reach one upstream subscription as the highest one any -//! of them holds. On an Established subscription to a track with DYNAMIC_GROUPS, that goes -//! upstream in a REQUEST_UPDATE unless it names a group the relay already has, or a request -//! still outstanding covers it. A request stays outstanding until the Largest Group passes -//! where it stood when the request was sent: the publisher acknowledging the update says -//! nothing about whether a new group exists. - -/// The NEW_GROUP_REQUEST outstanding on one upstream subscription. Dropped with it, so a -/// reconnect or another route starts with none. -#[derive(Debug, Default)] -pub(super) struct Outstanding(Option); - -#[derive(Debug, Clone, Copy)] -struct Sent { - value: u64, - /// The Largest Group when it was sent; the request is answered once that grows. - largest: Option, -} - -impl Outstanding { - /// Record the request a SUBSCRIBE carried, which the draft has a relay without an - /// Established subscription include unconditionally. `largest` is what its - /// SUBSCRIBE_OK said, the first Largest Group this subscription knows. - pub fn subscribed(&mut self, value: u64, largest: Option) { - self.0 = Some(Sent { value, largest }); - } - - /// Whether a request for `value` goes upstream now, given the track's `largest` Group, - /// recording it as outstanding when it does. The caller checked the track supports - /// dynamic groups. - pub fn forward(&mut self, value: u64, largest: Option) -> bool { - if self.0.is_some_and(|sent| largest > sent.largest) { - self.0 = None; - } - // A nonzero value at or below the Largest Group names a group that already exists. - if value != 0 && largest.is_some_and(|largest| value <= largest) { - return false; - } - let request = Sent { value, largest }; - if self.0.is_some_and(|sent| sent.reach() >= request.reach()) { - return false; - } - self.0 = Some(request); - true - } -} - -impl Sent { - /// The highest request this one covers. A 0 asks for any group past the Largest Group - /// it was sent at, the same as naming the one after it. - fn reach(self) -> u64 { - match (self.value, self.largest) { - (0, Some(largest)) => largest.saturating_add(1), - (value, _) => value, - } - } -} - -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn a_request_past_the_largest_group_is_forwarded() { - let mut outstanding = Outstanding::default(); - assert!(outstanding.forward(6, Some(5))); - } - - #[test] - fn zero_is_forwarded_whatever_the_largest_group() { - assert!(Outstanding::default().forward(0, None)); - assert!(Outstanding::default().forward(0, Some(5))); - } - - #[test] - fn a_request_for_an_existing_group_is_stale() { - let mut outstanding = Outstanding::default(); - assert!(!outstanding.forward(5, Some(5))); - assert!(!outstanding.forward(1, Some(5))); - // Nothing was sent, so nothing is outstanding. - assert!(outstanding.forward(6, Some(5))); - } - - #[test] - fn an_outstanding_request_covers_lower_and_equal_ones() { - let mut outstanding = Outstanding::default(); - assert!(outstanding.forward(6, Some(5))); - assert!(!outstanding.forward(6, Some(5))); - assert!(!outstanding.forward(0, Some(5))); - } - - #[test] - fn zero_covers_the_group_after_the_largest() { - let mut outstanding = Outstanding::default(); - assert!(outstanding.forward(0, Some(5))); - assert!(!outstanding.forward(6, Some(5))); - assert!(outstanding.forward(7, Some(5))); - } - - #[test] - fn a_higher_request_is_forwarded_past_an_outstanding_one() { - let mut outstanding = Outstanding::default(); - assert!(outstanding.forward(6, Some(5))); - assert!(outstanding.forward(7, Some(5))); - assert!(!outstanding.forward(7, Some(5))); - } - - #[test] - fn a_new_group_rearms_requests() { - let mut outstanding = Outstanding::default(); - assert!(outstanding.forward(0, Some(5))); - assert!(!outstanding.forward(0, Some(5))); - // The Largest Group grew, so the request was answered. - assert!(outstanding.forward(0, Some(6))); - assert!(outstanding.forward(8, Some(6))); - } - - #[test] - fn the_first_group_answers_a_request_sent_before_any() { - let mut outstanding = Outstanding::default(); - assert!(outstanding.forward(0, None)); - assert!(!outstanding.forward(0, None)); - assert!(outstanding.forward(0, Some(0))); - } - - #[test] - fn a_stale_subscribe_request_covers_no_zero() { - let mut outstanding = Outstanding::default(); - // SUBSCRIBE_OK showed group 5 already existed, so the request asked for nothing. - outstanding.subscribed(5, Some(7)); - assert!(outstanding.forward(0, Some(7))); - } - - #[test] - fn a_subscribe_request_is_outstanding_from_its_answer() { - let mut outstanding = Outstanding::default(); - outstanding.subscribed(0, Some(5)); - assert!(!outstanding.forward(0, Some(5))); - assert!(outstanding.forward(0, Some(6))); - } -} diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index a1cbb283cc6..5b883c213b8 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -18,7 +18,6 @@ use crate::{ AsPath, DecodeError, Error, Timescale, Timestamp, coding::{Decode as _, Encode as _, Encoder, Stream, Writer}, ietf::{self, Control, EndLocation, FetchHeader, FetchType, Filter, GroupOrder, Location, RequestId}, - model::NewGroup, priority::{Priority, PriorityHandle, PriorityQueue}, track::{Order, Subscription}, util::{MaybeBoxedExt, MaybeSendBox}, @@ -57,9 +56,8 @@ fn track_properties(info: &track::Info, wanted: bool) -> ietf::Properties { timescale: info.timescale, priority: Some(super::priority::to_wire(info.priority)), group_order: Some(GroupOrder::Descending), - // Advertised only where an upstream session carries the request back to the - // original publisher; a local track has nothing to answer it. - dynamic_groups: info.dynamic_groups, + // A track opted in to refresh answers a NEW_GROUP_REQUEST as a join. + dynamic_groups: info.refresh.is_some(), } } @@ -1169,10 +1167,9 @@ where }; let order = msg.group_order.to_order(); + // A NEW_GROUP_REQUEST here asks nothing more: subscribing is itself a join, + // which the track's refresh ratio judges. let mut subscription = serving_subscription(msg.subscriber_priority).with_order(order); - // Set before subscribing, so a relay that has no upstream subscription yet - // carries it on the SUBSCRIBE it opens, as the draft requires. - subscription.new_group = msg.new_group.and_then(|value| NewGroup::new(value, None)); // Subscribe before resolving the filter: on a routed broadcast the live edge only // becomes readable once the subscription's demand attaches a route, so the edge @@ -1208,8 +1205,6 @@ where None => track::Position::after_group(end.group), }), ); - // The live edge is only known once subscribed. - subscription.new_group = msg.new_group.and_then(|value| NewGroup::new(value, edge.latest)); let _ = track.update(subscription); // A Timestamp goes out wherever the draft can declare its units and the track // has them. A subscriber that opted out of this SUBSCRIBE_OK's properties learns @@ -1636,7 +1631,7 @@ where )) } // The draft forbids it on a track that did not advertise DYNAMIC_GROUPS. - None if update.new_group.is_some() && !serve.track.info().dynamic_groups => Some(( + None if update.new_group.is_some() && serve.track.info().refresh.is_none() => Some(( "NEW_GROUP_REQUEST on a track without DYNAMIC_GROUPS", Error::Unsupported, )), @@ -1657,7 +1652,7 @@ where .map_err(failed)?; } if let Some(value) = update.new_group { - serve.request_new_group(value).map_err(failed)?; + serve.request_new_group(value); } if let (Some(token), Some(grant)) = (update.authorization_token, request_grant) { renewal.verify(grant.verify_renewal(&self.auth, token.0), update.request_id); @@ -4107,17 +4102,14 @@ impl TrackServe { Ok(()) } - /// Hold the subscriber's NEW_GROUP_REQUEST until a group answers it; the upstream - /// session decides whether it goes further. One a held group answers asks nothing. - fn request_new_group(&mut self, value: u64) -> Result<(), Error> { - let Some(request) = NewGroup::new(value, self.track.latest_sequence()) else { - return Ok(()); - }; - let mut subscription = self.track.subscription(); - // Merged like requests from different subscribers, so a later, weaker request does - // not drop a stronger one still held. - subscription.new_group = subscription.new_group.max(Some(request)); - self.track.update(subscription) + /// The subscriber's NEW_GROUP_REQUEST counts as a join, judged by the track's refresh + /// ratio rather than forwarded as is: every hop's cache holds the same group. One + /// naming a group already held asks nothing, since that group is on its way. + fn request_new_group(&self, value: u64) { + if value != 0 && self.track.latest_sequence().is_some_and(|latest| value <= latest) { + return; + } + self.track.join(); } /// Group streams opened so far. @@ -6787,124 +6779,87 @@ mod serve_tests { ietf::SubscribeOk::decode_msg(&mut Decoder::new(&rest[2..2 + size], version.into()), version).unwrap() } - /// A SUBSCRIBE's NEW_GROUP_REQUEST for 0 reaches the track still 0, so a relay behind - /// the original publisher forwards what was asked, but answered only by a group past - /// the latest. SUBSCRIBE_OK advertises DYNAMIC_GROUPS only for a track that supports it. - #[moq_clock::test] - async fn a_subscribe_new_group_request_reaches_the_track() { - for (version, dynamic_groups) in [ - (Version::Draft15, true), - (Version::Draft15, false), - (Version::Draft16, true), - (Version::Draft16, false), - (Version::Draft22, true), - (Version::Draft22, false), - ] { - let h = serve_track( - version, - crate::track::Info { - dynamic_groups, - ..crate::track::Info::timed() - }, - ); - let _group = h.track.create_group(group::Info { sequence: 4 }).unwrap(); - let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); - let msg = ietf::Subscribe { - new_group: Some(0), - ..subscribe(Filter::NextObject, None) - }; - let mut serve = std::pin::pin!(h.publisher.clone().run_subscribe_stream(stream, msg)); - serve_until(serve.as_mut(), "the request reached the track past group 4", || { - h.track.new_group() == Some(NewGroup { value: 0, first: 5 }) - }) - .await; - assert_eq!( - subscribe_ok(&h.log, version).properties.dynamic_groups, - dynamic_groups, - "{version}" - ); - } + /// Group 4 of `h`'s track: a 3 byte first frame and a 5 byte delta, over a refresh + /// ratio of 1. + fn refresh_group(h: &Serve) -> group::Producer { + let mut group = h.track.create_group(group::Info { sequence: 4 }).unwrap(); + group.write_frame(Timestamp::ZERO, b"key".as_slice()).unwrap(); + group.write_frame(Timestamp::ZERO, b"delta".as_slice()).unwrap(); + group } - /// An update's NEW_GROUP_REQUEST is recorded on a track with DYNAMIC_GROUPS and - /// answered with REQUEST_OK. + /// A SUBSCRIBE is a join, with or without NEW_GROUP_REQUEST: a track opted in to refresh + /// wants the group past one over its ratio, and SUBSCRIBE_OK advertises DYNAMIC_GROUPS. #[moq_clock::test] - async fn a_new_group_update_reaches_a_dynamic_track() { + async fn a_subscribe_joins_under_the_refresh_ratio() { for version in [Version::Draft15, Version::Draft16, Version::Draft22] { - let h = serve_track( - version, - crate::track::Info { - dynamic_groups: true, - ..crate::track::Info::timed() - }, - ); - let mut session = ScriptedSession::new(new_group_update(version, 10, 9)); - let mut stream = Stream::open(&mut session, version).await.unwrap(); - let mut serving = TrackServe::new( - h.session.clone(), - h.track.subscribe(None), - RequestId(0), - version, - ServeRange::default(), - None, - ); - let mut finished = false; - let mut run = - std::pin::pin!( - h.publisher - .run_subscription(&mut stream, &mut serving, &mut finished, async {}, None) + for refresh in [Some(1), None] { + let h = serve_track(version, crate::track::Info::timed().with_refresh(refresh)); + let _group = refresh_group(&h); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let msg = ietf::Subscribe { + new_group: Some(0), + ..subscribe(Filter::NextObject, None) + }; + let wanted = if refresh.is_some() { 5 } else { 0 }; + let mut serve = std::pin::pin!(h.publisher.clone().run_subscribe_stream(stream, msg)); + serve_until(serve.as_mut(), "the join reached the track", || { + h.track.demand().wanted() == Some(wanted) && !h.log.trail().is_empty() + }) + .await; + assert_eq!( + subscribe_ok(&h.log, version).properties.dynamic_groups, + refresh.is_some(), + "{version}" ); - assert!(futures::poll!(run.as_mut()).is_pending(), "{version}: update ended it"); - assert_eq!(h.track.new_group(), Some(NewGroup { value: 9, first: 0 }), "{version}"); - // Draft 16 names the update it answers; later drafts answer on its own stream. - let written = session.log.writes.lock().unwrap().clone(); - assert_eq!(written[0], ietf::RequestOk::ID as u8, "{version}: {written:?}"); - if version == Version::Draft16 { - assert_eq!(written[3], 10, "{version}: {written:?}"); } } } - /// A weaker request on the same subscription keeps the stronger one it still holds. + /// An update's NEW_GROUP_REQUEST is a join on a track opted in to refresh, answered with + /// REQUEST_OK. One naming a group the track holds asks nothing. #[moq_clock::test] - async fn a_later_update_keeps_the_stronger_request() { + async fn a_new_group_update_joins_a_refreshing_track() { for version in [Version::Draft15, Version::Draft16, Version::Draft22] { - let h = serve_track( - version, - crate::track::Info { - dynamic_groups: true, - ..crate::track::Info::timed() - }, - ); - let mut session = - ScriptedSession::new([new_group_update(version, 10, 9), new_group_update(version, 12, 0)].concat()); - let mut stream = Stream::open(&mut session, version).await.unwrap(); - let mut serving = TrackServe::new( - h.session.clone(), - h.track.subscribe(None), - RequestId(0), - version, - ServeRange::default(), - None, - ); - let mut finished = false; - let mut run = - std::pin::pin!( - h.publisher - .run_subscription(&mut stream, &mut serving, &mut finished, async {}, None) + for (value, wanted) in [(0, 5), (5, 5), (4, 0)] { + let h = serve_track(version, crate::track::Info::timed().with_refresh(1)); + let mut session = ScriptedSession::new(new_group_update(version, 10, value)); + let mut stream = Stream::open(&mut session, version).await.unwrap(); + // Subscribed before the group, so only the update can ask for a new one. + let subscriber = h.track.subscribe(None); + let _group = refresh_group(&h); + let mut serving = TrackServe::new( + h.session.clone(), + subscriber, + RequestId(0), + version, + ServeRange::default(), + None, ); - assert!( - futures::poll!(run.as_mut()).is_pending(), - "{version}: an update ended it" - ); - assert_eq!(h.track.new_group(), Some(NewGroup { value: 9, first: 0 }), "{version}"); + let mut finished = false; + let mut run = std::pin::pin!(h.publisher.run_subscription( + &mut stream, + &mut serving, + &mut finished, + async {}, + None + )); + assert!(futures::poll!(run.as_mut()).is_pending(), "{version}: update ended it"); + assert_eq!(h.track.demand().wanted(), Some(wanted), "{version} {value}"); + // Draft 16 names the update it answers; later drafts answer on its own stream. + let written = session.log.writes.lock().unwrap().clone(); + assert_eq!(written[0], ietf::RequestOk::ID as u8, "{version}: {written:?}"); + if version == Version::Draft16 { + assert_eq!(written[3], 10, "{version}: {written:?}"); + } + } } } - /// A track without DYNAMIC_GROUPS cannot honor a NEW_GROUP_REQUEST update, which fails - /// the subscription like any update it cannot apply. + /// A track without refresh cannot honor a NEW_GROUP_REQUEST update, which fails the + /// subscription like any update it cannot apply. #[moq_clock::test] - async fn a_new_group_update_without_dynamic_groups_fails() { + async fn a_new_group_update_without_refresh_fails() { for version in [Version::Draft15, Version::Draft16, Version::Draft22] { let h = serve(version); let mut session = ScriptedSession::new(new_group_update(version, 10, 9)); @@ -6926,7 +6881,6 @@ mod serve_tests { matches!(served, Some(Served::UpdateFailed(Error::Unsupported))), "{version}: {served:?}" ); - assert_eq!(h.track.new_group(), None, "{version}"); } } diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 43ce2d39ce1..b48fc8b0ac2 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -429,13 +429,15 @@ impl Target { } } - /// The NEW_GROUP_REQUEST the subscribers hold, which a new SUBSCRIBE carries. + /// The group a join asked for past the newest cached, which a new SUBSCRIBE carries as + /// NEW_GROUP_REQUEST. A request has nothing cached for a join to be judged against. fn new_group(&self) -> Option { - let request = match self { - Self::Request(request) => request.new_group(), - Self::Resume(idle) => idle.track.new_group(), + let Self::Resume(idle) = self else { + return None; }; - request.map(|request| request.value) + let wanted = idle.demand.wanted()?; + let latest = idle.track.latest_sequence()?; + (wanted > latest).then_some(wanted) } fn producer(&self) -> Option<&track::Producer> { @@ -463,13 +465,13 @@ impl Target { fn accepted_info(properties: &ietf::Properties) -> track::Info { // Normalized to microseconds, but only for a track that declared a timescale: an // untimed one must not gain a timeline downstream. - let mut info = track::Info::default() + track::Info::default() .with_timescale(properties.timescale.map(|_| Timescale::MICRO)) .with_max_age(properties.max_cache_duration) - .with_priority(super::priority::from_wire(properties.priority.unwrap_or(128))); - // This session carries NEW_GROUP_REQUEST back to the original publisher. - info.dynamic_groups = properties.dynamic_groups; - info + .with_priority(super::priority::from_wire(properties.priority.unwrap_or(128))) + // A publisher answering NEW_GROUP_REQUEST refreshes on any join with a delta to skip; + // this session carries the request back to it. + .with_refresh(properties.dynamic_groups.then_some(0)) } /// The Largest Group a subscription knows: its SUBSCRIBE_OK's, or a newer one since. @@ -2674,7 +2676,7 @@ where // Park the origin request where a session abort can reject it. The producer // does not exist until SUBSCRIBE_OK, and dropping this task would otherwise // end the track as `Dropped`. - let resumed = match target { + let mut resumed = match target { Target::Request(request) => { let mut state = self.state.lock(); let Some(held) = state.subscribes.get_mut(&request_id) else { @@ -2721,12 +2723,12 @@ where return Poll::Ready(Setup::Response(res)); } let mut state = self.state.lock(); - if let Some(idle) = &resumed { + if let Some(idle) = &mut resumed { // A session abort drained the subscription, and the copy with it. if !state.subscribes.contains_key(&request_id) { return Poll::Ready(Setup::Gone); } - return match idle.demand.poll_unused(waiter) { + return match crate::util::poll_unwanted(&mut idle.demand, waiter) { Poll::Ready(_) => Poll::Ready(Setup::Unused), Poll::Pending => Poll::Pending, }; @@ -2738,7 +2740,7 @@ where else { return Poll::Ready(Setup::Gone); }; - if pending.demand().poll_unused(waiter).is_ready() { + if crate::util::poll_unwanted(&mut pending.demand(), waiter).is_ready() { return Poll::Ready(Setup::Unused); } Poll::Pending @@ -2925,14 +2927,12 @@ where NewGroup(u64), } - // The SUBSCRIBE's request is outstanding from the Largest Group its answer named. - let mut new_groups = super::new_group::Outstanding::default(); - if let Some(value) = new_group { - new_groups.subscribed(value, largest_group(&track, largest)); - } - let dynamic_groups = track.info().dynamic_groups && super::subscribe::has_new_group_request(self.version); - // The aggregate request last read, so only a change is considered. - let mut asked = None; + // The NEW_GROUP_REQUEST last sent, the SUBSCRIBE's included. It stays outstanding + // until the Largest Group reaches it, and joins meanwhile ask for the same group. + let mut requested = new_group; + let dynamic_groups = track.info().refresh.is_some() && super::subscribe::has_new_group_request(self.version); + // The group the track's consumers want, `None` once nobody does. + let mut wanted = None; // REQUEST_UPDATEs sent and not yet answered. Drafts 14-16 answer on the control // stream by the update's own Request ID, which reaches no subscription, so only // later drafts count them. @@ -2942,7 +2942,7 @@ where let mut fetch_done = fetching.is_none(); // Our grant stopped covering the track, which is aborted rather than kept lingering. let mut revoked = false; - let demand = track.demand(); + let mut demand = track.demand(); // Nobody subscribing at all (only fetches asked) needs no subscription. let mut subscribed = track.subscription().is_some(); let idle = { @@ -2977,7 +2977,17 @@ where while let Poll::Ready(Ok(subscription)) = track.poll_subscription_changed(waiter) { subscribed = subscription.is_some(); } - if !subscribed || demand.poll_unused(waiter).is_ready() { + loop { + match demand.poll_wanted_changed(waiter) { + Poll::Ready(Ok(next)) => wanted = next, + Poll::Ready(Err(_)) => wanted = None, + Poll::Pending => break, + } + if wanted.is_none() { + break; + } + } + if !subscribed || wanted.is_none() { return Poll::Ready(End::Idle); } if let Poll::Ready(res) = waiter.poll_future(done.as_mut()) { @@ -2988,10 +2998,11 @@ where // once its answer lands. Polled after the answers are read for that reason. if dynamic_groups && unanswered.load(Ordering::Relaxed) == 0 - && let Poll::Ready(Ok(Some(request))) = track.poll_new_group(&mut asked, waiter) - && new_groups.forward(request.value, largest_group(&track, largest)) + && let Some(value) = wanted + && largest_group(&track, largest).is_some_and(|largest| value > largest) + && requested.is_none_or(|requested| value > requested) { - return Poll::Ready(End::NewGroup(request.value)); + return Poll::Ready(End::NewGroup(value)); } Poll::Pending }) @@ -3004,6 +3015,7 @@ where let _ = track.clone().abort(err); break false; } + requested = Some(value); if answered_here { unanswered.fetch_add(1, Ordering::Relaxed); } @@ -3156,14 +3168,13 @@ where } // Nobody holds it: let it go after the linger. A reader waiting on a fetch holds // it too. A holder returning restarts the countdown when it next leaves. - if idle.demand.poll_unused(waiter).is_ready() { + if crate::util::poll_unwanted(&mut idle.demand, waiter).is_ready() { if linger.deadline().is_none() { linger.set(self.runtime.now().checked_add(track::IDLE_LINGER)); } if linger.poll(waiter).is_ready() { return Poll::Ready(Step::Expired); } - let _ = idle.demand.poll_used(waiter); } else { linger.set(None); } @@ -3588,7 +3599,7 @@ where // Nobody wanting the track any more ends the wait on a peer that may never answer, // and the session ending fails it with the session's reason. - let demand = request.demand(); + let mut demand = request.demand(); let mut closed = self.session.clone(); let response = { let mut response = std::pin::pin!(self.read_track_status_response(&mut stream)); @@ -3604,7 +3615,7 @@ where if let Poll::Ready(err) = closed.poll_closed(&mut waiter.context()) { return Poll::Ready(Some(Err(Error::from_transport(err)))); } - demand.poll_unused(waiter).map(|_| None) + crate::util::poll_unwanted(&mut demand, waiter).map(|_| None) }) .await; match res { @@ -14682,7 +14693,7 @@ mod joining_fetch_tests { } /// NEW_GROUP_REQUEST on the upstream subscription, with the original publisher's end of -/// the session played by hand and the downstream subscribers' requests set on the model. +/// the session played by hand and downstream subscribers joining the relay's copy. #[cfg(test)] mod new_group_tests { use super::*; @@ -14705,16 +14716,8 @@ mod new_group_tests { _tasks: TaskSet, } - /// A downstream subscriber holding `new_group`, as the downstream session sets it. - fn subscribe(track: &track::Consumer, new_group: Option) -> kio::Pending { - track.subscribe(track::Subscription { - new_group: new_group.and_then(|value| crate::model::NewGroup::new(value, None)), - ..Default::default() - }) - } - - /// Serve one track upstream, for a first subscriber holding `new_group`. - async fn relay(new_group: Option) -> (Relay, kio::Pending) { + /// Serve one track upstream, for a first subscriber still waiting on its answer. + async fn relay() -> (Relay, kio::Pending) { let (session, peer) = memory::pair(memory::Config::default()); let (tasks, task_set) = TaskSet::new(); let mut subscriber = Subscriber::new( @@ -14733,7 +14736,7 @@ mod new_group_tests { let broadcast = crate::broadcast::Info::default().produce(); let mut dynamic = broadcast.dynamic(); let track = broadcast.consume().track("video").unwrap(); - let first = subscribe(&track, new_group); + let first = track.subscribe(None); let request = dynamic.requested_track().await.expect("no track requested"); let probe = subscriber.clone(); let serving = moq_clock::sim::spawn(async move { @@ -14772,12 +14775,23 @@ mod new_group_tests { (stream, msg.new_group) } - /// The Largest Group the copy holds grows to `sequence`. - fn land(&self, sequence: u64) { + /// Group `sequence` lands in the copy: a first frame, and a delta when `delta`. + fn land(&self, sequence: u64, delta: bool) { let state = self.probe.state.lock(); let copy = state.subscribes.values().next().unwrap().producer.clone().unwrap(); drop(state); - copy.create_group(group::Info { sequence }).unwrap(); + let mut group = copy.create_group(group::Info { sequence }).unwrap(); + group.write_frame(None, b"key".as_slice()).unwrap(); + if delta { + group.write_frame(None, b"delta".as_slice()).unwrap(); + } + } + + /// A downstream subscriber joins the copy. + async fn join(&self) -> track::Subscriber { + let subscriber = self.track.subscribe(None).await.unwrap(); + settle().await; + subscriber } } @@ -14834,86 +14848,86 @@ mod new_group_tests { ); } - /// Without an Established subscription, the request rides on the SUBSCRIBE. + /// A copy with nothing cached has no group to judge a join by, so its SUBSCRIBE asks for + /// none. #[moq_clock::test] - async fn a_request_rides_the_subscribe() { - for new_group in [None, Some(0), Some(4)] { - let (mut relay, _first) = relay(new_group).await; - let (_stream, sent) = relay.accept().await; - assert_eq!(sent, new_group); - relay.serving.abort(); - } + async fn a_first_subscribe_asks_for_no_group() { + let (mut relay, _first) = relay().await; + let (_stream, sent) = relay.accept().await; + assert_eq!(sent, None); + relay.serving.abort(); } - /// Once the request the SUBSCRIBE carried is answered by SUBSCRIBE_OK, it stays - /// outstanding: the same request from another subscriber goes no further. + /// A join over the ratio goes upstream in a REQUEST_UPDATE for the group past the + /// newest. Joins until that group lands ask for the same one and go no further. #[moq_clock::test] - async fn the_subscribe_request_is_outstanding() { - let (mut relay, _first) = relay(Some(0)).await; + async fn a_join_over_the_ratio_requests_a_group() { + let (mut relay, _first) = relay().await; let (mut stream, _) = relay.accept().await; accept(&mut stream, true, 5).await; - let _second = subscribe(&relay.track, Some(0)); + relay.land(5, true); + + let _a = relay.join().await; + assert_eq!(update(&mut stream).await, Some(6)); + answer(&mut stream).await; + let _b = relay.join().await; quiet(&mut stream).await; - // The group after the Largest Group is what the 0 asked for. - let _third = subscribe(&relay.track, Some(6)); + + relay.land(6, true); + let _c = relay.join().await; + assert_eq!(update(&mut stream).await, Some(7)); + answer(&mut stream).await; quiet(&mut stream).await; relay.serving.abort(); } - /// On an Established subscription, a request past the Largest Group goes upstream in a - /// REQUEST_UPDATE, a repeat of it does not, and a higher one does. + /// A join under the ratio reads the current group and asks for nothing. #[moq_clock::test] - async fn an_established_subscription_forwards_new_requests() { - let (mut relay, _first) = relay(None).await; + async fn a_join_under_the_ratio_asks_nothing() { + let (mut relay, _first) = relay().await; let (mut stream, _) = relay.accept().await; accept(&mut stream, true, 5).await; - quiet(&mut stream).await; - - let _a = subscribe(&relay.track, Some(6)); - assert_eq!(update(&mut stream).await, Some(6)); - answer(&mut stream).await; - let _b = subscribe(&relay.track, Some(6)); - quiet(&mut stream).await; + relay.land(5, false); - let _c = subscribe(&relay.track, Some(7)); - assert_eq!(update(&mut stream).await, Some(7)); - answer(&mut stream).await; + let _a = relay.join().await; quiet(&mut stream).await; relay.serving.abort(); } - /// One REQUEST_UPDATE is in flight at a time; requests arriving meanwhile go up as the - /// highest of them once it is answered. + /// One REQUEST_UPDATE is in flight at a time; a join meanwhile goes up once it is answered. #[moq_clock::test] - async fn requests_behind_an_unanswered_update_coalesce() { - let (mut relay, _first) = relay(None).await; + async fn a_join_behind_an_unanswered_update_waits() { + let (mut relay, _first) = relay().await; let (mut stream, _) = relay.accept().await; accept(&mut stream, true, 5).await; + relay.land(5, true); - let _a = subscribe(&relay.track, Some(6)); + let _a = relay.join().await; assert_eq!(update(&mut stream).await, Some(6)); - let _b = subscribe(&relay.track, Some(7)); - let _c = subscribe(&relay.track, Some(8)); + relay.land(6, true); + let _b = relay.join().await; quiet(&mut stream).await; answer(&mut stream).await; - assert_eq!(update(&mut stream).await, Some(8)); + assert_eq!(update(&mut stream).await, Some(7)); answer(&mut stream).await; quiet(&mut stream).await; relay.serving.abort(); } /// A refused update ends the subscription, so nothing more goes up while PUBLISH_DONE - /// is on its way, even for a request that coalesced behind it. + /// is on its way, even for a join that waited behind it. #[moq_clock::test] async fn a_refused_update_sends_no_more() { - let (mut relay, _first) = relay(None).await; + let (mut relay, _first) = relay().await; let (mut stream, _) = relay.accept().await; accept(&mut stream, true, 5).await; + relay.land(5, true); - let _a = subscribe(&relay.track, Some(6)); + let _a = relay.join().await; assert_eq!(update(&mut stream).await, Some(6)); - let _b = subscribe(&relay.track, Some(8)); + relay.land(6, true); + let _b = relay.join().await; stream.writer.varint(ietf::RequestError::ID).await.unwrap(); stream .writer @@ -14929,117 +14943,43 @@ mod new_group_tests { relay.serving.abort(); } - /// A nonzero request at or below the Largest Group names a group that already exists. - #[moq_clock::test] - async fn a_stale_request_stays_put() { - let (mut relay, _first) = relay(None).await; - let (mut stream, _) = relay.accept().await; - accept(&mut stream, true, 5).await; - - let a = subscribe(&relay.track, Some(5)); - quiet(&mut stream).await; - drop(a); - relay.land(6); - let _b = subscribe(&relay.track, Some(6)); - quiet(&mut stream).await; - relay.serving.abort(); - } - - /// An outstanding 0 covers only the group after the Largest Group, so a higher request - /// arriving meanwhile still goes upstream. - #[moq_clock::test] - async fn a_higher_request_passes_an_outstanding_zero() { - let (mut relay, _first) = relay(None).await; - let (mut stream, _) = relay.accept().await; - accept(&mut stream, true, 5).await; - - let _a = subscribe(&relay.track, Some(0)); - assert_eq!(update(&mut stream).await, Some(0)); - answer(&mut stream).await; - let _b = subscribe(&relay.track, Some(9)); - assert_eq!(update(&mut stream).await, Some(9)); - relay.serving.abort(); - } - - /// A request for 0 goes up once, and stays outstanding until the Largest Group grows. + /// A group the publisher already has is on its way, so a join asking for it goes no + /// further. #[moq_clock::test] - async fn zero_is_rearmed_by_a_new_group() { - let (mut relay, _first) = relay(None).await; + async fn a_group_upstream_has_is_not_requested() { + let (mut relay, _first) = relay().await; let (mut stream, _) = relay.accept().await; - accept(&mut stream, true, 5).await; + accept(&mut stream, true, 7).await; + relay.land(5, true); - let a = subscribe(&relay.track, Some(0)); - assert_eq!(update(&mut stream).await, Some(0)); - answer(&mut stream).await; - drop(a); - settle().await; - - // Acknowledged is not answered: no group came yet. - let b = subscribe(&relay.track, Some(0)); + let _a = relay.join().await; quiet(&mut stream).await; - drop(b); - settle().await; - - relay.land(6); - let _c = subscribe(&relay.track, Some(0)); - assert_eq!(update(&mut stream).await, Some(0)); relay.serving.abort(); } - /// A request goes upstream once and the next group answers it, even one naming a group - /// far past it: new groups never send it again, so no value can make the publisher - /// start group after group. - #[moq_clock::test] - async fn new_groups_never_resend_a_request() { - for value in [0, 9, 1 << 40] { - let (mut relay, _first) = relay(None).await; - let (mut stream, _) = relay.accept().await; - accept(&mut stream, true, 5).await; - - let a = relay.track.subscribe(track::Subscription { - new_group: crate::model::NewGroup::new(value, Some(5)), - ..Default::default() - }); - assert_eq!(update(&mut stream).await, Some(value)); - answer(&mut stream).await; - - for sequence in 6..9 { - relay.land(sequence); - quiet(&mut stream).await; - } - - // Group 6 answered it, so the subscriber holds nothing once it reads past it. - let mut a = a.await.unwrap(); - while a.recv_group().await.unwrap().is_some_and(|group| group.sequence < 8) {} - let state = relay.probe.state.lock(); - let copy = state.subscribes.values().next().unwrap().producer.clone().unwrap(); - drop(state); - assert_eq!(copy.new_group(), None, "{value}"); - relay.serving.abort(); - } - } - - /// A publisher that did not advertise DYNAMIC_GROUPS still sees a SUBSCRIBE's request, - /// which it ignores, and never a REQUEST_UPDATE carrying one. + /// A publisher that did not advertise DYNAMIC_GROUPS refreshes on no join, so it never + /// hears a REQUEST_UPDATE carrying one. #[moq_clock::test] async fn a_publisher_without_dynamic_groups_hears_no_updates() { - let (mut relay, _first) = relay(Some(0)).await; - let (mut stream, sent) = relay.accept().await; - assert_eq!(sent, Some(0)); + let (mut relay, _first) = relay().await; + let (mut stream, _) = relay.accept().await; accept(&mut stream, false, 5).await; + relay.land(5, true); - let _a = subscribe(&relay.track, Some(6)); + let _a = relay.join().await; quiet(&mut stream).await; relay.serving.abort(); } - /// What was outstanding goes with its subscription: subscribing again starts afresh. + /// A group still wanted when the copy goes idle rides the SUBSCRIBE that resumes it, and + /// is outstanding from there. #[moq_clock::test] - async fn a_new_subscription_inherits_nothing() { - let (mut relay, first) = relay(None).await; + async fn a_resumed_copy_carries_its_request() { + let (mut relay, first) = relay().await; let (mut stream, _) = relay.accept().await; accept(&mut stream, true, 5).await; - let a = subscribe(&relay.track, Some(6)); + relay.land(5, true); + let a = relay.join().await; assert_eq!(update(&mut stream).await, Some(6)); answer(&mut stream).await; @@ -15047,12 +14987,11 @@ mod new_group_tests { drop((first, a)); settle().await; - let _b = subscribe(&relay.track, None); + let _b = relay.track.subscribe(None); let (mut stream, sent) = relay.accept().await; - assert_eq!(sent, None); + assert_eq!(sent, Some(6)); accept(&mut stream, true, 5).await; - let _c = subscribe(&relay.track, Some(6)); - assert_eq!(update(&mut stream).await, Some(6)); + quiet(&mut stream).await; relay.serving.abort(); } } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 3695ea33c8b..0dc7a99ff85 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -6239,7 +6239,6 @@ mod tests { reader: crate::coding::Reader::new(recv, version), }; let mut serve = RequestServe::<_, R>::new(publisher.shared.clone(), stream); - let waiter = kio::Waiter::noop(); assert!(!drive(&mut serve).await, "{case}: nothing to answer with"); // The lookup reached the track, which stays wanted while the requester waits. @@ -6249,10 +6248,7 @@ mod tests { .now_or_never() .expect("track requested") .unwrap(); - assert!( - track.demand().poll_unused(&waiter).is_pending(), - "{case}: nobody wants the track" - ); + assert!(track.demand().wanted().is_some(), "{case}: nobody wants the track"); track }); @@ -6260,9 +6256,10 @@ mod tests { assert!(drive(&mut serve).await, "{case}: still serving"); drop(serve); if let Some(track) = track { + let mut demand = track.demand(); let unused = moq_clock::timeout( Duration::from_millis(1), - kio::wait(|waiter| track.demand().poll_unused(waiter)), + kio::wait(|waiter| crate::util::poll_unwanted(&mut demand, waiter)), ); assert!(unused.await.is_ok(), "{case}: the track is still wanted"); } @@ -6390,7 +6387,7 @@ mod tests { matches!(serve.state, RequestState::Hold { finished, .. } if finished != blocked), "{case}: TRACK_INFO was not answered as expected" ); - assert!(track.demand().is_used(), "{case}: the track was let go"); + assert!(track.demand().wanted().is_some(), "{case}: the track was let go"); assert_eq!( publisher.shared.owed.load(Ordering::Relaxed), usize::from(blocked), @@ -6399,10 +6396,13 @@ mod tests { session.close(close); assert!(drive(&mut serve).await, "{case}: still holding"); - moq_clock::timeout(Duration::from_millis(1), track.demand().unused()) - .await - .unwrap_or_else(|_| panic!("{case}: the track is still wanted")) - .unwrap(); + let mut demand = track.demand(); + moq_clock::timeout( + Duration::from_millis(1), + kio::wait(|waiter| crate::util::poll_unwanted(&mut demand, waiter)), + ) + .await + .unwrap_or_else(|_| panic!("{case}: the track is still wanted")); // The incomplete reply is cancelled; a delivered one is not. assert_eq!( session.log.resets().is_empty(), diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 828082fa9ea..5a4fc30f9ae 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -5492,7 +5492,7 @@ impl kio::Task for TrackServeRun { // otherwise hold this task, its TRACK stream, and the track for good. // Dropping the fetch resets the stream. let pending = request.as_ref().expect("request pending"); - if pending.demand().poll_unused(waiter).is_ready() { + if crate::util::poll_unwanted(&mut pending.demand(), waiter).is_ready() { if pending.reject_unused(Error::Cancel) { self.state = TrackRunState::Done; return Poll::Ready(()); @@ -5948,7 +5948,7 @@ impl ServeLoop { { return Poll::Ready(ServeEnd::Finished); } - if self.fetches.is_empty() && self.demand.poll_unused(waiter).is_ready() { + if self.fetches.is_empty() && crate::util::poll_unwanted(&mut self.demand, waiter).is_ready() { return Poll::Ready(ServeEnd::Idle); } let mut cx = std::task::Context::from_waker(waiter.waker()); @@ -6028,17 +6028,16 @@ impl ServeLoop { // went with the last subscriber, so it lingers, cache and all, for a // reader or fetch that asks again soon, then is dropped. In-flight // fetches keep it alive: work already accepted still gets finished. - if self.fetches.is_empty() && self.demand.poll_unused(waiter).is_ready() { + if self.fetches.is_empty() && crate::util::poll_unwanted(&mut self.demand, waiter).is_ready() { self.held = None; if self.linger.deadline().is_none() { let now = serve.subscriber.runtime.now(); self.linger.set(now.checked_add(track::IDLE_LINGER)); } + // A reader returning restarts the countdown when it next leaves. if self.linger.poll(waiter).is_ready() { return Poll::Ready(ServeEnd::Idle); } - // A reader returning restarts the countdown when it next leaves. - let _ = self.demand.poll_used(waiter); } else { self.linger.set(None); } diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index 14e0ba9aa8e..30f9591d6f5 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -1713,24 +1713,18 @@ mod test { let consumer1 = c1_fut.await.unwrap(); // The producer should NOT be unused yet because there's a consumer. - assert!( - producer1.demand().unused().now_or_never().is_none(), - "track producer should be used" - ); + assert!(producer1.demand().wanted().is_some(), "track producer should be used"); // A second subscriber reuses the live producer (fast path / dedup). let consumer2 = bc.track("unknown_track").unwrap().subscribe(None).await.unwrap(); consumer2.assert_is_clone(&consumer1); drop(consumer1); - assert!( - producer1.demand().unused().now_or_never().is_none(), - "track producer should be used" - ); + assert!(producer1.demand().wanted().is_some(), "track producer should be used"); drop(consumer2); assert!( - producer1.demand().unused().now_or_never().is_some(), + producer1.demand().wanted().is_none(), "track producer should be unused after all consumers are dropped" ); @@ -1751,7 +1745,7 @@ mod test { let consumer4 = c4_fut.await.unwrap(); drop(consumer4); assert!( - producer2.demand().unused().now_or_never().is_some(), + producer2.demand().wanted().is_none(), "new track producer should be unused after its consumer is dropped" ); } @@ -2040,7 +2034,7 @@ mod test { let track = producer.create_track("video", crate::track::Info::timed()).unwrap(); // The unused wake a teardown acts on. - assert!(track.demand().poll_unused(&kio::Waiter::noop()).is_ready()); + assert!(track.demand().wanted().is_none()); // Demand returns in the gap before it commits. let viewer = consumer.track("video").unwrap().subscribe(None); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 96a887e9c29..751233d4f8e 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1329,6 +1329,21 @@ impl Producer { self.state.read().charge.size() } + /// Whether the payload cached after the first frame exceeds `ratio` times the first + /// frame: what [`track::Info::refresh`] judges a join by. A group holding no first + /// frame (one started past it, or not written yet) has nothing to compare against. + pub(super) fn over_refresh(&self, ratio: u32) -> bool { + let state = self.state.read(); + if state.offset != 0 { + return false; + } + let Some(first) = state.frames.front() else { + return false; + }; + let first = first.payload.len() as u64; + state.cache.saturating_sub(first) > first.saturating_mul(ratio.into()) + } + /// Tick of the group's last cache access, driving eviction protection and age /// expiry (see [`cache::Pool::average`]). pub(super) fn cache_accessed(&self) -> u64 { diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 04e7d797958..6d8fcd85ef8 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -43,9 +43,6 @@ use weak_cache::{WeakCache, WeakEntry}; pub use bytes::*; // pending: /quest/m1/public-model/serve.md pub(crate) use subscription::Cap; -#[cfg_attr(not(feature = "async"), allow(unused_imports))] -// private: passthrough -pub(crate) use subscription::NewGroup; // Datagram stays flat at the crate root (a small track-adjacent wire type), // not under a role module. pub use datagram::*; diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 4947b99e5f8..69fccbdb4f9 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -8432,7 +8432,7 @@ mod tests { // Parked: the source copy goes, the delivered group stays warm. The source // then tears its idle track down, so a returning reader asks it afresh. - moq_clock::timeout(Duration::from_secs(1), source.demand().unused()) + moq_clock::timeout(Duration::from_secs(1), source.demand().until(|wanted| wanted.is_none())) .await .expect("parked") .expect("source open"); @@ -10741,7 +10741,7 @@ mod tests { drop(group); drop(subscription); - moq_clock::timeout(Duration::from_secs(1), track.demand().unused()) + moq_clock::timeout(Duration::from_secs(1), track.demand().until(|wanted| wanted.is_none())) .await .expect("source unused should resolve far below track::IDLE_LINGER") .expect("source closed"); @@ -10761,7 +10761,7 @@ mod tests { .expect("track ended early"); assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"cached"); - moq_clock::timeout(Duration::from_secs(1), track.demand().used()) + moq_clock::timeout(Duration::from_secs(1), track.demand().until(|wanted| wanted.is_some())) .await .expect("returning reader re-splices the source") .expect("source closed"); @@ -10812,7 +10812,7 @@ mod tests { assert_eq!(&tail.payload[..], b"tail"); let end = moq_clock::timeout(Duration::from_secs(1), reading.read_frame()).await; assert!(matches!(end, Ok(Ok(None))), "the group should finish: {end:?}"); - moq_clock::timeout(Duration::from_secs(1), track.demand().unused()) + moq_clock::timeout(Duration::from_secs(1), track.demand().until(|wanted| wanted.is_none())) .await .expect("the front lets the source go once the held group ends") .expect("source closed"); @@ -10895,7 +10895,7 @@ mod tests { drop(group); drop(subscription); - moq_clock::timeout(Duration::from_secs(5), track.demand().unused()) + moq_clock::timeout(Duration::from_secs(5), track.demand().until(|wanted| wanted.is_none())) .await .expect("chained unused should resolve far below track::IDLE_LINGER") .expect("source closed"); @@ -10907,7 +10907,7 @@ mod tests { .subscribe(track::Subscription::default().with_max_delay(Duration::from_secs(3600))) .await .expect("resubscribe"); - moq_clock::timeout(Duration::from_secs(5), track.demand().used()) + moq_clock::timeout(Duration::from_secs(5), track.demand().until(|wanted| wanted.is_some())) .await .expect("resubscribe should reach the leaf") .expect("source open"); @@ -10922,7 +10922,7 @@ mod tests { drop(group); drop(subscription); - moq_clock::timeout(Duration::from_secs(5), track.demand().unused()) + moq_clock::timeout(Duration::from_secs(5), track.demand().until(|wanted| wanted.is_none())) .await .expect("second chained unused should resolve far below track::IDLE_LINGER") .expect("source closed"); @@ -10935,7 +10935,7 @@ mod tests { let fetch = edge_resolved.track("video").unwrap().fetch_group(2, None); let mut fetch = std::pin::pin!(fetch); assert!(futures::poll!(fetch.as_mut()).is_pending(), "fetch should re-splice"); - moq_clock::timeout(Duration::from_secs(5), track.demand().used()) + moq_clock::timeout(Duration::from_secs(5), track.demand().until(|wanted| wanted.is_some())) .await .expect("fetch should reach the leaf") .expect("source open"); @@ -11041,7 +11041,7 @@ mod tests { .expect("request"); drop(subscription); - moq_clock::timeout(Duration::from_secs(1), old.demand().unused()) + moq_clock::timeout(Duration::from_secs(1), old.demand().until(|wanted| wanted.is_none())) .await .expect("the draining source stays subscribed with nobody reading") .expect("open"); @@ -11072,7 +11072,7 @@ mod tests { drop(group); drop(subscription); - moq_clock::timeout(Duration::from_secs(1), old.demand().unused()) + moq_clock::timeout(Duration::from_secs(1), old.demand().until(|wanted| wanted.is_none())) .await .expect("parked") .expect("open"); @@ -11425,7 +11425,7 @@ mod tests { let track = broadcast.create_track("video", crate::track::Info::timed()).unwrap(); let resolved = consumer.request_broadcast("room/alice", None).await.expect("resolves"); let sub = resolved.track("video").unwrap().subscribe(None).await.unwrap(); - moq_clock::timeout(Duration::from_secs(1), track.demand().used()) + moq_clock::timeout(Duration::from_secs(1), track.demand().until(|wanted| wanted.is_some())) .await .expect("the front subscribed the source") .unwrap(); @@ -11436,7 +11436,7 @@ mod tests { drop(broadcast); settle(|| resolved.is_closed()).await; - moq_clock::timeout(Duration::from_secs(5), track.demand().unused()) + moq_clock::timeout(Duration::from_secs(5), track.demand().until(|wanted| wanted.is_none())) .await .expect("the ended copy must not keep the source subscribed") .unwrap(); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index c958c4b7641..2e32c414bf4 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -287,12 +287,7 @@ impl Copy { /// What this copy is asked for: the reader's own preferences, from no earlier than /// where it was asked to start, and through no later than where it was replaced. fn wire(&self, reader: &Subscription) -> Subscription { - let mut wire = reader.clamped(self.floor, self.end().map(Position::group)); - // A replaced copy only finishes what it had, so a new group from it never arrives. - if self.until.is_some() { - wire.new_group = None; - } - wire + reader.clamped(self.floor, self.end().map(Position::group)) } /// The first group past where this copy was replaced, if any: one replaced before diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index a7f8c6adc82..e8c37729e8e 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -83,47 +83,6 @@ pub struct Subscription { /// subscribers fresh. Each subscriber's own publisher (a relay's downstream session) /// still serves it in its own order. pub order: Order, - /// A moq-transport NEW_GROUP_REQUEST this subscriber is waiting on. - /// - /// Relay-only, so it stays out of the public API: the aggregate the public getters - /// report leaves it out. Cleared once this subscriber is handed a group that answers - /// it, so a request never outlives what it asked for. - // private: passthrough - pub(crate) new_group: Option, -} - -/// A NEW_GROUP_REQUEST as one hop holds it. -/// -/// Subscribers' requests combine as the greatest: the one answered later, whose answer -/// answers both. Between requests answered alike, the higher value says the most upstream, -/// and any value says more than a 0. -#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)] -// private: passthrough -pub(crate) struct NewGroup { - /// The first group sequence that answers it here: the one after the newest this hop - /// held when it arrived, not the one the subscriber is about to join. - pub first: u64, - /// The value as received, which is what goes upstream: the subscriber's largest known - /// group plus one, or 0 when it knows none. - pub value: u64, -} - -impl NewGroup { - /// A request for `value`, arriving while this hop's newest group is `latest`, or `None` - /// when a group the hop holds already answers it. - /// - /// Any newer group answers it here, even one below a value past the newest held. The - /// subscriber learned of its groups from the publisher, which so answers with a group at - /// or past the value; holding out for that exact group would only ask again, and a - /// value naming a group that never existed would ask on every group. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub fn new(value: u64, latest: Option) -> Option { - if value != 0 && latest.is_some_and(|latest| value <= latest) { - return None; - } - let first = latest.map_or(0, |latest| latest.saturating_add(1)); - Some(Self { first, value }) - } } /// Which of a subscription's pending groups the publisher sends first. @@ -296,7 +255,6 @@ impl Default for Subscription { max_delay: Duration::ZERO, ranges: vec![Range::oldest()], order: Order::Descending, - new_group: None, } } } @@ -431,6 +389,15 @@ impl Subscription { } Some(floor.unwrap_or(0)) } + + /// Whether a subscriber joins at the live edge: a range counting back from the latest + /// group and following it. A fixed start resumes a known group instead, such as a route + /// switch picking up where the reader stopped. + pub(super) fn joins_live(&self) -> bool { + self.ranges + .iter() + .any(|range| matches!(range.start, Anchor::Relative(_)) && range.end.is_none()) + } } /// The most demanding request across subscribers, folded in one at a time: the reference @@ -450,7 +417,6 @@ impl Combined { combined.priority = combined.priority.max(sub.priority); combined.max_delay = combined.max_delay.max(sub.max_delay); combined.ranges.extend_from_slice(&sub.ranges); - combined.new_group = combined.new_group.max(sub.new_group); // Sequence-first prioritization is enabled only when every subscriber wants it. if let Order::Descending = sub.order { combined.order = Order::Descending; @@ -841,28 +807,4 @@ mod tests { ); assert_eq!(combine(&[descending, ascending]).unwrap().order, Order::Descending); } - - /// Any group newer than the hop held answers a request, a value it already holds asks - /// nothing, and merged requests are answered once every subscriber's would be. - #[test] - fn new_group_requests_merge() { - let zero = NewGroup::new(0, Some(5)).unwrap(); - assert_eq!(zero, NewGroup { value: 0, first: 6 }); - // A value past the next group is still answered by it, so it can never ask again. - let nine = NewGroup::new(9, Some(5)).unwrap(); - assert_eq!(nine, NewGroup { value: 9, first: 6 }); - assert_eq!(NewGroup::new(4, None), Some(NewGroup { value: 4, first: 0 })); - // A value the hop already holds is answered. - assert_eq!(NewGroup::new(5, Some(5)), None); - // Answered alike, the value goes up in place of the 0, and the higher value wins. - assert_eq!(zero.max(nine), nine); - assert_eq!(nine.max(zero), nine); - let six = NewGroup::new(6, Some(5)).unwrap(); - assert_eq!(six.max(nine), nine); - assert_eq!(nine.max(six), nine); - // Otherwise the one answered later. - let later = NewGroup::new(0, Some(7)).unwrap(); - assert_eq!(nine.max(later), later); - assert_eq!(later.max(nine), later); - } } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 75dfa3981ed..726b1efbc2d 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -21,7 +21,6 @@ use super::ledger::{self, Ledger}; use super::{Datagram, Requests}; use super::Cap; -use super::subscription::NewGroup; pub use super::subscription::{Anchor, Order, Position, Range, Subscription}; use rangemap::RangeSet; @@ -137,14 +136,18 @@ pub struct Info { /// subscriptions of equal subscriber priority. Reported in TRACK_INFO (Lite05+). /// Higher is more urgent. Defaults to 127, the midpoint. pub priority: u8, - /// Whether the original publisher starts a group on a moq-transport NEW_GROUP_REQUEST - /// (DYNAMIC_GROUPS), as learned from an upstream moq-transport session. + /// The ratio of a group's bytes after its first frame to the first frame past which a + /// joining subscriber asks for a new group, or `None` (the default) to never ask. /// - /// Relay-only: a local publisher has no way to answer the request, and moq-lite does - /// not carry the capability, so both leave it unset. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // private: passthrough - pub(crate) dynamic_groups: bool, + /// A track opting in starts each group with an independent frame (a snapshot or a + /// keyframe) that the deltas after it build on. A joiner reads the newest group from its + /// start, so once the deltas outweigh `refresh` times the first frame, a fresh group is + /// cheaper: [`Demand::wanted`] moves past the newest group and the publisher opens one. + /// Every hop judges a join against its own cache, which holds the same group. + /// `Some(0)` asks on any join once a delta follows the first frame. + /// + /// On moq-transport, `Some` is advertised as DYNAMIC_GROUPS, which arrives as `Some(0)`. + pub refresh: Option, } impl Default for Info { @@ -153,7 +156,7 @@ impl Default for Info { timescale: None, max_age: None, priority: DEFAULT_PRIORITY, - dynamic_groups: false, + refresh: None, } } } @@ -180,6 +183,12 @@ impl Info { self.priority = priority; self } + + /// Set the [`refresh`](Self::refresh) ratio, returning `self` for chaining. + pub fn with_refresh(mut self, refresh: impl Into>) -> Self { + self.refresh = refresh.into(); + self + } } #[cfg(test)] @@ -627,6 +636,35 @@ pub(crate) struct FetchOutcome { } impl TrackState { + /// A consumer joined at the live edge: ask for the group after the newest when the + /// newest's bytes after its first frame exceed [`Info::refresh`] times that frame. + /// + /// Joins while the request is pending ask for the same group, so they coalesce until + /// the publisher creates it. A join under the ratio reads the current group and asks + /// for nothing, even while a request is pending. + /// + /// Takes the read guard to release it before locking the demand, so the two locks + /// never nest. + fn join(state: kio::Ref<'_, TrackState>) { + let Some(ratio) = state.info.as_ref().and_then(|info| info.refresh) else { + return; + }; + let Some(latest) = state.latest_group else { + return; + }; + if !state + .lookup + .get(&latest) + .is_some_and(|slot| slot.serving().over_refresh(ratio)) + { + return; + } + let subscriptions = state.subscriptions.clone(); + drop(state); + let mut wakes = subscriptions.lock().want(latest.saturating_add(1)); + wakes.wake(); + } + /// The starts a first frame of group `sequence` must fall between: the nearest checked /// starts cached on either side, since groups land out of sequence order, and the /// eviction watermark. A group at or below the watermark is late: its floor may be gone, @@ -2646,7 +2684,7 @@ impl Producer { /// Abort an unused track, returning the producer unchanged if consumers remain. /// /// Consumer creation and the unused check share a lock, so demand returning - /// after [`Demand::poll_unused`] prevents the abort. `Ok(())` means + /// after [`Demand::wanted`] went to `None` prevents the abort. `Ok(())` means /// the track is closed, including when it was already closed; existing handles /// may still observe its final state. `Err(producer)` leaves the track unchanged /// so the caller can continue serving and wait for the next unused wake. @@ -2740,10 +2778,7 @@ impl Producer { /// handle is weak, so holding one neither keeps the track alive nor pins its /// cached groups. pub fn demand(&self) -> Demand { - Demand { - name: self.name.clone(), - state: self.state.weak(), - } + Demand::new(self.name.clone(), self.state.weak()) } /// Get a consumer handle for this in-process track. @@ -2807,46 +2842,12 @@ impl Producer { /// [`Info::max_age`]: no subscriber can wait for a late group longer than the /// publisher keeps it. pub fn subscription(&self) -> Option { - public(self.aggregate()) - } - - /// The aggregate with the relay-only requests the public view leaves out. - fn aggregate(&self) -> Option { let state = self.state.read(); let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); snapshot_subscription(&subs, bound) } - /// The NEW_GROUP_REQUEST the subscribers hold now, if any; see - /// [`Subscription::new_group`]. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // private: passthrough - pub(crate) fn new_group(&self) -> Option { - new_group(self.aggregate()) - } - - /// Poll for the NEW_GROUP_REQUEST the subscribers hold to differ from `prev`: the - /// highest one whenever it changes, `None` once none does. Errors once the track is - /// aborted. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // private: passthrough - pub(crate) fn poll_new_group( - &self, - prev: &mut Option, - waiter: &kio::Waiter, - ) -> Poll>> { - if self.state.poll_closed(waiter).is_ready() { - let abort = self.state.read().abort.clone(); - return Poll::Ready(Err(abort.unwrap_or(Error::Dropped))); - } - let state = self.state.read(); - let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); - drop(state); - - poll_combined_changed(&subs, bound, prev, new_group, waiter).map(Ok) - } - /// Poll for a changed subscription: the /// aggregate subscription whenever it changes, or `None` once nobody is subscribed. /// Errors once the track is aborted. @@ -2863,7 +2864,7 @@ impl Producer { let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); - poll_combined_changed(&subs, bound, &mut self.prev_subscription, public, waiter).map(Ok) + poll_combined_changed(&subs, bound, &mut self.prev_subscription, waiter).map(Ok) } /// Create a [`Dynamic`] handle that serves on-demand fetches of uncached @@ -2982,10 +2983,7 @@ impl Dynamic { /// Watch subscriber demand without keeping the track alive. pub fn demand(&self) -> Demand { - Demand { - name: self.name.clone(), - state: self.state.weak(), - } + Demand::new(self.name.clone(), self.state.weak()) } } @@ -3017,16 +3015,23 @@ impl Drop for Dynamic { } fn set_sequence(state: &kio::Producer, sequence: Sequence) { - if let Ok(mut state) = state.write() { - debug_assert!( - state.max_sequence.is_none(), - "a track joins its namespace before writing" - ); - // What earlier producers of the name wrote is gone from this track's cache, so their - // highest checked start is its eviction watermark. - state.evicted = sequence.bound(); - state.sequence = sequence; - } + let Ok(mut state) = state.write() else { + return; + }; + debug_assert!( + state.max_sequence.is_none(), + "a track joins its namespace before writing" + ); + // What earlier producers of the name wrote is gone from this track's cache, so their + // highest checked start is its eviction watermark. + state.evicted = sequence.bound(); + // A replacement's consumers want the group past what earlier producers wrote. + let next = sequence.next(); + state.sequence = sequence; + let subscriptions = state.subscriptions.clone(); + drop(state); + let mut wakes = subscriptions.lock().want(next); + wakes.wake(); } /// Ends the track when the last [`Producer`] or [`Dynamic`] drops. @@ -3119,25 +3124,14 @@ impl Drop for Alive { } } -/// Poll the counted aggregate, as `view` sees it, without registering on individual readers. -fn poll_combined_changed( +/// Poll the counted aggregate without registering on individual readers. +fn poll_combined_changed( subs: &kio::Lock, bound: Option, - prev: &mut T, - view: impl Fn(Option) -> T, + prev: &mut Option, waiter: &kio::Waiter, -) -> Poll { - subs.lock().poll_changed(bound, prev, view, waiter) -} - -/// The aggregate as the public API reports it: without the relay-only requests. -fn public(combined: Option) -> Option { - combined.map(|sub| Subscription { new_group: None, ..sub }) -} - -/// The aggregate's NEW_GROUP_REQUEST, if any subscriber holds one. -fn new_group(combined: Option) -> Option { - combined.and_then(|sub| sub.new_group) +) -> Poll> { + subs.lock().poll_changed(bound, prev, waiter) } /// Read the counted aggregate without walking the audience. @@ -3320,34 +3314,82 @@ impl super::WeakEntry for TrackWeak { /// A cloneable, watch-only handle to a track's subscriber demand. /// /// Obtained from [`Producer::demand`], [`Request::demand`], or [`Dynamic::demand`]. -/// A publisher uses it to react to whether anyone is subscribed, querying, or fetching -/// (on-demand capture / encoding) without being able to publish frames or close the +/// A publisher uses it to learn which group anyone subscribed, querying, or fetching +/// wants (on-demand capture / encoding) without being able to publish frames or close the /// track. A bare [`Consumer`] is not demand. It's a weak handle, so it neither keeps /// the track alive nor pins its cached groups; once the owning [`Producer`] -/// goes away, [`poll_used`](Self::poll_used) / [`poll_unused`](Self::poll_unused) report the track's -/// closure. -#[derive(Clone)] +/// goes away, [`poll_wanted_changed`](Self::poll_wanted_changed) reports the track's +/// closure. Each clone watches on its own, so its first +/// [`poll_wanted_changed`](Self::poll_wanted_changed) reports the current value. pub struct Demand { name: Arc, state: kio::ProducerWeak, + // The value `poll_wanted_changed` last returned, or `None` before it returned any. + prev: Option>, +} + +impl Clone for Demand { + fn clone(&self) -> Self { + Self::new(self.name.clone(), self.state.clone()) + } } impl Demand { + fn new(name: Arc, state: kio::ProducerWeak) -> Self { + Self { + name, + state, + prev: None, + } + } + /// The track name this handle is bound to. pub fn name(&self) -> &str { &self.name } - /// Block until there is at least one active consumer. - #[cfg(feature = "async")] - pub async fn used(&self) -> Result<()> { - self.state.used().await.map_err(|_| self.abort_reason()) + /// The group consumers want: `None` while nobody consumes the open track, and + /// `Some(n)` while they want group `n` or later. + /// + /// A publisher opens a group whenever `n` passes its largest. The first consumer of a + /// track with no group asks for `Some(0)`, and a join judged by [`Info::refresh`] + /// asks for the group after the newest. `n` never goes back, so once a group reaches + /// it nothing is pending until another join asks. + pub fn wanted(&self) -> Option { + if !self.is_used() { + return None; + } + let subscriptions = self.state.read().subscriptions.clone(); + let wanted = subscriptions.lock().wanted(); + Some(wanted) } - /// Block until there are no active consumers. + /// Return [`wanted`](Self::wanted) once it differs from what this handle last returned: + /// immediately on the first call, then on each change. Errors once the track is closed + /// or aborted. + /// + /// So `while let Some(n) = demand.wanted_changed().await?` runs while anyone wants the + /// track, and `while demand.wanted_changed().await?.is_none()` waits for someone to. #[cfg(feature = "async")] - pub async fn unused(&self) -> Result<()> { - self.state.unused().await.map_err(|_| self.abort_reason()) + pub async fn wanted_changed(&mut self) -> Result> { + kio::wait(|waiter| self.poll_wanted_changed(waiter)).await + } + + /// Poll for [`wanted`](Self::wanted) to differ from what this handle last returned. + pub fn poll_wanted_changed(&mut self, waiter: &kio::Waiter) -> Poll>> { + let used = match self.poll_state(waiter) { + DemandState::Closed => return Poll::Ready(Err(self.abort_reason())), + DemandState::Active => true, + DemandState::Idle => false, + }; + let subscriptions = self.state.read().subscriptions.clone(); + let wanted = subscriptions.lock().poll_wanted(waiter); + let next = used.then_some(wanted); + if self.prev == Some(next) { + return Poll::Pending; + } + self.prev = Some(next); + Poll::Ready(Ok(next)) } /// Block until the track is closed or aborted, returning the cause. @@ -3367,24 +3409,11 @@ impl Demand { .map_or(DEFAULT_PRIORITY, |info| info.priority) } - /// Whether the track is open and anyone is subscribed right now, without waiting. - /// - /// A point-in-time snapshot for gating work on demand. Acting on it to *end* the - /// track is the race [`Producer::abort_unused`] exists for. - pub fn is_used(&self) -> bool { + /// Whether the track is open and anyone consumes it right now, without waiting. + pub(super) fn is_used(&self) -> bool { !self.state.is_closed() && self.state.is_used() } - /// Poll until a consumer is using this resource. - pub fn poll_used(&self, waiter: &kio::Waiter) -> Poll> { - self.state.poll_used(waiter).map_err(|_| self.abort_reason()) - } - - /// Poll until no consumer is using this resource. - pub fn poll_unused(&self, waiter: &kio::Waiter) -> Poll> { - self.state.poll_unused(waiter).map_err(|_| self.abort_reason()) - } - /// Whether the track is gone, without waiting. pub(super) fn is_closed(&self) -> bool { self.state.is_closed() @@ -3392,9 +3421,8 @@ impl Demand { /// Read the current demand and arm `waiter` for the next transition. /// - /// Level-triggered, unlike [`poll_used`](Self::poll_used) / [`poll_unused`](Self::poll_unused): it - /// answers what the demand is *now* and wakes on whichever way it can move - /// next, so a poll-driven caller watching several tracks at once doesn't have + /// Level-triggered: it answers what the demand is *now* and wakes on whichever way it + /// can move next, so a poll-driven caller watching several tracks at once doesn't have /// to track which edge it's waiting for. pub(super) fn poll_state(&self, waiter: &kio::Waiter) -> DemandState { loop { @@ -3420,6 +3448,25 @@ impl Demand { } } +#[cfg(all(test, feature = "async"))] +impl Demand { + /// Wait until [`Self::wanted`] satisfies `f`, returning it. Errors once the track closes. + // private: test + pub(crate) async fn until(&mut self, f: impl Fn(Option) -> bool) -> Result> { + kio::wait(|waiter| { + loop { + match self.poll_wanted_changed(waiter) { + Poll::Ready(Ok(wanted)) if f(wanted) => return Poll::Ready(Ok(wanted)), + Poll::Ready(Ok(_)) => continue, + Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), + Poll::Pending => return Poll::Pending, + } + } + }) + .await + } +} + /// What [`Demand::poll_state`] found. #[derive(Copy, Clone, Debug, Eq, PartialEq)] pub(super) enum DemandState { @@ -3707,6 +3754,19 @@ impl Consumer { routes.serving() } + /// Join the instance this handle reads at the live edge; see [`Subscriber::join`]. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + fn join(&self) { + if let Some(serving) = self.serving() { + return serving.join(); + } + self.with_state(|state| { + if let Some(state) = state { + TrackState::join(state.read()); + } + }); + } + /// Whether the cache is fed live, so the newest object it holds is the track's largest. /// Fetch-only, closed, and parked copies are not, even once they learn the end. #[cfg_attr(not(feature = "async"), allow(dead_code))] @@ -4668,6 +4728,9 @@ impl Cursor { // The ranges floor the cursor, and the budget picks where above it to start, timed // or not: delivery skips the cached groups it already judges stale, on whichever // clock convicts them. + if subscription.read().joins_live() { + TrackState::join(state.read()); + } let (floor, datagram_index) = { let preferences = subscription.read(); let state = state.read(); @@ -5205,23 +5268,6 @@ impl Subscriber { let mut delivered = std::mem::take(&mut self.delivered); self.forget_past_budget(&mut delivered); self.delivered = delivered; - self.answer_new_group(sequence); - } - - /// Drop a NEW_GROUP_REQUEST that `sequence` answers, so it never reaches a later - /// upstream subscription (a reconnect, or another route) as a request for a group - /// that already came. - fn answer_new_group(&self, sequence: u64) { - // Only a DYNAMIC_GROUPS track forwards a request, so every other track (moq-lite's - // included) skips the lock on each group handed out. - if !self.info.dynamic_groups { - return; - } - let channel = match &self.inner { - Inner::Plain(cursor) => &cursor.subscription, - Inner::Resume(resume, _) => resume.subscription(), - }; - channel.answer_new_group(sequence); } /// Forget the gaps in `delivered` below each group past this subscriber's budget now: @@ -5323,7 +5369,6 @@ impl Subscriber { // delivered whole here, so count it as the single-frame group it stands in for. if let Poll::Ready(Ok(Some(datagram))) = &res { meter.datagram(datagram.payload.len() as u64); - self.answer_new_group(datagram.sequence); } res } @@ -5545,6 +5590,22 @@ impl Subscriber { Inner::Resume(resume, _) => resume.latest(), } } + + /// Join again at the live edge, judged by [`Info::refresh`] like a new subscriber: a + /// moq-transport NEW_GROUP_REQUEST. A front's reader joins the copy serving it. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: passthrough + pub(crate) fn join(&self) { + match &self.inner { + Inner::Plain(cursor) => TrackState::join(cursor.state.read()), + Inner::Resume(_, state) => { + let routes = state.read().routes.clone(); + if let Some(copy) = routes.and_then(|routes| routes.serving()) { + copy.join(); + } + } + } + } } /// A [`Subscriber`] that reads groups in sequence order. @@ -5806,10 +5867,7 @@ impl Request { /// Watch subscriber demand without keeping the track alive. pub fn demand(&self) -> Demand { - Demand { - name: self.name.clone(), - state: self.state.weak(), - } + Demand::new(self.name.clone(), self.state.weak()) } /// Join the eventual track's demand, for a request made through its broadcast. @@ -5831,7 +5889,7 @@ impl Request { } /// Reject only while no consumer needs this pending track. Demand and the check - /// share one lock, so demand returning after `Demand::poll_unused` wins the race, and the + /// share one lock, so demand returning after `Demand::wanted` went to `None` wins the race, and the /// close under that lock stops a later consumer attaching to a dead request. #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/answer.md @@ -5886,25 +5944,12 @@ impl Request { /// The delivery preferences aggregated across everyone waiting on this request, /// or `None` if nobody is waiting. Useful for sizing the track before accepting. pub fn subscription(&self) -> Option { - public(self.aggregate()) - } - - /// The aggregate with the relay-only requests the public view leaves out. - fn aggregate(&self) -> Option { let state = self.state.read(); let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); snapshot_subscription(&subs, bound) } - /// The NEW_GROUP_REQUEST the waiting subscribers hold now, if any; see - /// [`Subscription::new_group`]. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // private: passthrough - pub(crate) fn new_group(&self) -> Option { - new_group(self.aggregate()) - } - /// Block until the aggregate [`subscription`](Self::subscription) changes, /// yielding `None` once nobody is waiting. #[cfg(feature = "async")] @@ -5918,7 +5963,7 @@ impl Request { let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); - poll_combined_changed(&subs, bound, &mut self.prev_subscription, public, waiter) + poll_combined_changed(&subs, bound, &mut self.prev_subscription, waiter) } pub(super) fn weak(&self) -> TrackWeak { @@ -6268,29 +6313,6 @@ mod test { assert_eq!(&got.payload[..], b"hello"); } - /// A datagram answers a NEW_GROUP_REQUEST the way a group does, so the request never - /// outlives its answer. - #[test] - #[cfg(feature = "async")] - fn a_datagram_answers_a_new_group_request() { - let info = Info { - dynamic_groups: true, - ..Info::timed() - }; - let mut producer = track_producer("test", info); - producer.append_datagram(Timestamp::ZERO, &b"a"[..]).unwrap(); - let mut dg = producer.subscribe(Subscription { - new_group: NewGroup::new(0, Some(0)), - ..Default::default() - }); - assert_eq!(recv_datagram(&mut dg).sequence, 0); - assert!(producer.new_group().is_some(), "the datagram it joined on asks still"); - - producer.append_datagram(Timestamp::ZERO, &b"b"[..]).unwrap(); - assert_eq!(recv_datagram(&mut dg).sequence, 1); - assert_eq!(producer.new_group(), None); - } - #[test] #[cfg(feature = "async")] fn insert_datagram_preserves_sequence() { @@ -9310,56 +9332,6 @@ mod test { } } - /// A NEW_GROUP_REQUEST aggregates as the one answered latest, stays out of the public - /// subscription, and leaves a subscriber once it is handed a group at or past it. - #[test] - fn new_group_requests_aggregate_out_of_sight() { - let info = Info { - dynamic_groups: true, - ..Info::timed() - }; - let mut producer = track_producer("test", info); - let wants = |value, latest| Subscription { - new_group: NewGroup::new(value, Some(latest)), - ..Default::default() - }; - // Answered by group 5 and group 3. - let mut a = producer.subscribe(wants(5, 4)); - let _b = producer.subscribe(wants(0, 2)); - - let mut prev = None; - let mut poll = |producer: &Producer| { - kio::wait(|waiter| producer.poll_new_group(&mut prev, waiter)) - .now_or_never() - .map(|polled| polled.unwrap().map(|new_group| new_group.value)) - }; - assert_eq!(poll(&producer), Some(Some(5))); - assert_eq!(poll(&producer), None, "unchanged"); - assert_eq!(producer.subscription().unwrap().new_group, None); - let waiter = kio::Waiter::noop(); - assert!(producer.poll_subscription_changed(&waiter).is_ready()); - - producer.create_group(group::Info { sequence: 4 }).unwrap(); - kio::wait(|waiter| a.poll_recv_group(waiter)) - .now_or_never() - .unwrap() - .unwrap() - .unwrap(); - assert_eq!(poll(&producer), None, "group 4 answers neither"); - - producer.create_group(group::Info { sequence: 5 }).unwrap(); - kio::wait(|waiter| a.poll_recv_group(waiter)) - .now_or_never() - .unwrap() - .unwrap() - .unwrap(); - assert_eq!(poll(&producer), Some(Some(0)), "the other request remains"); - assert!( - producer.poll_subscription_changed(&waiter).is_pending(), - "the public view never saw a request" - ); - } - /// An [`ArcWake`] that just records that it was woken. struct FlagWake(Arc); @@ -12626,6 +12598,141 @@ mod test { assert!(pool.used() < used, "its bytes are released"); } + /// Append a group of a 3 byte first frame and a `delta` byte delta. + fn refresh_group(producer: &Producer, delta: usize) { + let mut group = producer.append_group().unwrap(); + group.write_frame(None, &b"key"[..]).unwrap(); + if delta > 0 { + group.write_frame(None, vec![0u8; delta]).unwrap(); + } + } + + /// Poll `demand` for a change without waiting. + fn wanted_changed(demand: &mut Demand) -> Option> { + match demand.poll_wanted_changed(&kio::Waiter::noop()) { + Poll::Ready(res) => Some(res.unwrap()), + Poll::Pending => None, + } + } + + /// The first consumer of a track with no group wants group 0, and nobody wants it once + /// the last one leaves. + #[test] + fn wanted_follows_the_first_consumer() { + let producer = track_producer("test", Info::default().with_refresh(1)); + let mut demand = producer.demand(); + assert_eq!(demand.wanted(), None); + assert_eq!(wanted_changed(&mut demand), Some(None), "the first call reports"); + assert_eq!(wanted_changed(&mut demand), None, "then only changes"); + + let subscriber = producer.subscribe(None); + assert_eq!(demand.wanted(), Some(0)); + assert_eq!(wanted_changed(&mut demand), Some(Some(0))); + drop(subscriber); + assert_eq!(demand.wanted(), None); + assert_eq!(wanted_changed(&mut demand), Some(None)); + } + + /// A join reads the newest group, unless its bytes after the first frame exceed the + /// ratio times the first frame: then it wants the group after the newest. + #[test] + fn a_join_over_the_ratio_wants_a_new_group() { + for (delta, wanted) in [(0, 0), (3, 0), (4, 1)] { + let producer = track_producer("test", Info::default().with_refresh(1)); + refresh_group(&producer, delta); + let _subscriber = producer.subscribe(None); + assert_eq!(producer.demand().wanted(), Some(wanted), "{delta} byte delta"); + } + } + + /// Joins while a request is pending ask for the same group, so the publisher hears it + /// once. The group reaching it leaves nothing pending, and only a join over the ratio of + /// that group asks again. + #[test] + fn joins_coalesce_until_the_group_lands() { + let producer = track_producer("test", Info::default().with_refresh(1)); + let mut demand = producer.demand(); + refresh_group(&producer, 4); + let _a = producer.subscribe(None); + assert_eq!(wanted_changed(&mut demand), Some(Some(1))); + let _b = producer.subscribe(None); + assert_eq!(wanted_changed(&mut demand), None, "coalesced"); + + refresh_group(&producer, 0); + assert_eq!(wanted_changed(&mut demand), None, "group 1 answers it"); + let _c = producer.subscribe(None); + assert_eq!(wanted_changed(&mut demand), None, "group 1 is under the ratio"); + + refresh_group(&producer, 4); + let _d = producer.subscribe(None); + assert_eq!(wanted_changed(&mut demand), Some(Some(3))); + } + + /// A track without a ratio never asks for a group on a join. + #[test] + fn joins_without_refresh_ask_nothing() { + let producer = track_producer("test", Info::default()); + refresh_group(&producer, 1000); + let _subscriber = producer.subscribe(None); + assert_eq!(producer.demand().wanted(), Some(0)); + } + + /// Only a join at the live edge counts: a subscription resuming from a fixed group + /// already has the newest group's start. + #[test] + fn a_fixed_start_is_no_join() { + let producer = track_producer("test", Info::default().with_refresh(1)); + refresh_group(&producer, 4); + let _subscriber = producer.subscribe(Subscription::default().with_groups(0..)); + assert_eq!(producer.demand().wanted(), Some(0)); + } + + /// A replacement's consumers want the group past what earlier producers of the name + /// wrote, where its first group has to start. + #[test] + fn a_replacement_wants_past_its_predecessor() { + let broadcast = broadcast::Info::default().produce(); + let first = broadcast.create_track("test", Info::default()).unwrap(); + first.create_group(group::Info { sequence: 7 }).unwrap(); + first.finish().unwrap(); + drop(first); + + let second = broadcast.create_track("test", Info::default()).unwrap(); + let mut demand = second.demand(); + assert_eq!(wanted_changed(&mut demand), Some(None)); + let _subscriber = second.subscribe(None); + assert_eq!(wanted_changed(&mut demand), Some(Some(8))); + second.create_group(group::Info { sequence: 8 }).unwrap(); + assert_eq!(wanted_changed(&mut demand), None); + } + + /// The demand reports the track's closure as its abort reason. + #[test] + fn wanted_changed_errors_once_closed() { + let producer = track_producer("test", Info::default()); + let mut demand = producer.demand(); + producer.abort(Error::Cancel).unwrap(); + assert!(matches!( + demand.poll_wanted_changed(&kio::Waiter::noop()), + Poll::Ready(Err(Error::Cancel)) + )); + assert_eq!(demand.wanted(), None); + } + + /// A NEW_GROUP_REQUEST joins again: under the ratio it asks nothing, over it the group + /// past the newest. + #[test] + fn a_subscriber_joins_again() { + let producer = track_producer("test", Info::default().with_refresh(1)); + let subscriber = producer.subscribe(None); + refresh_group(&producer, 3); + subscriber.join(); + assert_eq!(producer.demand().wanted(), Some(0)); + refresh_group(&producer, 4); + subscriber.join(); + assert_eq!(producer.demand().wanted(), Some(2)); + } + #[test] #[cfg(feature = "async")] fn request_and_dynamic_share_weak_track_demand() { @@ -12643,7 +12750,10 @@ mod test { assert_eq!(producer.demand().name(), demand.name()); drop(producer); drop(dynamic); - assert!(matches!(demand.used().now_or_never(), Some(Err(Error::Dropped)))); + assert!(matches!( + demand.clone().wanted_changed().now_or_never(), + Some(Err(Error::Dropped)) + )); } #[test] diff --git a/rs/moq-net/src/model/track/demand.rs b/rs/moq-net/src/model/track/demand.rs index 071b50838d2..e882719a53a 100644 --- a/rs/moq-net/src/model/track/demand.rs +++ b/rs/moq-net/src/model/track/demand.rs @@ -1,7 +1,7 @@ //! Incremental demand, separate from the track's cached content. use std::{collections::BTreeMap, sync::Arc, task::Poll, time::Duration}; -use super::{NewGroup, Order, Subscription, TrackState, clamp_combined}; +use super::{Order, Subscription, TrackState, clamp_combined}; mod ranges; use ranges::Ranges; @@ -13,23 +13,23 @@ pub(super) struct Subscriptions { max_delay: BTreeMap, ranges: Ranges, descending: usize, - /// Only the subscribers holding a request. - new_group: BTreeMap, + /// The lowest group consumers want: raised past the newest group by a join over the + /// track's refresh ratio, and never lowered. See [`super::Demand::wanted`]. + wanted: u64, waiters: kio::WaiterList, } /// Everything the aggregate holds besides its ranges. -type Scalars = (u8, Duration, Order, Option); +type Scalars = (u8, Duration, Order); impl Subscriptions { pub(super) fn combined(&self) -> Option { - let (priority, max_delay, order, new_group) = self.scalars()?; + let (priority, max_delay, order) = self.scalars()?; Some(Subscription { priority, max_delay, ranges: self.ranges.union(), order, - new_group, }) } @@ -43,20 +43,17 @@ impl Subscriptions { } else { Order::Descending }, - self.new_group.last_key_value().map(|(new_group, _)| *new_group), ) }) } - /// Poll for the aggregate, as `view` sees it, to differ from `prev`. - pub(super) fn poll_changed( + pub(super) fn poll_changed( &mut self, bound: Option, - prev: &mut T, - view: impl Fn(Option) -> T, + prev: &mut Option, waiter: &kio::Waiter, - ) -> Poll { - let next = view(clamp_combined(self.combined(), bound)); + ) -> Poll> { + let next = clamp_combined(self.combined(), bound); if next != *prev { *prev = next.clone(); Poll::Ready(next) @@ -66,6 +63,26 @@ impl Subscriptions { } } + /// The lowest group consumers want, whether or not anyone consumes now. + pub(super) fn wanted(&self) -> u64 { + self.wanted + } + + /// [`Self::wanted`], arming `waiter` for its next change. + pub(super) fn poll_wanted(&mut self, waiter: &kio::Waiter) -> u64 { + waiter.register(&mut self.waiters); + self.wanted + } + + /// Raise [`Self::wanted`] to `group`, taking the wakes only when it moved. + pub(super) fn want(&mut self, group: u64) -> kio::WaiterList { + if group <= self.wanted { + return Default::default(); + } + self.wanted = group; + self.waiters.take() + } + /// Mutate counts under one lock, taking wakes only when the aggregate changes. fn replace(&mut self, old: Option<&Subscription>, new: Option<&Subscription>) -> kio::WaiterList { let prev = self.scalars(); @@ -81,9 +98,6 @@ impl Subscriptions { } } self.descending += usize::from(new.order == Order::Descending); - if let Some(new_group) = new.new_group { - add(&mut self.new_group, new_group); - } self.count += 1; } if let Some(old) = old { @@ -95,9 +109,6 @@ impl Subscriptions { } } self.descending -= usize::from(old.order == Order::Descending); - if let Some(new_group) = old.new_group { - remove(&mut self.new_group, new_group); - } self.count -= 1; } if reshaped || self.scalars() != prev { @@ -155,29 +166,7 @@ impl Preferences { } pub(super) fn update(&self, next: Subscription) -> crate::Result<()> { - self.update_with(|_| next) - } - - /// Drop a NEW_GROUP_REQUEST that `sequence` answers. - pub(super) fn answer_new_group(&self, sequence: u64) { - // Checked before taking the write, which wakes this channel's readers. - if !self - .read() - .new_group - .is_some_and(|new_group| sequence >= new_group.first) - { - return; - } - let _ = self.update_with(|value| Subscription { - new_group: value.new_group.filter(|new_group| sequence < new_group.first), - ..value.clone() - }); - } - - /// Replace the preference with what `next` makes of it, under one write. - fn update_with(&self, next: impl FnOnce(&Subscription) -> Subscription) -> crate::Result<()> { let mut value = self.0.value.write().map_err(|_| crate::Error::Closed)?; - let next = next(&value); if *value == next { return Ok(()); } @@ -276,10 +265,6 @@ mod tests { } else { Order::Descending }, - new_group: rng - .random_bool(0.5) - .then(|| NewGroup::new(rng.random_range(0..8), Some(rng.random_range(0..8)))) - .flatten(), }; match (&mut slots[index], rng.random_range(0..3)) { (slot @ None, _) => *slot = Some((producer.subscribe(next.clone()), next)), @@ -298,16 +283,7 @@ mod tests { expected.add(value); } let expected = expected.finish(); - assert_eq!( - producer.subscription(), - super::super::public(expected.clone()), - "operation {step}" - ); - assert_eq!( - producer.new_group(), - super::super::new_group(expected), - "operation {step}" - ); + assert_eq!(producer.subscription(), expected, "operation {step}"); } drop(slots); assert_eq!(producer.subscription(), None); diff --git a/rs/moq-net/src/util.rs b/rs/moq-net/src/util.rs index 03f38068ab5..110a4e1abdb 100644 --- a/rs/moq-net/src/util.rs +++ b/rs/moq-net/src/util.rs @@ -330,3 +330,15 @@ mod tests { assert_eq!(output, 42); } } + +/// Ready once nothing wants the track, or it closed; otherwise arm `waiter` for a change. +pub(crate) fn poll_unwanted(demand: &mut crate::track::Demand, waiter: &kio::Waiter) -> Poll<()> { + loop { + match demand.poll_wanted_changed(waiter) { + Poll::Ready(Ok(Some(_))) => continue, + Poll::Ready(_) => return Poll::Ready(()), + Poll::Pending if demand.wanted().is_none() => return Poll::Ready(()), + Poll::Pending => return Poll::Pending, + } + } +} diff --git a/rs/moq-net/tests/integration/announce_to_serve.rs b/rs/moq-net/tests/integration/announce_to_serve.rs index 5f694d30998..ddc00e258a2 100644 --- a/rs/moq-net/tests/integration/announce_to_serve.rs +++ b/rs/moq-net/tests/integration/announce_to_serve.rs @@ -162,7 +162,7 @@ async fn lifecycle(observer: Observer) -> Vec { // A track in flight across the unannounce. let mut reader = read(&first, "video").await; - moq_clock::timeout(SETTLE, track.demand().used()) + moq_clock::timeout(SETTLE, crate::support::wanted(track.demand())) .await .expect("no subscriber appeared") .unwrap(); @@ -202,7 +202,7 @@ async fn lifecycle(observer: Observer) -> Vec { let audio = broadcast.create_track("audio", timed()).unwrap(); let mut reader = read(&again, "audio").await; - moq_clock::timeout(SETTLE, audio.demand().used()) + moq_clock::timeout(SETTLE, crate::support::wanted(audio.demand())) .await .expect("no subscriber appeared after reannouncing") .unwrap(); diff --git a/rs/moq-net/tests/integration/dial_split_horizon.rs b/rs/moq-net/tests/integration/dial_split_horizon.rs index 0c9e08a4f5b..bb574f8c9af 100644 --- a/rs/moq-net/tests/integration/dial_split_horizon.rs +++ b/rs/moq-net/tests/integration/dial_split_horizon.rs @@ -191,7 +191,7 @@ async fn dialed_anonymous_session_does_not_echo_or_route_subscribe_back() { .subscribe(subscription) .await .expect("subscriber subscribes"); - moq_clock::timeout(SETTLE, track.demand().used()) + moq_clock::timeout(SETTLE, crate::support::wanted(track.demand())) .await .expect("the subscribe never reached the announcer") .unwrap(); diff --git a/rs/moq-net/tests/integration/fetch_only.rs b/rs/moq-net/tests/integration/fetch_only.rs index 85bac40deec..70d7bd7fffb 100644 --- a/rs/moq-net/tests/integration/fetch_only.rs +++ b/rs/moq-net/tests/integration/fetch_only.rs @@ -186,7 +186,7 @@ async fn a_subscribe_after_track_status_keeps_timestamps() { assert!(track.subscription().is_none(), "{version}: the query subscribed"); let mut sub = copy.subscribe(None).await.unwrap(); - track.demand().used().await.unwrap(); + crate::support::wanted(track.demand()).await.unwrap(); // Far from any arrival time, so a frame stamped on arrival cannot pass. let stamp = Timestamp::from_millis(123_456).unwrap(); let mut group = track.append_group().unwrap(); diff --git a/rs/moq-net/tests/integration/finite_relay.rs b/rs/moq-net/tests/integration/finite_relay.rs index 81f4a1798b3..2ec6bc63e75 100644 --- a/rs/moq-net/tests/integration/finite_relay.rs +++ b/rs/moq-net/tests/integration/finite_relay.rs @@ -127,7 +127,7 @@ async fn round(name: &str, arrival: Arrival) -> (Vec, Result<(), moq_net::E (seen, end) }); - moq_clock::timeout(TIMEOUT, track.demand().used()) + moq_clock::timeout(TIMEOUT, crate::support::wanted(track.demand())) .await .expect("no subscriber appeared") .unwrap(); diff --git a/rs/moq-net/tests/integration/history_groups.rs b/rs/moq-net/tests/integration/history_groups.rs index 97881d53156..a70687b8a5f 100644 --- a/rs/moq-net/tests/integration/history_groups.rs +++ b/rs/moq-net/tests/integration/history_groups.rs @@ -112,7 +112,7 @@ async fn round(version: &str, relay: bool, newest_first: bool) -> Vec<(u64, usiz got }); - moq_clock::timeout(TIMEOUT, track.demand().used()) + moq_clock::timeout(TIMEOUT, crate::support::wanted(track.demand())) .await .expect("no subscriber appeared") .unwrap(); @@ -235,7 +235,7 @@ async fn a_late_subscriber_receives_the_relays_cached_history() { read_history(&mut sub).await; sub }); - track.demand().used().await.unwrap(); + crate::support::wanted(track.demand()).await.unwrap(); upstream.server_transport.hold_unis(); let mut old = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); for _ in 0..3 { diff --git a/rs/moq-net/tests/integration/idle_cancel_refetch.rs b/rs/moq-net/tests/integration/idle_cancel_refetch.rs index bd83ab1d507..0705c09f658 100644 --- a/rs/moq-net/tests/integration/idle_cancel_refetch.rs +++ b/rs/moq-net/tests/integration/idle_cancel_refetch.rs @@ -69,7 +69,7 @@ async fn a_group_cut_by_an_idle_cancel_is_refetched_whole() { } // The relay cancels the idle upstream subscription. - moq_clock::timeout(TIMEOUT, track.demand().unused()) + moq_clock::timeout(TIMEOUT, crate::support::unwanted(track.demand())) .await .unwrap() .unwrap(); diff --git a/rs/moq-net/tests/integration/late_lower_group.rs b/rs/moq-net/tests/integration/late_lower_group.rs index 59efc071811..2cf29eee790 100644 --- a/rs/moq-net/tests/integration/late_lower_group.rs +++ b/rs/moq-net/tests/integration/late_lower_group.rs @@ -136,7 +136,7 @@ async fn session(version: &str, relay: bool, start: Option) -> Vec<(u6 read_all(&mut sub).await }); - moq_clock::timeout(TIMEOUT, track.demand().used()) + moq_clock::timeout(TIMEOUT, crate::support::wanted(track.demand())) .await .expect("no subscriber appeared") .unwrap(); diff --git a/rs/moq-net/tests/integration/received_rewind.rs b/rs/moq-net/tests/integration/received_rewind.rs index f27d20beb46..5cc999f7143 100644 --- a/rs/moq-net/tests/integration/received_rewind.rs +++ b/rs/moq-net/tests/integration/received_rewind.rs @@ -91,7 +91,7 @@ async fn relay(downstream: &str) -> (Option, Vec) { (timescale, got) }); - moq_clock::timeout(TIMEOUT, track.demand().used()) + moq_clock::timeout(TIMEOUT, crate::support::wanted(track.demand())) .await .expect("no subscriber appeared") .unwrap(); diff --git a/rs/moq-net/tests/integration/rejoin.rs b/rs/moq-net/tests/integration/rejoin.rs index 42f8d148c8b..e209bc30674 100644 --- a/rs/moq-net/tests/integration/rejoin.rs +++ b/rs/moq-net/tests/integration/rejoin.rs @@ -78,7 +78,7 @@ async fn rejoin_recovers_the_group_reset_on_leave() { // Leave mid-group; the publisher cuts the open group once demand is gone. drop(sub); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); open.write_frame(ts(133), b"b1".as_ref()).unwrap(); open.finish().unwrap(); @@ -162,7 +162,7 @@ async fn rejoin_skips_a_cache_kept_by_another_handle() { let mut group = sub.recv_group().await.unwrap().unwrap(); assert_eq!(read_all(&mut group).await.unwrap(), [b"old".to_vec()], "{version}"); drop((group, sub)); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); // The publisher moves on while nobody subscribes. for sequence in 1..=3u64 { @@ -226,12 +226,12 @@ async fn rejoin_mid_group_keeps_the_head_for_later_readers() { let mut group = sub.recv_group().await.unwrap().unwrap(); assert_eq!(group.read_frame().await.unwrap().unwrap().payload, b"a0".as_ref()); drop((group, sub)); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); let mut rejoined = remote.track("video").unwrap().subscribe(None).await.unwrap(); let mut rejoined = rejoined.recv_group().await.unwrap().unwrap(); assert_eq!(rejoined.read_frame().await.unwrap().unwrap().payload, b"a0".as_ref()); - track.demand().used().await.unwrap(); + crate::support::wanted(track.demand()).await.unwrap(); let later = relay.consume().request_broadcast("bench", None).await.unwrap(); let mut sub = later.track("video").unwrap().subscribe(None).await.unwrap(); @@ -298,7 +298,7 @@ async fn rejoin_goes_live_without_the_join_head() { let mut group = sub.recv_group().await.unwrap().unwrap(); assert_eq!(group.read_frame().await.unwrap().unwrap().payload, b"a0".as_ref()); drop((group, sub)); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); // The rejoin's join stream is lost before its header. upstream.server_transport.hold_unis(); @@ -311,7 +311,7 @@ async fn rejoin_goes_live_without_the_join_head() { } } }); - track.demand().used().await.unwrap(); + crate::support::wanted(track.demand()).await.unwrap(); moq_clock::sleep(Duration::from_millis(100)).await; upstream.server_transport.drop_unis(); @@ -367,7 +367,7 @@ async fn rejoin_during_the_cancel_skips_the_cache() { let mut group = sub.recv_group().await.unwrap().unwrap(); assert_eq!(read_all(&mut group).await.unwrap(), [b"old".to_vec()], "{version}"); drop((group, sub)); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); // The publisher moves on while the relay's cancel is still in flight. for sequence in 1..=3u64 { @@ -430,7 +430,7 @@ async fn rejoin_waits_for_the_answers_first_frame() { let mut group = sub.recv_group().await.unwrap().unwrap(); assert_eq!(read_all(&mut group).await.unwrap(), [b"old".to_vec()], "{version}"); drop((group, sub)); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); let mut group = track.append_group().unwrap(); group.write_frame(ts(500), b"new".as_ref()).unwrap(); @@ -571,7 +571,7 @@ async fn rejoin_keeps_source_timestamps() { for (sequence, ms) in [(0, 123_456), (1, 654_321)] { let mut sub = remote.track("video").unwrap().subscribe(None).await.unwrap(); - track.demand().used().await.unwrap(); + crate::support::wanted(track.demand()).await.unwrap(); let mut group = track.append_group().unwrap(); group.write_frame(ts(ms), b"frame".as_ref()).unwrap(); group.finish().unwrap(); @@ -589,7 +589,7 @@ async fn rejoin_keeps_source_timestamps() { "{version} group {sequence}" ); drop((group, sub)); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); } }) .await @@ -698,7 +698,7 @@ async fn quiet_catalog_survives_cache_expiry(version: Version, takeover: bool) { let (mut first, remote, pair) = session(3).await; assert_eq!(first.recv_group().await.unwrap().unwrap().sequence, 0, "{version}"); drop((first, remote, pair)); - track.demand().unused().await.unwrap(); + crate::support::unwanted(track.demand()).await.unwrap(); let (mut holder, remote, pair) = session(4).await; assert_eq!(holder.recv_group().await.unwrap().unwrap().sequence, 0, "{version}"); (holder, remote, pair) diff --git a/rs/moq-net/tests/integration/request_caps.rs b/rs/moq-net/tests/integration/request_caps.rs index afbc2b1f677..7f003f97234 100644 --- a/rs/moq-net/tests/integration/request_caps.rs +++ b/rs/moq-net/tests/integration/request_caps.rs @@ -98,7 +98,7 @@ async fn closed_requests_are_granted_back() { // Wait for the server to see it end, so the next round is a fresh request. let published = &setup.tracks[round]; - moq_clock::timeout(TIMEOUT, published.demand().unused()) + moq_clock::timeout(TIMEOUT, crate::support::unwanted(published.demand())) .await .unwrap_or_else(|_| panic!("{version}: round {round} never ended")) .unwrap(); diff --git a/rs/moq-net/tests/integration/session_close.rs b/rs/moq-net/tests/integration/session_close.rs index 04097a37872..46701b97e9b 100644 --- a/rs/moq-net/tests/integration/session_close.rs +++ b/rs/moq-net/tests/integration/session_close.rs @@ -108,7 +108,9 @@ async fn track_info_interest_precedes_a_subscription() { let remote = consumer.request_broadcast("bcast", None).await.unwrap(); let copy = remote.track("video").unwrap(); copy.query().await.expect("TRACK_INFO"); - track.demand().used().await.expect("TRACK_INFO holds demand"); + crate::support::wanted(track.demand()) + .await + .expect("TRACK_INFO holds demand"); assert!(track.subscription().is_none(), "{version}: no SUBSCRIBE was requested"); } } diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index e6016fecf19..1f0545c732a 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -106,7 +106,7 @@ async fn ahead_then_live(version: Option<&str>, relay: bool) -> (Vec, Vec Setup { } }); - moq_clock::timeout(TIMEOUT, track.demand().used()) + moq_clock::timeout(TIMEOUT, crate::support::wanted(track.demand())) .await .expect("no subscriber appeared") .unwrap(); diff --git a/rs/moq-net/tests/integration/subscription_end_integrity.rs b/rs/moq-net/tests/integration/subscription_end_integrity.rs index d6be2a4253b..7517d8442f2 100644 --- a/rs/moq-net/tests/integration/subscription_end_integrity.rs +++ b/rs/moq-net/tests/integration/subscription_end_integrity.rs @@ -113,7 +113,7 @@ async fn round(drop_session: bool) -> (Vec>, Option) { } }); - moq_clock::timeout(TIMEOUT, track.demand().used()) + moq_clock::timeout(TIMEOUT, crate::support::wanted(track.demand())) .await .expect("no subscriber appeared") .unwrap(); @@ -252,7 +252,9 @@ async fn killed(version: &str, local: bool) -> (Option, Option moq_net::Result { + loop { + if let Some(wanted) = demand.wanted_changed().await? { + return Ok(wanted); + } + } +} + +/// Wait until nobody wants the track. +#[allow(dead_code)] +pub async fn unwanted(mut demand: track::Demand) -> moq_net::Result<()> { + while demand.wanted_changed().await?.is_some() {} + Ok(()) +} diff --git a/rs/moq-net/tests/integration/track_info_cancel.rs b/rs/moq-net/tests/integration/track_info_cancel.rs index 99e8cafb3a0..d7d06873aff 100644 --- a/rs/moq-net/tests/integration/track_info_cancel.rs +++ b/rs/moq-net/tests/integration/track_info_cancel.rs @@ -48,13 +48,10 @@ async fn abandoned_request_reaches_the_publisher(version: &str, relays: u64) { // The publisher never answers; the reader gives up. drop(waiting); - moq_clock::timeout( - Duration::from_secs(5), - kio::wait(|waiter| request.demand().poll_unused(waiter)), - ) - .await - .unwrap_or_else(|_| panic!("{version:?} over {relays} relays: the publisher's request is still wanted")) - .expect("the pending request is still open"); + moq_clock::timeout(Duration::from_secs(5), crate::support::unwanted(request.demand())) + .await + .unwrap_or_else(|_| panic!("{version:?} over {relays} relays: the publisher's request is still wanted")) + .expect("the pending request is still open"); } #[moq_clock::test] diff --git a/rs/moq-net/tests/integration/track_stream_demand.rs b/rs/moq-net/tests/integration/track_stream_demand.rs index 6bcd0393a94..df515800c86 100644 --- a/rs/moq-net/tests/integration/track_stream_demand.rs +++ b/rs/moq-net/tests/integration/track_stream_demand.rs @@ -44,8 +44,7 @@ async fn link(version: Version, publisher: &origin::Producer, subscriber: &origi connect_mock(options).await } -/// Every demand edge a `broadcast::Demand` or `track::Demand` reports from here on, -/// `true` for used. +/// Every demand edge a `broadcast::Demand` reports from here on, `true` for used. macro_rules! record { ($demand:expr) => {{ let edges = Rc::new(RefCell::new(Vec::new())); @@ -64,6 +63,25 @@ macro_rules! record { }}; } +/// Every demand edge a `track::Demand` reports from here on, `true` for wanted. +macro_rules! record_track { + ($demand:expr) => {{ + let edges = Rc::new(RefCell::new(Vec::new())); + let log = edges.clone(); + let mut demand = $demand; + drop(moq_clock::sim::spawn(async move { + let mut was = false; + while let Ok(wanted) = demand.wanted_changed().await { + if wanted.is_some() != was { + was = wanted.is_some(); + log.borrow_mut().push(was); + } + } + })); + edges + }}; +} + /// A reader subscribes through `relays` relays and stays: the publisher, which starts /// the track on demand, is asked for it once, and its broadcast and track each see exactly /// one `used` edge, then `unused` once the reader leaves. @@ -93,7 +111,10 @@ async fn one_used_edge(version: &str, relays: usize, reorder: bool) { let served = (requests.clone(), track_edges.clone()); let publisher = moq_clock::sim::spawn(async move { while let Ok(request) = dynamic.requested_track().await { - served.1.borrow_mut().get_or_insert_with(|| record!(request.demand())); + served + .1 + .borrow_mut() + .get_or_insert_with(|| record_track!(request.demand())); moq_clock::sleep(STARTUP).await; let track = request.accept(timed()); let mut group = track.append_group().unwrap(); @@ -142,7 +163,7 @@ async fn one_used_edge(version: &str, relays: usize, reorder: bool) { drop(received); drop(subscriber); let track = requests.borrow()[0].0.clone(); - moq_clock::timeout(TIMEOUT, track.demand().unused()) + moq_clock::timeout(TIMEOUT, crate::support::unwanted(track.demand())) .await .unwrap_or_else(|_| panic!("{label}: demand outlived the reader")) .unwrap(); @@ -226,9 +247,9 @@ async fn bare_handle_is_lazy(version: &str, relays: usize) { "{label}: the query never reached the publisher" ); let track = requests.borrow()[0].0.clone(); - assert!(track.demand().is_used(), "{label}: a held query let go"); + assert!(track.demand().wanted().is_some(), "{label}: a held query let go"); drop(query); - moq_clock::timeout(TIMEOUT, track.demand().unused()) + moq_clock::timeout(TIMEOUT, crate::support::unwanted(track.demand())) .await .unwrap_or_else(|_| panic!("{label}: a dropped query is still demand")) .unwrap(); @@ -243,9 +264,12 @@ async fn bare_handle_is_lazy(version: &str, relays: usize) { .unwrap_or_else(|_| panic!("{label}: no group arrived")) .unwrap() .expect("the track is live"); - assert!(track.demand().is_used(), "{label}: the subscription is not demand"); + assert!( + track.demand().wanted().is_some(), + "{label}: the subscription is not demand" + ); drop(subscriber); - moq_clock::timeout(TIMEOUT, track.demand().unused()) + moq_clock::timeout(TIMEOUT, crate::support::unwanted(track.demand())) .await .unwrap_or_else(|_| panic!("{label}: the publisher still reads the track as used")) .unwrap(); @@ -289,7 +313,7 @@ async fn held_tracks_share_the_cap_with_their_subscriptions() { let track = broadcast.create_track(format!("t{i}"), timed()).unwrap(); let mut group = track.append_group().unwrap(); group.write_frame(Timestamp::ZERO, b"key".as_ref()).unwrap(); - let edges = record!(track.demand()); + let edges = record_track!(track.demand()); tracks.push((track, group, edges)); } broadcast.announce(Default::default()).unwrap(); diff --git a/rs/moq-net/tests/integration/unannounce_release.rs b/rs/moq-net/tests/integration/unannounce_release.rs index e730df27edd..69cb03f9e2e 100644 --- a/rs/moq-net/tests/integration/unannounce_release.rs +++ b/rs/moq-net/tests/integration/unannounce_release.rs @@ -31,14 +31,14 @@ async fn release(version: Version) { consumer.routed("a/b").await.expect("routed"); let remote = consumer.request_broadcast("a/b", None).await.expect("resolves"); let sub = remote.track("t").unwrap().subscribe(None).await.expect("subscribes"); - track.demand().used().await.unwrap(); + crate::support::wanted(track.demand()).await.unwrap(); broadcast.unannounce(); moq_clock::sleep(Duration::from_secs(1)).await; drop(sub); drop(remote); - moq_clock::timeout(Duration::from_secs(600), track.demand().unused()) + moq_clock::timeout(Duration::from_secs(600), crate::support::unwanted(track.demand())) .await .unwrap_or_else(|_| panic!("{version}: the relay kept its upstream subscription")) .unwrap(); diff --git a/rs/moq-net/tests/loom.rs b/rs/moq-net/tests/loom.rs index e449eca2def..08384e7c970 100644 --- a/rs/moq-net/tests/loom.rs +++ b/rs/moq-net/tests/loom.rs @@ -184,15 +184,18 @@ fn subscriber_wakes_parked_demand() { let broadcast = broadcast::Info::new().produce(); let consumer = broadcast.consume(); let track = broadcast.create_track("video", None).expect("create track"); - let demand = track.demand(); + let mut demand = track.demand(); let subscriber = thread::spawn(move || { let track_consumer = consumer.track("video").expect("track"); - // Held until joined, so it outlives the `used()` poll. + // Held until joined, so it outlives the `wanted_changed()` poll. block_on(track_consumer.subscribe(None)).expect("subscribe") }); - block_on(demand.used()).expect("the new subscriber was missed"); + while block_on(demand.wanted_changed()) + .expect("the new subscriber was missed") + .is_none() + {} drop(subscriber.join().unwrap()); drop(track); @@ -268,7 +271,7 @@ fn a_front_sees_a_reader_come_and_go() { // A first reader gets the source asked, then leaves. let first = room.track("video").expect("track").query(); driver.poll(now, &noop).unwrap(); - assert!(demand.is_used(), "the front never asked the source"); + assert!(demand.wanted().is_some(), "the front never asked the source"); drop(first); let racing = room.clone(); @@ -278,9 +281,9 @@ fn a_front_sees_a_reader_come_and_go() { block_on(std::future::poll_fn(|cx| { driver.poll(now, &kio::Waiter::new(cx.waker().clone())).unwrap(); - match demand.is_used() { - true => std::task::Poll::Pending, - false => std::task::Poll::Ready(()), + match demand.wanted() { + Some(_) => std::task::Poll::Pending, + None => std::task::Poll::Ready(()), } })); }); @@ -311,7 +314,7 @@ fn a_front_sees_a_reader_return() { driver.poll(now, &noop).unwrap(); drop(first); driver.poll(now, &noop).unwrap(); - assert!(!demand.is_used(), "the front kept the source for nobody"); + assert!(demand.wanted().is_none(), "the front kept the source for nobody"); let leaving = room.track("video").expect("track").query(); let racing = room.clone(); @@ -324,9 +327,9 @@ fn a_front_sees_a_reader_return() { block_on(std::future::poll_fn(|cx| { driver.poll(now, &kio::Waiter::new(cx.waker().clone())).unwrap(); - match demand.is_used() { - true => std::task::Poll::Ready(()), - false => std::task::Poll::Pending, + match demand.wanted() { + Some(_) => std::task::Poll::Ready(()), + None => std::task::Poll::Pending, } })); drop(returned); diff --git a/rs/moq-rtc/src/egress.rs b/rs/moq-rtc/src/egress.rs index bb37b4ea047..83f455f1d4b 100644 --- a/rs/moq-rtc/src/egress.rs +++ b/rs/moq-rtc/src/egress.rs @@ -1172,7 +1172,12 @@ mod tests { assert_eq!(written(&mut writes).await.as_ref(), b"low-0"); drop(writes); - tokio::time::timeout(Duration::from_secs(1), low.demand().unused()) + let mut demand = low.demand(); + let unwanted = async { + while demand.wanted_changed().await?.is_some() {} + moq_net::Result::Ok(()) + }; + tokio::time::timeout(Duration::from_secs(1), unwanted) .await .expect("the line unsubscribes") .unwrap(); diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 30bec6bc277..d98dd4fce38 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -577,7 +577,7 @@ impl TrackPair { /// Whether any consumer exists on either flavor. fn is_used(&self) -> bool { - self.plain.demand().is_used() || self.compressed.demand().is_used() + self.plain.demand().wanted().is_some() || self.compressed.demand().wanted().is_some() } /// Publish this drain's entries on both flavors (`{}` when there are none) @@ -673,10 +673,12 @@ impl PendingPair { /// this can read used for a while after the end subscriber left; that only /// delays reclamation, it never strands anyone. fn is_used(&self, waiter: &kio::Waiter) -> bool { - self.plain - .iter() - .chain(self.compressed.iter()) - .any(|request| request.demand().poll_unused(waiter).is_pending()) + self.plain.iter().chain(self.compressed.iter()).any(|request| { + let mut demand = request.demand(); + // Drain the changes so the waiter stays registered, then read where demand settled. + while let Poll::Ready(Ok(Some(_))) = demand.poll_wanted_changed(waiter) {} + demand.wanted().is_some() + }) } } diff --git a/rs/moq-tokio/tests/integration/broadcast.rs b/rs/moq-tokio/tests/integration/broadcast.rs index e447a44a344..a9021e1cdd8 100644 --- a/rs/moq-tokio/tests/integration/broadcast.rs +++ b/rs/moq-tokio/tests/integration/broadcast.rs @@ -1265,7 +1265,7 @@ async fn rejoin_skips_a_stale_warm_cache(version: &str) { drop(sub); // The front parks the track and cancels upstream, while the publisher moves on. - tokio::time::timeout(TIMEOUT, live.demand().unused()) + tokio::time::timeout(TIMEOUT, crate::unwanted(live.demand())) .await .expect("upstream never canceled") .expect("track open"); @@ -1412,7 +1412,7 @@ async fn rejoin_replays_a_current_warm_cache(version: &str, open: bool) { drop(reading); drop(sub); // The front parks the track and cancels upstream before the next round rejoins. - tokio::time::timeout(TIMEOUT, live.demand().unused()) + tokio::time::timeout(TIMEOUT, crate::unwanted(live.demand())) .await .unwrap_or_else(|_| panic!("{ctx}: upstream never canceled")) .expect("track open"); diff --git a/rs/moq-tokio/tests/integration/main.rs b/rs/moq-tokio/tests/integration/main.rs index 79552d9449e..1da44656090 100644 --- a/rs/moq-tokio/tests/integration/main.rs +++ b/rs/moq-tokio/tests/integration/main.rs @@ -13,3 +13,15 @@ mod stream_code; mod subscription_end_integrity; mod unannounce; mod worker; + +/// Wait until some subscriber wants the track. +async fn wanted(mut demand: moq_net::track::Demand) -> moq_net::Result<()> { + while demand.wanted_changed().await?.is_none() {} + Ok(()) +} + +/// Wait until no subscriber wants the track. +async fn unwanted(mut demand: moq_net::track::Demand) -> moq_net::Result<()> { + while demand.wanted_changed().await?.is_some() {} + Ok(()) +} diff --git a/rs/moq-tokio/tests/integration/subscription_end_integrity.rs b/rs/moq-tokio/tests/integration/subscription_end_integrity.rs index 14e45bae069..761f60cafc2 100644 --- a/rs/moq-tokio/tests/integration/subscription_end_integrity.rs +++ b/rs/moq-tokio/tests/integration/subscription_end_integrity.rs @@ -126,7 +126,7 @@ async fn round(drop_session: bool) -> (usize, Option) { .await .expect("publisher session"); - tokio::time::timeout(TIMEOUT, track.demand().used()) + tokio::time::timeout(TIMEOUT, crate::wanted(track.demand())) .await .expect("no subscriber appeared") .expect("track closed"); diff --git a/rs/moq-tokio/tests/integration/unannounce.rs b/rs/moq-tokio/tests/integration/unannounce.rs index f06bfe88ef3..e40aa15d674 100644 --- a/rs/moq-tokio/tests/integration/unannounce.rs +++ b/rs/moq-tokio/tests/integration/unannounce.rs @@ -14,7 +14,7 @@ async fn release(unannounce: bool, settle: bool) { let track = broadcast.create_track("t", None).unwrap(); let consumer = origin.consume().request_broadcast("a/b", None).await.unwrap(); let sub = consumer.track("t").unwrap().subscribe(None).await.unwrap(); - track.demand().used().await.unwrap(); + crate::wanted(track.demand()).await.unwrap(); if unannounce { broadcast.unannounce(); @@ -25,7 +25,7 @@ async fn release(unannounce: bool, settle: bool) { drop(sub); drop(consumer); - tokio::time::timeout(Duration::from_secs(600), track.demand().unused()) + tokio::time::timeout(Duration::from_secs(600), crate::unwanted(track.demand())) .await .expect("demand released") .unwrap(); diff --git a/rs/moq-transcode/src/lib.rs b/rs/moq-transcode/src/lib.rs index 79b401fd595..15ff49664eb 100644 --- a/rs/moq-transcode/src/lib.rs +++ b/rs/moq-transcode/src/lib.rs @@ -1248,7 +1248,7 @@ mod tests { #[tokio::test] async fn an_idle_rung_leaves_its_source_unused() { let source = source_catalog(320, 240); - let demand = source._track.demand(); + let mut demand = source._track.demand(); let config = Config { ladder: Ladder::new([Rung::new(120, moq_net::bandwidth::Rate::from_bps(100_000))]).unwrap(), @@ -1273,21 +1273,29 @@ mod tests { snapshot.video.renditions.contains_key("video/120p") }) .await; - assert!(!demand.is_used(), "the published ladder holds its source"); + assert_eq!(demand.wanted(), None, "the published ladder holds its source"); // A held query is demand, so the rung starts encoding and subscribes to the // source. let rung = consumer.track("video/120p").unwrap(); let mut query = rung.query(); (&mut query).await.unwrap(); - tokio::time::timeout(std::time::Duration::from_secs(5), demand.used()) + let wanted = async { + while demand.wanted_changed().await?.is_none() {} + moq_net::Result::Ok(()) + }; + tokio::time::timeout(std::time::Duration::from_secs(5), wanted) .await .expect("the rung never asked for its source") .unwrap(); // Its task outlives the viewer, idle until the next one. drop(query); - tokio::time::timeout(std::time::Duration::from_secs(5), demand.unused()) + let unwanted = async { + while demand.wanted_changed().await?.is_some() {} + moq_net::Result::Ok(()) + }; + tokio::time::timeout(std::time::Duration::from_secs(5), unwanted) .await .expect("the idle rung kept its source wanted") .unwrap(); diff --git a/rs/moq-transcode/src/rung.rs b/rs/moq-transcode/src/rung.rs index 513d34094ed..1e0603ddb07 100644 --- a/rs/moq-transcode/src/rung.rs +++ b/rs/moq-transcode/src/rung.rs @@ -163,6 +163,12 @@ pub(crate) async fn serve(rung: Rung, request: moq_net::track::Request) -> Resul result } +/// Wait until some subscriber wants the track, or none does. +async fn until_wanted(demand: &mut moq_net::track::Demand, wanted: bool) -> moq_net::Result<()> { + while demand.wanted_changed().await?.is_some() != wanted {} + Ok(()) +} + /// The live path: wait for demand, attach to the shared decode [`Feed`], and /// resize + encode its frames group for group until demand goes away. The /// heavy lifting (subscription, decode) is shared with every other active rung @@ -171,7 +177,7 @@ pub(crate) async fn serve(rung: Rung, request: moq_net::track::Request) -> Resul /// Reports whether the track is still open rather than finishing it: [`serve`] /// owns that, once the fetches in flight can no longer add a group. async fn live(rung: &Rung, producer: &mut moq_net::track::Producer) -> Result { - let demand = producer.demand(); + let mut demand = producer.demand(); let mut retire = rung.retire.clone(); // Set once the ladder retires this rung. The track is finished at the next // group boundary rather than mid-group, so the last thing a subscriber gets @@ -184,7 +190,7 @@ async fn live(rung: &Rung, producer: &mut moq_net::track::Producer) -> Result if used.is_err() { + wanted = until_wanted(&mut demand, true) => if wanted.is_err() { // The output track closed; nothing more to serve. return Ok(Ended::Closed); }, @@ -219,7 +225,7 @@ async fn live(rung: &Rung, producer: &mut moq_net::track::Producer) -> Result item, - _ = demand.unused() => { + _ = until_wanted(&mut demand, false) => { if let Some(output) = current.take() { // Signal downstream that the group is incomplete. output.abort(moq_net::Error::Cancel)?; diff --git a/rs/moq-video/src/capture/wgc.rs b/rs/moq-video/src/capture/wgc.rs index d381af55686..fd688ef965e 100644 --- a/rs/moq-video/src/capture/wgc.rs +++ b/rs/moq-video/src/capture/wgc.rs @@ -320,7 +320,7 @@ mod tests { .reserve() .with_timeline_hint(config.gop.duration(config.framerate)); let mut producer = Producer::with_track(track, reserved, rendition).unwrap(); - assert!(producer.demand().is_used()); + assert!(producer.demand().wanted().is_some()); // Only one captured picture arrives; more than three intervals of paced // output must still reach a real video subscriber with advancing timestamps. diff --git a/rs/moq-video/src/encode/producer.rs b/rs/moq-video/src/encode/producer.rs index 5a666876ea6..4dfe16333cb 100644 --- a/rs/moq-video/src/encode/producer.rs +++ b/rs/moq-video/src/encode/producer.rs @@ -623,6 +623,14 @@ fn capture_stopped(producer: &mut Producer) -> Result<(), Erro producer.discontinuity() } +/// Wait until some viewer wants the track, or none does. +#[cfg(feature = "capture")] +async fn until_wanted(demand: &moq_net::track::Demand, wanted: bool) -> Result<(), moq_net::Error> { + let mut demand = demand.clone(); + while demand.wanted_changed().await?.is_some() != wanted {} + Ok(()) +} + // Race source setup or an encode against the last viewer leaving, so an unwatched track // stops waiting promptly. #[cfg(feature = "capture")] @@ -632,7 +640,7 @@ async fn wait_capture( ) -> Result, Error> { tokio::select! { biased; - res = demand.unused() => { + res = until_wanted(demand, false) => { if let Err(err) = res { log_track_ended(err); } @@ -672,7 +680,7 @@ async fn capture_loop( // Idle until a viewer subscribes; the track ending is a clean exit. The // catalog rendition was published when the track was created, so a // subscriber can get here without a frame ever having been encoded. - if let Err(err) = demand.used().await { + if let Err(err) = until_wanted(demand, true).await { log_track_ended(err); return Ok(()); } @@ -731,7 +739,7 @@ async fn capture_loop( // unwatched track stops before reading another frame. let frame = tokio::select! { biased; - res = demand.unused() => { + res = until_wanted(demand, false) => { if let Err(err) = res { log_track_ended(err); return Ok(()); diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 9227b0b2d5e..4b995111697 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#REFRESH\_PR) + +`TrackDemand.isUsed`, `used()`, and `unused()` are gone. +`wanted` is nil while nobody subscribes, otherwise the group subscribers want next, and `wantedChanged()` waits for it to change (the first call returns at once). +Loop on `wantedChanged()` until it returns non-nil where you awaited `used()`, and nil where you awaited `unused()`. +`TrackInfo` gains `refresh`. `GroupDemand` is unchanged. + ### Subscriptions carry group ranges (#5732) `Subscription.groupStart` and `groupEnd` are replaced by `ranges`, a list of `Subscription.Range` whose ends are a `Subscription.Anchor` (`.absolute(group:frame:)` or `.relative(groups:)`), and an optional `order`. diff --git a/swift/Sources/Moq/Track.swift b/swift/Sources/Moq/Track.swift index f5883967f14..c4566ba3286 100644 --- a/swift/Sources/Moq/Track.swift +++ b/swift/Sources/Moq/Track.swift @@ -129,19 +129,15 @@ public final class TrackDemand: Sendable { ffi.name() } - /// Whether the track has at least one active consumer right now. - public var isUsed: Bool { - ffi.isUsed() + /// The group subscribers want next, or nil while nobody subscribes. A value past the + /// newest group asks for a new group now, typically a keyframe. + public var wanted: UInt64? { + ffi.wanted() } - /// Suspend until the track has at least one active consumer. - public func used() async throws { - try await ffi.used() - } - - /// Suspend until the track has no active consumers. - public func unused() async throws { - try await ffi.unused() + /// Suspend until `wanted` changes and return it. The first call returns at once. + public func wantedChanged() async throws -> UInt64? { + try await ffi.wantedChanged() } } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 88dd732a0fc..6b440fd0847 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -328,21 +328,21 @@ final class SmokeTests: XCTestCase { let snapshotDemand = try snapshot.demand() let streamDemand = try stream.demand() XCTAssertEqual(snapshotDemand.name, "status") - XCTAssertFalse(snapshotDemand.isUsed) + XCTAssertNil(snapshotDemand.wanted) let consumer = try broadcast.consume() let snapshotConsumer = try Json.SnapshotConsumer<[String: Int]>( track: try await consumer.subscribeTrack(name: "status")) let streamConsumer = try Json.StreamConsumer<[String: Int]>( track: try await consumer.subscribeTrack(name: "events")) - try await snapshotDemand.used() - try await streamDemand.used() - XCTAssertTrue(snapshotDemand.isUsed) + while try await snapshotDemand.wantedChanged() == nil {} + while try await streamDemand.wantedChanged() == nil {} + XCTAssertEqual(snapshotDemand.wanted, 0) snapshotConsumer.cancel() streamConsumer.cancel() - try await snapshotDemand.unused() - try await streamDemand.unused() + while try await snapshotDemand.wantedChanged() != nil {} + while try await streamDemand.wantedChanged() != nil {} try broadcast.close() } diff --git a/test/interop/clients/rust/tail.rs b/test/interop/clients/rust/tail.rs index c7ecc4d0cd6..7aba491c29d 100644 --- a/test/interop/clients/rust/tail.rs +++ b/test/interop/clients/rust/tail.rs @@ -39,7 +39,8 @@ async fn main() -> anyhow::Result<()> { .connect(url) .established() .await?; - track.demand().used().await?; + let mut demand = track.demand(); + while demand.wanted_changed().await?.is_none() {} // Declare the end before the final group's payload is even available. track.finish_at(moq_net::track::Position::group(GROUPS))?; for sequence in 0..GROUPS { From c7a097f4a22110cd5c7c6f1bfcd1452709a4a880 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:53:08 -0700 Subject: [PATCH 03/11] fix: migrate the remaining demand callers and docs to wanted Co-Authored-By: Claude Opus 5.5 --- bench/browser/page/transport.ts | 4 ++-- rs/moq-audio/src/encode/producer.rs | 2 +- rs/moq-net/src/model/origin.rs | 4 ++-- rs/moq-net/src/util.rs | 23 +++++++++---------- rs/moq-net/tests/loom.rs | 2 +- rs/moq-video/src/encode/producer.rs | 2 +- .../clients/js/src/capture.test.ts | 5 +++- test/interop/clients/js-native/tail.ts | 2 +- test/interop/compat/client.ts | 13 +++++++---- test/p2p/src/main.ts | 4 ++-- test/wasm/baseline/publisher.ts | 4 ++-- test/wasm/src/main.ts | 10 ++++---- test/wasm/uniffi/cases.ts | 12 +++++++--- 13 files changed, 49 insertions(+), 38 deletions(-) diff --git a/bench/browser/page/transport.ts b/bench/browser/page/transport.ts index 65bf31e03a5..53f30ffea1a 100644 --- a/bench/browser/page/transport.ts +++ b/bench/browser/page/transport.ts @@ -35,7 +35,7 @@ async function publish(config: Transport): Promise { const producer = origin.createBroadcast(Moq.Path.from(config.path)); // Retention covers the whole run, so a slow consumer cannot lose a group to eviction. const track = producer.createTrack("data", { timescale: Moq.Time.Timescale.MILLI, maxAge: Milli(600_000) }); - const demand = track.demand().used; + const demand = track.demand().wanted; producer.announce(); const connection = await Moq.Connection.connect({ url: new URL(config.url), @@ -50,7 +50,7 @@ async function publish(config: Transport): Promise { origin.close(); }); writer = (async () => { - while (!demand.peek() && track.closed.peek() === undefined) + while (demand.peek() === undefined && track.closed.peek() === undefined) await Promise.race([demand.changed(), track.closed]); if (track.closed.peek() !== undefined) return; for (let start = 0; start < config.frames; start += config.group) { diff --git a/rs/moq-audio/src/encode/producer.rs b/rs/moq-audio/src/encode/producer.rs index f9da91b58b6..471ab8474a7 100644 --- a/rs/moq-audio/src/encode/producer.rs +++ b/rs/moq-audio/src/encode/producer.rs @@ -272,7 +272,7 @@ impl Producer { /// A watch-only handle to the track's subscriber demand, created eagerly so /// subscription state is observable before any frames arrive. Watch it via - /// [`used`](moq_net::track::Demand::used) / [`unused`](moq_net::track::Demand::unused). + /// [`wanted`](moq_net::track::Demand::wanted) / [`wanted_changed`](moq_net::track::Demand::wanted_changed). pub fn demand(&self) -> moq_net::track::Demand { self.track.track().demand() } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 69fccbdb4f9..ae6f2240cd2 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -10714,7 +10714,7 @@ mod tests { } /// An origin front drops the source track as soon as its last reader leaves, - /// so the publisher's `unused()` resolves far below `track::IDLE_LINGER`. + /// so the publisher's demand goes unwanted far below `track::IDLE_LINGER`. /// Cached groups stay on the front for the linger; a returning reader /// replays them and asks the source again for groups past that edge. #[moq_clock::test] @@ -10852,7 +10852,7 @@ mod tests { } /// A front serving from another front still drops upstream on the unused edge, - /// so the publisher's `unused()` resolves far below `track::IDLE_LINGER` through + /// so the publisher's demand goes unwanted far below `track::IDLE_LINGER` through /// the whole chain, and a returning reader reaches the publisher's cache afresh. #[moq_clock::test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/util.rs b/rs/moq-net/src/util.rs index 110a4e1abdb..828c66125c1 100644 --- a/rs/moq-net/src/util.rs +++ b/rs/moq-net/src/util.rs @@ -275,6 +275,17 @@ impl Drop for TaskSet { } } +/// Ready once nothing wants the track, or it closed; otherwise arm `waiter` for a change. +#[cfg(feature = "async")] +pub(crate) fn poll_unwanted(demand: &mut crate::track::Demand, waiter: &kio::Waiter) -> Poll<()> { + // Drain the changes so the waiter stays registered, then read where demand settled. + while let Poll::Ready(Ok(Some(_))) = demand.poll_wanted_changed(waiter) {} + match demand.wanted() { + None => Poll::Ready(()), + Some(_) => Poll::Pending, + } +} + #[cfg(all(test, feature = "async"))] mod tests { use std::sync::{ @@ -330,15 +341,3 @@ mod tests { assert_eq!(output, 42); } } - -/// Ready once nothing wants the track, or it closed; otherwise arm `waiter` for a change. -pub(crate) fn poll_unwanted(demand: &mut crate::track::Demand, waiter: &kio::Waiter) -> Poll<()> { - loop { - match demand.poll_wanted_changed(waiter) { - Poll::Ready(Ok(Some(_))) => continue, - Poll::Ready(_) => return Poll::Ready(()), - Poll::Pending if demand.wanted().is_none() => return Poll::Ready(()), - Poll::Pending => return Poll::Pending, - } - } -} diff --git a/rs/moq-net/tests/loom.rs b/rs/moq-net/tests/loom.rs index 08384e7c970..7467ac28360 100644 --- a/rs/moq-net/tests/loom.rs +++ b/rs/moq-net/tests/loom.rs @@ -176,7 +176,7 @@ fn group_abort_flag_never_leads_the_group_state() { }); } -/// A publisher parked on `Demand::used` drives on-demand capture, so a subscriber +/// A publisher parked on `Demand::wanted_changed` drives on-demand capture, so a subscriber /// appearing on another thread must always wake it. #[test] fn subscriber_wakes_parked_demand() { diff --git a/rs/moq-video/src/encode/producer.rs b/rs/moq-video/src/encode/producer.rs index 4dfe16333cb..274c1ed42f2 100644 --- a/rs/moq-video/src/encode/producer.rs +++ b/rs/moq-video/src/encode/producer.rs @@ -147,7 +147,7 @@ impl Producer { /// A watch-only handle to the track's subscriber demand, created eagerly so /// subscription state is observable before any frames arrive. Watch it via - /// [`used`](moq_net::track::Demand::used) / [`unused`](moq_net::track::Demand::unused). + /// [`wanted`](moq_net::track::Demand::wanted) / [`wanted_changed`](moq_net::track::Demand::wanted_changed). pub fn demand(&self) -> moq_net::track::Demand { match &self.codecs { Codecs::H264 { import, .. } => import.demand(), diff --git a/test/audio-quality/clients/js/src/capture.test.ts b/test/audio-quality/clients/js/src/capture.test.ts index 2b1189134cd..c8580975294 100644 --- a/test/audio-quality/clients/js/src/capture.test.ts +++ b/test/audio-quality/clients/js/src/capture.test.ts @@ -91,7 +91,10 @@ test("the observer shares playback demand and closes without ending playback", a await capture.close(); expect(player.closed.peek()).toBeUndefined(); player.close(); - await track.demand().unused(); + const demand = track.demand(); + while (demand.wanted.peek() !== undefined && demand.closed.peek() === undefined) { + await Signal.race(demand.wanted, demand.closed); + } expect(capture.error()).toBeUndefined(); } finally { await capture.close(); diff --git a/test/interop/clients/js-native/tail.ts b/test/interop/clients/js-native/tail.ts index 9fd958338ef..10377e6edad 100644 --- a/test/interop/clients/js-native/tail.ts +++ b/test/interop/clients/js-native/tail.ts @@ -27,7 +27,7 @@ try { const track = broadcast.createTrack("tail"); broadcast.announce(); const demand = track.demand(); - while (!demand.used.peek()) await demand.used.changed(); + while (demand.wanted.peek() === undefined) await demand.wanted.changed(); // The end precedes the last group's data; the transport still has to drain it. track.finishAt({ group: GROUPS, frame: 0 }); for (let sequence = 0; sequence < GROUPS; sequence++) { diff --git a/test/interop/compat/client.ts b/test/interop/compat/client.ts index f58924c20b4..5c403a5d686 100644 --- a/test/interop/compat/client.ts +++ b/test/interop/compat/client.ts @@ -144,11 +144,14 @@ if (command === "sign") { // Stopped by the harness with SIGTERM: close, so the relay sees a close rather than timing it out. process.once("SIGTERM", () => void connection.close()); console.log("published"); - // `demand()` replaced the producer's own `used` after @moq/net 0.4.2, and this one - // client runs against both packages. - type Used = { peek(): boolean; changed(): Promise }; - const used: Used = "demand" in track ? track.demand().used : (track as unknown as { used: Used }).used; - while (!used.peek()) await used.changed(); + // `demand()` replaced the producer's own `used` after @moq/net 0.4.2, then `wanted` + // replaced `demand().used`, and this one client runs against each package. + type Watch = { peek(): unknown; changed(): Promise }; + const demand = ("demand" in track ? track.demand() : track) as unknown as { used?: Watch; wanted?: Watch }; + const watch = demand.wanted ?? demand.used; + if (!watch) throw new Error("track has no demand"); + const wanted = () => (demand.wanted ? watch.peek() !== undefined : watch.peek() === true); + while (!wanted()) await watch.changed(); const group = track.appendGroup(); group.writeFrame({ payload: new TextEncoder().encode("compat-fetch"), diff --git a/test/p2p/src/main.ts b/test/p2p/src/main.ts index f83fe03e14a..84dea2b2e91 100644 --- a/test/p2p/src/main.ts +++ b/test/p2p/src/main.ts @@ -77,8 +77,8 @@ window.checkTransport = async () => { if (!active) throw new Error("broadcast disappeared"); const subscriber = active.track("data").subscribe().ordered(); try { - const demand = track.demand().used; - while (!demand.peek()) await demand.changed(); + const demand = track.demand().wanted; + while (demand.peek() === undefined) await demand.changed(); const payload = Uint8Array.from({ length: 256 * 1024 }, (_, i) => i % 251); track.writeFrame({ payload, timestamp: Moq.Time.Timestamp.now() }); const frame = await subscriber.readFrame(); diff --git a/test/wasm/baseline/publisher.ts b/test/wasm/baseline/publisher.ts index 4a3819104d1..2a0ade8def1 100644 --- a/test/wasm/baseline/publisher.ts +++ b/test/wasm/baseline/publisher.ts @@ -10,7 +10,7 @@ async function prepare(config: Workload): Promise { const origin = new Moq.Origin.Producer(); const broadcast = origin.createBroadcast(Moq.Path.from(`${config.id}/${index}`)); const track = broadcast.createTrack("data", { timescale: Moq.Time.Timescale.MILLI }); - const demand = track.demand().used; + const demand = track.demand().wanted; broadcast.announce(); const connection = await Moq.Connection.connect({ url: new URL(config.url), @@ -25,7 +25,7 @@ async function prepare(config: Workload): Promise { }); writers.push( (async () => { - while (!demand.peek() && track.closed.peek() === undefined) + while (demand.peek() === undefined && track.closed.peek() === undefined) await Promise.race([demand.changed(), track.closed]); if (track.closed.peek() !== undefined) return; const group = new Moq.Group.Producer(config.sequence); diff --git a/test/wasm/src/main.ts b/test/wasm/src/main.ts index 7a4aa79afaa..6b151dd6cd0 100644 --- a/test/wasm/src/main.ts +++ b/test/wasm/src/main.ts @@ -146,8 +146,8 @@ async function withPublisher( const broadcast = origin.createBroadcast(Moq.Path.from(path)); const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); const missing = broadcast.createTrack("missing"); - const used = track.demand().used; - const missingUsed = missing.demand().used; + const used = track.demand().wanted; + const missingUsed = missing.demand().wanted; broadcast.announce(); const connection = await Moq.Connection.connect({ url: new URL(relay.url), publish: origin.consume() }); @@ -160,7 +160,7 @@ async function withPublisher( }; const writer = (async () => { while (!stopped && track.closed.peek() === undefined) { - if (!used.peek() || wanted === 0) { + if (used.peek() === undefined || wanted === 0) { const advanced = new Promise((resolve) => { wake = resolve; }); @@ -177,10 +177,10 @@ async function withPublisher( track.close(); })(); const rejecting = (async () => { - while (!missingUsed.peek() && missing.closed.peek() === undefined) { + while (missingUsed.peek() === undefined && missing.closed.peek() === undefined) { await Promise.race([missingUsed.changed(), missing.closed]); } - if (missingUsed.peek()) missing.close(new Error("no such track: missing")); + if (missingUsed.peek() !== undefined) missing.close(new Error("no such track: missing")); })(); try { diff --git a/test/wasm/uniffi/cases.ts b/test/wasm/uniffi/cases.ts index 4ac1e21bb02..d6d0c5061ce 100644 --- a/test/wasm/uniffi/cases.ts +++ b/test/wasm/uniffi/cases.ts @@ -165,16 +165,22 @@ const local: Record Promise> = { const track = broadcast.publishTrack("data", TIMED); const demand = track.demand(); const consumer = track.consume(undefined); - await within(demand.used(), 1000, "demand.used"); + const wanted = async () => { + while ((await demand.wantedChanged()) === undefined) {} + }; + const unwanted = async () => { + while ((await demand.wantedChanged()) !== undefined) {} + }; + await within(wanted(), 1000, "demand wanted"); const abort = new AbortController(); const read = consumer.recvGroup({ signal: abort.signal }).catch(() => undefined); // The generated `*Like` return types omit uniffiDestroy; only the class declares it. (consumer as MoqTrackConsumer).uniffiDestroy(); await sleep(20); - const heldByFuture = demand.isUsed(); + const heldByFuture = demand.wanted() !== undefined; abort.abort(); await read; - await within(demand.unused(), 1000, "demand.unused after abort"); + await within(unwanted(), 1000, "demand unwanted after abort"); if (!heldByFuture) throw new Error("demand dropped before the pending future was freed"); return undefined; }, From f206e038ea1f18af4ddc99004a1d22994c9ff3ff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:58:14 -0700 Subject: [PATCH 04/11] docs: link the demand migration to #5930 Co-Authored-By: Claude Opus 5.5 --- dart/moq/MIGRATE.md | 2 +- go/wrapper/MIGRATE.md | 2 +- js/net/MIGRATE.md | 2 +- kt/moq/MIGRATE.md | 2 +- py/moq-rs/MIGRATE.md | 2 +- rs/moq-ffi/MIGRATE.md | 2 +- rs/moq-net/MIGRATE.md | 2 +- swift/MIGRATE.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 2d48666f428..3e11b206f6b 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `TrackDemand.isUsed()`, `used()`, and `unused()` are gone. `wanted()` returns null while nobody subscribes, otherwise the group subscribers want next, and `wantedChanged()` waits for it to change (the first call returns at once). diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index b532b261ec9..3c0be64b9b9 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `TrackDemand.IsUsed`, `Used`, and `Unused` are gone. `Wanted()` returns nil while nobody subscribes, otherwise the group subscribers want next, and `WantedChanged(ctx)` waits for it to change (the first call returns at once). diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 762bed1e04f..674bd1348f5 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `Track.Demand.used` and `unused()` are gone. `demand.wanted` is a `Getter`: `undefined` while nobody subscribes, otherwise the group subscribers want next. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 663e2aab715..b2a8fc92914 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `TrackDemand.isUsed()`, `used()`, and `unused()` are gone. `wanted()` returns null while nobody subscribes, otherwise the group subscribers want next, and `wantedChanged()` waits for it to change (the first call returns at once). diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 4f2e44aea3d..bf5eece07fe 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `TrackDemand.is_used()`, `used()`, and `unused()` are gone. `wanted()` returns `None` while nobody subscribes, otherwise the group subscribers want next, and `await wanted_changed()` waits for it to change (the first call returns at once). diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 7501ead7149..d5e12fd5b3e 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,7 +5,7 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `MoqTrackDemand::is_used`, `used`, and `unused` are gone. `wanted()` returns null while nobody subscribes, otherwise the group subscribers want next, and `wanted_changed()` waits for it to change (the first call returns at once). diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 1c68f9c1987..39762509d81 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `track::Demand::used`, `unused`, `is_used`, `poll_used`, and `poll_unused` are gone. `wanted()` returns `None` while nobody consumes the track and `Some(n)` while consumers want group `n` or later; open a group whenever `n` passes your largest. diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 4b995111697..b6a86e5836b 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,7 +4,7 @@ How to update your code for each breaking change, newest first. ## Unreleased -### Track demand reports the wanted group (#REFRESH\_PR) +### Track demand reports the wanted group (#5930) `TrackDemand.isUsed`, `used()`, and `unused()` are gone. `wanted` is nil while nobody subscribes, otherwise the group subscribers want next, and `wantedChanged()` waits for it to change (the first call returns at once). From be25ffa7295c1e7e615fc75007a3c412c5b99dcf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 09:30:40 -0700 Subject: [PATCH 05/11] feat(moq-c): report the wanted group and accept refresh moq_track_info gains refresh and refresh_present, and moq_publish_demand_wanted reads the group a demand watcher's subscribers want. The on_demand callback now repeats MOQ_DEMAND_USED whenever that group moves. The C++ docs and MIGRATE.md cover the moq-ffi demand change. Co-Authored-By: Claude Opus 5.5 --- cpp/moq/MIGRATE.md | 7 ++++ doc/lib/c/index.md | 1 + doc/lib/cpp/index.md | 2 + rs/moq-c/MIGRATE.md | 12 ++++++ rs/moq-c/README.md | 1 + rs/moq-c/src/api.rs | 46 ++++++++++++++++++--- rs/moq-c/src/publish.rs | 65 ++++++++++++++++------------- rs/moq-c/src/test.rs | 91 +++++++++++++++++++++++++++++++++++++++++ 8 files changed, 190 insertions(+), 35 deletions(-) diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 63ce5456a5b..23b3068755f 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Track demand reports the wanted group (#5930) + +`TrackDemand::is_used`, `used`, and `unused` are gone. +`wanted()` returns `std::nullopt` while nobody subscribes, otherwise the group subscribers want next, and `wanted_changed()` waits for it to change (the first call returns at once). +Loop on `wanted_changed()` until it returns a value where you awaited `used()`, and `std::nullopt` where you awaited `unused()`. +`TrackInfo` gains `refresh`, the ratio past which a joining subscriber asks for a new group. + ### Subscriptions carry group ranges (#5732) `Subscription::group_start` and `group_end` are replaced by `ranges`, a list of `Range` whose ends are an `Anchor` (an absolute group and frame, or a count of groups before the latest), and an optional `order`. diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index f228d34c458..0dda3d7e3ae 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -66,6 +66,7 @@ inside. The header is the reference: each function carries a doc comment. - **Live encoder timing.** After writing a frame you encoded yourself, call `moq_publish_media_flush` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. - **Decoded frames hold decoder buffers.** Free each frame id with `moq_decode_video_frame_free` promptly, or the decoder stalls. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`, and while a session reconnects `moq_session_failure()` returns why, with the reason in `moq_error()`. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. +- **Demand.** A watcher from `moq_publish_track_demand()` (or the media, video, and audio variants) calls back `MOQ_DEMAND_USED` or `MOQ_DEMAND_UNUSED`, again whenever the wanted group moves. `moq_publish_demand_wanted()` reads that group: start a new one once it passes your largest. Set `refresh` in `moq_track_info` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. - **Disabled renditions.** Audio and video convenience decoders reject a catalog configuration with `enabled: false`. Select an enabled rendition from the latest catalog before opening a decoder. ## Reference diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 3447337708c..a22edb1ba12 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -192,6 +192,8 @@ Hold the owned `BandwidthConsumer` returned by `session->recv_bandwidth()` to re ## Track demand +`demand()->wanted()` is the group subscribers want, or `std::nullopt` while nobody subscribes, and `wanted_changed()` waits for it to move: start a new group once it passes your largest. Set `TrackInfo::refresh` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. + Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. ## Stats diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index 83b105d149e..838dc876d99 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,18 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Demand reports the wanted group (#5930) + +`moq_track_info` gains `refresh` and `refresh_present`, which changes its ABI; a zeroed field leaves refresh off. +A demand watcher's `on_demand` now repeats `MOQ_DEMAND_USED` whenever the wanted group moves, so treat it as "read the wanted group" rather than an edge. +Read it with `moq_publish_demand_wanted`, and start a new group (a keyframe) once it passes the largest group written. + +```c +uint64_t group; +bool present; +if (moq_publish_demand_wanted(watcher, &group, &present) == 0 && present && group > largest) start_group(); +``` + ### OpenH264 is a build feature (#5771) The release archives and the CMake build still carry the software H.264 fallback. diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index b4eabd8fff9..1dee9eee174 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -90,6 +90,7 @@ int32_t moq_publish_media_demand(uint32_t media, moq_status_callback on_demand, int32_t moq_encode_video_demand(uint32_t producer, moq_status_callback on_demand, void *user_data); int32_t moq_encode_audio_demand(uint32_t producer, moq_status_callback on_demand, void *user_data); int32_t moq_publish_demand_cancel(uint32_t watcher); +int32_t moq_publish_demand_wanted(uint32_t watcher, uint64_t *group, bool *present); // Publishing: Requests int32_t moq_publish_dynamic(uint32_t broadcast, moq_status_callback on_request, void *user_data); diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 80890cd5231..042f0cf2dcc 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -519,6 +519,12 @@ pub struct moq_track_info { /// Whether `timescale` is set. When false, the default microsecond timescale /// applies, matching the `timestamp_us` units used everywhere else in this ABI. pub timescale_present: bool, + + /// A joining subscriber asks for a new group once the newest group's bytes after its + /// first frame exceed `refresh` times that frame. `0` asks once any frame follows the first. + pub refresh: u32, + /// Whether `refresh` is set. When false, a joining subscriber never asks for a new group. + pub refresh_present: bool, } impl TryFrom<&moq_track_info> for moq_net::track::Info { @@ -536,6 +542,9 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { if info.timescale_present { out = out.with_timescale(moq_net::Timescale::new(info.timescale)?); } + if info.refresh_present { + out = out.with_refresh(info.refresh); + } Ok(out) } } @@ -543,12 +552,13 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { /// Whether a published track has subscribers, as reported by a demand watcher. /// /// The positive values an `on_demand` callback receives; `0` and negative codes are -/// the terminal statuses every callback shares. +/// the terminal statuses every callback shares. [moq_publish_demand_wanted] reads which +/// group the subscribers want. #[repr(C)] #[allow(non_camel_case_types)] #[derive(Clone, Copy, Debug)] pub enum moq_demand { - /// At least one subscriber is active. + /// At least one subscriber is active. Repeats when the wanted group moves. MOQ_DEMAND_USED = 1, /// No subscriber is active. MOQ_DEMAND_UNUSED = 2, @@ -2213,10 +2223,11 @@ pub extern "C" fn moq_publish_media_finish(export: u32) -> i32 { /// Watch whether a media track has subscribers, so an encoder runs only while someone watches. /// /// `on_demand` fires right away with the current [moq_demand] state, again on every -/// change, then exactly once more with a terminal code: `0` (the track ended or the -/// watcher was stopped with [moq_publish_demand_cancel]) or a negative error. After the -/// terminal (`<= 0`) callback, `user_data` is never touched again. Reporting the current -/// state first means a track that went unused before the watcher existed still reports it. +/// change, including a move of the wanted group that [moq_publish_demand_wanted] reads, +/// then exactly once more with a terminal code: `0` (the track ended or the watcher was +/// stopped with [moq_publish_demand_cancel]) or a negative error. After the terminal +/// (`<= 0`) callback, `user_data` is never touched again. Reporting the current state +/// first means a track that went unused before the watcher existed still reports it. /// /// A container handle is refused: it publishes several tracks and has no single demand. /// @@ -2254,6 +2265,29 @@ pub extern "C" fn moq_publish_demand_cancel(watcher: u32) -> i32 { }) } +/// Read the group a demand watcher's subscribers want, typically from its `on_demand` callback. +/// +/// `present` is false while nobody subscribes. Otherwise subscribers want `group` or later: +/// once `group` passes the largest group written, start a new one (a keyframe). `group` +/// never goes back, so once a group reaches it nothing is pending until a joiner asks again. +/// +/// Returns zero on success, or a negative code once the watcher's terminal callback fired. +/// +/// # Safety +/// - `group` and `present` must be valid pointers. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_publish_demand_wanted(watcher: u32, group: *mut u64, present: *mut bool) -> i32 { + ffi::enter(move || { + let watcher = ffi::parse_id(watcher)?; + let group = unsafe { group.as_mut() }.ok_or(Error::InvalidPointer)?; + let present = unsafe { present.as_mut() }.ok_or(Error::InvalidPointer)?; + let wanted = State::lock().publish.demand_wanted(watcher)?; + *group = wanted.unwrap_or(0); + *present = wanted.is_some(); + Ok(()) + }) +} + /// Write a whole chunk of container bytes. /// /// No timestamp: a container carries its tracks' timing itself, and the importer diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index e5cdbb9764e..4b66375bbc0 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -17,6 +17,12 @@ struct TaskEntry { callback: OnStatus, } +/// A demand watcher's task, plus a handle to peek the wanted group from its callback. +struct DemandEntry { + task: TaskEntry, + demand: moq_net::track::Demand, +} + /// A subscriber's request for a track the broadcast has not declared, kept with the /// broadcast it was made on so media can be published onto it under that broadcast's catalog. struct TrackRequest { @@ -98,7 +104,7 @@ pub struct Publish { binary_stream: NonZeroSlab>>, /// Demand watchers. Close signals shutdown; the task delivers a final callback, then removes itself. - demand: NonZeroSlab>, + demand: NonZeroSlab, /// Track and group request handlers. Close drops the handler, so pending requests /// are rejected; the task delivers a final callback, then removes itself. @@ -473,25 +479,28 @@ impl Publish { /// Watch a track's subscriber demand, reporting the current state and every change. /// - /// `on_demand` fires with a [`moq_demand`] value immediately and again on each change, then - /// once with a terminal code: `0` when the track ends or the watcher is closed, negative when - /// the track aborts. Seeding with the current state is what makes a late registration safe: a - /// track that went unused before the watcher existed still reports it. + /// `on_demand` fires with a [`moq_demand`] value immediately and again on each change of the + /// wanted group, then once with a terminal code: `0` when the track ends or the watcher is + /// closed, negative when the track aborts. Seeding with the current state is what makes a late + /// registration safe: a track that went unused before the watcher existed still reports it. pub fn demand(&mut self, demand: moq_net::track::Demand, on_demand: OnStatus) -> Result { let channel = oneshot::channel(); - let id = self.demand.insert(Some(TaskEntry { - close: Some(channel.0), - callback: on_demand, - }))?; + let id = self.demand.insert(DemandEntry { + task: TaskEntry { + close: Some(channel.0), + callback: on_demand, + }, + demand: demand.clone(), + })?; tokio::spawn(async move { let res = crate::ffi::run(Self::run_demand(on_demand, demand, channel.1)).await; // Deliver one final terminal callback (code <= 0), then drop the entry. // Pull it out from under the lock so the callback never runs while held. - let entry = State::lock().publish.demand.remove(id).flatten(); + let entry = State::lock().publish.demand.remove(id); if let Some(entry) = entry { - entry.callback.call(res); + entry.task.callback.call(res); } }); @@ -507,41 +516,39 @@ impl Publish { // watcher closed before its first poll still reports USED or UNUSED before the terminal. // An application dropping its producer ends the watcher; it does not keep the track // alive and reports the close as clean. - let mut used = None; + let mut first = true; loop { - let next = match used { - None => demand.wanted_changed().await, - Some(_) => tokio::select! { + let next = if first { + first = false; + demand.wanted_changed().await + } else { + tokio::select! { biased; _ = &mut close => return Ok(()), res = demand.wanted_changed() => res, - }, + } }; - let next = match next { - Ok(wanted) => wanted.is_some(), + let state = match next { + Ok(Some(_)) => moq_demand::MOQ_DEMAND_USED, + Ok(None) => moq_demand::MOQ_DEMAND_UNUSED, Err(moq_net::Error::Dropped) => return Ok(()), Err(err) => return Err(err.into()), }; - // A join that only moves the wanted group is no edge here. - if used == Some(next) { - continue; - } - used = Some(next); - let state = if next { - moq_demand::MOQ_DEMAND_USED - } else { - moq_demand::MOQ_DEMAND_UNUSED - }; callback.call(state as i32); } } + /// The group a demand watcher's subscribers want right now, until its terminal callback. + pub fn demand_wanted(&self, watcher: Id) -> Result, Error> { + Ok(self.demand.get(watcher).ok_or(Error::NotFound)?.demand.wanted()) + } + /// Stop a demand watcher. The task still delivers its terminal callback. pub fn demand_close(&mut self, watcher: Id) -> Result<(), Error> { self.demand .get_mut(watcher) - .and_then(|entry| entry.as_mut()) .ok_or(Error::NotFound)? + .task .close .take() .ok_or(Error::NotFound)?; diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index ac8de2aea69..3d23cf0796a 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1406,6 +1406,8 @@ fn publish_track_invalid_broadcast() { max_age_present: false, timescale: 0, timescale_present: false, + refresh: 0, + refresh_present: false, }; assert!(unsafe { moq_publish_track(0, name.as_ptr() as *const c_char, name.len(), &info) } < 0); assert!(moq_publish_track_group(9999) < 0); @@ -1435,6 +1437,8 @@ fn publish_track_with_info_rejects_invalid_timescale() { max_age_present: false, timescale: 0, timescale_present: true, + refresh: 0, + refresh_present: false, }; assert!(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) } < 0); @@ -1709,6 +1713,8 @@ fn raw_track_subscription_options_and_update() { max_age_present: true, timescale: 1_000_000, timescale_present: true, + refresh: 0, + refresh_present: false, }; let track = id(unsafe { moq_publish_track(broadcast, track_name.as_ptr() as *const c_char, track_name.len(), &info) }); @@ -2454,6 +2460,91 @@ fn track_demand_follows_subscribers() { assert_eq!(moq_origin_close(origin), 0); } +/// Read a demand watcher's wanted group, or `None` while nobody subscribes. +fn demand_wanted(watcher: u32) -> Option { + let mut group = u64::MAX; + let mut present = true; + assert_eq!( + unsafe { moq_publish_demand_wanted(watcher, &mut group, &mut present) }, + 0 + ); + present.then_some(group) +} + +/// Cancel a raw track subscription, freeing the frames delivered before its terminal. +fn cancel_track(consumer: u32, cb: &Callback) { + assert_eq!(moq_consume_track_cancel(consumer), 0); + loop { + let code = cb.recv(); + if code <= 0 { + assert_eq!(code, 0); + return; + } + assert_eq!(moq_consume_track_frame_free(id(code)), 0); + } +} + +#[test] +fn track_demand_reports_the_wanted_group() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"track-demand-wanted"); + let name = b"data"; + let info = moq_track_info { + priority: 127, + max_age_us: 0, + max_age_present: false, + timescale: 0, + timescale_present: false, + refresh: 0, + refresh_present: true, + }; + let track = id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) }); + + let demand_cb = Callback::new(); + let watcher = id(unsafe { moq_publish_track_demand(track, Some(channel_callback), demand_cb.ptr) }); + assert_eq!(demand_cb.recv(), moq_demand::MOQ_DEMAND_UNUSED as i32); + assert_eq!(demand_wanted(watcher), None); + + // The first subscriber of a track with no group wants group 0. + let consume = consume_local(broadcast); + let first_cb = Callback::new(); + let first = consume_track(consume, name, &first_cb); + assert_eq!(demand_cb.recv(), moq_demand::MOQ_DEMAND_USED as i32); + assert_eq!(demand_wanted(watcher), Some(0)); + + // A delta after the first frame puts the group past a `refresh` of 0. + let group = id(moq_publish_track_group(track)); + for timestamp_us in [0, 1_000] { + assert_eq!( + unsafe { moq_publish_group_frame(group, name.as_ptr(), name.len(), timestamp_us) }, + 0 + ); + } + + // A joiner asks for the next group, and the callback repeats USED to say so. + let second_cb = Callback::new(); + let second = consume_track(consume, name, &second_cb); + assert_eq!(demand_cb.recv(), moq_demand::MOQ_DEMAND_USED as i32); + assert_eq!(demand_wanted(watcher), Some(1)); + + cancel_track(first, &first_cb); + cancel_track(second, &second_cb); + assert_eq!(demand_cb.recv(), moq_demand::MOQ_DEMAND_UNUSED as i32); + assert_eq!(demand_wanted(watcher), None); + + assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(demand_cb.recv_terminal(), 0); + let (mut group, mut present) = (0, false); + assert!( + unsafe { moq_publish_demand_wanted(watcher, &mut group, &mut present) } < 0, + "the watcher is gone after its terminal" + ); + + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + /// A watcher closed before its task is first polled still reports the current state before /// its terminal. The C surface cannot order the close against the runtime thread, so this /// drives the watcher's loop directly with the close already pending. From 53afd7e40785b007b1af334a98ff82e61877d539 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 11:03:07 -0700 Subject: [PATCH 06/11] fix(net): an absolute IETF SUBSCRIBE is no join The provisional subscription a moq-transport SUBSCRIBE subscribes with joined at the live edge, so an absolute filter was judged under the refresh ratio before its fixed start replaced the range. Bound it to the filter first when the filter resolves without the live edge, in Rust and JS. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/publisher.test.ts | 25 +++++++++++++ js/net/src/ietf/publisher.ts | 19 +++++++--- rs/moq-net/src/ietf/publisher.rs | 58 +++++++++++++++++++++++++------ 3 files changed, 87 insertions(+), 15 deletions(-) diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 94bf76e8296..66c4022ada1 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -2216,6 +2216,31 @@ test("draft-20: an absolute filter trims the range it serves", async () => { } }); +/** An absolute filter has a fixed start, so its SUBSCRIBE is no join even over the refresh ratio. */ +test("draft-20: an absolute subscribe is no join", async () => { + const fx = fixture(); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI, refresh: 0 }); + writeGroup(track, 3); + + const { client } = await runSubscribe( + fx, + new Subscribe({ + requestId: 7n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 0, + filter: { kind: "absolute", startGroup: 0n, startObject: 0n }, + }), + ); + + try { + expect(track.demand().wanted.peek()).toBe(0); + } finally { + fx.close(); + client.close(); + } +}); + /** * The draft's own current-group join: a Next Object subscription for the live tail, plus a * StartGroup=1 fill for the head already published. The two must meet exactly, so the head diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 54a049c7ace..251b5555814 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -27,7 +27,7 @@ import * as Path from "../path.ts"; import { Priority } from "../priority.ts"; import { type Stream, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; -import type { Location as TrackLocation, Subscriber as TrackSubscriber } from "../track.ts"; +import type { Groups, Location as TrackLocation, Subscriber as TrackSubscriber } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { Deadline, REQUEST_TIMEOUT_MS, requestOptions } from "../util/deadline.ts"; import { LIMITS, type Limits, Slots } from "../util/limits.ts"; @@ -467,6 +467,9 @@ export class Publisher { const priority = fromWire(msg.subscriberPriority); const order = msg.groupOrder; + // A range that resolves without the live edge has a fixed start, which is no join: + // bound the subscription before subscribing so the refresh ratio never judges it. + const fixed = subscribeRange(msg, {}, version); const track = wireOf(broadcast).subscribe(msg.trackName, { priority, order, @@ -475,6 +478,7 @@ export class Publisher { // Keep the sentinel encodable if this demand crosses a Lite hop before the // producer's retention bound is known. maxDelay: Milli(Varint.MAX_U53), + groups: fixed.start ? rangeGroups(fixed) : undefined, }); let cache: TrackSubscriber | undefined; @@ -527,10 +531,7 @@ export class Publisher { priority, order, maxDelay: Milli(Varint.MAX_U53), - groups: { - start: range.start ? { included: Number(range.start.group) } : undefined, - end: range.end ? { included: Number(range.end.group) } : undefined, - }, + groups: rangeGroups(range), }); const startGroup = range.start ? Number(range.start.group) : hooks.latestSequence(track); if (startGroup !== undefined) track.setGroups({ start: { included: startGroup } }); @@ -2090,6 +2091,14 @@ interface ServeRange { end?: EndLocation; } +/** The model's group bounds for a {@link ServeRange}: an absent start joins at the latest group. */ +function rangeGroups(range: ServeRange): Groups { + return { + start: range.start ? { included: Number(range.start.group) } : undefined, + end: range.end ? { included: Number(range.end.group) } : undefined, + }; +} + /** The slice of one group a subscription's {@link ServeRange} selects. */ interface GroupSlice { /** Objects dropped from the front; also the first written object's absolute id. */ diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index ac7399ca628..12b75af9f9e 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1165,6 +1165,18 @@ where // A NEW_GROUP_REQUEST here asks nothing more: subscribing is itself a join, // which the track's refresh ratio judges. let mut subscription = serving_subscription(msg.subscriber_priority).with_order(order); + // A range that resolves without the live edge has a fixed start, which is no + // join: bound the subscription before subscribing so the ratio never judges it. + // From the start of its group, so a relay's copy holds the group's head for + // its other readers, as a live join would; the resolved range trims below. + let fixed = subscribe_range(&msg, LiveEdge::default(), self.version); + if let Some(start) = fixed.start { + ServeRange { + start: Some(Location { object: 0, ..start }), + ..fixed + } + .apply(&mut subscription); + } // Subscribe before resolving the filter: on a routed broadcast the live edge only // becomes readable once the subscription's demand attaches a route, so the edge @@ -1190,16 +1202,7 @@ where // cover the group with no gap and no overlap. let edge = live_edge(&cache); let range = subscribe_range(&msg, edge, self.version); - subscription.set_bounds( - range.start.map(|start| track::Position { - group: start.group, - frame: start.object, - }), - range.end.and_then(|end| match end.object { - Some(object) => track::Position::after(end.group, object), - None => track::Position::after_group(end.group), - }), - ); + range.apply(&mut subscription); let _ = track.update(subscription); // A Timestamp goes out wherever the draft can declare its units and the track // has them. A subscriber that opted out of this SUBSCRIBE_OK's properties learns @@ -6811,6 +6814,25 @@ mod serve_tests { } } + /// An absolute filter has a fixed start, so its SUBSCRIBE is no join even over the ratio. + #[moq_clock::test] + async fn an_absolute_subscribe_is_no_join() { + let version = Version::Draft22; + let h = serve_track(version, crate::track::Info::timed().with_refresh(1)); + let _group = refresh_group(&h); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let msg = subscribe( + Filter::Absolute { + start: Location { group: 4, object: 0 }, + end: None, + }, + None, + ); + let mut serve = std::pin::pin!(h.publisher.clone().run_subscribe_stream(stream, msg)); + serve_until(serve.as_mut(), "SUBSCRIBE_OK", || !h.log.trail().is_empty()).await; + assert_eq!(h.track.demand().wanted(), Some(0)); + } + /// An update's NEW_GROUP_REQUEST is a join on a track opted in to refresh, answered with /// REQUEST_OK. One naming a group the track holds asks nothing. #[moq_clock::test] @@ -14309,6 +14331,22 @@ struct ServeRange { end: Option, } +impl ServeRange { + /// Bound `subscription` to this range. + fn apply(&self, subscription: &mut Subscription) { + subscription.set_bounds( + self.start.map(|start| track::Position { + group: start.group, + frame: start.object, + }), + self.end.and_then(|end| match end.object { + Some(object) => track::Position::after(end.group, object), + None => track::Position::after_group(end.group), + }), + ); + } +} + /// The slice of one group a subscription's [`ServeRange`] selects. #[derive(Default, Clone, Copy, Debug, PartialEq, Eq)] struct GroupSlice { From ac4e3f864b0424ff832a01398f1c8e3065a814b3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 11:52:56 -0700 Subject: [PATCH 07/11] fix(net): an absolute SUBSCRIBE's NEW_GROUP_REQUEST asks as an update's would A fixed start is no implicit join, so its NEW_GROUP_REQUEST went unheard. Judge it like an update's: past a group the track holds, a join under the refresh ratio. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/publisher.rs | 35 ++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index f832ad6b5f0..fc7664dc201 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1184,8 +1184,8 @@ where }; let order = msg.group_order.to_order(); - // A NEW_GROUP_REQUEST here asks nothing more: subscribing is itself a join, - // which the track's refresh ratio judges. + // A live SUBSCRIBE's NEW_GROUP_REQUEST asks nothing more: subscribing is itself + // a join, which the track's refresh ratio judges. let mut subscription = serving_subscription(msg.subscriber_priority).with_order(order); // A range that resolves without the live edge has a fixed start, which is no // join: bound the subscription before subscribing so the ratio never judges it. @@ -1251,6 +1251,12 @@ where let mut track_serve = TrackServe::new(self.session.clone(), track, request_id, self.version, range, timescale) .ranked(self.priority.clone()); + // A fixed start is no join, so its NEW_GROUP_REQUEST asks as an update's would. + if fixed.start.is_some() + && let Some(value) = msg.new_group + { + track_serve.request_new_group(value); + } // Draft-20 replaced joining FETCH with subscription fills. Older drafts save // the same boundary used by the subscription so the two streams never overlap. @@ -6860,6 +6866,31 @@ mod serve_tests { assert_eq!(h.track.demand().wanted(), Some(0)); } + /// An absolute SUBSCRIBE carrying NEW_GROUP_REQUEST asks as an update would: past a group + /// the track holds, it is a join under the ratio. + #[moq_clock::test] + async fn an_absolute_subscribe_with_a_new_group_request_joins() { + let version = Version::Draft22; + for (value, wanted) in [(0, 5), (5, 5), (4, 0)] { + let h = serve_track(version, crate::track::Info::timed().with_refresh(1)); + let _group = refresh_group(&h); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let msg = ietf::Subscribe { + new_group: Some(value), + ..subscribe( + Filter::Absolute { + start: Location { group: 4, object: 0 }, + end: None, + }, + None, + ) + }; + let mut serve = std::pin::pin!(h.publisher.clone().run_subscribe_stream(stream, msg)); + serve_until(serve.as_mut(), "SUBSCRIBE_OK", || !h.log.trail().is_empty()).await; + assert_eq!(h.track.demand().wanted(), Some(wanted), "{value}"); + } + } + /// An update's NEW_GROUP_REQUEST is a join on a track opted in to refresh, answered with /// REQUEST_OK. One naming a group the track holds asks nothing. #[moq_clock::test] From 1f0fb2376a3dfc72df8d58c1e26a3a7c62a64aa5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 14:57:44 -0700 Subject: [PATCH 08/11] fix(net): a refresh join asks for the next free sequence A datagram past the newest group already took the sequence after it, so asking for latest + 1 named a written sequence and the refresh never fired. Ask for one past max_sequence instead, in Rust and JS. Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 9 +++++++++ js/net/src/track.ts | 9 +++++---- rs/moq-net/src/model/track.rs | 21 +++++++++++++++++---- 3 files changed, 31 insertions(+), 8 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index d607c8ba442..ea1f1e3d7a7 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -134,6 +134,15 @@ test("a join over the refresh ratio wants the group after the newest", () => { } }); +test("a join wants past a datagram after the newest group", () => { + const producer = new TrackProducer("test").accept({ refresh: 1 }); + refreshGroup(producer, 4); + expect(producer.appendDatagram(undefined, enc.encode("dgram"))).toBe(1); + const subscriber = producer.subscribe(); + expect(producer.demand().wanted.peek()).toBe(2); + subscriber.close(); +}); + test("joins coalesce until the wanted group lands", () => { const producer = new TrackProducer("test").accept({ refresh: 1 }); refreshGroup(producer, 4); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index de2ac3eed65..0e6d01b65ff 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -599,7 +599,7 @@ export class Demand { * The group subscribers want: `undefined` while nobody subscribes, otherwise the sequence * the next group should have at least. A publisher opens a group whenever it passes its * largest. The first subscriber of a track with no group wants `0`, and a join judged by - * {@link Info.refresh} wants the group after the newest. It never goes back. Watch it + * {@link Info.refresh} wants the next free sequence. It never goes back. Watch it * (`effect.get` / `.peek()`) to follow demand. */ get wanted(): Getter { @@ -843,14 +843,15 @@ export class Producer { return this.#demand; } - // A subscriber joined at the live edge: ask for a new group when the newest one's bytes - // after its first frame exceed the refresh ratio times the first frame. + // A subscriber joined at the live edge: ask for the next free sequence when the newest + // group's bytes after its first frame exceed the refresh ratio times the first frame. A + // datagram past that group already took the sequence after it. #join(): void { const ratio = this.#state.info.peek()?.refresh; const latest = this.#state.latest; if (ratio === undefined || latest === undefined) return; const group = this.#cached.get(latest)?.group; - if (group && hooks.overRefresh(group, ratio)) this.#want(latest + 1); + if (group && hooks.overRefresh(group, ratio)) this.#want(this.#received); } // Raise the wanted floor, reporting it while anyone subscribes. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 008d32cfe3e..4fcf4ce5365 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -645,8 +645,9 @@ pub(crate) struct FetchOutcome { } impl TrackState { - /// A consumer joined at the live edge: ask for the group after the newest when the - /// newest's bytes after its first frame exceed [`Info::refresh`] times that frame. + /// A consumer joined at the live edge: ask for the next free sequence when the newest + /// group's bytes after its first frame exceed [`Info::refresh`] times that frame. A + /// datagram past that group already took the sequence after it. /// /// Joins while the request is pending ask for the same group, so they coalesce until /// the publisher creates it. A join under the ratio reads the current group and asks @@ -668,9 +669,10 @@ impl TrackState { { return; } + let next = state.edge(); let subscriptions = state.subscriptions.clone(); drop(state); - let mut wakes = subscriptions.lock().want(latest.saturating_add(1)); + let mut wakes = subscriptions.lock().want(next); wakes.wake(); } @@ -3362,7 +3364,7 @@ impl Demand { /// /// A publisher opens a group whenever `n` passes its largest. The first consumer of a /// track with no group asks for `Some(0)`, and a join judged by [`Info::refresh`] - /// asks for the group after the newest. `n` never goes back, so once a group reaches + /// asks for the next free sequence. `n` never goes back, so once a group reaches /// it nothing is pending until another join asks. pub fn wanted(&self) -> Option { if !self.is_used() { @@ -12677,6 +12679,17 @@ mod test { } } + /// A datagram past the newest group took the sequence after it, so a join over the + /// ratio wants the next free one rather than one already written. + #[test] + fn a_join_wants_past_a_later_datagram() { + let mut producer = track_producer("test", Info::default().with_refresh(1)); + refresh_group(&producer, 4); + assert_eq!(producer.append_datagram(None, &b"dgram"[..]).unwrap(), 1); + let _subscriber = producer.subscribe(None); + assert_eq!(producer.demand().wanted(), Some(2)); + } + /// Joins while a request is pending ask for the same group, so the publisher hears it /// once. The group reaching it leaves nothing pending, and only a join over the ratio of /// that group asks again. From b34d0e8da7c15ceb9edee909bd91985246aa4174 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 15:45:43 -0700 Subject: [PATCH 09/11] fix(net): read a pending refresh against the namespace A join stored the next free sequence as a number, so a datagram taking it before the publisher reacted left the ask on a written sequence and the refresh was lost. A join now only marks a refresh pending, and wanted reads it as the namespace's next free sequence until a group lands there. Writes wake the demand watchers while one is pending. Mirrored in JS. Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 16 ++++++++ js/net/src/track.ts | 51 ++++++++++++++++------- rs/moq-net/src/model/track.rs | 61 +++++++++++++++++++++------- rs/moq-net/src/model/track/demand.rs | 52 ++++++++++++++++++++---- 4 files changed, 142 insertions(+), 38 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index ea1f1e3d7a7..e9c1d641b5b 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -143,6 +143,22 @@ test("a join wants past a datagram after the newest group", () => { subscriber.close(); }); +test("a datagram never overtakes a pending refresh", () => { + const producer = new TrackProducer("test").accept({ refresh: 1 }); + refreshGroup(producer, 4); + const subscriber = producer.subscribe(); + expect(producer.demand().wanted.peek()).toBe(1); + + expect(producer.appendDatagram(undefined, enc.encode("dgram"))).toBe(1); + expect(producer.demand().wanted.peek()).toBe(2); + + // Group 2 answers it, and later datagrams ask for nothing. + refreshGroup(producer, 0); + producer.appendDatagram(undefined, enc.encode("dgram")); + expect(producer.demand().wanted.peek()).toBe(2); + subscriber.close(); +}); + test("joins coalesce until the wanted group lands", () => { const producer = new TrackProducer("test").accept({ refresh: 1 }); refreshGroup(producer, 4); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 0e6d01b65ff..ec85e233259 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -599,7 +599,8 @@ export class Demand { * The group subscribers want: `undefined` while nobody subscribes, otherwise the sequence * the next group should have at least. A publisher opens a group whenever it passes its * largest. The first subscriber of a track with no group wants `0`, and a join judged by - * {@link Info.refresh} wants the next free sequence. It never goes back. Watch it + * {@link Info.refresh} wants the next free sequence until a group lands there, so a + * datagram taking it moves the ask past. It never goes back. Watch it * (`effect.get` / `.peek()`) to follow demand. */ get wanted(): Getter { @@ -682,8 +683,12 @@ export class Producer { // The group subscribers want while any is attached, watched through {@link demand}. #wanted = new Signal(undefined); - // The lowest group they want; raised by a join over the refresh ratio, never lowered. + // The lowest group they want while no refresh is pending, never lowered. #floor = 0; + // A join over the refresh ratio asked for a group past every sequence written, and none + // has landed yet. Read against the namespace rather than stored as a number, so a + // datagram taking the next sequence can never leave the ask behind. + #refresh = false; #demand: Demand; #largestSeen?: Location; // The largest group's content may still grow: it has not closed cleanly, and it is not a @@ -843,22 +848,31 @@ export class Producer { return this.#demand; } - // A subscriber joined at the live edge: ask for the next free sequence when the newest - // group's bytes after its first frame exceed the refresh ratio times the first frame. A - // datagram past that group already took the sequence after it. + // A subscriber joined at the live edge: ask for a group past every sequence written when + // the newest group's bytes after its first frame exceed the refresh ratio times the first + // frame. #join(): void { const ratio = this.#state.info.peek()?.refresh; const latest = this.#state.latest; if (ratio === undefined || latest === undefined) return; const group = this.#cached.get(latest)?.group; - if (group && hooks.overRefresh(group, ratio)) this.#want(this.#received); + if (!group || !hooks.overRefresh(group, ratio)) return; + this.#refresh = true; + this.#reportWanted(); } // Raise the wanted floor, reporting it while anyone subscribes. #want(group: number): void { if (group <= this.#floor) return; this.#floor = group; - if (this.#sinks.size > 0) this.#wanted.set(group); + this.#reportWanted(); + } + + // Report the wanted group while anyone subscribes: the namespace's next free sequence + // while a refresh is pending. + #reportWanted(): void { + const wanted = this.#refresh ? Math.max(this.#sequence.next, this.#floor) : this.#floor; + this.#wanted.set(this.#sinks.size > 0 ? wanted : undefined); } // Register a downstream sink: seed its info, replay the retained window, and (while @@ -875,7 +889,7 @@ export class Producer { if (closed === undefined) { if (joinsLive(sink.update.peek())) this.#join(); this.#sinks.add(sink); - this.#wanted.set(this.#floor); + this.#reportWanted(); // Forward subscription updates from the sink's Subscriber to the producer's own // state, which the wire layer (or the serving application) watches. @@ -894,7 +908,7 @@ export class Producer { this.#updateSubscription(); // Update demand: once the last subscriber leaves, the consumer wire (watching // {@link Demand.wanted}) tears the upstream down instead of downloading to nobody. - this.#wanted.set(this.#sinks.size > 0 ? this.#floor : undefined); + this.#reportWanted(); // A closed track leaves a sink's buffered mirrors readable; they age out // with the cache, so a stale consumer can't pin them. if (this.#state.closed.peek() !== undefined) { @@ -1180,7 +1194,7 @@ export class Producer { } this.#cache.push(entry); this.#cached.set(group.sequence, entry); - this.#advance(group.sequence); + this.#advance(group.sequence, true); this.#arrive(group.sequence); this.#state.latest = Math.max(this.#state.latest ?? 0, group.sequence); for (const sink of this.#sinks) this.#mirror(entry, sink); @@ -1198,12 +1212,21 @@ export class Producer { } // Record a written sequence, here and in the name's namespace. It raises the largest too, - // at the head of an empty group, so a later group below it never changes it. - #advance(sequence: number): void { + // at the head of an empty group, so a later group below it never changes it. A group + // (`answers`) at or past the namespace's next free sequence answers a pending refresh; + // anything else written there moves the sequence it asks for. + #advance(sequence: number, answers: boolean): void { + const next = this.#sequence.next; this.#received = Math.max(this.#received, sequence + 1); - this.#sequence.next = Math.max(this.#sequence.next, sequence + 1); + this.#sequence.next = Math.max(next, sequence + 1); this.#advanceLargest({ group: sequence, frame: 0 }); this.#endLargest(); + if (!this.#refresh || sequence < next) return; + if (answers) { + this.#refresh = false; + this.#floor = Math.max(this.#floor, sequence); + } + this.#reportWanted(); } // The sequence the next append takes: one past this producer's own writes. The @@ -1302,7 +1325,7 @@ export class Producer { // Fan a datagram out to every live subscriber, dropping the oldest once the ring is full. // Late subscribers do NOT replay old datagrams (best-effort, unlike the group cache). #publishDatagram(datagram: Datagram): void { - this.#advance(datagram.sequence); + this.#advance(datagram.sequence, false); this.#arrive(datagram.sequence); this.#finishLargest(datagram.sequence); for (const sink of this.#sinks) { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 7a4c09afd56..80d93f543eb 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -645,9 +645,9 @@ pub(crate) struct FetchOutcome { } impl TrackState { - /// A consumer joined at the live edge: ask for the next free sequence when the newest - /// group's bytes after its first frame exceed [`Info::refresh`] times that frame. A - /// datagram past that group already took the sequence after it. + /// A consumer joined at the live edge: ask for a group past every sequence written when + /// the newest group's bytes after its first frame exceed [`Info::refresh`] times that + /// frame. /// /// Joins while the request is pending ask for the same group, so they coalesce until /// the publisher creates it. A join under the ratio reads the current group and asks @@ -669,10 +669,9 @@ impl TrackState { { return; } - let next = state.edge(); let subscriptions = state.subscriptions.clone(); drop(state); - let mut wakes = subscriptions.lock().want(next); + let mut wakes = subscriptions.lock().refresh(); wakes.wake(); } @@ -1475,10 +1474,15 @@ impl TrackState { /// Record a written sequence, here and in the name's shared namespace. It raises the /// largest too, so a later group below it never changes it, even one below a reached end. - fn advance(&mut self, sequence: u64) { + /// + /// `answers` when it is a group subscribers receive, which answers a pending refresh. + fn advance(&mut self, sequence: u64, answers: bool) { self.max_sequence = Some(self.max_sequence.map_or(sequence, |max| max.max(sequence))); + let next = self.sequence.next(); self.sequence.advance(sequence); self.cache.advance_largest(Position::group(sequence)); + let mut wakes = self.subscriptions.lock().wrote(sequence, next, answers); + wakes.wake(); } /// The sequence the next append takes: one past this track's own writes. @@ -1551,7 +1555,7 @@ impl TrackState { self.evict.push_back((sequence, stamp)); } - self.advance(sequence); + self.advance(sequence, visible); // A publisher may re-create a group it cut; the sequence is no longer given up. if visible && self.drops.contains(&sequence) @@ -2366,7 +2370,7 @@ impl Producer { { return Err(Error::Closed); } - state.advance(sequence); + state.advance(sequence, false); state.cache.finish_largest(sequence); meter.datagram(payload.len() as u64); state.push_datagram( @@ -2422,7 +2426,7 @@ impl Producer { if state.final_sequence().is_some_and(|fin| datagram.sequence >= fin) { return Err(Error::Closed); } - state.advance(datagram.sequence); + state.advance(datagram.sequence, false); state.cache.finish_largest(datagram.sequence); meter.datagram(datagram.payload.len() as u64); state.push_datagram(datagram); @@ -3366,14 +3370,15 @@ impl Demand { /// /// A publisher opens a group whenever `n` passes its largest. The first consumer of a /// track with no group asks for `Some(0)`, and a join judged by [`Info::refresh`] - /// asks for the next free sequence. `n` never goes back, so once a group reaches - /// it nothing is pending until another join asks. + /// asks for the next free sequence until a group lands there, so a datagram taking it + /// moves the ask past. `n` never goes back, so once a group reaches it nothing is + /// pending until another join asks. pub fn wanted(&self) -> Option { if !self.is_used() { return None; } - let subscriptions = self.state.read().subscriptions.clone(); - let wanted = subscriptions.lock().wanted(); + let (subscriptions, namespace) = self.subscriptions(); + let wanted = subscriptions.lock().wanted(&namespace); Some(wanted) } @@ -3388,6 +3393,12 @@ impl Demand { kio::wait(|waiter| self.poll_wanted_changed(waiter)).await } + /// The demand aggregate, and the name's sequence namespace a pending refresh reads. + fn subscriptions(&self) -> (kio::Lock, Sequence) { + let state = self.state.read(); + (state.subscriptions.clone(), state.sequence.clone()) + } + /// Poll for [`wanted`](Self::wanted) to differ from what this handle last returned. pub fn poll_wanted_changed(&mut self, waiter: &kio::Waiter) -> Poll>> { let used = match self.poll_state(waiter) { @@ -3395,8 +3406,8 @@ impl Demand { DemandState::Active => true, DemandState::Idle => false, }; - let subscriptions = self.state.read().subscriptions.clone(); - let wanted = subscriptions.lock().poll_wanted(waiter); + let (subscriptions, namespace) = self.subscriptions(); + let wanted = subscriptions.lock().poll_wanted(&namespace, waiter); let next = used.then_some(wanted); if self.prev == Some(next) { return Poll::Pending; @@ -12744,6 +12755,26 @@ mod test { assert_eq!(producer.demand().wanted(), Some(2)); } + /// A datagram taking the sequence a pending refresh asked for moves the ask past it, so + /// it still names a group the publisher has to open. The group landing answers it. + #[test] + fn a_datagram_never_overtakes_a_pending_refresh() { + let mut producer = track_producer("test", Info::default().with_refresh(1)); + let mut demand = producer.demand(); + refresh_group(&producer, 4); + let _subscriber = producer.subscribe(None); + assert_eq!(wanted_changed(&mut demand), Some(Some(1))); + + assert_eq!(producer.append_datagram(None, &b"dgram"[..]).unwrap(), 1); + assert_eq!(wanted_changed(&mut demand), Some(Some(2)), "the datagram took group 1"); + + refresh_group(&producer, 0); + assert_eq!(wanted_changed(&mut demand), None, "group 2 answers it"); + producer.append_datagram(None, &b"dgram"[..]).unwrap(); + assert_eq!(wanted_changed(&mut demand), None, "nothing is pending"); + assert_eq!(demand.wanted(), Some(2)); + } + /// Joins while a request is pending ask for the same group, so the publisher hears it /// once. The group reaching it leaves nothing pending, and only a join over the ratio of /// that group asks again. diff --git a/rs/moq-net/src/model/track/demand.rs b/rs/moq-net/src/model/track/demand.rs index e882719a53a..e1d03c52fbd 100644 --- a/rs/moq-net/src/model/track/demand.rs +++ b/rs/moq-net/src/model/track/demand.rs @@ -1,7 +1,7 @@ //! Incremental demand, separate from the track's cached content. use std::{collections::BTreeMap, sync::Arc, task::Poll, time::Duration}; -use super::{Order, Subscription, TrackState, clamp_combined}; +use super::{Order, Sequence, Subscription, TrackState, clamp_combined}; mod ranges; use ranges::Ranges; @@ -13,9 +13,13 @@ pub(super) struct Subscriptions { max_delay: BTreeMap, ranges: Ranges, descending: usize, - /// The lowest group consumers want: raised past the newest group by a join over the - /// track's refresh ratio, and never lowered. See [`super::Demand::wanted`]. + /// The lowest group consumers want while no refresh is pending, never lowered. See + /// [`super::Demand::wanted`]. wanted: u64, + /// A join over the track's refresh ratio asked for a group past every sequence written, + /// and no such group has landed yet. Read against the namespace rather than stored as a + /// number, so a datagram taking the next sequence can never leave the ask behind. + refresh: bool, waiters: kio::WaiterList, } @@ -63,18 +67,25 @@ impl Subscriptions { } } - /// The lowest group consumers want, whether or not anyone consumes now. - pub(super) fn wanted(&self) -> u64 { - self.wanted + /// The lowest group consumers want, whether or not anyone consumes now: the next free + /// sequence of `namespace` while a refresh is pending. + /// + /// Read under this lock, so a write that moves the namespace after it wakes the waiters + /// armed here (see [`Self::wrote`]). + pub(super) fn wanted(&self, namespace: &Sequence) -> u64 { + match self.refresh { + true => namespace.next().max(self.wanted), + false => self.wanted, + } } /// [`Self::wanted`], arming `waiter` for its next change. - pub(super) fn poll_wanted(&mut self, waiter: &kio::Waiter) -> u64 { + pub(super) fn poll_wanted(&mut self, namespace: &Sequence, waiter: &kio::Waiter) -> u64 { waiter.register(&mut self.waiters); - self.wanted + self.wanted(namespace) } - /// Raise [`Self::wanted`] to `group`, taking the wakes only when it moved. + /// Raise the floor of [`Self::wanted`] to `group`, taking the wakes only when it moved. pub(super) fn want(&mut self, group: u64) -> kio::WaiterList { if group <= self.wanted { return Default::default(); @@ -83,6 +94,29 @@ impl Subscriptions { self.waiters.take() } + /// A join over the refresh ratio: ask for a group past every sequence written. Joins + /// while one is pending coalesce into it. + pub(super) fn refresh(&mut self) -> kio::WaiterList { + if std::mem::replace(&mut self.refresh, true) { + return Default::default(); + } + self.waiters.take() + } + + /// Sequence `sequence` was written at or past `next`, the namespace's next free sequence + /// before it. A group subscribers receive answers a pending refresh; anything else, such + /// as a datagram, moves the sequence it asks for. + pub(super) fn wrote(&mut self, sequence: u64, next: u64, answers: bool) -> kio::WaiterList { + if !self.refresh || sequence < next { + return Default::default(); + } + if answers { + self.refresh = false; + self.wanted = self.wanted.max(sequence); + } + self.waiters.take() + } + /// Mutate counts under one lock, taking wakes only when the aggregate changes. fn replace(&mut self, old: Option<&Subscription>, new: Option<&Subscription>) -> kio::WaiterList { let prev = self.scalars(); From cc9b39f6c7c115c892cd4897ac308332eb7ad5cb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 16:27:58 -0700 Subject: [PATCH 10/11] docs(net): clarify refresh migration notes; time only the join in the refresh bench The JS note says a join asks for a group only over the ratio, and the C snippet starts the first group before any is written. The refresh bench writes each answering group outside the timed section. Co-Authored-By: Claude Opus 5.5 --- js/net/MIGRATE.md | 2 +- rs/moq-c/MIGRATE.md | 4 +++- rs/moq-net/benches/refresh.rs | 32 ++++++++++++++++++++++---------- 3 files changed, 26 insertions(+), 12 deletions(-) diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 393cfd79a6b..3c2bc0e0b6e 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -9,7 +9,7 @@ How to update your code for each breaking change, newest first. `Track.Demand.used` and `unused()` are gone. `demand.wanted` is a `Getter`: `undefined` while nobody subscribes, otherwise the group subscribers want next. Watch it where you watched `used`, comparing against `undefined`, and wait for it to become `undefined` where you awaited `unused()`. -`Track.Info.refresh` opts a track in to new groups on join. +`Track.Info.refresh` opts a track in to new groups on join: a live-edge join asks for one only when the newest group's bytes after its first frame exceed `refresh` times that frame, not on every join. Broadcast and group demand keep `used` and `unused()`. ### An expired group fails with `Old` even when drained (#5944) diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index f73dc7bd893..3f6ece96e60 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -9,11 +9,13 @@ How to update your code for each breaking change, newest first. `moq_track_info` gains `refresh` and `refresh_present`, which changes its ABI; a zeroed field leaves refresh off. A demand watcher's `on_demand` now repeats `MOQ_DEMAND_USED` whenever the wanted group moves, so treat it as "read the wanted group" rather than an edge. Read it with `moq_publish_demand_wanted`, and start a new group (a keyframe) once it passes the largest group written. +Before any group is written, the first subscriber wants group 0, so start one whenever it is present. ```c +// `written` is false until a group is written; `largest` is the largest group written. uint64_t group; bool present; -if (moq_publish_demand_wanted(watcher, &group, &present) == 0 && present && group > largest) start_group(); +if (moq_publish_demand_wanted(watcher, &group, &present) == 0 && present && (!written || group > largest)) start_group(); ``` ### Key logging is opt-in (#5907) diff --git a/rs/moq-net/benches/refresh.rs b/rs/moq-net/benches/refresh.rs index 51043b072e4..ab437136dd9 100644 --- a/rs/moq-net/benches/refresh.rs +++ b/rs/moq-net/benches/refresh.rs @@ -1,10 +1,15 @@ -//! A join judged by the track's refresh ratio, then the group it asked for: swept over -//! tracks and subscribers per track. The judgment reads only the joined track's newest -//! group, so a cost that grows with the other tracks or the joined track's audience -//! shows up as a slope. +//! A join judged by the track's refresh ratio and the demand it raises: swept over tracks +//! and subscribers per track. The judgment reads only the joined track's newest group, so +//! a cost that grows with the other tracks or the joined track's audience shows up as a +//! slope. The group answering each join is written outside the timed section. //! //! Run with `cargo bench -p moq-net --bench refresh`. +// Custom timings measure the real time the work took, not the ambient clock. +#![allow(clippy::disallowed_methods)] + +use std::time::{Duration, Instant}; + use bytes::Bytes; use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; use moq_net::{broadcast, track}; @@ -38,12 +43,19 @@ fn join(c: &mut Criterion) { refreshable(track); let mut latest = 0; group.bench_function(BenchmarkId::new(format!("{tracks}x"), subscribers), |b| { - b.iter(|| { - let joined = track.subscribe(None); - assert_eq!(demand.wanted(), Some(latest + 1)); - drop(joined); - refreshable(track); - latest += 1; + b.iter_custom(|iterations| { + let mut elapsed = Duration::ZERO; + for _ in 0..iterations { + let start = Instant::now(); + let joined = track.subscribe(None); + let wanted = demand.wanted(); + elapsed += start.elapsed(); + assert_eq!(wanted, Some(latest + 1)); + drop(joined); + refreshable(track); + latest += 1; + } + elapsed }) }); } From 73f26f5c50d9c614a6ad746cab9113bdbb7baaeb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 16:47:28 -0700 Subject: [PATCH 11/11] test(net): read JS resume track demand through wanted The resume tests main added watched the removed Track.Demand.used. Co-Authored-By: Claude Opus 5.5 --- js/net/src/resume.test.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 7a02492714e..d09f886cf0c 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -522,7 +522,7 @@ test("a recovery fetch a later route supersedes is abandoned", async () => { stalled.close(new StreamError(StreamCode.SessionClosed)); const read = group.readFrame(); await settle(); - const fetching = tb.producer.demand().used.peek(); + const fetching = tb.producer.demand().wanted.peek() !== undefined; // Another route has it cached: the group continues there, and the fetch from b stops. tc.write(0, 2); @@ -531,7 +531,7 @@ test("a recovery fetch a later route supersedes is abandoned", async () => { sub.close(); await settle(); expect(fetching).toBe(true); - expect(tb.producer.demand().used.peek()).toBe(false); + expect(tb.producer.demand().wanted.peek()).toBeUndefined(); front.consumer.close(); a.close(); @@ -563,13 +563,13 @@ test("a datagram reader lets go of the copies a swap replaced", async () => { copy(b); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); - expect(ta.producer.demand().used.peek()).toBe(true); + expect(ta.producer.demand().wanted.peek()).toBeDefined(); front.serve(b.consume()); await settle(); // A read with nothing to deliver is the pass that lets go of a's copy. void sub.recvDatagram(); await settle(); - expect(ta.producer.demand().used.peek()).toBe(false); + expect(ta.producer.demand().wanted.peek()).toBeUndefined(); sub.close(); front.consumer.close(); @@ -829,7 +829,7 @@ test.each([true, false])( // The serving copy's group bounded the previous route's copy, so the next read lets it go. pending = next(); await settle(); - expect(copies[route - 1].producer.demand().used.peek()).toBe(false); + expect(copies[route - 1].producer.demand().wanted.peek()).toBeUndefined(); } view?.close();