diff --git a/cpp/moq/bench/main.cpp b/cpp/moq/bench/main.cpp index d052bace6a9..eba8d17aca9 100644 --- a/cpp/moq/bench/main.cpp +++ b/cpp/moq/bench/main.cpp @@ -121,7 +121,7 @@ void throughput(Case c, double budget, std::vector &results) readers.push_back(read(c, consumer, payload, n).completion); } for (auto &track : tracks) { - auto group = ok(track->append_group()); + auto group = ok(track->append_group(moq::Timestamp{n * c.frames(), 1000000})); for (int f = 0; f < c.frames(); ++f) ok(group->write_frame({payload, moq::Timestamp{n * c.frames() + f, 1000000}})); ok(group->finish()); @@ -183,7 +183,7 @@ int main() auto broadcast = ok(moq::BroadcastProducer::init()); auto track = ok(broadcast->publish_track("calls", {})); - auto producer = ok(track->append_group()); + auto producer = ok(track->append_group(moq::Timestamp{0, std::nullopt})); auto group = ok(producer->consume()); auto consumer = ok(track->consume({})); auto call = [&](const char *name, auto fn) { diff --git a/dart/moq/bench/ffi.dart b/dart/moq/bench/ffi.dart index c8a930fad1a..33cde27522d 100644 --- a/dart/moq/bench/ffi.dart +++ b/dart/moq/bench/ffi.dart @@ -78,7 +78,9 @@ Future throughput( Future step(int n) async { final readers = [for (final consumer in consumers) read(consumer, n)]; for (final track in tracks) { - final group = track.appendGroup(); + final group = track.appendGroup( + start: Timestamp(value: n * c.frames, scale: 1000000), + ); try { for (var f = 0; f < c.frames; f++) { group.writeFrame( @@ -156,7 +158,7 @@ Future main() async { } final broadcast = BroadcastProducer(); final track = broadcast.publishTrack(name: 'calls', info: null); - final producer = track.appendGroup(); + final producer = track.appendGroup(start: Timestamp.unscaled(0)); final group = producer.consume(); final consumer = track.consume(subscription: null); void call(String name, Object? Function() fn) { diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index edf66189cbd..1cd1739b35c 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -247,7 +247,9 @@ void main() { info: TrackInfo(maxAge: null, timescale: 1000000), ); for (var ms = 0; ms < 3; ms++) { - final group = track.appendGroup(); + final group = track.appendGroup( + start: Duration(milliseconds: ms).toTimestamp(), + ); group.writeFrame( frame: Frame( payload: utf8.encode('x'), @@ -269,7 +271,7 @@ void main() { final group = await consumer.recvGroup().timeout(timeout); starts.add(group!.start()); } - expect(starts, [0, 1, 2]); + expect(starts, [0, 1000, 2000]); broadcast.close(); }, ); @@ -538,7 +540,7 @@ void main() { final demand = track.demand(); while (await demand.wantedChanged().timeout(timeout) == null) {} - final producer = track.appendGroup(); + final producer = track.appendGroup(start: Duration.zero.toTimestamp()); producer.writeFrame( frame: MoqFrame( payload: utf8.encode('dart round trip'), diff --git a/dart/moq_ffi/test/leak_test.dart b/dart/moq_ffi/test/leak_test.dart index b415f69aa23..3d4db659efe 100644 --- a/dart/moq_ffi/test/leak_test.dart +++ b/dart/moq_ffi/test/leak_test.dart @@ -84,7 +84,9 @@ void main() { info: MoqTrackInfo(timescale: 1000000), ); final consumer = track.consume(subscription: null); - final producer = track.appendGroup(); + final producer = track.appendGroup( + start: MoqTimestamp(value: 0, scale: 1000000), + ); producer.writeFrame( frame: MoqFrame( payload: payload, diff --git a/dart/moq_ffi/test/smoke_test.dart b/dart/moq_ffi/test/smoke_test.dart index ad52d65f94f..b358cecadd9 100644 --- a/dart/moq_ffi/test/smoke_test.dart +++ b/dart/moq_ffi/test/smoke_test.dart @@ -20,7 +20,9 @@ void main() { info: null, ); final consumer = track.consume(subscription: null); - final producer = track.appendGroup(); + final producer = track.appendGroup( + start: MoqTimestamp(value: 0, scale: null), + ); final group = await consumer.nextGroup(); producer.abort(errorCode: 404); await expectLater( @@ -52,7 +54,9 @@ void main() { final consumer = track.consume(subscription: null); final nextGroup = consumer.nextGroup(); - final producer = track.appendGroup(); + final producer = track.appendGroup( + start: MoqTimestamp(value: 0, scale: 1000000), + ); producer.writeFrame( frame: MoqFrame( payload: utf8.encode('dart'), diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index fc12d300c9b..e3d3e028144 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -128,7 +128,7 @@ inside. The header is the reference: each function carries a doc comment. - **Discovery.** Announcement captures are always a list of wildcard matches, empty when the filter has no wildcards. - **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` or `moq_route_free()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. -- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write takes one, with `moq_publish_group_start` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, or an out-of-range value, fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write and `moq_publish_track_group` takes one, with `moq_publish_group_start` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, or an out-of-range value, fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. - **Catalog timing.** Each catalog snapshot from `moq_consume_catalog` takes effect at the media timestamp `moq_consume_catalog_timestamp` fills. A zero `delay_us` delivers only the newest catalog; a player that holds each update until its media reaches that time passes its playout delay instead, and receives in order every update it may still need. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index c6e0680865d..7f8b38ec8f4 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -135,7 +135,7 @@ final route = moq.route('live/camera'); // visible at once, under a fresh instan print(route.instance()); final mine = route.broadcast(); final track = mine.publishTrack(name: 'video', info: null); -final group = track.appendGroup(); +final group = track.appendGroup(start: Timestamp.unscaled(0)); group.writeFrame(frame: Frame(payload: bytes, timestamp: Timestamp.unscaled(group.start()))); group.finish(); track.finish(); diff --git a/go/wrapper/errors_test.go b/go/wrapper/errors_test.go index 80c84dfd720..2708d794d18 100644 --- a/go/wrapper/errors_test.go +++ b/go/wrapper/errors_test.go @@ -20,7 +20,7 @@ func TestStreamAbortProtocolDetails(t *testing.T) { if err != nil { t.Fatal(err) } - producer, err := track.AppendGroup() + producer, err := track.AppendGroup(moq.Unscaled(0)) if err != nil { t.Fatal(err) } diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index c637507087f..d1a782ee077 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -717,7 +717,7 @@ func TestFetchGroupAndServeDynamicMiss(t *testing.T) { t.Fatal(err) } - cached, err := track.AppendGroup() + cached, err := track.AppendGroup(ts(0)) if err != nil { t.Fatal(err) } @@ -933,7 +933,7 @@ func TestTrackPublishConsume(t *testing.T) { t.Fatalf("frame = %+v, want payload=hello ts=12345", frame) } - group, err := track.AppendGroup() + group, err := track.AppendGroup(ts(23_456)) if err != nil { t.Fatal(err) } @@ -976,7 +976,7 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) { t.Fatal(err) } for i := range 3 { - group, err := track.AppendGroup() + group, err := track.AppendGroup(ts(uint64(i) * 1000)) if err != nil { t.Fatal(err) } @@ -1010,8 +1010,8 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) { } starts = append(starts, group.Start()) } - if !slices.Equal(starts, []uint64{0, 1, 2}) { - t.Fatalf("starts = %v, want [0 1 2]", starts) + if !slices.Equal(starts, []uint64{0, 1_000, 2_000}) { + t.Fatalf("starts = %v, want [0 1000 2000]", starts) } } @@ -1033,7 +1033,7 @@ func TestReadFrameSkipsEmptyThenPopulatedGroups(t *testing.T) { } defer consumer.Cancel() - empty, err := track.AppendGroup() + empty, err := track.AppendGroup(ts(0)) if err != nil { t.Fatal(err) } @@ -1333,7 +1333,7 @@ func TestRecvGroupCancelKeepsConsumer(t *testing.T) { t.Fatalf("cancelled RecvGroup = %v, want context.Canceled", err) } - group, err := track.AppendGroup() + group, err := track.AppendGroup(moq.Unscaled(0)) if err != nil { t.Fatal(err) } diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 79043b225eb..47851bcac06 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -189,9 +189,11 @@ func (t *TrackProducer) Requests() (*TrackRequests, error) { return &TrackRequests{inner: inner}, nil } -// AppendGroup starts a new group; write frames into it, then Finish. -func (t *TrackProducer) AppendGroup() (*GroupProducer, error) { - inner, err := t.inner.AppendGroup() +// AppendGroup starts the next group at start, converted to the track's timescale +// (on a scale-less track, Unscaled at the group's key); write frames into it, then +// Finish. A start at or before a group the track holds is refused. +func (t *TrackProducer) AppendGroup(start Timestamp) (*GroupProducer, error) { + inner, err := t.inner.AppendGroup(start) if err != nil { return nil, err } diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go index b5363b6a169..18813910430 100644 --- a/go/wrapper/runtime_bench_test.go +++ b/go/wrapper/runtime_bench_test.go @@ -97,7 +97,7 @@ func BenchmarkFFI(b *testing.B) { } b.Run("call/start", func(b *testing.B) { track := benchTrack(b, "calls") - producer, err := track.AppendGroup() + producer, err := track.AppendGroup(moq.Unscaled(0)) if err != nil { b.Fatal(err) } @@ -210,7 +210,7 @@ func benchThroughput(b *testing.B, c benchCase) { }() } for _, track := range tracks { - group, err := track.AppendGroup() + group, err := track.AppendGroup(moq.TimestampFromScale(uint64(n*frames), 1_000_000)) if err != nil { return err } diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 9be04c2f1dd..e1221825b47 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -136,7 +136,7 @@ class SmokeTest { fun `stream abort preserves protocol details`() = runTest { BroadcastProducer().use { broadcast -> val track = broadcast.publishTrack("errors", null) - val producer = track.appendGroup() + val producer = track.appendGroup(Timestamp.unscaled(0uL)) val group = broadcast.consume().fetchGroup("errors", 0uL, FetchGroupOptions()) producer.abort(404u) val error = assertFailsWith { group.readFrame() } @@ -322,7 +322,7 @@ class SmokeTest { "events", TrackInfo(maxAge = java.time.Duration.ZERO, timescale = 1_000_000uL), ) - val group = track.appendGroup() + val group = track.appendGroup(Timestamp(0uL, 1_000_000uL)) group.writeFrame( Frame( payload = "cached".encodeToByteArray(), @@ -360,7 +360,7 @@ class SmokeTest { TrackInfo(maxAge = null, timescale = 1_000_000uL), ) for (ms in 0uL until 3uL) { - val group = track.appendGroup() + val group = track.appendGroup(Timestamp(ms, 1_000uL)) group.writeFrame( Frame(payload = "x".encodeToByteArray(), timestamp = Timestamp(ms, 1_000uL)) ) @@ -379,7 +379,7 @@ class SmokeTest { ) ) val starts = List(3) { checkNotNull(consumer.recvGroup()).start() } - assertEquals(listOf(0uL, 1uL, 2uL), starts) + assertEquals(listOf(0uL, 1_000uL, 2_000uL), starts) } } @@ -417,8 +417,8 @@ class SmokeTest { TrackInfo(maxAge = java.time.Duration.ZERO, timescale = 1_000_000uL), ) val consumer = track.consume(null) - track.appendGroup().finish() - track.appendGroup().finish() + track.appendGroup(Timestamp(0uL, 1_000_000uL)).finish() + track.appendGroup(Timestamp(1_000uL, 1_000_000uL)).finish() track.writeFrame( Frame( payload = "populated".encodeToByteArray(), @@ -831,7 +831,7 @@ class SmokeTest { fun `a flow releases its handle however collection ends`() = runTest { BroadcastProducer().use { broadcast -> val track = broadcast.publishTrack("thrown", null) - track.appendGroup().finish() + track.appendGroup(Timestamp.unscaled(0uL)).finish() // Finished, so a handle left open would read the end instead of failing. track.finish() val consumer = broadcast.consume().subscribeTrack("thrown", null) diff --git a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt index 6e1de08ecdc..bf7b672aca5 100644 --- a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt +++ b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt @@ -59,7 +59,7 @@ class FfiBench { val broadcast = BroadcastProducer() val track = broadcast.publishTrack("calls", null) - val producer = track.appendGroup() + val producer = track.appendGroup(Timestamp.unscaled(0uL)) val group = producer.consume() call("start", results) { group.start() } val consumer = track.consume(null) @@ -118,7 +118,8 @@ class FfiBench { } } tracks.forEach { track -> - track.appendGroup().use { group -> + track.appendGroup(Timestamp((n * case.frames).toULong(), 1_000_000uL)).use { + group -> repeat(case.frames) { f -> group.writeFrame( Frame( diff --git a/py/moq-rs/benches/ffi.py b/py/moq-rs/benches/ffi.py index a2e6e69deae..20aed450a48 100644 --- a/py/moq-rs/benches/ffi.py +++ b/py/moq-rs/benches/ffi.py @@ -81,7 +81,7 @@ async def step(n: int) -> None: # Each consumer reads on its own task while this one writes each group in turn. readers = [asyncio.create_task(read(case, consumer, payload, n)) for consumer in consumers] for track in tracks: - group = track.append_group() + group = track.append_group(moq.Timestamp(n * case.frames, 1_000_000)) for f in range(case.frames): group.write_frame(payload, moq.Timestamp(n * case.frames + f, 1_000_000)) group.finish() @@ -170,7 +170,7 @@ async def main() -> None: await throughput(case, results) track = moq.BroadcastProducer().publish_track("calls") - group = track.append_group().consume() + group = track.append_group(moq.Timestamp.unscaled(0)).consume() call("start", lambda: group.start, results) consumer = track.consume() call("info", consumer.info, results) diff --git a/py/moq-rs/examples/clock.py b/py/moq-rs/examples/clock.py index d251cecf3ce..dc1cdc8ea3b 100644 --- a/py/moq-rs/examples/clock.py +++ b/py/moq-rs/examples/clock.py @@ -25,7 +25,7 @@ async def publish(url: str, broadcast_name: str, track_name: str, insecure: bool while True: now = datetime.now(timezone.utc).replace(microsecond=0) timestamp = moq.Timestamp(int(now.timestamp()), 1) - group = track.append_group() + group = track.append_group(timestamp) group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp) current_minute = now.minute diff --git a/py/moq-rs/examples/serve_clock.py b/py/moq-rs/examples/serve_clock.py index 01e4871700a..0495626d898 100644 --- a/py/moq-rs/examples/serve_clock.py +++ b/py/moq-rs/examples/serve_clock.py @@ -32,7 +32,7 @@ async def run(bind: str, broadcast_name: str, track_name: str, host: str) -> Non while True: now = datetime.now(timezone.utc).replace(microsecond=0) timestamp = moq.Timestamp(int(now.timestamp()), 1) - group = track.append_group() + group = track.append_group(timestamp) group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp) current_minute = now.minute diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 50e3306504c..6aa44cdf31f 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -134,9 +134,14 @@ def requests(self) -> TrackRequests: """Serve fetches for groups that are not currently cached.""" return TrackRequests(self._inner.requests()) - def append_group(self) -> GroupProducer: - """Start a new group; write frames into it, then finish().""" - return GroupProducer(self._inner.append_group()) + def append_group(self, start: Timestamp) -> GroupProducer: + """Start the next group at ``start``; write frames into it, then finish(). + + ``start`` is converted to the track's timescale; on a scale-less track it is + :meth:`Timestamp.unscaled` at the group's key. A start at or before a group the + track holds is refused. + """ + return GroupProducer(self._inner.append_group(start._ffi())) def create_group(self, start: int) -> GroupProducer: """Create a group with an explicit start.""" diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 05766796c4b..9d227be954c 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -625,7 +625,7 @@ async def test_fetch_group_and_serve_dynamic_miss(): track = broadcast.publish_track("events", moq.TrackInfo(timescale=1_000_000)) consumer = broadcast.consume() - cached = track.append_group() + cached = track.append_group(moq.Timestamp(0, 1_000_000)) cached.write_frame(b"cached", moq.Timestamp(0, 1_000_000)) cached.finish() @@ -985,18 +985,14 @@ async def test_dynamic_broadcast_request_can_reject(): await asyncio.wait_for(requesting, timeout=5.0) -def test_raw_append_group_start_increments(): - """append_group hands out monotonically increasing start.""" +def test_raw_append_group_starts_at_its_timestamp(): + """append_group starts the group at its timestamp, in the track's timescale.""" broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("seq") + track = broadcast.publish_track("seq", moq.TrackInfo(timescale=1_000_000)) - starts = [] - for _ in range(5): - group = track.append_group() - starts.append(group.start) - group.finish() - - assert starts == [0, 1, 2, 3, 4] + group = track.append_group(moq.Timestamp(2, 1_000)) + assert group.start == 2_000 + group.finish() def test_raw_group_write_multiple_frames(): @@ -1004,7 +1000,7 @@ def test_raw_group_write_multiple_frames(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("chunks", moq.TrackInfo(timescale=1_000_000)) - group = track.append_group() + group = track.append_group(moq.Timestamp(0, 1_000_000)) for i in range(10): group.write_frame(f"frame-{i}".encode(), moq.Timestamp(i, 1_000_000)) group.finish() @@ -1015,7 +1011,7 @@ def test_raw_group_empty_payload(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("empty") - group = track.append_group() + group = track.append_group(moq.Timestamp.unscaled(0)) group.write_frame(b"", moq.Timestamp.unscaled(group.start)) group.finish() @@ -1023,7 +1019,7 @@ def test_raw_group_empty_payload(): def test_raw_group_write_after_finish_fails(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("t") - group = track.append_group() + group = track.append_group(moq.Timestamp.unscaled(0)) group.finish() with pytest.raises(Exception): @@ -1033,7 +1029,7 @@ def test_raw_group_write_after_finish_fails(): def test_raw_group_abort_after_finish(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("t") - group = track.append_group() + group = track.append_group(moq.Timestamp.unscaled(0)) group.finish() group.abort(409) @@ -1069,7 +1065,7 @@ def test_raw_sparse_groups_and_known_end(): track.finish() with pytest.raises(Exception): - track.append_group() + track.append_group(moq.Timestamp.unscaled(5)) def test_raw_parallel_groups(): @@ -1078,9 +1074,8 @@ def test_raw_parallel_groups(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("parallel", moq.TrackInfo(timescale=1_000_000)) - # Without a start, each append takes the next start past the largest. - g0 = track.append_group() - g1 = track.append_group() + g0 = track.append_group(moq.Timestamp(0, 1_000_000)) + g1 = track.append_group(moq.Timestamp(1, 1_000_000)) assert g0.start == 0 assert g1.start == 1 @@ -1228,7 +1223,7 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): broadcast = moq.BroadcastProducer() track = broadcast.publish_track("backlog", moq.TrackInfo(max_age=None, timescale=1_000_000)) for ms in range(3): - group = track.append_group() + group = track.append_group(moq.Timestamp(ms, 1_000)) group.write_frame(b"x", moq.Timestamp(ms, 1_000)) group.finish() @@ -1244,7 +1239,7 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): group = await asyncio.wait_for(consumer.recv_group(), timeout=5.0) assert group is not None starts.append(group.start) - assert starts == [0, 1, 2] + assert starts == [0, 1_000, 2_000] async def test_time_anchor_starts_at_the_group_containing_it(): @@ -1274,7 +1269,7 @@ async def test_raw_group_producer_consume_direct(): """Consume a single group directly from the group producer.""" broadcast = moq.BroadcastProducer() track = broadcast.publish_track("group-direct") - group = track.append_group() + group = track.append_group(moq.Timestamp.unscaled(0)) group_consumer = group.consume() assert group_consumer.start == group.start @@ -1319,7 +1314,7 @@ async def test_raw_group_start(): sent_starts = [] for i in range(3): - group = raw.append_group() + group = raw.append_group(moq.Timestamp(i, 1_000_000)) sent_starts.append(group.start) group.write_frame(f"msg-{i}".encode(), moq.Timestamp(i, 1_000_000)) group.finish() @@ -1400,17 +1395,17 @@ async def test_container_group_decodes_arrival_order(): track = broadcast.publish_track("audio", moq.TrackInfo(timescale=1_000_000)) consumer = await broadcast.consume().subscribe_track("audio") - first = track.append_group() + first = track.append_group(moq.Timestamp(1, 1_000)) first.write_frame(_legacy(1_000_000, b"a"), moq.Timestamp(1, 1_000)) first_media = await _recv_media(consumer) frame = await asyncio.wait_for(anext(first_media), timeout=5.0) assert (frame.payload, frame.timestamp, frame.keyframe) == (b"a", moq.Timestamp(1_000_000, 1_000_000), True) # A newer group lands while the first is stalled mid-way. - second = track.append_group() + second = track.append_group(moq.Timestamp(2, 1_000)) second.write_frame(_legacy(1_040_000, b"c"), moq.Timestamp(2, 1_000)) second_media = await _recv_media(consumer) - assert second_media.start == 1 + assert second_media.start == 2_000 frame = await asyncio.wait_for(anext(second_media), timeout=5.0) assert (frame.payload, frame.timestamp) == (b"c", moq.Timestamp(1_040_000, 1_000_000)) @@ -1431,14 +1426,14 @@ async def test_container_group_takes_over_an_unread_group(): track = broadcast.publish_track("audio", moq.TrackInfo(timescale=1_000_000)) consumer = await broadcast.consume().subscribe_track("audio") - group = track.append_group() + group = track.append_group(moq.Timestamp(1, 1_000)) group.write_frame(_legacy(1_000_000, b"a"), moq.Timestamp(1, 1_000)) raw = await _recv_raw(consumer) assert await raw.read_frame() is not None with pytest.raises(moq.Error.AlreadyCommitted): moq.media.GroupConsumer(raw, _LEGACY) - group = track.append_group() + group = track.append_group(moq.Timestamp(2, 1_000)) group.write_frame(_legacy(1_020_000, b"b"), moq.Timestamp(2, 1_000)) raw = await _recv_raw(consumer) media = moq.media.GroupConsumer(raw, _LEGACY) @@ -1454,7 +1449,7 @@ async def test_container_group_fails_loudly(): track = broadcast.publish_track("audio", moq.TrackInfo(timescale=1_000_000)) consumer = await broadcast.consume().subscribe_track("audio") - group = track.append_group() + group = track.append_group(moq.Timestamp(1, 1_000)) # A truncated varint timestamp: the 2-byte form with only its first byte. group.write_frame(b"\x40", moq.Timestamp(1, 1_000)) raw = await _recv_raw(consumer) @@ -1479,7 +1474,7 @@ async def test_raw_multi_frame_group(): broadcast_consumer = await consumer.request(announcement.prefix) raw_consumer = await broadcast_consumer.subscribe_track("chunks") - group_producer = raw.append_group() + group_producer = raw.append_group(moq.Timestamp.unscaled(0)) chunks = [b"chunk-0", b"chunk-1", b"chunk-2"] for chunk in chunks: group_producer.write_frame(chunk, moq.Timestamp.unscaled(group_producer.start)) @@ -1526,7 +1521,7 @@ async def test_raw_read_frame_preserves_timestamp(): assert frame.payload == b"ready" assert frame.timestamp == moq.Timestamp(12_345, 1_000_000) - group = track.append_group() + group = track.append_group(moq.Timestamp(23_456, 1_000_000)) group_consumer = group.consume() group.write_frame(b"group", moq.Timestamp(23_456, 1_000_000)) group.finish() @@ -1543,7 +1538,7 @@ async def test_read_frame_skips_remaining_frames_in_group(): track = broadcast.publish_track("mixed", moq.TrackInfo(max_age=None)) consumer = track.consume(moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0)) - group = track.append_group() + group = track.append_group(moq.Timestamp.unscaled(0)) group.write_frame(b"first", moq.Timestamp.unscaled(group.start)) group.write_frame(b"second-ignored", moq.Timestamp.unscaled(group.start)) group.finish() @@ -1579,7 +1574,7 @@ async def test_read_frame_skips_empty_group_on_open_track(): track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) consumer = track.consume() - track.append_group().finish() + track.append_group(moq.Timestamp(0, 1_000_000)).finish() read = asyncio.create_task(consumer.read_frame()) await polled() @@ -1598,8 +1593,8 @@ async def test_read_frame_skips_empty_then_populated_groups(): track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) consumer = track.consume() - track.append_group().finish() - track.append_group().finish() + track.append_group(moq.Timestamp(0, 1_000_000)).finish() + track.append_group(moq.Timestamp(1_000, 1_000_000)).finish() track.write_frame(b"populated", moq.Timestamp(2_000, 1_000_000)) frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) @@ -1614,7 +1609,7 @@ async def test_read_frame_keeps_group_across_cancelled_call(): track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) consumer = track.consume() - group = track.append_group() + group = track.append_group(moq.Timestamp(3_000, 1_000_000)) read = asyncio.create_task(consumer.read_frame()) await polled() assert not read.done() diff --git a/py/moq-rs/tests/test_testing_clock.py b/py/moq-rs/tests/test_testing_clock.py index 587e906d12e..ee2986dc384 100644 --- a/py/moq-rs/tests/test_testing_clock.py +++ b/py/moq-rs/tests/test_testing_clock.py @@ -33,8 +33,8 @@ async def main(): # Group 0 stalls with no frame, so the in-order read waits on it until # group 1 has been out for delay.max: a native timer is pending. - _stalled = track.append_group() - later = track.append_group() + _stalled = track.append_group(moq.Timestamp.unscaled(0)) + later = track.append_group(moq.Timestamp.unscaled(1)) later.write_frame(b"later", moq.Timestamp.unscaled(later.start)) later.finish() pending = asyncio.ensure_future(consumer.read_frame()) diff --git a/quest/m2/time-addressing/bindings.md b/quest/m2/time-addressing/bindings.md deleted file mode 100644 index dcb7207bfe7..00000000000 --- a/quest/m2/time-addressing/bindings.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] Bindings start a group at a given timestamp - -## Goal - -moq-ffi's `MoqTrackProducer::append_group()` and moq-c's `track_group` take a -required `Timestamp` start, the way Rust's `track::Producer::append_group` -does, in every binding, so no binding invents "one past the newest start". - -## Plan - -[moq-dev/moq#8915](https://github.com/moq-dev/moq/pull/8915) renamed every -binding's `sequence` to `start`; this is what it left. Rust's -`track::Producer::append_group` takes a required `Timestamp` start -([moq-dev/moq#8961](https://github.com/moq-dev/moq/pull/8961)), with no -implicit "one past the previous start". moq-ffi's `append_group()` -(`rs/moq-ffi/src/producer.rs`) and moq-c's `track_group` -(`rs/moq-c/src/publish.rs`) still take no start and compute one past the -newest start in the track's timescale, each with a private `next_start`. - -Recommended (kept by the maintainer in #8961): give both a required timestamp -start, the `{value, scale}` record the bindings already pass, in one breaking -release, and drop both `next_start`s. `create_group(start)` already takes an -explicit start, so the choice is whether a binding keeps a start-less -convenience at all. Then update every wrapper (Python, Go, Swift, Kotlin, -Dart, C++), the tests and benches that call `append_group()`, and each -`doc/lib` page, and list the rename in the PR's Impact for each package's -`MIGRATE.md`. Check the group rename once more: a name left behind is a -second breaking release. - -Public API: breaking in every binding. Wire: none. diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 23e60559599..9d813c19bc4 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -124,7 +124,7 @@ int32_t moq_publish_container_finish(uint32_t container); int32_t moq_publish_media_finish(uint32_t media); int32_t moq_publish_media_frame(uint32_t media, const uint8_t *payload, uintptr_t payload_size, moq_timestamp timestamp); int32_t moq_publish_track(uint32_t broadcast, const char *name, uintptr_t name_len, const moq_track_info *info); -int32_t moq_publish_track_group(uint32_t track); +int32_t moq_publish_track_group(uint32_t track, const moq_timestamp *start); int32_t moq_publish_track_frame(uint32_t track, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); int32_t moq_publish_group_frame(uint32_t group, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); int32_t moq_publish_group_start(uint32_t group, uint64_t *dst); diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index f75f8cbb710..5567aad3495 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -3678,18 +3678,25 @@ unsafe fn parse_track_info(info: *const moq_track_info) -> Result i32 { +pub unsafe extern "C" fn moq_publish_track_group(track: u32, start: *const moq_timestamp) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; - State::lock().publish.track_group(track) + let start = unsafe { ffi::parse_timestamp(start)? }; + State::lock().publish.track_group(track, start) }) } @@ -4185,7 +4192,7 @@ pub unsafe extern "C" fn moq_publish_group_frame( /// Read the start of a raw group, which names it within its track. /// /// On a scale-less track this is the key every [moq_publish_group_frame] timestamp carries -/// (unscaled, `has_scale` false), including for a group [moq_publish_track_group] numbered. +/// (unscaled, `has_scale` false). /// /// Returns a zero on success, or a negative code on failure. /// diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 3ab923551d0..3f1aa67cd9e 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -102,17 +102,6 @@ enum Family { Closed, } -/// One past the newest group's start, or 0 on an empty track, in the track's timescale: where a -/// group the caller gave no start for begins, which stands in until every write carries a -/// timestamp. -fn next_start(track: &moq_net::track::Producer) -> moq_net::Result { - let key = track.largest().map_or(0, |largest| largest.group.saturating_add(1)); - match track.info().timescale { - Some(scale) => moq_net::Timestamp::new(key, scale).map_err(|_| moq_net::Error::TimestampMismatch), - None => Ok(moq_net::Timestamp::unscaled(key)), - } -} - /// The track-publishing handles of one broadcast. /// /// Closing the broadcast ends every child still open with `Unroutable` (`Internal` to a @@ -1245,11 +1234,10 @@ impl Publish { } } - /// Append a new group to a raw track, one past the newest group's start, returning a - /// group producer. - pub fn track_group(&mut self, track: Id) -> Result { + /// Append the next group to a raw track, starting at `start`, returning a group producer. + pub fn track_group(&mut self, track: Id, start: moq_net::Timestamp) -> Result { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; - let group = raw.inner.append_group(next_start(&raw.inner)?)?; + let group = raw.inner.append_group(start)?; self.insert_group(group) } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 85e927d7e2d..a41df0e4c0b 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1652,7 +1652,7 @@ fn raw_loc_video_uses_the_declared_catalog_container() { let timestamp_us = 42_000; let payload = b"codec frame"; let loc = moq_loc::encode(timestamp_us, payload).unwrap(); - let group = id(moq_publish_track_group(track)); + let group = id(unsafe { moq_publish_track_group(track, µs(timestamp_us)) }); assert_eq!( unsafe { moq_publish_group_frame(group, loc.as_ptr(), loc.len(), µs(timestamp_us)) }, 0 @@ -2011,7 +2011,7 @@ fn publish_track_invalid_broadcast() { compression: 0, }; assert!(unsafe { moq_publish_track(0, name.as_ptr() as *const c_char, name.len(), &info) } < 0); - assert!(moq_publish_track_group(9999) < 0); + assert!(unsafe { moq_publish_track_group(9999, µs(0)) } < 0); assert!(unsafe { moq_publish_track_frame(9999, name.as_ptr(), name.len(), µs(0)) } < 0); assert!(unsafe { moq_publish_group_frame(9999, name.as_ptr(), name.len(), µs(0)) } < 0); assert!(moq_publish_track_finish(9999) < 0); @@ -2354,8 +2354,19 @@ fn raw_track_publish_consume() { assert!(!frame.keyframe, "raw frames have no keyframe flag"); assert_eq!(moq_consume_track_frame_free(frame_id), 0); - // Multi-frame group via the explicit group API. - let group = id(moq_publish_track_group(track)); + // Multi-frame group via the explicit group API, starting at a time converted to the + // track's microseconds. A start that doesn't move past the last group is refused. + assert!(unsafe { moq_publish_track_group(track, std::ptr::null()) } < 0); + assert!(unsafe { moq_publish_track_group(track, µs(timestamp_us)) } < 0); + let start = moq_timestamp { + value: 20, + scale: 1_000, + has_scale: true, + }; + let group = id(unsafe { moq_publish_track_group(track, &start) }); + let mut key = 0; + assert_eq!(unsafe { moq_publish_group_start(group, &mut key) }, 0); + assert_eq!(key, 20_000); let parts: [(&[u8], u64); 2] = [(b"part-0", 20_000), (b"part-1", 30_000)]; for (part, timestamp_us) in parts { assert_eq!( @@ -2666,7 +2677,7 @@ fn raw_track_and_group_abort_consume_their_handles() { let name = b"aborted"; let track = id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), std::ptr::null()) }); - let group = id(moq_publish_track_group(track)); + let group = id(unsafe { moq_publish_track_group(track, µs(0)) }); assert_eq!(moq_publish_group_abort(group, 409), 0); assert!(moq_publish_group_finish(group) < 0); assert_eq!(moq_publish_track_abort(track, 410), 0); @@ -4634,7 +4645,7 @@ fn track_demand_reports_the_wanted_group() { 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)); + let group = id(unsafe { moq_publish_track_group(track, µs(0)) }); for timestamp_us in [0, 1_000] { assert_eq!( unsafe { moq_publish_group_frame(group, name.as_ptr(), name.len(), µs(timestamp_us)) }, @@ -4800,7 +4811,7 @@ fn track_abort_unwanted_keeps_a_late_reader() { &demand_cb, || moq_publish_track_abort_unwanted(track, 7), || { - let group = id(moq_publish_track_group(track)); + let group = id(unsafe { moq_publish_track_group(track, µs(0)) }); assert_eq!( unsafe { moq_publish_group_frame(group, name.as_ptr(), name.len(), µs(0)) }, 0 diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index 46b4c208530..20b8c3cc493 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -120,8 +120,8 @@ fn socket_round_trip() { // The halves outlive the stream handles. assert_eq!(moq_socket_stream_free(server), 0); - for part in [b"one".as_slice(), b"two"] { - let group = id(moq_publish_track_group(writer)); + for (key, part) in [b"one".as_slice(), b"two"].into_iter().enumerate() { + let group = id(unsafe { moq_publish_track_group(writer, &moq_timestamp::unscaled(key as u64)) }); assert_eq!(write_unscaled(group, part), 0); assert_eq!(moq_publish_group_finish(group), 0); } @@ -147,8 +147,8 @@ fn socket_track_round_trip_and_endpoint_close() { let track = id(moq_socket_stream_writer(client)); let frames = Callback::new(); let _reader = id(unsafe { moq_socket_stream_reader(server, Some(channel_callback), frames.ptr) }); - for part in [b"first".as_slice(), b"later"] { - let group = id(moq_publish_track_group(track)); + for (key, part) in [b"first".as_slice(), b"later"].into_iter().enumerate() { + let group = id(unsafe { moq_publish_track_group(track, &moq_timestamp::unscaled(key as u64)) }); assert_eq!(write_unscaled(group, part), 0); assert_eq!(moq_publish_group_finish(group), 0); } @@ -191,7 +191,7 @@ fn socket_finished_tracks_are_not_kept_by_the_endpoint() { let track = id(moq_socket_stream_writer(client)); let frames = Callback::new(); let _reader = id(unsafe { moq_socket_stream_reader(server, Some(channel_callback), frames.ptr) }); - let group = id(moq_publish_track_group(track)); + let group = id(unsafe { moq_publish_track_group(track, &moq_timestamp::unscaled(0)) }); assert_eq!(write_unscaled(group, &[round]), 0); assert_eq!(moq_publish_group_finish(group), 0); assert_eq!(moq_publish_track_finish(track), 0); @@ -383,7 +383,7 @@ fn group_ready_across_a_broadcast_close() { assert_eq!(moq_publish_track_finish_at(declared, 1), 0); let (open_group, declared_group) = ( - id(moq_publish_track_group(open)), + id(unsafe { moq_publish_track_group(open, µs(0)) }), id(moq_publish_track_group_at(declared, 0)), ); // Unread, so both waits park. @@ -525,10 +525,12 @@ fn session_tokens_and_grants() { let _watcher = id(unsafe { moq_session_grants(client, Some(channel_callback), ending.ptr) }); assert_eq!(moq_grant_free(id(ending.recv())), 0); - assert_eq!(moq_session_close(session), 0); - session_cb.recv_terminal(); + // The client first: closed by its peer before it was healthy, it would end on its own. assert_eq!(moq_session_close(client), 0); client_cb.recv_terminal(); + // Its peer gone, the accepted session ends too, which releases its handle. + session_cb.recv_terminal(); + assert!(moq_session_close(session) < 0); loop { let code = ending.recv(); if code <= 0 { diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index 734accef704..f0258c3b501 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -176,7 +176,12 @@ async fn ffi_round( }) .collect(); for track in tracks { - let group = track.append_group().unwrap(); + let group = track + .append_group(MoqTimestamp { + value: n * case.frames() as u64, + scale: Some(1_000_000), + }) + .unwrap(); for f in 0..case.frames() { let frame = MoqFrame { payload: payload.to_vec(), @@ -280,7 +285,11 @@ async fn rust_ffi() { let broadcast = MoqBroadcastProducer::new().unwrap(); let track = broadcast.publish_track("calls".into(), None).unwrap(); - let group = track.append_group().unwrap().consume().unwrap(); + let group = track + .append_group(MoqTimestamp::unscaled(0)) + .unwrap() + .consume() + .unwrap(); report.call("start", || { black_box(black_box(&group).start()); }); diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index a5fcec58775..be6a21a8e70 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -936,7 +936,7 @@ mod supervision_tests { let route = origin.route("routed".into(), Default::default()).unwrap(); let broadcast = route.broadcast(); let track = broadcast.publish_track("data".into(), None).unwrap(); - let open = track.append_group().unwrap(); + let open = track.append_group(crate::media::MoqTimestamp::unscaled(0)).unwrap(); let consumer = origin.consume().request("routed".into(), None).await.unwrap(); let subscriber = consumer.subscribe_track("data".into(), None).await.unwrap(); let group = subscriber.recv_group().await.unwrap().unwrap(); diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index b726f3cf6be..4b4e395db6b 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -9,7 +9,7 @@ use crate::consumer::{MoqBroadcastConsumer, MoqGroupConsumer, MoqOrder, MoqSubsc use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::{Background, OneShot, Polled}; -use crate::media::MoqFrame; +use crate::media::{MoqFrame, MoqTimestamp}; /// A location within a track, mirroring [`moq_net::track::Position`]. #[derive(Clone, Copy, Debug, PartialEq, Eq, uniffi::Record)] @@ -109,17 +109,6 @@ impl TryFrom for moq_net::track::Info { } } -/// One past the newest group's start, or 0 on an empty track, in the track's timescale: where a -/// group the caller gave no start for begins, which stands in until every write carries a -/// timestamp. -fn next_start(track: &moq_net::track::Producer) -> moq_net::Result { - let key = track.largest().map_or(0, |largest| largest.group.saturating_add(1)); - match track.info().timescale { - Some(scale) => moq_net::Timestamp::new(key, scale).map_err(|_| moq_net::Error::TimestampMismatch), - None => Ok(moq_net::Timestamp::unscaled(key)), - } -} - fn raw_track_info(info: Option) -> Result { info.map(moq_net::track::Info::try_from) .transpose() @@ -855,20 +844,25 @@ impl MoqTrackProducer { Ok(Arc::new(MoqTrackConsumer::new(track, Background::default()))) } - /// Append a new group to the track, one past the newest group's start, returning a - /// producer for writing frames into it. - pub fn append_group(&self) -> Result, MoqError> { + /// Append the next group, starting at `start`, returning a producer for writing frames into it. + /// + /// A timed track converts `start` into its timescale, as [`write_frame`](Self::write_frame) + /// does; a scale-less track takes the [unscaled](MoqTimestamp::unscaled) group key. A start + /// at or before a group the track holds, or one that doesn't match the track, is refused with + /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch). + pub fn append_group(&self, start: MoqTimestamp) -> Result, MoqError> { let _guard = crate::ffi::enter(); + let start: moq_net::Timestamp = start.try_into()?; let mut phase = self.phase.lock().unwrap(); let raw = phase.raw()?; - let group = raw.append_group(next_start(raw)?)?; + let group = raw.append_group(start)?; Ok(Arc::new(MoqGroupProducer::from_inner(group))) } /// Create a group starting at `start`, in the track's timescale, which names it. /// - /// Use this for sparse or replayed tracks. [`append_group`](Self::append_group) - /// remains the convenient live-stream path. + /// Use this for sparse or replayed tracks: unlike [`append_group`](Self::append_group), it + /// declares nothing below it skipped. pub fn create_group(&self, start: u64) -> Result, MoqError> { let _guard = crate::ffi::enter(); let mut phase = self.phase.lock().unwrap(); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index f1bfdd3ff7b..0f250f71db7 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1895,7 +1895,7 @@ async fn json_consumer_takes_an_unread_track() { .subscribe_track("events".into(), None) .await .unwrap(); - track.append_group().unwrap().finish().unwrap(); + track.append_group(MoqTimestamp::unscaled(0)).unwrap().finish().unwrap(); kio::clock::timeout(TIMEOUT, read.recv_group()) .await .expect("timed out waiting for a group") @@ -1961,7 +1961,7 @@ async fn abort_unwanted_keeps_a_late_reader() { // A reader joins after the publisher saw nobody wanted the track. let late = consumer.subscribe_track("events".into(), None).await.unwrap(); assert!(!track.abort_unwanted(7).unwrap()); - track.append_group().unwrap().finish().unwrap(); + track.append_group(MoqTimestamp::unscaled(0)).unwrap().finish().unwrap(); let group = kio::clock::timeout(TIMEOUT, late.recv_group()) .await .expect("timed out waiting for the late reader's group") @@ -1976,7 +1976,10 @@ async fn abort_unwanted_keeps_a_late_reader() { demand.until_unwanted().await.unwrap(); assert!(track.abort_unwanted(7).unwrap()); assert!(matches!(track.abort_unwanted(7), Err(MoqError::Closed))); - assert!(matches!(track.append_group(), Err(MoqError::Closed))); + assert!(matches!( + track.append_group(MoqTimestamp::unscaled(1)), + Err(MoqError::Closed) + )); // The next reader asks the publisher again instead of finding the aborted track. let next = tokio::spawn(async move { consumer.subscribe_track("events".into(), None).await }); @@ -2305,7 +2308,7 @@ async fn raw_untimed_frames_roundtrip() { let frame = consumer.read_frame().await.unwrap().unwrap(); assert_eq!(frame.payload, b"frame"); assert_eq!(frame.timestamp, MoqTimestamp::unscaled(5)); - let group = track.append_group().unwrap(); + let group = track.append_group(MoqTimestamp::unscaled(6)).unwrap(); assert_eq!(group.start(), 6); let reader = group.consume().unwrap(); let mismatched = group.write_frame(MoqFrame { @@ -2334,6 +2337,22 @@ async fn raw_untimed_frames_roundtrip() { track.finish().unwrap(); } +/// `append_group` starts the group at its timestamp, in the track's timescale, and only moving +/// forward. +#[test] +fn append_group_starts_at_its_timestamp() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let track = broadcast.publish_track("timed".into(), Some(timed_info())).unwrap(); + let millis = MoqTimestamp { + value: 2, + scale: Some(1_000), + }; + assert_eq!(track.append_group(millis).unwrap().start(), 2_000); + assert!(track.append_group(us(2_000)).is_err()); + assert!(track.append_group(MoqTimestamp::unscaled(3_000)).is_err()); + assert_eq!(track.append_group(us(2_001)).unwrap().start(), 2_001); +} + /// An explicitly timed raw track refuses unscaled timestamps. #[test] fn raw_timed_writes_need_a_scale() { @@ -2355,7 +2374,7 @@ fn raw_timed_writes_need_a_scale() { ) }; assert!(refused(track.write_frame(untimed()).unwrap_err())); - let group = track.append_group().unwrap(); + let group = track.append_group(us(0)).unwrap(); assert!(refused(group.write_frame(untimed()).unwrap_err())); } @@ -2381,7 +2400,7 @@ async fn raw_frame_timestamps() { assert_eq!(frame.payload, payload); assert_eq!(micros(frame.timestamp), 12_345); - let group = track.append_group().unwrap(); + let group = track.append_group(us(23_456)).unwrap(); let group_consumer = group.consume().unwrap(); let payload = b"group frame".to_vec(); group @@ -2510,7 +2529,7 @@ async fn abort_after_finish_keeps_the_track_handle() { async fn abort_after_finish_reaches_group_consumer() { let broadcast = MoqBroadcastProducer::new().unwrap(); let track = broadcast.publish_track("aborted".into(), Some(timed_info())).unwrap(); - let group = track.append_group().unwrap(); + let group = track.append_group(us(0)).unwrap(); let consumer = group.consume().unwrap(); group @@ -2529,7 +2548,7 @@ async fn abort_after_finish_reaches_group_consumer() { async fn raw_group_abort_reaches_consumer() { let broadcast = MoqBroadcastProducer::new().unwrap(); let track = broadcast.publish_track("aborted".into(), None).unwrap(); - let group = track.append_group().unwrap(); + let group = track.append_group(MoqTimestamp::unscaled(0)).unwrap(); let consumer = group.consume().unwrap(); group.abort(409).unwrap(); @@ -2568,7 +2587,7 @@ async fn dynamic_track_request_can_abort() { async fn fetches_cached_group_without_subscribing() { let broadcast = MoqBroadcastProducer::new().unwrap(); let track = broadcast.publish_track("events".into(), Some(timed_info())).unwrap(); - let group = track.append_group().unwrap(); + let group = track.append_group(us(0)).unwrap(); group .write_frame(MoqFrame { payload: b"first".to_vec(), @@ -5657,7 +5676,7 @@ async fn raw_read_frame_skips_empty_group_on_open_track() { let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); - let empty = track.append_group().unwrap(); + let empty = track.append_group(us(0)).unwrap(); empty.finish().unwrap(); let read = { @@ -5699,8 +5718,8 @@ async fn raw_read_frame_skips_empty_then_populated_groups() { let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); - track.append_group().unwrap().finish().unwrap(); - track.append_group().unwrap().finish().unwrap(); + track.append_group(us(0)).unwrap().finish().unwrap(); + track.append_group(us(1_000)).unwrap().finish().unwrap(); let payload = b"populated".to_vec(); track @@ -5785,7 +5804,7 @@ async fn raw_read_frame_keeps_group_across_cancelled_call() { let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); - let group = track.append_group().unwrap(); + let group = track.append_group(us(3_000)).unwrap(); cancel_parked_read_frame(&consumer, &group).await; let payload = b"kept".to_vec(); @@ -5823,7 +5842,7 @@ async fn raw_read_frame_drops_aborted_pending_group() { let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); - let first = track.append_group().unwrap(); + let first = track.append_group(us(0)).unwrap(); let read = { let consumer = consumer.clone(); tokio::spawn(async move { consumer.read_frame().await }) @@ -5871,7 +5890,7 @@ async fn raw_read_frame_and_next_group_share_the_cursor() { let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let consumer = track.consume(None).unwrap(); - let first = track.append_group().unwrap(); + let first = track.append_group(us(0)).unwrap(); cancel_parked_read_frame(&consumer, &first).await; first .write_frame(MoqFrame { @@ -5920,7 +5939,7 @@ async fn raw_read_frame_terminal_cancel_releases_demand() { .expect("timed out waiting for the subscriber") .unwrap(); - let open = track.append_group().unwrap(); + let open = track.append_group(MoqTimestamp::unscaled(0)).unwrap(); let read = { let consumer = consumer.clone(); spawn_parked(async move { consumer.read_frame().await }).await @@ -8775,7 +8794,7 @@ async fn shutdown_without_waiter_survives_session_disposal() { let remote = await_announced(&subscriber.consume(), "tail").await; let reader = remote.subscribe_track("data".into(), None).await.unwrap(); shutdown_ready(&track, &reader).await; - let group = track.append_group().unwrap(); + let group = track.append_group(us(1)).unwrap(); group .write_frame(MoqFrame { timestamp: us(1), @@ -8884,7 +8903,7 @@ async fn session_pair(version: &str) -> (Arc, Arc, Arc GroupProducer { - GroupProducer(try ffi.appendGroup()) + /// Append the next group at `start`, returning a producer for its frames. `start` is + /// converted to the track's timescale; on a scale-less track it is `Timestamp.unscaled(key)` + /// at the group's key. A start at or before a group the track holds throws. + public func appendGroup(start: Timestamp) throws -> GroupProducer { + GroupProducer(try ffi.appendGroup(start: start)) } /// Create a group with an explicit start. diff --git a/swift/Tests/MoqTests/FfiBench.swift b/swift/Tests/MoqTests/FfiBench.swift index 975dec3ba89..8bfef364b7e 100644 --- a/swift/Tests/MoqTests/FfiBench.swift +++ b/swift/Tests/MoqTests/FfiBench.swift @@ -46,7 +46,7 @@ final class FfiBench: XCTestCase { } let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "calls") - let producer = try track.appendGroup() + let producer = try track.appendGroup(start: .unscaled(0)) let group = try producer.consume() let consumer = try track.consume() func call(_ name: String, _ fn: () throws -> Void) rethrows -> Result { @@ -97,7 +97,7 @@ final class FfiBench: XCTestCase { } } for track in tracks { - let group = try track.appendGroup() + let group = try track.appendGroup(start: Timestamp(value: UInt64(n * c.frames), scale: 1_000_000)) for f in 0.. T: async def exchange(stream: socket.TrackStream) -> None: assert stream.peer == "rust" assert stream.consumer.info().max_age is None - for _ in range(3): - group = stream.producer.append_group() + for key in range(3): + group = stream.producer.append_group(moq.Timestamp.unscaled(key)) for payload in PAYLOADS: - group.write_frame(payload, moq.Timestamp.unscaled(group.start)) + group.write_frame(payload, moq.Timestamp.unscaled(key)) group.finish() stream.producer.finish() received = [(group.start, [frame.payload async for frame in group]) async for group in stream.consumer]