diff --git a/cpp/moq/bench/main.cpp b/cpp/moq/bench/main.cpp index 205575f12b0..d052bace6a9 100644 --- a/cpp/moq/bench/main.cpp +++ b/cpp/moq/bench/main.cpp @@ -196,7 +196,7 @@ int main() } while (seconds(start) < budget); results.push_back({std::string("call/") + name, "ns", seconds(start) * 1e9 / calls}); }; - call("sequence", [&] { group->sequence(); }); + call("start", [&] { group->start(); }); call("info", [&] { (void)consumer->info(); }); std::filesystem::create_directories(out); std::ofstream file(std::filesystem::path(out) / "cpp.json"); diff --git a/dart/moq/bench/ffi.dart b/dart/moq/bench/ffi.dart index 9ceb210d2f1..c8a930fad1a 100644 --- a/dart/moq/bench/ffi.dart +++ b/dart/moq/bench/ffi.dart @@ -175,7 +175,7 @@ Future main() async { }); } - call('sequence', group.sequence); + call('start', group.start); call('info', consumer.info); consumer.dispose(); group.dispose(); diff --git a/dart/moq/lib/media.dart b/dart/moq/lib/media.dart index b2346265b31..88b44493362 100644 --- a/dart/moq/lib/media.dart +++ b/dart/moq/lib/media.dart @@ -105,7 +105,7 @@ typedef AudioRendition = AudioMoqRendition; /// A catalog rendition and live delivery options. typedef TrackConfig = MoqMediaTrackConfig; -/// A catalog rendition's group sequence and fetch delivery options. +/// A catalog rendition's group start and fetch delivery options. typedef GroupConfig = MoqMediaGroupConfig; /// The packaging advertised for a media track. diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 297ca657cbc..16b599c9243 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -136,7 +136,7 @@ typedef TrackRequests = MoqTrackRequests; /// A watch-only handle to whether a published track has subscribers; holding it keeps nothing open. typedef TrackDemand = MoqTrackDemand; -/// The read side of a raw track: yields groups in sequence order, skipping ahead if it falls behind. +/// The read side of a raw track: yields groups in start order, skipping ahead if it falls behind. typedef TrackConsumer = MoqTrackConsumer; /// A run of groups readers miss: accept each group you have and drop the rest. @@ -211,10 +211,10 @@ typedef Anchor = MoqAnchor; /// Which pending group the publisher sends first. typedef Order = MoqOrder; -/// A location within a track: a group sequence and a frame index in it. +/// A location within a track: a group start and a frame index in it. typedef Position = MoqPosition; -/// Options for fetching one past group by sequence. +/// Options for fetching one past group by start. typedef FetchGroupOptions = MoqFetchGroupOptions; /// How a track's frames are compressed on the wire: `Compression.deflate()`, or null in diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index f7f90692a65..edf66189cbd 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -264,12 +264,12 @@ void main() { order: Order.ascending, ), ); - final sequences = []; + final starts = []; for (var i = 0; i < 3; i++) { final group = await consumer.recvGroup().timeout(timeout); - sequences.add(group!.sequence()); + starts.add(group!.start()); } - expect(sequences, [0, 1, 2]); + expect(starts, [0, 1, 2]); broadcast.close(); }, ); diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 0625844c8ac..90185eb6d29 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -87,9 +87,9 @@ keeps it across `moq_route_withdraw()` and `moq_route_announce()`, so a restarte being a new route, is a new stream that `moq_origin_follow` hands viewers instead of a stalled broadcast; the path stays `MOQ_ANNOUNCE_KIND_PRESENT` throughout. The follow callback reports each instance as `MOQ_FOLLOW_EVENT_ONLINE` with its handle, -`MOQ_FOLLOW_EVENT_OFFLINE` when the path goes offline, and one `MOQ_FOLLOW_EVENT_END`. Set `instance` only for a publisher that continues its group sequences +`MOQ_FOLLOW_EVENT_OFFLINE` when the path goes offline, and one `MOQ_FOLLOW_EVENT_END`. Set `instance` only for a publisher that continues its group starts across restarts, and raise `epoch` on each: readers stitch every route of one instance -together, so restarting the sequences under an old instance splices unrelated groups into +together, so restarting the starts under an old instance splices unrelated groups into their tracks. To serve paths on demand, `moq_origin_claim()` returns a claim handle and delivers each request to answer with `moq_broadcast_request_serve()`, `moq_broadcast_request_route()`, or `moq_broadcast_request_reject()`; `moq_claim_announce()`, `moq_claim_withdraw()`, @@ -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_sequence` 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 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`. - **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. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. A decoder setup refusal reports `MOQ_ERROR_UNSUPPORTED_CONFIG` on its terminal callback, so the caller can try another rendition; later peer or decode failures retain their own error codes. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 7f08f5f6d98..c6e0680865d 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -136,7 +136,7 @@ print(route.instance()); final mine = route.broadcast(); final track = mine.publishTrack(name: 'video', info: null); final group = track.appendGroup(); -group.writeFrame(frame: Frame(payload: bytes, timestamp: Timestamp.unscaled(group.sequence()))); +group.writeFrame(frame: Frame(payload: bytes, timestamp: Timestamp.unscaled(group.start()))); group.finish(); track.finish(); mine.close(); // ends the route too diff --git a/doc/lib/index.md b/doc/lib/index.md index 93e1132ee3c..67e976a144b 100644 --- a/doc/lib/index.md +++ b/doc/lib/index.md @@ -71,13 +71,13 @@ how it looks in that language: - **Publish and subscribe to media** with the hang catalog filled in from the bitstream, or hand over raw pixels and PCM and let the binding encode and decode (VideoToolbox, Media Foundation, NVENC, openh264, Opus). The built-in video encoder can follow the connection's send estimate. The audio decoder reports the playout delay to buffer ahead of the playhead, fixed or estimated from arrivals, so read each frame as soon as the last is handled rather than pacing reads to the speaker. - **Raw stream tracks** of arbitrary bytes, with per-subscriber priority and max delay, and separate live datagram tracks without groups or caching. - **JSON tracks** as a latest value with merge-patch deltas, an append log, or a sliding window of records. Each value reads back with its frame timestamp, and a snapshot reader either replays every state or skips to the newest. -- **Fetch** a single cached group by sequence. +- **Fetch** a single cached group by start. - **Catalog extensions**: write your own section next to `video` and `audio`, and read others' back. - **Routes**: see which relays a broadcast came through, and advertise a cost as a standby publisher. - **Connection stats** and **errors** that tell an auth rejection (don't retry) from a shutdown or a transport failure. - **Authorization in band**: read the grant the relay sent back (the patterns this side may publish and subscribe to, and when it lapses), and present a fresh token before the current one expires, without reconnecting. It needs `moq-lite-07-wip`, which is opt-in. -C cannot fetch a single group by sequence. +C cannot fetch a single group by start. ## Upgrading diff --git a/doc/lib/layers.md b/doc/lib/layers.md index 1df69ed3d04..d57d49f0f58 100644 --- a/doc/lib/layers.md +++ b/doc/lib/layers.md @@ -43,8 +43,8 @@ Sessions, origins, broadcasts, tracks, and groups: `Client`, `Server`, | C | `moq_session_*`, `moq_origin_*`, `moq_publish_track_*`, `moq_consume_track_*` | `moq_publish_track` | On-demand broadcast requests in every binding can answer with held content -without announcing an exact route. The answer uses the claim's -continuous sequence space at that path. Use a fresh publication for a job +without announcing an exact route. The answer continues the claim's +group starts at that path. Use a fresh publication for a job that may restart independently; see [work on demand](/concept/identity#work-on-demand) and the [Go](/lib/go/) and [C](/lib/c/) binding references. diff --git a/go/wrapper/errors.go b/go/wrapper/errors.go index f3db68681d9..1db2a306427 100644 --- a/go/wrapper/errors.go +++ b/go/wrapper/errors.go @@ -77,7 +77,7 @@ var ( ErrUnsupported = ffi.ErrMoqErrorUnsupported // ErrUnsupportedConfig is returned when media setup refuses a rendition or decoder output. ErrUnsupportedConfig = ffi.ErrMoqErrorUnsupportedConfig - // ErrAlreadyCommitted is returned when a track already reading one way (arrival order, sequence order, or a typed reader) is asked to read another; subscribe again for a second cursor. + // ErrAlreadyCommitted is returned when a track already reading one way (arrival order, start order, or a typed reader) is asked to read another; subscribe again for a second cursor. ErrAlreadyCommitted = ffi.ErrMoqErrorAlreadyCommitted // ErrInvalidInstance is returned when an instance is empty. ErrInvalidInstance = ffi.ErrMoqErrorInvalidInstance diff --git a/go/wrapper/media/media.go b/go/wrapper/media/media.go index 40d5633ba98..dc7c91c36d7 100644 --- a/go/wrapper/media/media.go +++ b/go/wrapper/media/media.go @@ -287,7 +287,7 @@ func NewTrackConsumer(ctx context.Context, broadcast *moq.BroadcastConsumer, con // GroupConfig names a catalog rendition's group and fetch delivery options. type GroupConfig struct { Rendition Rendition - Sequence uint64 + Start uint64 Options *moq.FetchGroupOptions } @@ -301,7 +301,7 @@ func FetchGroup(ctx context.Context, broadcast *moq.BroadcastConsumer, config Gr return nil, err } } - inner, err := ffi.MoqMediaGroupConsumerFetch(ctx, bridge.BroadcastConsumer(broadcast), ffi.MoqMediaGroupConfig{Rendition: config.Rendition, Sequence: config.Sequence, Options: config.Options}) + inner, err := ffi.MoqMediaGroupConsumerFetch(ctx, bridge.BroadcastConsumer(broadcast), ffi.MoqMediaGroupConfig{Rendition: config.Rendition, Start: config.Start, Options: config.Options}) if err != nil { return nil, err } @@ -443,12 +443,12 @@ func (m *TrackProducer) Cut() error { return m.inner.Cut() } -// Seek draws a group boundary and numbers the next group sequence. +// Seek draws a group boundary and starts the next group at start. // -// Cut with an explicit sequence, for a publisher whose group numbers have to be +// Cut with an explicit start, for a publisher whose group starts have to be // deterministic: two encoders aligning per GOP so a consumer can fail over between them. -func (m *TrackProducer) Seek(sequence uint64) error { - return m.inner.Seek(sequence) +func (m *TrackProducer) Seek(start uint64) error { + return m.inner.Seek(start) } // AbortUnwanted closes the track with an application error code, but only while @@ -491,9 +491,9 @@ func (c *ContainerProducer) Cut() error { return c.inner.Cut() } -// Seek starts a new segment and numbers its groups sequence. -func (c *ContainerProducer) Seek(sequence uint64) error { - return c.inner.Seek(sequence) +// Seek starts a new segment and starts its groups at start. +func (c *ContainerProducer) Seek(start uint64) error { + return c.inner.Seek(start) } // Finish finishes every track this container publishes. @@ -613,9 +613,9 @@ type GroupConsumer struct { inner *ffi.MoqMediaGroupConsumer } -// Sequence is this group's sequence number within the track. -func (m *GroupConsumer) Sequence() uint64 { - return m.inner.Sequence() +// Start is this group's start within the track. +func (m *GroupConsumer) Start() uint64 { + return m.inner.Start() } // Next returns the next decoded frame, or (nil, nil) when the group ends. diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index f58f986cbde..c637507087f 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -999,7 +999,7 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) { } defer consumer.Cancel() - var sequences []uint64 + var starts []uint64 for range 3 { group, err := consumer.RecvGroup(ctx) if err != nil { @@ -1008,10 +1008,10 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) { if group == nil { t.Fatal("expected a group") } - sequences = append(sequences, group.Sequence()) + starts = append(starts, group.Start()) } - if !slices.Equal(sequences, []uint64{0, 1, 2}) { - t.Fatalf("sequences = %v, want [0 1 2]", sequences) + if !slices.Equal(starts, []uint64{0, 1, 2}) { + t.Fatalf("starts = %v, want [0 1 2]", starts) } } @@ -1066,8 +1066,8 @@ func TestTrackSparseGroupsAndKnownEnd(t *testing.T) { if err != nil { t.Fatal(err) } - if group.Sequence() != 2 { - t.Fatalf("sequence = %d, want 2", group.Sequence()) + if group.Start() != 2 { + t.Fatalf("start = %d, want 2", group.Start()) } if err := group.Finish(); err != nil { t.Fatal(err) @@ -1083,7 +1083,7 @@ func TestTrackSparseGroupsAndKnownEnd(t *testing.T) { t.Fatal(err) } if _, err := track.CreateGroup(5); err == nil { - t.Fatal("expected group at final sequence to fail") + t.Fatal("expected group at final start to fail") } if err := track.Finish(); err != nil { t.Fatal(err) @@ -1343,8 +1343,8 @@ func TestRecvGroupCancelKeepsConsumer(t *testing.T) { if err != nil { t.Fatalf("RecvGroup after cancel = %v", err) } - if got == nil || got.Sequence() != group.Sequence() { - t.Fatalf("RecvGroup after cancel = %v, want group %d", got, group.Sequence()) + if got == nil || got.Start() != group.Start() { + t.Fatalf("RecvGroup after cancel = %v, want group %d", got, group.Start()) } } diff --git a/go/wrapper/origin.go b/go/wrapper/origin.go index 6fdb7d8f3e8..1f9f36b642d 100644 --- a/go/wrapper/origin.go +++ b/go/wrapper/origin.go @@ -44,9 +44,9 @@ type RouteOptions struct { // Cost is the static production cost: lower wins among routes covering the same prefix. Cost uint64 // Instance is a stable stream to serve, or nil to mint a fresh one. Set it only for a - // publisher that continues its group sequences across restarts and raises Epoch on each, + // publisher that continues its group starts across restarts and raises Epoch on each, // or to forward an announced route's stream as is: readers stitch every route of one - // instance together, so restarting the sequences under an old instance splices unrelated + // instance together, so restarting the starts under an old instance splices unrelated // groups into their tracks. Instance *Instance // Epoch is which run of a stable Instance this is: only the highest is eligible. Ignored without one. @@ -256,7 +256,7 @@ func (r *BroadcastRequest) Route(options RouteOptions) (*Route, error) { return newRoute(inner), nil } -// Serve answers with held content under the claim's continuous sequence space, +// Serve answers with held content under the claim's continuous group starts, // without announcing an exact route. The broadcast remains the caller's to release. func (r *BroadcastRequest) Serve(broadcast *BroadcastConsumer) error { return r.inner.Serve(broadcast.inner) diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 3e528c15ca2..79043b225eb 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -198,9 +198,9 @@ func (t *TrackProducer) AppendGroup() (*GroupProducer, error) { return &GroupProducer{inner: inner}, nil } -// CreateGroup creates a group with an explicit sequence number. -func (t *TrackProducer) CreateGroup(sequence uint64) (*GroupProducer, error) { - inner, err := t.inner.CreateGroup(sequence) +// CreateGroup creates a group with an explicit start. +func (t *TrackProducer) CreateGroup(start uint64) (*GroupProducer, error) { + inner, err := t.inner.CreateGroup(start) if err != nil { return nil, err } @@ -258,10 +258,10 @@ func (t *TrackProducer) Finish() error { return t.inner.Finish() } -// FinishAt declares the exclusive final group sequence ahead of the live edge. +// FinishAt declares the exclusive final group start ahead of the live edge. // The producer remains open for groups below the boundary. -func (t *TrackProducer) FinishAt(finalSequence uint64) error { - return t.inner.FinishAt(finalSequence) +func (t *TrackProducer) FinishAt(finalStart uint64) error { + return t.inner.FinishAt(finalStart) } // GroupProducer writes frames into a single group on a track. @@ -269,9 +269,9 @@ type GroupProducer struct { inner *ffi.MoqGroupProducer } -// Sequence is this group's sequence number within the track. -func (g *GroupProducer) Sequence() uint64 { - return g.inner.Sequence() +// Start is this group's start within the track. +func (g *GroupProducer) Start() uint64 { + return g.inner.Start() } // Consume reads frames from this group. @@ -295,7 +295,7 @@ func (g *GroupProducer) Ready(ctx context.Context, size uint64) error { // WriteFrame appends frame to the group. It never blocks: without Ready, a writer // that outpaces its readers sheds the front of the group instead. On a scale-less track -// the frame's timestamp is Unscaled at this group's Sequence. +// the frame's timestamp is Unscaled at this group's Start. func (g *GroupProducer) WriteFrame(frame Frame) error { return g.inner.WriteFrame(frame) } @@ -388,10 +388,10 @@ func (f *Fill) WantedChanged(ctx context.Context) (*uint64, error) { return f.inner.WantedChanged(ctx) } -// Accept inserts group sequence and returns a producer for it. The first group +// Accept inserts group start and returns a producer for it. The first group // starts at Start's frame, so its frames keep their indices. -func (f *Fill) Accept(sequence uint64) (*GroupProducer, error) { - inner, err := f.inner.Accept(sequence) +func (f *Fill) Accept(start uint64) (*GroupProducer, error) { + inner, err := f.inner.Accept(start) if err != nil { return nil, err } @@ -403,14 +403,14 @@ func (f *Fill) DropGroups(start, end uint64) { f.inner.DropGroups(start, end) } -// IsWanted reports whether a reader still waits for group sequence from this fill: +// IsWanted reports whether a reader still waits for group start from this fill: // false once every reader took it or narrowed past it, or nobody waits on the fill. -func (f *Fill) IsWanted(sequence uint64) bool { - return f.inner.IsWanted(sequence) +func (f *Fill) IsWanted(start uint64) bool { + return f.inner.IsWanted(start) } -// Unwanted blocks until no reader waits for group sequence from this fill, so stop +// Unwanted blocks until no reader waits for group start from this fill, so stop // serving it. -func (f *Fill) Unwanted(ctx context.Context, sequence uint64) error { - return f.inner.Unwanted(ctx, sequence) +func (f *Fill) Unwanted(ctx context.Context, start uint64) error { + return f.inner.Unwanted(ctx, start) } diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go index 708628e67b7..b5363b6a169 100644 --- a/go/wrapper/runtime_bench_test.go +++ b/go/wrapper/runtime_bench_test.go @@ -95,7 +95,7 @@ func BenchmarkFFI(b *testing.B) { for _, c := range benchCases { b.Run("throughput/"+c.name(), func(b *testing.B) { benchThroughput(b, c) }) } - b.Run("call/sequence", func(b *testing.B) { + b.Run("call/start", func(b *testing.B) { track := benchTrack(b, "calls") producer, err := track.AppendGroup() if err != nil { @@ -106,7 +106,7 @@ func BenchmarkFFI(b *testing.B) { b.Fatal(err) } b.Cleanup(group.Cancel) - benchCall(b, func() { group.Sequence() }) + benchCall(b, func() { group.Start() }) }) b.Run("call/info", func(b *testing.B) { consumer, err := benchTrack(b, "calls").Consume(nil) diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index 95dc964acbc..ce7ea95ff6c 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -37,12 +37,12 @@ func (b *BroadcastConsumer) SubscribeTrack( return &TrackConsumer{inner: inner}, nil } -// FetchGroup fetches one complete group by track name and group sequence +// FetchGroup fetches one complete group by track name and group start // without holding a live subscription. func (b *BroadcastConsumer) FetchGroup( ctx context.Context, name string, - sequence uint64, + start uint64, options *FetchGroupOptions, ) (*GroupConsumer, error) { if options != nil { @@ -50,7 +50,7 @@ func (b *BroadcastConsumer) FetchGroup( return nil, err } } - inner, err := b.inner.FetchGroup(ctx, name, sequence, options) + inner, err := b.inner.FetchGroup(ctx, name, start, options) if err != nil { return nil, err } @@ -85,9 +85,9 @@ type GroupConsumer struct { inner *ffi.MoqGroupConsumer } -// Sequence is this group's sequence number within the track. -func (g *GroupConsumer) Sequence() uint64 { - return g.inner.Sequence() +// Start is this group's start within the track. +func (g *GroupConsumer) Start() uint64 { + return g.inner.Start() } // ReadFrame returns the next raw frame, or (nil, nil) when the group ends. @@ -111,16 +111,16 @@ type TrackConsumer struct { inner *ffi.MoqTrackConsumer } -// RecvGroup returns the next group in arrival order (possibly out of sequence), +// RecvGroup returns the next group in arrival order (possibly out of start order), // or (nil, nil) when the track ends. Prefer this for live, latency-sensitive // consumption. func (t *TrackConsumer) RecvGroup(ctx context.Context) (*GroupConsumer, error) { return t.group(ctx, t.inner.RecvGroup) } -// NextGroup returns the next group in sequence order, skipping forward if +// NextGroup returns the next group in start order, skipping forward if // behind, or (nil, nil) when the track ends. Prefer this when order matters -// more than latency. Shares the sequence cursor with ReadFrame: a group one +// more than latency. Shares the ordered cursor with ReadFrame: a group one // method has already taken is not returned by the other. func (t *TrackConsumer) NextGroup(ctx context.Context) (*GroupConsumer, error) { return t.group(ctx, t.inner.NextGroup) @@ -162,13 +162,13 @@ func (t *TrackConsumer) Update(subscription Subscription) error { return t.inner.Update(sub) } -// Groups ranges over groups in sequence order. +// Groups ranges over groups in start order. func (t *TrackConsumer) Groups(ctx context.Context) iter.Seq2[*GroupConsumer, error] { return bridge.Seq(ctx, t.inner.Cancel, t.NextGroup) } // GroupsAsArrived ranges over groups in arrival order, including -// out-of-sequence deliveries. +// out-of-order deliveries. func (t *TrackConsumer) GroupsAsArrived(ctx context.Context) iter.Seq2[*GroupConsumer, error] { return bridge.Seq(ctx, t.inner.Cancel, t.RecvGroup) } diff --git a/go/wrapper/types.go b/go/wrapper/types.go index 27003c5b850..c284d6067c1 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -77,7 +77,7 @@ type ( // DeflateCompression, and compare a received one by Name; a new compression joins as a // new builder. Compression = ffi.MoqCompression - // Position is a location within a track: a group sequence and a frame index in it. + // Position is a location within a track: a group start and a frame index in it. Position = ffi.MoqPosition // VideoCodec selects the video encoder codec. Build one with H264VideoCodec or // H265VideoCodec; adding a codec later adds a constructor, not a breaking enum change. @@ -159,7 +159,7 @@ func NamedEncoder(name string) VideoEncoderKind { // Order values: which pending group the publisher sends first. const ( - // OrderAscending sends the oldest first, draining a backlog in sequence order. + // OrderAscending sends the oldest first, draining a backlog in start order. OrderAscending = ffi.MoqOrderAscending // OrderDescending sends the newest first, so congestion sheds the backlog rather than the live edge. OrderDescending = ffi.MoqOrderDescending diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 4d05a749cf2..badf6becf54 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -161,7 +161,7 @@ typealias TrackRequests = uniffi.moq.MoqTrackRequests typealias TrackDemand = uniffi.moq.MoqTrackDemand /** - * The read side of a raw track: yields groups in sequence order, skipping ahead if it falls behind. + * The read side of a raw track: yields groups in start order, skipping ahead if it falls behind. */ typealias TrackConsumer = uniffi.moq.MoqTrackConsumer @@ -258,10 +258,10 @@ typealias AnchorTime = uniffi.moq.MoqAnchor.Time /** Which pending group the publisher sends first: `ASCENDING` or `DESCENDING`. */ typealias Order = uniffi.moq.MoqOrder -/** A location within a track: a group sequence and a frame index in it. */ +/** A location within a track: a group start and a frame index in it. */ typealias Position = uniffi.moq.MoqPosition -/** Options for fetching one past group by sequence. */ +/** Options for fetching one past group by start. */ typealias FetchGroupOptions = uniffi.moq.MoqFetchGroupOptions /** Delivery settings for a raw track: priority, ordering, latency budget, and timescale. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt index 8eed7ff40ff..31799212952 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Flows.kt @@ -23,10 +23,10 @@ fun dev.moq.video.Consumer.reads(): Flow = pull({ cancel() } /** Stream of encoded media frames, gaps, and encoder ends in delivery order. */ fun dev.moq.media.TrackConsumer.reads(): Flow = pull({ cancel() }) { next() } -/** Stream of groups in sequence order, skipping forward if the reader falls behind. */ +/** Stream of groups in start order, skipping forward if the reader falls behind. */ fun TrackConsumer.groups(): Flow = pull({ cancel() }) { nextGroup() } -/** Stream of groups in arrival order, including out-of-sequence deliveries. */ +/** Stream of groups in arrival order, including out-of-order deliveries. */ fun TrackConsumer.groupsAsArrived(): Flow = pull({ cancel() }) { recvGroup() } /** diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt index 588a7025220..587de3d4437 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt @@ -121,7 +121,7 @@ typealias AudioRendition = uniffi.moq.MoqRendition.Audio /** A catalog rendition and live delivery options. */ typealias TrackConfig = uniffi.moq.MoqMediaTrackConfig -/** A catalog rendition's group sequence and fetch delivery options. */ +/** A catalog rendition's group start and fetch delivery options. */ typealias GroupConfig = uniffi.moq.MoqMediaGroupConfig /** The packaging advertised for a media track. */ diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index f5ce70cd318..9be04c2f1dd 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -339,7 +339,7 @@ class SmokeTest { 0uL, FetchGroupOptions(priority = 3), ) - assertEquals(0uL, fetched.sequence()) + assertEquals(0uL, fetched.start()) assertEquals("cached", fetched.readFrame()?.payload?.decodeToString()) assertNull(fetched.readFrame()) } @@ -378,8 +378,8 @@ class SmokeTest { order = Order.ASCENDING, ) ) - val sequences = List(3) { checkNotNull(consumer.recvGroup()).sequence() } - assertEquals(listOf(0uL, 1uL, 2uL), sequences) + val starts = List(3) { checkNotNull(consumer.recvGroup()).start() } + assertEquals(listOf(0uL, 1uL, 2uL), starts) } } @@ -532,7 +532,7 @@ class SmokeTest { consumer, dev.moq.media.GroupConfig( rendition = dev.moq.media.AudioRendition(name, audio), - sequence = 5_000_000uL, + start = 5_000_000uL, options = FetchGroupOptions(priority = 3), ), ) @@ -541,7 +541,7 @@ class SmokeTest { media.finish() fetched.use { - assertEquals(5_000_000uL, it.sequence()) + assertEquals(5_000_000uL, it.start()) val frames = it.frames().toList() assertEquals(1, frames.size) val frame = frames.single() diff --git a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt index 00f275afd6b..6e1de08ecdc 100644 --- a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt +++ b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt @@ -61,7 +61,7 @@ class FfiBench { val track = broadcast.publishTrack("calls", null) val producer = track.appendGroup() val group = producer.consume() - call("sequence", results) { group.sequence() } + call("start", results) { group.start() } val consumer = track.consume(null) call("info", results) { consumer.info() } listOf(consumer, group, producer, track, broadcast).forEach { it.close() } diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index d157f3fe516..d0031a0af79 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -180,10 +180,10 @@ client = moq.Client( - **`TrackProducer` / `GroupProducer`**. Write raw payloads with no codec parsing. - `.write_frame(payload, timestamp)` writes a payload with its capture time; on a scale-less track (no `timescale`) the timestamp is `Timestamp.unscaled(key)` at the frame's group key. - `await .ready(size)` (`GroupProducer`) waits until a frame of `size` bytes fits a window ahead of the fastest reader. Await it before each write for backpressure. A writer that doesn't wait sheds the front of the group instead. - - `.create_group(sequence)` creates a sparse or replayed group at an explicit sequence. + - `.create_group(start)` creates a sparse or replayed group at an explicit start. - `.skip_groups(start, end)` (`TrackProducer`) declares groups `start` up to the exclusive `end` will never be produced, so readers move past them; creating one there then fails. - `.finish()` ends at the live edge; the handle remains so `.abort(error_code)` can still run. - - `.finish_at(final_sequence)` declares the first group that will never be produced while leaving lower groups writable. + - `.finish_at(final_start)` declares the first group that will never be produced while leaving lower groups writable. - `.abort(error_code)` terminates the track or group with an application error. - `.largest() -> Position | None` (`TrackProducer`) reports the newest group written, at its newest frame. Datagrams are numbered apart from groups and never move it. @@ -211,7 +211,7 @@ client = moq.Client( decodes live media from a catalog rendition: its ID (catalog key) and its `Video` or `Audio` config. It follows the rendition's `broadcast` and `track` itself and yields `MediaFrame`, `Gap`, or `End`. An encoder end is not iterator EOF; media can resume after it. -- `await media.GroupConsumer.fetch(broadcast, id, rendition, sequence, *, options=None)` +- `await media.GroupConsumer.fetch(broadcast, id, rendition, start, *, options=None)` fetches and decodes exactly one group of a catalog rendition. - `media.GroupConsumer(group, container)` decodes a raw group, such as one from `TrackConsumer.recv_group()` for arrival-order reads, with container media time on each frame @@ -219,7 +219,7 @@ client = moq.Client( `media.TrackProducer.write_frame(payload, timestamp)` requires the caller's capture time as a `Timestamp`; returned `media.MediaFrame.timestamp` uses it too. `demand()` owns the track name and -subscriber waits. `.cut()` / `.seek(sequence)` draw group boundaries; `.finish()` ends the import. +subscriber waits. `.cut()` / `.seek(start)` draw group boundaries; `.finish()` ends the import. ### Data @@ -239,9 +239,9 @@ same either way. Opaque bytes go on a plain `TrackProducer`. - **`BroadcastConsumer`**. Subscribe to tracks within a broadcast. - `await .subscribe_track(name, subscription=None) → TrackConsumer` -- **`TrackConsumer`**. Async iterator of raw groups, in sequence order. - - `await .next_group() → GroupConsumer | None`. Sequence order; what the default iteration yields. - - `await .recv_group() → GroupConsumer | None`. Arrival order, which may be out of sequence. Prefer it when latency matters more than order. +- **`TrackConsumer`**. Async iterator of raw groups, in start order. + - `await .next_group() → GroupConsumer | None`. Start order; what the default iteration yields. + - `await .recv_group() → GroupConsumer | None`. Arrival order, which may be out of start order. Prefer it when latency matters more than order. - `.groups_as_arrived()`. Async iterator over `recv_group()`. - `.read_frame() -> Frame | None` returns the first frame of the next group. Empty groups are skipped; `None` is track EOF. - `.info() → TrackInfo` @@ -287,7 +287,7 @@ moq-transport on every relay hop; this API does not add pre-07 capability detect - **`Claim`**. A prefix route on an origin. Hold it: dropping or cancelling it retracts it and rejects the requests still waiting. - `.instance → Instance`. The stream it serves now, kept across `withdraw()` and `announce()`. Unless one is named, it moves to a fresh one each time a job holding it ends. - `.announce()`, `.withdraw()`, `.set_cost(cost)`, `.set_auth(credential)`. Show, hide, re-price, or swap its request credential (`None` for the session's scope) in place. - - `await .requested() → BroadcastRequest | None`, or async iteration. Call `.serve(consumer)` to answer with held content under the claim's continuous sequence space, `.route(hidden=..., ...)` for the path's own route, which continues the claim's instance until the job ends and then moves the claim to a fresh one (unless either names an instance: a named claim lends none, and a named job keeps its own), or `.reject(code)` to fail the requester. + - `await .requested() → BroadcastRequest | None`, or async iteration. Call `.serve(consumer)` to answer with held content under the claim's continuous group starts, `.route(hidden=..., ...)` for the path's own route, which continues the claim's instance until the job ends and then moves the claim to a fresh one (unless either names an instance: a named claim lends none, and a named job keeps its own), or `.reject(code)` to fail the requester. - **`OriginConsumer`**. Discover broadcasts. - `.announced(prefix, filter=None) → AnnounceConsumer` (async iterator of `AnnounceEvent`: `AnnounceEventPresent`, `AnnounceEventUnavailable`, `AnnounceEventAvailable`, `AnnounceEventAbsent`, or `AnnounceEventOffline`, each carrying an `Announce` whose `.route.instance` names the stream; another instance taking a path over keeps it present, so `follow` the path to see that); `filter` is a pattern relative to the literal prefix, while each `Announce.prefix` stays origin-relative and `.captures` is a required list of wildcard matches, empty without wildcards - `.follow(path, instance=None) → Following` (awaitable, waits until something serves the path, then returns each stream that takes over, or `None` once the path goes offline; an `instance` follows only that stream) diff --git a/py/moq-rs/benches/ffi.py b/py/moq-rs/benches/ffi.py index 207fc8ebbdf..a2e6e69deae 100644 --- a/py/moq-rs/benches/ffi.py +++ b/py/moq-rs/benches/ffi.py @@ -171,7 +171,7 @@ async def main() -> None: track = moq.BroadcastProducer().publish_track("calls") group = track.append_group().consume() - call("sequence", lambda: group.sequence, results) + call("start", lambda: group.start, results) consumer = track.consume() call("info", consumer.info, results) diff --git a/py/moq-rs/moq/media.py b/py/moq-rs/moq/media.py index f451ca3c9d5..4721aaed5b9 100644 --- a/py/moq-rs/moq/media.py +++ b/py/moq-rs/moq/media.py @@ -229,14 +229,14 @@ def cut(self) -> None: """ self._inner.cut() - def seek(self, sequence: int) -> None: - """Draw a group boundary and number the next group ``sequence``. + def seek(self, start: int) -> None: + """Draw a group boundary and number the next group ``start``. - :meth:`cut` with an explicit sequence, for a publisher whose group + :meth:`cut` with an explicit start, for a publisher whose group numbers have to be deterministic: two encoders aligning per GOP so a consumer can fail over between them. """ - self._inner.seek(sequence) + self._inner.seek(start) def abort_unwanted(self, error_code: int) -> bool: """Abort this track with an application error code, but only while nobody wants it. @@ -276,9 +276,9 @@ def cut(self) -> None: """ self._inner.cut() - def seek(self, sequence: int) -> None: - """Start a new segment and number its groups ``sequence``.""" - self._inner.seek(sequence) + def seek(self, start: int) -> None: + """Start a new segment and number its groups ``start``.""" + self._inner.seek(start) def finish(self) -> None: """Finish every track this container publishes.""" @@ -415,18 +415,18 @@ async def fetch( broadcast: BroadcastConsumer, id: str, rendition: Video | Audio, - sequence: int, + start: int, *, options: FetchGroupOptions | None = None, ) -> GroupConsumer: """Fetch and decode one group of the catalog rendition ``id``, following its broadcast and track.""" - config = MoqMediaGroupConfig(rendition=_rendition(id, rendition), sequence=sequence, options=options) + config = MoqMediaGroupConfig(rendition=_rendition(id, rendition), start=start, options=options) return cls._from_inner(await MoqMediaGroupConsumer.fetch(broadcast._inner, config)) @property - def sequence(self) -> int: - """The sequence number of this group within the track.""" - return self._inner.sequence() + def start(self) -> int: + """The start of this group within the track.""" + return self._inner.start() async def _next(self) -> MediaFrame | None: frame = await self._inner.next() diff --git a/py/moq-rs/moq/origin.py b/py/moq-rs/moq/origin.py index 1f3bd315285..99b9bfa827b 100644 --- a/py/moq-rs/moq/origin.py +++ b/py/moq-rs/moq/origin.py @@ -151,7 +151,7 @@ def route(self, *, hidden: bool = False, cost: int = 0, instance: Instance | Non return Route(self._inner.route(_options(hidden=hidden, cost=cost, instance=instance, epoch=epoch))) def serve(self, broadcast: BroadcastConsumer) -> None: - """Serve held content under the claim's continuous sequence space, without an exact route.""" + """Serve held content under the claim's continuous start space, without an exact route.""" self._inner.serve(broadcast._inner) def reject(self, error_code: int) -> None: diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 7fb8f3ec1fd..50e3306504c 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -40,9 +40,9 @@ def __init__(self, inner: MoqGroupProducer) -> None: self._inner = inner @property - def sequence(self) -> int: - """The sequence number of this group within the track.""" - return self._inner.sequence() + def start(self) -> int: + """The start of this group within the track.""" + return self._inner.start() def consume(self) -> GroupConsumer: """Create a consumer that reads frames from this group.""" @@ -65,7 +65,7 @@ async def ready(self, size: int) -> None: def write_frame(self, payload: bytes, timestamp: Timestamp) -> None: """Write a frame with its presentation timestamp. - On a scale-less track the timestamp is ``Timestamp.unscaled(self.sequence)``. + On a scale-less track the timestamp is ``Timestamp.unscaled(self.start)``. Never blocks: without :meth:`ready`, a writer that outpaces its readers sheds the front of the group instead. @@ -138,9 +138,9 @@ def append_group(self) -> GroupProducer: """Start a new group; write frames into it, then finish().""" return GroupProducer(self._inner.append_group()) - def create_group(self, sequence: int) -> GroupProducer: - """Create a group with an explicit sequence number.""" - return GroupProducer(self._inner.create_group(sequence)) + def create_group(self, start: int) -> GroupProducer: + """Create a group with an explicit start.""" + return GroupProducer(self._inner.create_group(start)) def skip_groups(self, start: int, end: int) -> None: """Declare that groups ``start`` up to the exclusive ``end`` will never be produced. @@ -191,9 +191,9 @@ def finish(self) -> None: """ self._inner.finish() - def finish_at(self, final_sequence: int) -> None: - """Declare the exclusive final group sequence ahead of the live edge.""" - self._inner.finish_at(final_sequence) + def finish_at(self, final_start: int) -> None: + """Declare the exclusive final group start ahead of the live edge.""" + self._inner.finish_at(final_start) class TrackRequest: @@ -289,27 +289,27 @@ async def wanted_changed(self) -> int | None: """ return await self._inner.wanted_changed() - def accept(self, sequence: int) -> GroupProducer: - """Insert group ``sequence`` and return a producer for it. + def accept(self, start: int) -> GroupProducer: + """Insert group ``start`` and return a producer for it. The first group starts at :attr:`start`'s frame, so its frames keep their indices. """ - return GroupProducer(self._inner.accept(sequence)) + return GroupProducer(self._inner.accept(start)) def drop_groups(self, start: int, end: int) -> None: """Name groups ``start`` up to the exclusive ``end`` as never to be delivered.""" self._inner.drop_groups(start, end) - def is_wanted(self, sequence: int) -> bool: - """Whether a reader still waits for group ``sequence`` from this fill. + def is_wanted(self, start: int) -> bool: + """Whether a reader still waits for group ``start`` from this fill. False once every reader took it or narrowed past it, or nobody waits on the fill. """ - return self._inner.is_wanted(sequence) + return self._inner.is_wanted(start) - async def unwanted(self, sequence: int) -> None: - """Wait until no reader waits for group ``sequence`` from this fill, so stop serving it.""" - await self._inner.unwanted(sequence) + async def unwanted(self, start: int) -> None: + """Wait until no reader waits for group ``start`` from this fill, so stop serving it.""" + await self._inner.unwanted(start) class TrackRequests(_Stream[Fill]): diff --git a/py/moq-rs/moq/subscribe.py b/py/moq-rs/moq/subscribe.py index 732ca03b448..bf93bd909cd 100644 --- a/py/moq-rs/moq/subscribe.py +++ b/py/moq-rs/moq/subscribe.py @@ -37,9 +37,9 @@ def __init__(self, inner: MoqGroupConsumer) -> None: self._inner = inner @property - def sequence(self) -> int: - """The sequence number of this group within the track.""" - return self._inner.sequence() + def start(self) -> int: + """The start of this group within the track.""" + return self._inner.start() async def _next(self) -> Frame | None: return await self.read_frame() @@ -54,7 +54,7 @@ def cancel(self) -> None: class TrackConsumer(_Stream[GroupConsumer]): - """Async iterator of groups from a track, in sequence order. + """Async iterator of groups from a track, in start order. Iterating yields groups via :meth:`next_group`. Use :meth:`recv_group` (or :meth:`groups_as_arrived`) for arrival order instead. @@ -71,9 +71,9 @@ async def _next(self) -> GroupConsumer | None: return await self.next_group() async def groups_as_arrived(self) -> AsyncIterator[GroupConsumer]: - """Iterate groups in arrival order, including out-of-sequence deliveries. + """Iterate groups in arrival order, including out-of-order deliveries. - The default iteration uses sequence order instead. Use this for live + The default iteration uses start order instead. Use this for live consumption where latency matters more than order. """ while True: @@ -85,7 +85,7 @@ async def groups_as_arrived(self) -> AsyncIterator[GroupConsumer]: async def recv_group(self) -> GroupConsumer | None: """Return the next group in arrival order. Returns `None` when the track ends. - Groups are returned as they arrive on the wire, which may be out of sequence + Groups are returned as they arrive on the wire, which may be out of start order. Use this for live consumption where latency matters more than order. """ group = await self._inner.recv_group() @@ -94,9 +94,9 @@ async def recv_group(self) -> GroupConsumer | None: return GroupConsumer(group) async def next_group(self) -> GroupConsumer | None: - """Return the next group in sequence order, skipping forward if behind. + """Return the next group in start order, skipping forward if behind. - Returns `None` when the track ends. Shares the sequence cursor with + Returns `None` when the track ends. Shares the ordered cursor with :meth:`read_frame`: a group one method has already taken is not returned by the other. This is what the default iteration yields; use `recv_group` when latency matters more than order. @@ -162,15 +162,15 @@ async def subscribe_track(self, name: str, subscription: Subscription | None = N async def fetch_group( self, name: str, - sequence: int, + start: int, options: FetchGroupOptions | None = None, ) -> GroupConsumer: - """Fetch one complete group by track name and group sequence. + """Fetch one complete group by track name and group start. This does not hold a live subscription. The returned group may still be receiving frames, so iterate it until completion. """ - return GroupConsumer(await self._inner.fetch_group(name, sequence, options)) + return GroupConsumer(await self._inner.fetch_group(name, start, options)) async def resolve(self, id: str, rendition: Video | Audio) -> "BroadcastConsumer": """Resolve the catalog rendition ``id`` to the broadcast serving its track. diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index ece664a2b37..05766796c4b 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -620,7 +620,7 @@ def test_string_sequences_refuse_a_bare_string(): async def test_fetch_group_and_serve_dynamic_miss(): - """Fetch a cached group, then serve an uncached sequence through TrackRequests.""" + """Fetch a cached group, then serve an uncached start through TrackRequests.""" broadcast = moq.BroadcastProducer() track = broadcast.publish_track("events", moq.TrackInfo(timescale=1_000_000)) consumer = broadcast.consume() @@ -630,7 +630,7 @@ async def test_fetch_group_and_serve_dynamic_miss(): cached.finish() fetched = await consumer.fetch_group("events", 0, moq.FetchGroupOptions(priority=3)) - assert fetched.sequence == 0 + assert fetched.start == 0 assert [frame.payload async for frame in fetched] == [b"cached"] dynamic = track.requests() @@ -752,7 +752,7 @@ async def test_json_window_cut_restates_the_window(): while True: group = await asyncio.wait_for(raw.recv_group(), timeout=5.0) assert group is not None - if group.sequence > 0: + if group.start > 0: break header = await asyncio.wait_for(group.read_frame(), timeout=5.0) assert header is not None @@ -776,7 +776,7 @@ async def test_json_window_skips_records_outside_the_checkpoint(): while True: group = await asyncio.wait_for(joiner.recv_group(), timeout=5.0) assert group is not None - if group.sequence > 0: + if group.start > 0: break consumer = moq.json.WindowConsumer(await broadcast.consume().subscribe_track("log")) @@ -985,18 +985,18 @@ async def test_dynamic_broadcast_request_can_reject(): await asyncio.wait_for(requesting, timeout=5.0) -def test_raw_append_group_sequence_increments(): - """append_group hands out monotonically increasing sequence numbers.""" +def test_raw_append_group_start_increments(): + """append_group hands out monotonically increasing start.""" broadcast = moq.BroadcastProducer() track = broadcast.publish_track("seq") - sequences = [] + starts = [] for _ in range(5): group = track.append_group() - sequences.append(group.sequence) + starts.append(group.start) group.finish() - assert sequences == [0, 1, 2, 3, 4] + assert starts == [0, 1, 2, 3, 4] def test_raw_group_write_multiple_frames(): @@ -1016,7 +1016,7 @@ def test_raw_group_empty_payload(): track = broadcast.publish_track("empty") group = track.append_group() - group.write_frame(b"", moq.Timestamp.unscaled(group.sequence)) + group.write_frame(b"", moq.Timestamp.unscaled(group.start)) group.finish() @@ -1027,7 +1027,7 @@ def test_raw_group_write_after_finish_fails(): group.finish() with pytest.raises(Exception): - group.write_frame(b"too late", moq.Timestamp.unscaled(group.sequence)) + group.write_frame(b"too late", moq.Timestamp.unscaled(group.start)) def test_raw_group_abort_after_finish(): @@ -1059,7 +1059,7 @@ def test_raw_sparse_groups_and_known_end(): track = broadcast.publish_track("sparse") group = track.create_group(2) - assert group.sequence == 2 + assert group.start == 2 group.finish() track.finish_at(5) @@ -1081,8 +1081,8 @@ def test_raw_parallel_groups(): # Without a start, each append takes the next start past the largest. g0 = track.append_group() g1 = track.append_group() - assert g0.sequence == 0 - assert g1.sequence == 1 + assert g0.start == 0 + assert g1.start == 1 # A frame lands at or past its group's start and before the next group's. g0.write_frame(b"a0", moq.Timestamp(0, 1_000_000)) @@ -1239,12 +1239,12 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): order=moq.Order.ASCENDING, ) ) - sequences = [] + starts = [] for _ in range(3): group = await asyncio.wait_for(consumer.recv_group(), timeout=5.0) assert group is not None - sequences.append(group.sequence) - assert sequences == [0, 1, 2] + starts.append(group.start) + assert starts == [0, 1, 2] async def test_time_anchor_starts_at_the_group_containing_it(): @@ -1267,7 +1267,7 @@ async def test_time_anchor_starts_at_the_group_containing_it(): ) group = await asyncio.wait_for(consumer.recv_group(), timeout=5.0) assert group is not None - assert group.sequence == 1_000 + assert group.start == 1_000 async def test_raw_group_producer_consume_direct(): @@ -1276,10 +1276,10 @@ async def test_raw_group_producer_consume_direct(): track = broadcast.publish_track("group-direct") group = track.append_group() group_consumer = group.consume() - assert group_consumer.sequence == group.sequence + assert group_consumer.start == group.start - group.write_frame(b"a", moq.Timestamp.unscaled(group.sequence)) - group.write_frame(b"b", moq.Timestamp.unscaled(group.sequence)) + group.write_frame(b"a", moq.Timestamp.unscaled(group.start)) + group.write_frame(b"b", moq.Timestamp.unscaled(group.start)) group.finish() received = [frame.payload async for frame in group_consumer] @@ -1302,8 +1302,8 @@ async def test_broadcast_producer_consume_direct(): break -async def test_raw_group_sequence(): - """Consumer sees the same sequence numbers the producer assigned.""" +async def test_raw_group_start(): + """Consumer sees the same start the producer assigned.""" origin = moq.OriginProducer() route = origin.route("track/seq") broadcast = route.broadcast @@ -1317,27 +1317,27 @@ async def test_raw_group_sequence(): "seq", moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0) ) - sent_sequences = [] + sent_starts = [] for i in range(3): group = raw.append_group() - sent_sequences.append(group.sequence) + sent_starts.append(group.start) group.write_frame(f"msg-{i}".encode(), moq.Timestamp(i, 1_000_000)) group.finish() - received_sequences = [] + received_starts = [] async for group in raw_consumer: - received_sequences.append(group.sequence) + received_starts.append(group.start) async for _ in group: pass - if len(received_sequences) == len(sent_sequences): + if len(received_starts) == len(sent_starts): break - assert received_sequences == sent_sequences + assert received_starts == sent_starts break -async def test_default_iteration_is_sequence_order(): - """Iterating a track yields sequence order; groups_as_arrived yields arrival order. +async def test_default_iteration_is_start_order(): + """Iterating a track yields start order; groups_as_arrived yields arrival order. Group 5 is produced before group 3, so the two orderings genuinely diverge and this fails if the default iteration ever reverts to recv_group. @@ -1351,16 +1351,16 @@ async def test_default_iteration_is_sequence_order(): seq_consumer = raw.consume(subscription) arr_consumer = raw.consume(subscription) - for sequence in (5, 3): - group = raw.create_group(sequence) - group.write_frame(f"group-{sequence}".encode(), moq.Timestamp.unscaled(sequence)) + for start in (5, 3): + group = raw.create_group(start) + group.write_frame(f"group-{start}".encode(), moq.Timestamp.unscaled(start)) group.finish() - # Arrival order sees them as produced, newest sequence first. - assert [g.sequence async for g in _take(arr_consumer.groups_as_arrived(), 2)] == [5, 3] + # Arrival order sees them as produced, newest start first. + assert [g.start async for g in _take(arr_consumer.groups_as_arrived(), 2)] == [5, 3] - # The default iteration sorts them back into ascending sequence order. - assert [g.sequence async for g in _take(seq_consumer, 2)] == [3, 5] + # The default iteration sorts them back into ascending start order. + assert [g.start async for g in _take(seq_consumer, 2)] == [3, 5] async def _take(iterator, count: int): @@ -1410,7 +1410,7 @@ async def test_container_group_decodes_arrival_order(): second = track.append_group() second.write_frame(_legacy(1_040_000, b"c"), moq.Timestamp(2, 1_000)) second_media = await _recv_media(consumer) - assert second_media.sequence == 1 + assert second_media.start == 1 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)) @@ -1482,7 +1482,7 @@ async def test_raw_multi_frame_group(): group_producer = raw.append_group() chunks = [b"chunk-0", b"chunk-1", b"chunk-2"] for chunk in chunks: - group_producer.write_frame(chunk, moq.Timestamp.unscaled(group_producer.sequence)) + group_producer.write_frame(chunk, moq.Timestamp.unscaled(group_producer.start)) group_producer.finish() async for group in raw_consumer: @@ -1544,11 +1544,11 @@ async def test_read_frame_skips_remaining_frames_in_group(): consumer = track.consume(moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0)) group = track.append_group() - group.write_frame(b"first", moq.Timestamp.unscaled(group.sequence)) - group.write_frame(b"second-ignored", moq.Timestamp.unscaled(group.sequence)) + group.write_frame(b"first", moq.Timestamp.unscaled(group.start)) + group.write_frame(b"second-ignored", moq.Timestamp.unscaled(group.start)) group.finish() - track.write_frame(b"next-group-first", moq.Timestamp.unscaled(group.sequence + 1)) + track.write_frame(b"next-group-first", moq.Timestamp.unscaled(group.start + 1)) frame = await consumer.read_frame() assert frame is not None diff --git a/py/moq-rs/tests/test_socket.py b/py/moq-rs/tests/test_socket.py index 3b789213b3f..1895e3360c5 100644 --- a/py/moq-rs/tests/test_socket.py +++ b/py/moq-rs/tests/test_socket.py @@ -101,12 +101,12 @@ async def test_track_default_retains_ascending_messages_and_subscription(): del server gc.collect() assert consumer.info().max_age is None - for sequence, payload in ((1, b"later"), (0, b"first")): - group = producer.create_group(sequence) - group.write_frame(payload, moq.Timestamp.unscaled(sequence)) + for start, payload in ((1, b"later"), (0, b"first")): + group = producer.create_group(start) + group.write_frame(payload, moq.Timestamp.unscaled(start)) group.finish() producer.finish() - assert [(group.sequence, [frame.payload async for frame in group]) async for group in consumer] == [ + assert [(group.start, [frame.payload async for frame in group]) async for group in consumer] == [ (0, [b"first"]), (1, [b"later"]), ] diff --git a/py/moq-rs/tests/test_testing_clock.py b/py/moq-rs/tests/test_testing_clock.py index 866f8c870ff..587e906d12e 100644 --- a/py/moq-rs/tests/test_testing_clock.py +++ b/py/moq-rs/tests/test_testing_clock.py @@ -35,7 +35,7 @@ async def main(): # group 1 has been out for delay.max: a native timer is pending. _stalled = track.append_group() later = track.append_group() - later.write_frame(b"later", moq.Timestamp.unscaled(later.sequence)) + later.write_frame(b"later", moq.Timestamp.unscaled(later.start)) later.finish() pending = asyncio.ensure_future(consumer.read_frame()) diff --git a/quest/m2/README.md b/quest/m2/README.md index 18cb10e0505..a1746844cfd 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -330,5 +330,5 @@ what would need a breaking release had it landed right after the cut: [moq-dev/moq#8774](https://github.com/moq-dev/moq/pull/8774); the public `Ordered` API waits for the model. Catalog at timestamp no longer waits - for `@moq/net` by start, and [the bindings](/quest/m2/time-addressing/bindings.md) - shrink to a rename, since the model already fills each field with the start. + for `@moq/net` by start, and the bindings shrank to a rename, since the model + already filled each field with the start. diff --git a/quest/m2/time-addressing/bindings.md b/quest/m2/time-addressing/bindings.md index a99d4bab623..dcb7207bfe7 100644 --- a/quest/m2/time-addressing/bindings.md +++ b/quest/m2/time-addressing/bindings.md @@ -1,60 +1,30 @@ -# [S] Bindings address groups by start +# [M] Bindings start a group at a given timestamp ## Goal -moq-ffi, `moq-c`, and every language binding expose groups by start -timestamp instead of sequence number, including `seek` for GOP-aligned -failover, with each `doc/lib` page and the PR's Impact section saying how to migrate. +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 -Follow the cross-package sync table from `rs/moq-ffi` outward. Timestamps -already cross the bindings as `{value, scale}`, so a start reuses that -type. Decided 2026-11-03 (maintainer, replacing 2026-10-27's "producer arguments -keep their optional timestamp"): every read and write carries a timestamp. -Reads drop the `Option` that exact timestamps keeps for untimed, producer -arguments take a required one, and nothing is wall-clock stamped. A -scale-less track's frames carry their group's key. See -[the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md). - -Resized from M to S 2026-11-14 (the m2 triage before the cut, under -/quest-afk, for the maintainer's review): [moq-dev/moq#8638](https://github.com/moq-dev/moq/pull/8638) -already makes every binding's timestamps required and fills each group field -with the start, so what remains is the names. moq-ffi still says `sequence` -where it now means the start: the group record's field, `fetch_group`'s -argument, `seek`, and the docs on the ordered and arrival readers -(`rs/moq-ffi/src/consumer.rs`, `media.rs`). Rename them to `start` the same -way in moq-ffi, `moq-c`, and every binding, mirroring Rust's `group::Info`. -It stays in m2 because the rename is breaking and the cut would otherwise -publish a `sequence` that holds a start. - -Found 2026-11-16 (/quest-plan of the pre-cut audit): that inventory is -short. The producer side says `sequence` too, in -`rs/moq-ffi/src/producer.rs`: `MoqFill::accept`, `is_wanted`, and `unwanted` -take `sequence` (`:582-601`); `MoqTrackProducer::create_group(sequence)` -(`:859`) already passes it as `group::Info { start }`; -`finish_at(final_sequence)` (`:950`); `MoqGroupProducer::sequence()` -(`:1002`, filled from `group.start` at `:993`); and `MoqPosition.group`'s -doc calls it "The group sequence" (`:17`). The hand-written C API has -`moq_group_request_sequence` (`rs/moq-c/src/api.rs:4035`) and -`moq_publish_group_sequence` (`:4154`). Rename all of them in the same PR, -then grep every wrapper and `doc/lib` page for `sequence` once more: a name -left behind is a second breaking release. - -Decided 2026-11-16 (maintainer, same run): the hand-written C API ships as -`libmoq` ([its name](/quest/m2/libmoq-name.md)), so where this quest says -`moq-c` it means that crate, whichever name it carries when this lands. The -JS half renames a frame's `sequence` to `index` -([JS](/quest/m2/time-addressing/js.md)); a frame's position in the bindings -takes the same name if any binding exposes one. - -Found 2026-11-16 ([moq-dev/moq#8961](https://github.com/moq-dev/moq/pull/8961)): -Rust's `track::Producer::append_group` now takes a required `Timestamp` -start, with no implicit "one past the previous start". moq-ffi's -`MoqTrackProducer::append_group()` and moq-c's `track_group` still take no -start and compute one past the newest start in the track's timescale (their -private `next_start`). Recommended: give both a required timestamp start, -the `{value, scale}` record the bindings already pass, in this rename's -breaking release, and drop `next_start`. +[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/quest/m3/ffi-exporter.md b/quest/m3/ffi-exporter.md index 252d2a81df8..92c560301d0 100644 --- a/quest/m3/ffi-exporter.md +++ b/quest/m3/ffi-exporter.md @@ -142,8 +142,7 @@ language's public API (`sh/api-diff`) and its Impact section lists every rename for the packages' `MIGRATE.md`. Reshapes that outlive the generator land before the cut instead: the open-set rule in `rs/moq-ffi/AGENTS.md` (selector objects, `Unknown` variants, and a null `max_age` for no limit) and -[the group rename](/quest/m2/time-addressing/bindings.md); the switch keeps -those shapes. The audit's other binding findings were not picked: the `Moq` +the group rename; the switch keeps those shapes. The audit's other binding findings were not picked: the `Moq` facade Kotlin and Dart start from stays, and `MoqError`'s variants stay as they are. diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 2134f212876..28cfd98e022 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -127,7 +127,7 @@ int32_t moq_publish_track(uint32_t broadcast, const char *name, uintptr_t name_l int32_t moq_publish_track_group(uint32_t track); 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_sequence(uint32_t group, uint64_t *dst); +int32_t moq_publish_group_start(uint32_t group, uint64_t *dst); int32_t moq_publish_group_finish(uint32_t group); int32_t moq_publish_group_ready(uint32_t group, uint64_t size, moq_status_callback on_ready, void *user_data); int32_t moq_publish_track_finish(uint32_t track); @@ -155,7 +155,7 @@ int32_t moq_track_request_video(uint32_t request, const moq_video_init *config); int32_t moq_track_request_audio(uint32_t request, const moq_audio_init *config); int32_t moq_track_request_abort(uint32_t request, uint16_t error_code); int32_t moq_track_request_free(uint32_t request); -int32_t moq_group_request_sequence(uint32_t request, uint64_t *dst); +int32_t moq_group_request_start(uint32_t request, uint64_t *dst); int32_t moq_group_request_priority(uint32_t request, int8_t *dst); int32_t moq_group_request_frame_start(uint32_t request, uint64_t *dst); int32_t moq_group_request_accept(uint32_t request); @@ -234,7 +234,7 @@ A scale-less track has no time, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence). Every write takes a non-NULL timestamp: `moq_publish_track_frame` and `moq_publish_group_frame` convert theirs to the track's timescale, a microsecond one unless -`moq_track_info.timescale` sets another, and `moq_publish_group_sequence` reads +`moq_track_info.timescale` sets another, and `moq_publish_group_start` reads the key a scale-less group's frames carry. `moq_consume_track_frame` points `moq_frame.timestamp` at the timestamp read, never NULL, valid until the frame is freed. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 9fc56f8079e..a7f02c4d14b 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -924,7 +924,7 @@ pub enum moq_anchor_kind { pub enum moq_order { /// Newest first, so congestion sheds the backlog rather than the live edge. MOQ_ORDER_DESCENDING = 0, - /// Oldest first, draining a backlog in sequence order. + /// Oldest first, draining a backlog in start order. MOQ_ORDER_ASCENDING = 1, } @@ -1046,9 +1046,9 @@ pub struct moq_route_options { /// /// A route keeps its instance for its lifetime, across [moq_route_withdraw] and /// [moq_route_announce], so a new route is a new stream viewers restart onto. Set one only - /// for a publisher that continues its group sequences across restarts and raises `epoch` + /// for a publisher that continues its group starts across restarts and raises `epoch` /// on each: readers stitch every route of one instance together, so restarting the - /// sequences under an old instance splices unrelated groups into their tracks. + /// starts under an old instance splices unrelated groups into their tracks. pub instance: u32, /// Which run of a stable `instance` this is: only its highest epoch is eligible, cheaper /// or not. Ignored without one. @@ -2533,7 +2533,7 @@ pub unsafe extern "C" fn moq_broadcast_request_path(request: u32, dst: *mut moq_ /// Serve a held consumer under the claim's instance without announcing an exact route. /// -/// Every answer at this path must continue the same sequences and bytes. Start a new +/// Every answer at this path must continue the same group starts and bytes. Start a new /// claim for different content, or route a job, whose end moves the claim to another /// instance. /// Consumes the request handle; the consumer remains owned by the caller. @@ -3144,7 +3144,7 @@ pub extern "C" fn moq_publish_media_cut(media: u32) -> i32 { }) } -/// Draw a group boundary and start the next group at `sequence`, in the track's timescale. +/// Draw a group boundary and start the next group at `start`, in the track's timescale. /// /// [moq_publish_media_cut] keyed explicitly rather than at the next frame's time, which has to come /// after every group the track holds. Groups are keyed by their first frame's time, so two encoders @@ -3152,10 +3152,10 @@ pub extern "C" fn moq_publish_media_cut(media: u32) -> i32 { /// /// Returns a zero on success, or a negative code on failure. #[unsafe(no_mangle)] -pub extern "C" fn moq_publish_media_seek(media: u32, sequence: u64) -> i32 { +pub extern "C" fn moq_publish_media_seek(media: u32, start: u64) -> i32 { ffi::enter(move || { let media = ffi::parse_id(media)?; - State::lock().publish.media_seek(media, sequence) + State::lock().publish.media_seek(media, start) }) } @@ -3279,15 +3279,15 @@ pub extern "C" fn moq_publish_container_cut(container: u32) -> i32 { }) } -/// Start a new segment whose first group starts at `sequence`, in its track's timescale, after +/// Start a new segment whose first group starts at `start`, in its track's timescale, after /// every group the track holds. /// /// Returns zero on success, or a negative code on failure. #[unsafe(no_mangle)] -pub extern "C" fn moq_publish_container_seek(container: u32, sequence: u64) -> i32 { +pub extern "C" fn moq_publish_container_seek(container: u32, start: u64) -> i32 { ffi::enter(move || { let container = ffi::parse_id(container)?; - State::lock().publish.container_seek(container, sequence) + State::lock().publish.container_seek(container, start) }) } @@ -3664,8 +3664,8 @@ unsafe fn parse_track_info(info: *const moq_track_info) -> Result i32 { }) } -/// Create a raw group with an explicit sequence number. +/// Create a raw group with an explicit start. /// /// Returns a non-zero group handle on success, or a negative code on failure. #[unsafe(no_mangle)] -pub extern "C" fn moq_publish_track_group_at(track: u32, sequence: u64) -> i32 { +pub extern "C" fn moq_publish_track_group_at(track: u32, start: u64) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; - State::lock().publish.track_group_at(track, sequence) + State::lock().publish.track_group_at(track, start) }) } @@ -3773,16 +3773,16 @@ pub extern "C" fn moq_publish_track_finish(track: u32) -> i32 { }) } -/// Declare a raw track's exclusive final group sequence. +/// Declare a raw track's exclusive final group start. /// -/// Groups below `final_sequence` may still be created. Groups at or above it +/// Groups below `final_start` may still be created. Groups at or above it /// are rejected. The track remains open for groups below the boundary. Call /// [moq_publish_track_finish] after producing the remaining groups. #[unsafe(no_mangle)] -pub extern "C" fn moq_publish_track_finish_at(track: u32, final_sequence: u64) -> i32 { +pub extern "C" fn moq_publish_track_finish_at(track: u32, final_start: u64) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; - State::lock().publish.track_finish_at(track, final_sequence) + State::lock().publish.track_finish_at(track, final_start) }) } @@ -4032,14 +4032,14 @@ pub extern "C" fn moq_track_request_free(request: u32) -> i32 { }) } -/// The group sequence a group request asks for. +/// The group start a group request asks for. /// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - `dst` must point at a writable `uint64_t`. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_group_request_sequence(request: u32, dst: *mut u64) -> i32 { +pub unsafe extern "C" fn moq_group_request_start(request: u32, dst: *mut u64) -> i32 { ffi::enter(move || { let request = ffi::parse_id(request)?; let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; @@ -4148,7 +4148,7 @@ pub unsafe extern "C" fn moq_publish_group_frame( }) } -/// Read the sequence of a raw group, which names it within its track. +/// 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. @@ -4158,11 +4158,11 @@ pub unsafe extern "C" fn moq_publish_group_frame( /// # Safety /// - `dst` must be a valid pointer to a writable `uint64_t`. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publish_group_sequence(group: u32, dst: *mut u64) -> i32 { +pub unsafe extern "C" fn moq_publish_group_start(group: u32, dst: *mut u64) -> i32 { ffi::enter(move || { let group = ffi::parse_id(group)?; let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; - *dst = State::lock().publish.group_sequence(group)?; + *dst = State::lock().publish.group_start(group)?; Ok(()) }) } @@ -4887,7 +4887,7 @@ pub extern "C" fn moq_consume_close(consume: u32) -> i32 { /// /// This is the counterpart to [moq_publish_track]: no catalog lookup or /// container parsing. `on_frame` is called with a positive raw frame ID for each -/// frame in sequence order, then exactly once more with a terminal code: `0` +/// frame in start order, then exactly once more with a terminal code: `0` /// (closed cleanly) or a negative error. After the terminal (`<= 0`) callback, /// `on_frame` is never called again and `user_data` is never touched again, so /// release `user_data` there. The terminal callback fires even after diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index a9778ada38f..73c62840e97 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -788,7 +788,7 @@ impl Consume { /// /// No catalog lookup or container parsing. This is the moq-net primitive for /// non-media tracks. `on_frame` is called with a raw frame ID for each frame, - /// in sequence order. Frames must be released with [`Self::raw_frame_close`]. + /// in start order. Frames must be released with [`Self::raw_frame_close`]. pub fn raw_track( &mut self, broadcast: Id, @@ -866,7 +866,7 @@ impl Consume { mut track: moq_net::track::Ordered, mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { - // Deliver every frame in sequence order, reading all frames within each + // Deliver every frame in start order, reading all frames within each // group rather than the one-frame-per-group convenience. This is the // "raw track contents" model: the consumer sees exactly what the // producer wrote, regardless of how it was grouped. @@ -1468,8 +1468,8 @@ mod read_tests { format(), ); let timestamp = |us| moq_net::Timestamp::from_micros(us).unwrap(); - let write = |sequence, us, payload: bytes::Bytes| { - let mut group = track.create_group(moq_net::group::Info { start: sequence }).unwrap(); + let write = |start, us, payload: bytes::Bytes| { + let mut group = track.create_group(moq_net::group::Info { start }).unwrap(); format() .write( &mut group, @@ -1605,11 +1605,8 @@ mod tests { } } - fn write(&mut self, sequence: u64, micros: u64) { - let mut group = self - .track - .create_group(moq_net::group::Info { start: sequence }) - .unwrap(); + fn write(&mut self, start: u64, micros: u64) { + let mut group = self.track.create_group(moq_net::group::Info { start }).unwrap(); hang::container::Frame { timestamp: moq_net::Timestamp::from_micros(micros).unwrap(), payload: bytes::Bytes::from_static(b"frame"), diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index aa1fb8922b4..7685ac057b2 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -36,7 +36,7 @@ enum Request { /// group at a time. struct GroupRequest { fill: Arc, - sequence: u64, + start: u64, /// Dropped once the request is answered or freed, so its fill's next group follows. _pending: oneshot::Sender<()>, } @@ -675,13 +675,13 @@ impl Publish { Ok(()) } - /// Draw a group boundary and start the next group at `sequence`, in the track's timescale. + /// Draw a group boundary and start the next group at `start`, in the track's timescale. /// /// [`media_cut`](Self::media_cut) keyed explicitly rather than at the next frame's time, which /// has to come after every group the track holds. - pub fn media_seek(&mut self, media: Id, sequence: u64) -> Result<(), Error> { + pub fn media_seek(&mut self, media: Id, start: u64) -> Result<(), Error> { let track = self.media.get_mut(media).ok_or(Error::MediaNotFound)?; - track.seek(sequence)?; + track.seek(start)?; Ok(()) } @@ -717,11 +717,11 @@ impl Publish { Ok(result?) } - /// Start a new segment whose first group starts at `sequence`, in its track's timescale. - pub fn container_seek(&mut self, container: Id, sequence: u64) -> Result<(), Error> { + /// Start a new segment whose first group starts at `start`, in its track's timescale. + pub fn container_seek(&mut self, container: Id, start: u64) -> Result<(), Error> { let container = self.containers.get_mut(container).ok_or(Error::MediaNotFound)?; container.driver.check()?; - let result = container.inner.seek(sequence); + let result = container.inner.seek(start); container.driver.check()?; Ok(result?) } @@ -1057,18 +1057,18 @@ impl Publish { /// nobody reads it any more, until every group is answered or nobody waits on the fill. async fn serve_fill(callback: OnStatus, fill: Arc) { let mut changes = (*fill).clone(); - while let Some(sequence) = changes.wanted_changed().await { + while let Some(start) = changes.wanted_changed().await { let (pending, answered) = oneshot::channel(); let request = GroupRequest { fill: fill.clone(), - sequence, + start, _pending: pending, }; let Ok(id) = State::lock().publish.group_request.insert(request) else { return; }; callback.call(id); - let unwanted = kio::wait(|waiter| fill.poll_unwanted(sequence, waiter)); + let unwanted = kio::wait(|waiter| fill.poll_unwanted(start, waiter)); tokio::select! { _ = answered => {} // Withdrawn, so answering it fails as not found, and the fill moves on. @@ -1153,13 +1153,13 @@ impl Publish { Ok(()) } - /// The sequence, priority, and first frame of a requested group. + /// The start, priority, and first frame of a requested group. pub fn group_request_info(&self, request: Id) -> Result<(u64, i8, u64), Error> { let request = self.group_request.get(request).ok_or(Error::NotFound)?; Ok(( - request.sequence, + request.start, request.fill.priority(), - request.fill.frame_start(request.sequence), + request.fill.frame_start(request.start), )) } @@ -1169,7 +1169,7 @@ impl Publish { /// indices they have in the group rather than restarting at 0. pub fn group_request_accept(&mut self, request: Id) -> Result { let request = self.group_request.remove(request).ok_or(Error::NotFound)?; - let group = request.fill.accept(request.sequence, None)?; + let group = request.fill.accept(request.start, None)?; self.insert_group(group) } @@ -1184,7 +1184,7 @@ impl Publish { let request = self.group_request.remove(request).ok_or(Error::NotFound)?; request .fill - .refuse_groups(request.sequence..request.sequence + 1, moq_net::Error::NotFound); + .refuse_groups(request.start..request.start + 1, moq_net::Error::NotFound); Ok(()) } @@ -1235,10 +1235,10 @@ impl Publish { self.insert_group(group) } - /// Create a raw group starting at `sequence`, in the track's timescale, which names it. - pub fn track_group_at(&mut self, track: Id, sequence: u64) -> Result { + /// Create a raw group starting at `start`, in the track's timescale, which names it. + pub fn track_group_at(&mut self, track: Id, start: u64) -> Result { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; - let group = raw.inner.create_group(moq_net::group::Info { start: sequence })?; + let group = raw.inner.create_group(moq_net::group::Info { start })?; self.insert_group(group) } @@ -1279,10 +1279,10 @@ impl Publish { Ok(self.tracks.get(track).ok_or(Error::TrackNotFound)?.inner.largest()) } - /// Declare a raw track's exclusive final group sequence. - pub fn track_finish_at(&mut self, track: Id, final_sequence: u64) -> Result<(), Error> { + /// Declare a raw track's exclusive final group start. + pub fn track_finish_at(&mut self, track: Id, final_start: u64) -> Result<(), Error> { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; - raw.inner.finish_at(moq_net::track::Position::group(final_sequence))?; + raw.inner.finish_at(moq_net::track::Position::group(final_start))?; Ok(()) } @@ -1549,9 +1549,9 @@ impl Publish { Ok((entry.inner.clone(), entry.ended.subscribe())) } - /// The sequence (start) of a raw group, which names it: on a scale-less track, the + /// The start of a raw group, which names it: on a scale-less track, the /// unscaled key its frames carry. - pub fn group_sequence(&self, group: Id) -> Result { + pub fn group_start(&self, group: Id) -> Result { let group = self.groups.get(group).ok_or(Error::GroupNotFound)?; let group = group.inner.lock(); Ok(group.as_ref().ok_or(Error::GroupNotFound)?.start) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index fd5efbb7650..8e5550ee3f7 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -3882,7 +3882,7 @@ fn double_close_all_resource_types() { /// Audio has no keyframes, so `moq_publish_media_cut` is the only thing that gives it group /// boundaries: without it every packet lands in one group that never closes. Cutting per packet is -/// what a live publisher does, and `_seek` does the same with a chosen sequence number. +/// what a live publisher does, and `_seek` does the same with a chosen start. #[test] fn media_cut_bounds_audio_groups() { let origin = id(moq_origin_create()); @@ -4865,7 +4865,7 @@ fn track_request_accepted_after_the_broadcast_closes_is_refused() { fn fetch_group( broadcast: u32, name: &str, - sequence: u64, + start: u64, priority: i8, ) -> mpsc::Receiver), moq_net::Error>> { let consumer = State::lock() @@ -4879,7 +4879,7 @@ fn fetch_group( let res = async { let track = consumer.track(&name)?; let options = moq_net::group::Fetch::default().with_priority(priority); - let mut group = track.fetch_group(sequence, options).await?; + let mut group = track.fetch_group(start, options).await?; let index = group.index(); let frame = group.read_frame().await?.expect("expected a fetched frame"); Ok((index, frame.payload.to_vec())) @@ -4903,13 +4903,13 @@ fn track_dynamic_serves_a_fetch_miss() { let fetch = fetch_group(broadcast, "data", 5, 11); let request = id(group_cb.recv()); - let mut sequence = 0u64; + let mut start = 0u64; let mut priority = 0i8; let mut frame_start = 1u64; - assert_eq!(unsafe { moq_group_request_sequence(request, &mut sequence) }, 0); + assert_eq!(unsafe { moq_group_request_start(request, &mut start) }, 0); assert_eq!(unsafe { moq_group_request_priority(request, &mut priority) }, 0); assert_eq!(unsafe { moq_group_request_frame_start(request, &mut frame_start) }, 0); - assert_eq!(sequence, 5); + assert_eq!(start, 5); assert_eq!(priority, 11); assert_eq!(frame_start, 0); @@ -4984,15 +4984,15 @@ fn a_group_request_nobody_reads_is_withdrawn() { reader }; let first = id(group_cb.recv_reading(&mut reader)); - let mut sequence = 0u64; - assert_eq!(unsafe { moq_group_request_sequence(first, &mut sequence) }, 0); - assert_eq!(sequence, 7); + let mut start = 0u64; + assert_eq!(unsafe { moq_group_request_start(first, &mut start) }, 0); + assert_eq!(start, 7); // Reading only 8, so the fill owes nothing once 8 is let go. reader.update(ascending(8, Some(8))).unwrap(); let next = id(group_cb.recv_reading(&mut reader)); - assert_eq!(unsafe { moq_group_request_sequence(next, &mut sequence) }, 0); - assert_eq!(sequence, 8, "group 7, which nobody reads, held the fill back"); + assert_eq!(unsafe { moq_group_request_start(next, &mut start) }, 0); + assert_eq!(start, 8, "group 7, which nobody reads, held the fill back"); assert!(moq_group_request_accept(first) < 0, "the withdrawn request"); assert_eq!(moq_group_request_free(next), 0); @@ -5041,15 +5041,15 @@ fn a_rejected_group_request_binds_only_its_readers() { }; let waiter = kio::Waiter::noop(); - let mut sequence = 0u64; + let mut start = 0u64; for reject in [ |request| moq_group_request_abort(request, 9), |request| moq_group_request_free(request), ] { let mut reader = subscribe(); let request = id(group_cb.recv_reading(&mut reader)); - assert_eq!(unsafe { moq_group_request_sequence(request, &mut sequence) }, 0); - assert_eq!(sequence, 6); + assert_eq!(unsafe { moq_group_request_start(request, &mut start) }, 0); + assert_eq!(start, 6); assert_eq!(reject(request), 0); } @@ -5090,9 +5090,9 @@ fn track_request_dynamic_survives_accept() { let track = id(unsafe { moq_track_request_accept(request, std::ptr::null()) }); let group_request = id(group_cb.recv()); - let mut sequence = 0u64; - assert_eq!(unsafe { moq_group_request_sequence(group_request, &mut sequence) }, 0); - assert_eq!(sequence, 9); + let mut start = 0u64; + assert_eq!(unsafe { moq_group_request_start(group_request, &mut start) }, 0); + assert_eq!(start, 9); let group = id(moq_group_request_accept(group_request)); let payload = b"archive"; assert_eq!( diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index da8d9c0b723..46b4c208530 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -36,7 +36,7 @@ fn next_frame(cb: &Callback) -> Vec { /// Write `payload` into a raw group of a scale-less track, stamped with the group's key. fn write_unscaled(group: u32, payload: &[u8]) -> i32 { let mut key = 0; - assert_eq!(unsafe { moq_publish_group_sequence(group, &mut key) }, 0); + assert_eq!(unsafe { moq_publish_group_start(group, &mut key) }, 0); unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), &moq_timestamp::unscaled(key)) } } diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index d5580933bcd..734accef704 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -281,8 +281,8 @@ 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(); - report.call("sequence", || { - black_box(black_box(&group).sequence()); + report.call("start", || { + black_box(black_box(&group).start()); }); let consumer = track.consume(None).unwrap(); report.call("info", || { diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 69a27d6da31..01bab12a2fe 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -136,7 +136,7 @@ pub enum MoqAnchor { /// [`moq_net::track::Order`]. #[derive(Clone, Copy, uniffi::Enum)] pub enum MoqOrder { - /// Oldest first, draining a backlog in sequence order. + /// Oldest first, draining a backlog in start order. Ascending, /// Newest first, so congestion sheds the backlog rather than the live edge. Descending, @@ -202,7 +202,7 @@ impl From for MoqOrder { } } -/// Options for fetching one past group by sequence. +/// Options for fetching one past group by start. #[derive(Clone, uniffi::Record)] pub struct MoqFetchGroupOptions { /// Delivery priority for the fetch stream; higher values preempt lower ones. @@ -389,7 +389,7 @@ impl MoqBroadcastConsumer { .await } - /// Fetch one complete group by track name and group sequence. + /// Fetch one complete group by track name and group start. /// /// This does not create a live subscription. A retained group resolves immediately; /// otherwise the request waits for a dynamic producer to serve it. The returned @@ -397,14 +397,14 @@ impl MoqBroadcastConsumer { pub async fn fetch_group( &self, name: String, - sequence: u64, + start: u64, options: Option, ) -> Result, MoqError> { self.driver .watch(async { let options = options.map(moq_net::group::Fetch::from); let track = self.inner.track(&name).map_err(map_fetch_error)?; - let group = track.fetch_group(sequence, options).await.map_err(map_fetch_error)?; + let group = track.fetch_group(start, options).await.map_err(map_fetch_error)?; Ok(Arc::new(MoqGroupConsumer::new(group, self.driver.clone()))) }) .await @@ -432,7 +432,7 @@ enum Cursor { Uncommitted(moq_net::track::Subscriber), /// Committed to arrival order by the first `recv_group`. Arrival(moq_net::track::Subscriber), - /// Committed to sequence order by the first `next_group` or `read_frame`. + /// Committed to start order by the first `next_group` or `read_frame`. Ordered(Box), /// Transient, while the subscriber is moved out to be converted. Converting, @@ -454,7 +454,7 @@ struct TrackInner { impl TrackInner { /// The arrival cursor, committing this track to it, or [`MoqError::AlreadyCommitted`] - /// once it committed to sequence order. + /// once it committed to start order. fn arrival(&mut self) -> Result<&mut moq_net::track::Subscriber, MoqError> { if let Cursor::Uncommitted(_) = &self.track { let Cursor::Uncommitted(track) = std::mem::replace(&mut self.track, Cursor::Converting) else { @@ -471,7 +471,7 @@ impl TrackInner { } } - /// The sequence cursor, committing this track to it, or [`MoqError::AlreadyCommitted`] + /// The ordered cursor, committing this track to it, or [`MoqError::AlreadyCommitted`] /// once it committed to arrival order. fn ordered(&mut self) -> Result<&mut OrderedCursor, MoqError> { // Only move the subscriber out when there is one to convert: `ordered()` consumes @@ -515,7 +515,7 @@ impl TrackInner { } } - /// The first frame of the next group in sequence order, skipping completed empty groups. + /// The first frame of the next group in start order, skipping completed empty groups. /// /// One poll does the whole step, so it never trusts a slot it filled on an earlier poll: /// a group `next_group` took from `pending` in between is simply gone, and the wake it @@ -604,12 +604,12 @@ impl MoqTrackConsumer { impl MoqTrackConsumer { /// Return the next group in arrival order. Returns `None` when the track ends. /// - /// Groups are returned as they arrive on the wire, which may be out of sequence + /// Groups are returned as they arrive on the wire, which may be out of start /// order (e.g. if a later group lands before an earlier one on a separate stream). /// One that drifts further behind the live edge than the subscription's `delay.max` /// is skipped, or ends its pending read if already returned; raise it to keep stalled groups. /// - /// The first call commits this track to arrival order: sequence-order reads + /// The first call commits this track to arrival order: start-order reads /// ([`Self::next_group`], [`Self::read_frame`]) fail with /// [`MoqError::AlreadyCommitted`] afterwards. pub async fn recv_group(&self) -> Result>, MoqError> { @@ -617,14 +617,14 @@ impl MoqTrackConsumer { Ok(self.group(group)) } - /// Return the next group with a higher sequence number than any previously + /// Return the next group with a later start than any previously /// returned, skipping late arrivals. Returns `None` when the track ends. /// - /// Shares the sequence cursor with [`Self::read_frame`]: a group one method + /// Shares the ordered cursor with [`Self::read_frame`]: a group one method /// has already taken is not returned by the other. A `read_frame` cancelled /// after acquiring a group leaves that group here. /// - /// The first call commits this track to sequence order: arrival-order reads + /// The first call commits this track to start order: arrival-order reads /// ([`Self::recv_group`]) fail with [`MoqError::AlreadyCommitted`] afterwards. pub async fn next_group(&self) -> Result>, MoqError> { let group = self.reads.wait(|inner, waiter| inner.poll_next_group(waiter)).await?; @@ -638,7 +638,7 @@ impl MoqTrackConsumer { /// only when the track ends. Cancelling one call keeps the current group so a /// later `read_frame` or [`Self::next_group`] still sees it. /// - /// Shares the sequence cursor with [`Self::next_group`], committing the track + /// Shares the ordered cursor with [`Self::next_group`], committing the track /// the same way. pub async fn read_frame(&self) -> Result, MoqError> { let frame = self.reads.wait(|inner, waiter| inner.poll_read_frame(waiter)).await?; @@ -675,7 +675,7 @@ impl MoqTrackConsumer { /// A group whose frames can be read in order. #[derive(uniffi::Object)] pub struct MoqGroupConsumer { - sequence: u64, + start: u64, reads: Polled, driver: Background, } @@ -683,7 +683,7 @@ pub struct MoqGroupConsumer { impl MoqGroupConsumer { pub(crate) fn new(group: moq_net::group::Consumer, driver: Background) -> Self { Self { - sequence: group.start, + start: group.start, reads: Polled::new(group).supervised(driver.clone()), driver, } @@ -708,8 +708,8 @@ impl MoqGroupConsumer { #[uniffi::export] impl MoqGroupConsumer { /// The start of this group, in its track's timescale, which names it within the track. - pub fn sequence(&self) -> u64 { - self.sequence + pub fn start(&self) -> u64 { + self.start } /// Read the next frame in this group, including its timestamp. diff --git a/rs/moq-ffi/src/demand.rs b/rs/moq-ffi/src/demand.rs index 48fdbc39699..262ebae57c4 100644 --- a/rs/moq-ffi/src/demand.rs +++ b/rs/moq-ffi/src/demand.rs @@ -35,7 +35,7 @@ impl MoqTrackDemand { } /// 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 + /// start 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() diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 8c802b63ea2..11d1af231e9 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -345,7 +345,7 @@ pub enum MoqError { /// This track or group already committed to another way of reading it. /// - /// A track is read in arrival order, in sequence order, or by a typed reader such as a + /// A track is read in arrival order, in start order, or by a typed reader such as a /// JSON consumer, never two of them, and the first group read picks the order. A group is /// read raw or by a media group consumer, and the first frame read picks raw. Reaching /// for another one afterwards is this error rather than [`Self::Unsupported`]: each works diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index df71a0a88a1..dcc73facfc7 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -1231,16 +1231,16 @@ impl MoqMediaTrackProducer { Ok(()) } - /// Draw a group boundary and start the next group at `sequence`, in the track's timescale. + /// Draw a group boundary and start the next group at `start`, in the track's timescale. /// /// [`cut`](Self::cut) keyed explicitly rather than at the next keyframe's time, which has to /// come after every group the track holds. Groups are keyed by their first frame's time, so /// two encoders of the same content align without it. - pub fn seek(&self, sequence: u64) -> Result<(), MoqError> { + pub fn seek(&self, start: u64) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); let media = guard.as_mut().ok_or(MoqError::Closed)?; - media.import.seek(sequence).map_err(|err| MoqError::Codec { + media.import.seek(start).map_err(|err| MoqError::Codec { reason: format!("seek failed: {err}"), })?; Ok(()) @@ -1333,15 +1333,15 @@ impl MoqMediaContainerProducer { result } - /// Start a new segment whose first group starts at `sequence`, in its track's timescale, after + /// Start a new segment whose first group starts at `start`, in its track's timescale, after /// every group the track holds. - pub fn seek(&self, sequence: u64) -> Result<(), MoqError> { + pub fn seek(&self, start: u64) -> Result<(), MoqError> { self.driver.check()?; let result = (|| { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); let container = guard.as_mut().ok_or(MoqError::Closed)?; - container.import.seek(sequence).map_err(|err| MoqError::Codec { + container.import.seek(start).map_err(|err| MoqError::Codec { reason: format!("seek failed: {err}"), })?; Ok(()) @@ -1533,8 +1533,8 @@ pub struct MoqMediaTrackConfig { pub struct MoqMediaGroupConfig { /// The catalog rendition to fetch from. pub rendition: MoqRendition, - /// The group sequence. - pub sequence: u64, + /// The group start. + pub start: u64, /// Fetch delivery options, or defaults when absent. #[uniffi(default = None)] pub options: Option, @@ -1679,8 +1679,8 @@ mod read_tests { async fn raw_media_catalog_warmup_reaches_the_subscription() { let (_broadcast, track, reader) = subscribe_warmup().await; let mut media = reader.reads.take(|_| Ok(())).unwrap(); - let write = |sequence: u64, micros| { - let mut group = track.create_group(sequence.into()).unwrap(); + let write = |start: u64, micros| { + let mut group = track.create_group(start.into()).unwrap(); moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Audio) .write( &mut group, @@ -1813,7 +1813,7 @@ mod read_tests { /// A finite, container-decoded media group, fetched or decoded from a raw group. #[derive(uniffi::Object)] pub struct MoqMediaGroupConsumer { - sequence: u64, + start: u64, reads: Polled>, } @@ -1825,7 +1825,7 @@ impl MoqMediaGroupConsumer { ) -> Self { let inner = moq_mux::container::GroupConsumer::new(group, container); Self { - sequence: inner.start(), + start: inner.start(), reads: Polled::new(inner).supervised(driver), } } @@ -1834,8 +1834,8 @@ impl MoqMediaGroupConsumer { #[uniffi::export] impl MoqMediaGroupConsumer { /// The start of this group, in its track's timescale, which names it within the track. - pub fn sequence(&self) -> u64 { - self.sequence + pub fn start(&self) -> u64 { + self.start } /// Read the next decoded media frame, or `None` when the group ends. @@ -2000,7 +2000,7 @@ impl MoqMediaGroupConsumer { ) -> Result, MoqError> { let MoqMediaGroupConfig { rendition, - sequence, + start, options, } = config; let (reference, instance, name, container) = rendition.into_parts(); @@ -2015,7 +2015,7 @@ impl MoqMediaGroupConsumer { .driver .watch(async { let track = resolved.track(&name).map_err(map_fetch_error)?; - track.fetch_group(sequence, options).await.map_err(map_fetch_error) + track.fetch_group(start, options).await.map_err(map_fetch_error) }) .await?; Ok(Arc::new(MoqMediaGroupConsumer::from_inner( diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index 1b5421993bc..a5fcec58775 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -50,9 +50,9 @@ pub struct MoqRouteOptions { pub cost: u64, /// A stable instance for the stream, or `None` to mint a fresh one. /// - /// Set one only for a publisher that continues its group sequences across restarts and + /// Set one only for a publisher that continues its group starts across restarts and /// raises `epoch` on each, or to forward an observed route's stream as is: readers stitch - /// every route of one instance together, so restarting the sequences under an old instance + /// every route of one instance together, so restarting the starts under an old instance /// splices unrelated groups into their tracks. Naming an instance grants nothing: /// publishing still needs the path's grant. #[uniffi(default = None)] @@ -712,7 +712,7 @@ impl MoqBroadcastRequest { /// Serve a held broadcast under the claim's instance without announcing an exact route. /// - /// Every answer at this path must continue the same sequences and bytes. Start a new + /// Every answer at this path must continue the same group starts and bytes. Start a new /// claim for different content, or route a job, whose end moves the claim to another /// instance. pub fn serve(&self, broadcast: &Arc) -> Result<(), MoqError> { diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index bd16fdfd1e8..b726f3cf6be 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -14,7 +14,7 @@ use crate::media::MoqFrame; /// A location within a track, mirroring [`moq_net::track::Position`]. #[derive(Clone, Copy, Debug, PartialEq, Eq, uniffi::Record)] pub struct MoqPosition { - /// The group sequence. + /// The group start. pub group: u64, /// The frame index within the group, numbered from 0 in write order. pub frame: u64, @@ -589,11 +589,11 @@ impl MoqFill { .await } - /// Insert group `sequence` and return a producer for filling it. The first group starts + /// Insert group `start` and return a producer for filling it. The first group starts /// at [`start`](Self::start)'s frame, so its frames keep their indices. - pub fn accept(&self, sequence: u64) -> Result, MoqError> { + pub fn accept(&self, start: u64) -> Result, MoqError> { let _guard = crate::ffi::enter(); - let group = self.inner.accept(sequence, None)?; + let group = self.inner.accept(start, None)?; Ok(Arc::new(MoqGroupProducer::from_inner(group))) } @@ -603,16 +603,16 @@ impl MoqFill { self.inner.drop_groups(start..end); } - /// Whether a reader still waits for group `sequence` from this fill: false once every + /// Whether a reader still waits for group `start` from this fill: false once every /// reader took it or narrowed past it, or nobody waits on the fill. - pub fn is_wanted(&self, sequence: u64) -> bool { - self.inner.is_wanted(sequence) + pub fn is_wanted(&self, start: u64) -> bool { + self.inner.is_wanted(start) } - /// Wait until no reader waits for group `sequence` from this fill, so stop serving it. - pub async fn unwanted(&self, sequence: u64) -> Result<(), MoqError> { + /// Wait until no reader waits for group `start` from this fill, so stop serving it. + pub async fn unwanted(&self, start: u64) -> Result<(), MoqError> { crate::ffi::run(async { - self.inner.unwanted(sequence).await; + self.inner.unwanted(start).await; Ok::<_, MoqError>(()) }) .await @@ -865,15 +865,15 @@ impl MoqTrackProducer { Ok(Arc::new(MoqGroupProducer::from_inner(group))) } - /// Create a group starting at `sequence`, in the track's timescale, which names it. + /// 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. - pub fn create_group(&self, sequence: u64) -> Result, MoqError> { + pub fn create_group(&self, start: u64) -> Result, MoqError> { let _guard = crate::ffi::enter(); let mut phase = self.phase.lock().unwrap(); let raw = phase.raw()?; - let group = raw.create_group(moq_net::group::Info { start: sequence })?; + let group = raw.create_group(moq_net::group::Info { start })?; Ok(Arc::new(MoqGroupProducer::from_inner(group))) } @@ -982,16 +982,16 @@ impl MoqTrackProducer { Ok(()) } - /// Declare the exclusive final group sequence, possibly ahead of the live edge. + /// Declare the exclusive final group start, possibly ahead of the live edge. /// - /// Groups below `final_sequence` may still be created afterwards. Groups at or + /// Groups below `final_start` may still be created afterwards. Groups at or /// above it are rejected. The producer remains open for groups below the boundary; /// call [`finish`](Self::finish) after producing the remaining groups. - pub fn finish_at(&self, final_sequence: u64) -> Result<(), MoqError> { + pub fn finish_at(&self, final_start: u64) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut phase = self.phase.lock().unwrap(); let raw = phase.raw()?; - raw.finish_at(moq_net::track::Position::group(final_sequence))?; + raw.finish_at(moq_net::track::Position::group(final_start))?; Ok(()) } } @@ -999,7 +999,7 @@ impl MoqTrackProducer { /// A group to which frames can be published. #[derive(uniffi::Object)] pub struct MoqGroupProducer { - sequence: u64, + start: u64, /// The group keeps one writer waker, so every [`ready`](Self::ready) call polls it with the /// bridge's, which wakes them all. Every other call locks it through the bridge too, so a /// wake it causes reaches a foreign continuation only after the lock is released. @@ -1030,7 +1030,7 @@ impl MoqGroupProducer { /// Wrap `group`, for a track's writer. pub(crate) fn from_inner(group: moq_net::group::Producer) -> Self { Self { - sequence: group.start, + start: group.start, inner: kio::Bridge::new(GroupPhase::Writing(group)), } } @@ -1039,8 +1039,8 @@ impl MoqGroupProducer { #[uniffi::export] impl MoqGroupProducer { /// The start of this group, in its track's timescale, which names it within the track. - pub fn sequence(&self) -> u64 { - self.sequence + pub fn start(&self) -> u64 { + self.start } /// Create a consumer that reads frames from this group. diff --git a/rs/moq-ffi/src/socket.rs b/rs/moq-ffi/src/socket.rs index 74b44321e1f..0c3c778328d 100644 --- a/rs/moq-ffi/src/socket.rs +++ b/rs/moq-ffi/src/socket.rs @@ -205,7 +205,7 @@ mod tests { fn frame(group: &MoqGroupProducer, payload: &[u8]) -> MoqFrame { MoqFrame { payload: payload.into(), - timestamp: MoqTimestamp::unscaled(group.sequence()), + timestamp: MoqTimestamp::unscaled(group.start()), } } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 8747e880e4b..9963fc98bc7 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1480,14 +1480,14 @@ async fn json_snapshot_refreshes_for_a_joiner() { let refreshed = kio::clock::timeout(TIMEOUT, async { loop { let group = joiner.recv_group().await.unwrap().expect("expected a group"); - if group.sequence() > 0 { + if group.start() > 0 { return group; } } }) .await .expect("timed out waiting for the refresh"); - assert_eq!(refreshed.sequence(), 3000, "the restatement starts at the value's time"); + assert_eq!(refreshed.start(), 3000, "the restatement starts at the value's time"); let consumer = MoqJsonSnapshotConsumer::new(&broadcast.consume().unwrap(), "meta".into(), None).unwrap(); let value = kio::clock::timeout(TIMEOUT, consumer.next()) .await @@ -1651,7 +1651,7 @@ async fn json_window_cut_restates_the_window() { let group = kio::clock::timeout(TIMEOUT, async { loop { let group = raw.recv_group().await.unwrap().expect("expected a group"); - if group.sequence() > 0 { + if group.start() > 0 { return group; } } @@ -1659,7 +1659,7 @@ async fn json_window_cut_restates_the_window() { .await .expect("timed out waiting for the cut's group"); assert_eq!( - group.sequence(), + group.start(), 4000, "a repeated cut opens no extra group: the next starts at the next push" ); @@ -1710,7 +1710,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { // The join crosses the ratio, so the producer restates the window without another edit. let joiner = subscribe(&broadcast, "log").await; kio::clock::timeout(TIMEOUT, async { - while joiner.recv_group().await.unwrap().expect("expected a group").sequence() == 0 {} + while joiner.recv_group().await.unwrap().expect("expected a group").start() == 0 {} }) .await .expect("timed out waiting for the refresh"); @@ -2306,7 +2306,7 @@ async fn raw_untimed_frames_roundtrip() { assert_eq!(frame.payload, b"frame"); assert_eq!(frame.timestamp, MoqTimestamp::unscaled(5)); let group = track.append_group().unwrap(); - assert_eq!(group.sequence(), 6); + assert_eq!(group.start(), 6); let reader = group.consume().unwrap(); let mismatched = group.write_frame(MoqFrame { payload: b"group".to_vec(), @@ -2465,7 +2465,7 @@ fn raw_track_supports_sparse_groups_and_known_end() { let track = broadcast.publish_track("sparse".into(), None).unwrap(); let group = track.create_group(2).unwrap(); - assert_eq!(group.sequence(), 2); + assert_eq!(group.start(), 2); group.finish().unwrap(); track.finish_at(5).unwrap(); @@ -2596,7 +2596,7 @@ async fn fetches_cached_group_without_subscribing() { .await .unwrap(); - assert_eq!(fetched.sequence(), 0); + assert_eq!(fetched.start(), 0); let frame = fetched.read_frame().await.unwrap().expect("expected first frame"); assert_eq!(frame.payload, b"first".to_vec()); assert_eq!(micros(frame.timestamp), 0); @@ -2639,7 +2639,7 @@ async fn fetches_cached_media_group_and_decodes_container() { MoqMediaGroupConfig { rendition: rendition("media", crate::media::MoqContainer::Legacy), // The group starts at its first frame, a second in, in the track's milliseconds. - sequence: 1000, + start: 1000, options: Some(MoqFetchGroupOptions { priority: 7, max_delay: None, @@ -2649,7 +2649,7 @@ async fn fetches_cached_media_group_and_decodes_container() { .await .unwrap(); - assert_eq!(fetched.sequence(), 1000); + assert_eq!(fetched.start(), 1000); let frame = fetched.next().await.unwrap().expect("expected keyframe"); assert_eq!(frame.payload, b"keyframe"); assert_eq!(micros(frame.timestamp), 1_000_000); @@ -2671,7 +2671,7 @@ async fn fetch_media_group_rejects_invalid_container_before_fetching() { &consumer, MoqMediaGroupConfig { rendition: rendition("media", crate::media::MoqContainer::Cmaf { init: Vec::new() }), - sequence: 0, + start: 0, options: None, }, ) @@ -2722,7 +2722,7 @@ async fn fetch_media_group_decodes_multiple_cmaf_samples() { MoqMediaGroupConfig { rendition: rendition("video", crate::media::MoqContainer::Cmaf { init: init.to_vec() }), // The group starts at its first sample, in the init's ticks. - sequence: moq_net::Timestamp::from_micros(2_000_000) + start: moq_net::Timestamp::from_micros(2_000_000) .unwrap() .convert(muxer.timescale()) .unwrap() @@ -2823,7 +2823,7 @@ async fn media_group_decodes_arrival_order_groups() { let mut first = track.append_group(moq_net::Timestamp::from_micros(0).unwrap()).unwrap(); write_legacy(&mut first, 1, 1_000_000, b"a"); let first_media = recv_media_group(&consumer).await; - assert_eq!(first_media.sequence(), 0); + assert_eq!(first_media.start(), 0); let frame = next_media(&first_media).await.unwrap().expect("expected a frame"); assert_eq!(frame.payload, b"a"); assert_eq!(micros(frame.timestamp), 1_000_000); @@ -2833,7 +2833,7 @@ async fn media_group_decodes_arrival_order_groups() { let mut second = track.append_group(moq_net::Timestamp::from_micros(1).unwrap()).unwrap(); write_legacy(&mut second, 2, 1_040_000, b"c"); let second_media = recv_media_group(&consumer).await; - assert_eq!(second_media.sequence(), 1); + assert_eq!(second_media.start(), 1); let frame = next_media(&second_media).await.unwrap().expect("expected a frame"); assert_eq!(frame.payload, b"c"); assert_eq!(micros(frame.timestamp), 1_040_000); @@ -2947,7 +2947,7 @@ async fn dynamic_track_serves_fetch_miss_and_priority() { .expect("timed out waiting for fetch") .expect("fetch task panicked") .unwrap(); - assert_eq!(fetched.sequence(), 5); + assert_eq!(fetched.start(), 5); let frame = fetched.read_frame().await.unwrap().expect("expected fetched frame"); assert_eq!(frame.payload, b"fetched".to_vec()); assert_eq!(micros(frame.timestamp), 100_000); @@ -3791,7 +3791,7 @@ async fn media_consumers_follow_a_rendition_track_in_a_sibling_broadcast() { &broadcast, MoqMediaGroupConfig { rendition, - sequence: 0, + start: 0, options: None, }, ), @@ -4663,7 +4663,7 @@ async fn video_decode_start() { .expect("timed out") .unwrap() .expect("the track ended early") - .sequence() + .start() == 0 {} let catalog_consumer = MoqMediaCatalogConsumer::subscribe(&broadcast_consumer, Duration::ZERO) @@ -5506,7 +5506,7 @@ async fn cancel_retracts_the_route_synchronously() { } } -/// The sequence cursor commits on first use, so every later read has to reach the same +/// The ordered cursor commits on first use, so every later read has to reach the same /// converted handle. Repeating the conversion (or dropping it on the way through) leaves /// the track in its transient state and panics the next read. #[tokio::test] @@ -5545,11 +5545,11 @@ async fn raw_track_next_group_is_repeatable() { assert_eq!(frame.payload, payload); } - // The arrival cursor is gone once the track committed to sequence order. + // The arrival cursor is gone once the track committed to start order. assert!(matches!(consumer.recv_group().await, Err(MoqError::AlreadyCommitted))); } -/// The first group read commits the cursor either way: mixing arrival and sequence +/// The first group read commits the cursor either way: mixing arrival and start /// reads on one track is refused rather than silently interleaving two cursors. #[tokio::test] async fn raw_track_group_order_commits_on_first_read() { @@ -5575,7 +5575,7 @@ async fn raw_track_group_order_commits_on_first_read() { .expect("timed out waiting for a group") .unwrap() .expect("expected a group"); - assert_eq!(group.sequence(), 0); + assert_eq!(group.start(), 0); assert!(matches!(consumer.next_group().await, Err(MoqError::AlreadyCommitted))); assert!(matches!(consumer.read_frame().await, Err(MoqError::AlreadyCommitted))); @@ -5591,7 +5591,7 @@ async fn raw_track_group_order_commits_on_first_read() { .expect("timed out waiting for a group") .unwrap() .expect("expected a group"); - assert_eq!(group.sequence(), 1); + assert_eq!(group.start(), 1); } fn raw_track() -> ( @@ -9044,16 +9044,16 @@ async fn ascending_subscription_reads_a_cached_backlog_oldest_first() { ); let consumer = track.consume(Some(subscription)).unwrap(); - let mut sequences = Vec::new(); + let mut starts = Vec::new(); for _ in 0..3 { let group = kio::clock::timeout(TIMEOUT, consumer.recv_group()) .await .expect("timed out waiting for a cached group") .unwrap() .expect("expected a group"); - sequences.push(group.sequence()); + starts.push(group.start()); } - assert_eq!(sequences, vec![0, 1, 2]); + assert_eq!(starts, vec![0, 1, 2]); } /// Wait until `session` grants `want`, following its changes. @@ -9462,16 +9462,16 @@ async fn time_anchors_start_at_the_containing_group() { Err(MoqError::Protocol { details }) if details.kind == MoqProtocolKind::TimestampMismatch )); let consumer = track.consume(Some(since(1_500))).unwrap(); - let mut sequences = Vec::new(); + let mut starts = Vec::new(); for _ in 0..2 { let group = kio::clock::timeout(TIMEOUT, consumer.recv_group()) .await .expect("timed out waiting for a cached group") .unwrap() .expect("expected a group"); - sequences.push(group.sequence()); + starts.push(group.start()); } - assert_eq!(sequences, vec![1_000, 2_000]); + assert_eq!(starts, vec![1_000, 2_000]); let untimed = broadcast .publish_track( @@ -9690,7 +9690,7 @@ async fn raw_read_frame_moves_on_when_next_group_takes_its_group() { .expect("next_group timed out") .unwrap() .expect("expected the open group"); - assert_eq!(taken.sequence(), 0); + assert_eq!(taken.start(), 0); let frame = kio::clock::timeout(TIMEOUT, read) .await @@ -9756,7 +9756,7 @@ async fn raw_next_group_wakes_read_frame_after_unlocking() { .expect("next_group timed out") .unwrap() .expect("expected the open group"); - assert_eq!(taken.sequence(), 0); + assert_eq!(taken.start(), 0); assert_eq!( inline.polls.load(std::sync::atomic::Ordering::SeqCst), 2, @@ -9785,7 +9785,7 @@ async fn raw_track_concurrent_reads_take_every_group_once() { })) .unwrap(); - // Each reader returns the group sequences it took: a frame's payload names its group. + // Each reader returns the group starts it took: a frame's payload names its group. let frames = |consumer: Arc| { tokio::spawn(async move { let mut taken = Vec::new(); @@ -9799,7 +9799,7 @@ async fn raw_track_concurrent_reads_take_every_group_once() { tokio::spawn(async move { let mut taken = Vec::new(); while let Some(group) = consumer.next_group().await.unwrap() { - taken.push(group.sequence()); + taken.push(group.start()); } taken }) @@ -9812,16 +9812,16 @@ async fn raw_track_concurrent_reads_take_every_group_once() { ]; ffi_caught_up().await; - for sequence in 0..GROUPS { - let group = track.create_group(sequence).unwrap(); + for start in 0..GROUPS { + let group = track.create_group(start).unwrap(); group .write_frame(MoqFrame { - payload: sequence.to_be_bytes().to_vec(), - timestamp: us(sequence), + payload: start.to_be_bytes().to_vec(), + timestamp: us(start), }) .unwrap(); group.finish().unwrap(); - if sequence % 8 == 0 { + if start % 8 == 0 { tokio::task::yield_now().await; } } @@ -10147,7 +10147,7 @@ async fn write_ahead_of_a_slow_reader( let track = broadcast.publish_track("tcp".into(), None).unwrap(); let group = track.append_group().unwrap(); let reader = group.consume().unwrap(); - let key = MoqTimestamp::unscaled(group.sequence()); + let key = MoqTimestamp::unscaled(group.start()); let frame = move || MoqFrame { payload: vec![7; MIB], timestamp: key, @@ -10254,7 +10254,7 @@ async fn concurrent_ready_calls_all_wake() { let track = broadcast.publish_track("tcp".into(), None).unwrap(); let group = track.append_group().unwrap(); let reader = group.consume().unwrap(); - let key = MoqTimestamp::unscaled(group.sequence()); + let key = MoqTimestamp::unscaled(group.start()); let frame = move || MoqFrame { payload: vec![7; MIB], timestamp: key, diff --git a/swift/README.md b/swift/README.md index 35f7687fcfd..50e646fbf11 100644 --- a/swift/README.md +++ b/swift/README.md @@ -70,7 +70,7 @@ A note on enum casing: `MoqError` keeps Rust's PascalCase variants, some with no The wrapper fully wraps every stateful handle (`Client`, `Session`, `BroadcastProducer`, `TrackConsumer`, …) and re-exports the plain data records/enums under de-prefixed names via typealias (`Frame`, `Media.Catalog`, `Media.Audio`, `Media.Container`, …). Because the records are typealiased, new fields on the `moq-ffi` side flow through automatically; only new FFI *methods* need a matching wrapper method. -Every consumer conforms to `AsyncSequence`, so `for try await x in consumer` works directly. `TrackConsumer` iterates groups in sequence order; use its `groupsAsArrived` property for arrival order. +Every consumer conforms to `AsyncSequence`, so `for try await x in consumer` works directly. `TrackConsumer` iterates groups in start order; use its `groupsAsArrived` property for arrival order. Incoming server `Request` values expose the query-free `path` before acceptance. It is consistent across transports and is empty for the root or missing path. The encoded `query` may contain credentials. diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index a954d025b07..ab8de5ce2f5 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -76,7 +76,7 @@ public typealias Subscription = MoqFFI.MoqSubscription /// `nil` for no subscriber limit, is how far a non-latest group may fall behind before it is /// skipped. A `min` past `max` starts at `max`. public typealias Delay = MoqFFI.MoqDelay -/// Options for fetching one complete group by sequence. +/// Options for fetching one complete group by start. public typealias FetchGroupOptions = MoqFFI.MoqFetchGroupOptions /// Publisher-side track properties: priority, group ordering, max age, /// and timescale. @@ -136,7 +136,7 @@ public typealias ProtocolKind = MoqFFI.MoqProtocolKind /// A protocol failure: scope, verbatim wire code, kind, and a diagnostic message. public typealias ProtocolError = MoqFFI.MoqProtocolError -/// A location within a track: a group sequence and a frame index in it. +/// A location within a track: a group start and a frame index in it. public typealias Position = MoqFFI.MoqPosition // Nested rather than top-level: a module-level `Range` would shadow `Swift.Range` diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index 30cf19f63b2..7b771368954 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -21,14 +21,14 @@ public final class BroadcastConsumer: Sendable { TrackConsumer(try await ffi.subscribeTrack(name: name, subscription: subscription)) } - /// Fetch one complete group by track name and group sequence without holding + /// Fetch one complete group by track name and group start without holding /// a live subscription. The group may still be receiving frames. public func fetchGroup( name: String, - sequence: UInt64, + start: UInt64, options: FetchGroupOptions? = nil ) async throws -> GroupConsumer { - GroupConsumer(try await ffi.fetchGroup(name: name, sequence: sequence, options: options)) + GroupConsumer(try await ffi.fetchGroup(name: name, start: start, options: options)) } /// Resolve a catalog rendition to the broadcast serving its track. diff --git a/swift/Sources/Moq/Media.swift b/swift/Sources/Moq/Media.swift index ce4671c1daf..a8190bd559d 100644 --- a/swift/Sources/Moq/Media.swift +++ b/swift/Sources/Moq/Media.swift @@ -117,7 +117,7 @@ public enum Media { public typealias Rendition = MoqRendition /// A catalog rendition and live delivery options. public typealias TrackConfig = MoqMediaTrackConfig - /// A catalog rendition's group sequence and fetch delivery options. + /// A catalog rendition's group start and fetch delivery options. public typealias GroupConfig = MoqMediaGroupConfig /// Updates a catalog without keeping its broadcast open. @@ -246,9 +246,9 @@ public enum Media { self.init(try MoqMediaGroupConsumer(group: group.ffi, container: container)) } - /// The sequence number of this group within the track. - public var sequence: UInt64 { - ffi.sequence() + /// The start of this group within the track. + public var start: UInt64 { + ffi.start() } /// The next frame, or `nil` once the group ends. @@ -326,12 +326,12 @@ public enum Media { try ffi.cut() } - /// Draw a group boundary and number the next group `sequence`. + /// Draw a group boundary and start the next group at `start`. /// - /// ``cut()`` with an explicit sequence, for a publisher whose group numbers have to be + /// ``cut()`` with an explicit start, for a publisher whose group starts have to be /// deterministic: two encoders aligning per GOP so a consumer can fail over between them. - public func seek(_ sequence: UInt64) throws { - try ffi.seek(sequence: sequence) + public func seek(_ start: UInt64) throws { + try ffi.seek(start: start) } /// Abort the track with an application error code, but only while nobody wants it: call it @@ -377,9 +377,9 @@ public enum Media { try ffi.cut() } - /// Start a new segment and number its groups `sequence`. - public func seek(_ sequence: UInt64) throws { - try ffi.seek(sequence: sequence) + /// Start a new segment and start its groups at `start`. + public func seek(_ start: UInt64) throws { + try ffi.seek(start: start) } /// Finish every track this container publishes. diff --git a/swift/Sources/Moq/Origin.swift b/swift/Sources/Moq/Origin.swift index b071f9ad0cf..5dbaf8fd9ae 100644 --- a/swift/Sources/Moq/Origin.swift +++ b/swift/Sources/Moq/Origin.swift @@ -82,7 +82,7 @@ public final class BroadcastRequest: Sendable { try ffi.route(options: MoqRouteOptions(hidden: hidden, cost: cost, instance: instance, epoch: epoch))) } - /// Serve held content under the claim's continuous sequence space, without an exact route. + /// Serve held content under the claim's continuous group starts, without an exact route. public func serve(broadcast: BroadcastConsumer) throws { try ffi.serve(broadcast: broadcast.ffi) } diff --git a/swift/Sources/Moq/Requests.swift b/swift/Sources/Moq/Requests.swift index 0bb545dd6e5..6dfcd9c264e 100644 --- a/swift/Sources/Moq/Requests.swift +++ b/swift/Sources/Moq/Requests.swift @@ -43,7 +43,7 @@ public final class TrackRequest: Sendable { /// returns them; `wanted` names what is still owed, in the fill's order. Releasing the fill /// names whatever is left as dropped while a reader still wants it; once nobody does, it is /// withdrawn, so stop serving it once `wanted` is nil. Stop serving a single group when -/// `unwanted(sequence:)` returns for it, and move on to `wanted`. Serve the fills you take +/// `unwanted(start:)` returns for it, and move on to `wanted`. Serve the fills you take /// concurrently: each waits on its own readers. public final class Fill: Sendable { let ffi: MoqFill @@ -91,10 +91,10 @@ public final class Fill: Sendable { try await ffi.wantedChanged() } - /// Insert group `sequence` and return a producer for it. The first group starts at + /// Insert group `start` and return a producer for it. The first group starts at /// `start`'s frame, so its frames keep their indices. - public func accept(sequence: UInt64) throws -> GroupProducer { - GroupProducer(try ffi.accept(sequence: sequence)) + public func accept(start: UInt64) throws -> GroupProducer { + GroupProducer(try ffi.accept(start: start)) } /// Name groups `start` up to the exclusive `end` as never to be delivered. @@ -102,15 +102,15 @@ public final class Fill: Sendable { ffi.dropGroups(start: start, end: end) } - /// Whether a reader still waits for group `sequence` from this fill: false once every + /// Whether a reader still waits for group `start` from this fill: false once every /// reader took it or narrowed past it, or nobody waits on the fill. - public func isWanted(sequence: UInt64) -> Bool { - ffi.isWanted(sequence: sequence) + public func isWanted(start: UInt64) -> Bool { + ffi.isWanted(start: start) } - /// Suspend until no reader waits for group `sequence` from this fill, so stop serving it. - public func unwanted(sequence: UInt64) async throws { - try await ffi.unwanted(sequence: sequence) + /// Suspend until no reader waits for group `start` from this fill, so stop serving it. + public func unwanted(start: UInt64) async throws { + try await ffi.unwanted(start: start) } } diff --git a/swift/Sources/Moq/Track.swift b/swift/Sources/Moq/Track.swift index b4740214c36..64f34404b68 100644 --- a/swift/Sources/Moq/Track.swift +++ b/swift/Sources/Moq/Track.swift @@ -1,10 +1,10 @@ import Foundation import MoqFFI -/// Read side of a raw track. Iterating yields groups in sequence order, skipping +/// Read side of a raw track. Iterating yields groups in start order, skipping /// forward if the reader falls behind: `for try await group in track { ... }`. public final class TrackConsumer: AsyncSequence, Sendable { - /// The group emitted by this sequence, in sequence order. + /// The group emitted by this sequence, in start order. public typealias Element = GroupConsumer let ffi: MoqTrackConsumer @@ -13,14 +13,14 @@ public final class TrackConsumer: AsyncSequence, Sendable { self.ffi = ffi } - /// The next group in sequence order, skipping forward on fall-behind. `nil` - /// once the track ends. Shares the sequence cursor with `readFrame`: a group + /// The next group in start order, skipping forward on fall-behind. `nil` + /// once the track ends. Shares the ordered cursor with `readFrame`: a group /// one method has already taken is not returned by the other. public func nextGroup() async throws -> GroupConsumer? { (try await ffi.nextGroup()).map(GroupConsumer.init) } - /// The next group in arrival order, which may be out of sequence. `nil` once + /// The next group in arrival order, which may be out of start order. `nil` once /// the track ends. public func recvGroup() async throws -> GroupConsumer? { (try await ffi.recvGroup()).map(GroupConsumer.init) @@ -50,8 +50,8 @@ public final class TrackConsumer: AsyncSequence, Sendable { ffi.cancel() } - /// Groups in arrival order, including out-of-sequence deliveries. The default - /// `AsyncSequence` iteration uses sequence order instead. + /// Groups in arrival order, including out-of-order deliveries. The default + /// `AsyncSequence` iteration uses start order instead. public var groupsAsArrived: AsyncThrowingStream { moqStream(cancel: { [ffi] in ffi.cancel() }) { [ffi] in (try await ffi.recvGroup()).map(GroupConsumer.init) @@ -77,9 +77,9 @@ public final class GroupConsumer: AsyncSequence, Sendable { self.ffi = ffi } - /// The sequence number of this group within the track. - public var sequence: UInt64 { - ffi.sequence() + /// The start of this group within the track. + public var start: UInt64 { + ffi.start() } /// The next raw frame, or `nil` once the group ends. @@ -160,9 +160,9 @@ public final class TrackProducer: Sendable { GroupProducer(try ffi.appendGroup()) } - /// Create a group with an explicit sequence number. - public func createGroup(sequence: UInt64) throws -> GroupProducer { - GroupProducer(try ffi.createGroup(sequence: sequence)) + /// Create a group with an explicit start. + public func createGroup(start: UInt64) throws -> GroupProducer { + GroupProducer(try ffi.createGroup(start: start)) } /// Declare that groups `start` up to the exclusive `end` will never be produced. @@ -201,10 +201,10 @@ public final class TrackProducer: Sendable { try ffi.finish() } - /// Declare the exclusive final group sequence ahead of the live edge. + /// Declare the exclusive final group start ahead of the live edge. /// The producer remains open for groups below the boundary. - public func finish(at finalSequence: UInt64) throws { - try ffi.finishAt(finalSequence: finalSequence) + public func finish(at finalStart: UInt64) throws { + try ffi.finishAt(finalStart: finalStart) } } @@ -216,9 +216,9 @@ public final class GroupProducer: Sendable { self.ffi = ffi } - /// The sequence number of this group within the track. - public var sequence: UInt64 { - ffi.sequence() + /// The start of this group within the track. + public var start: UInt64 { + ffi.start() } /// A read handle for this group's frames. @@ -237,7 +237,7 @@ public final class GroupProducer: Sendable { try await ffi.ready(size: size) } - /// Write a frame with a presentation timestamp, or `Timestamp.unscaled(sequence)` on a + /// Write a frame with a presentation timestamp, or `Timestamp.unscaled(start)` on a /// scale-less track. Never blocks: without `ready`, a writer that outpaces its readers sheds /// the group's front instead. public func writeFrame(_ payload: Data, timestamp: Timestamp) throws { diff --git a/swift/Tests/MoqTests/FfiBench.swift b/swift/Tests/MoqTests/FfiBench.swift index 74e25e70356..975dec3ba89 100644 --- a/swift/Tests/MoqTests/FfiBench.swift +++ b/swift/Tests/MoqTests/FfiBench.swift @@ -60,7 +60,7 @@ final class FfiBench: XCTestCase { name: "call/\(name)", unit: "ns", value: (ProcessInfo.processInfo.systemUptime - start) * 1e9 / Double(calls)) } - results.append(call("sequence") { _ = group.sequence }) + results.append(call("start") { _ = group.start }) results.append(try call("info") { _ = consumer.info() }) try broadcast.close() let directory = URL(fileURLWithPath: dir, isDirectory: true) diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 8b77612c13c..7287f91408e 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -76,7 +76,7 @@ final class SmokeTests: XCTestCase { let track = try broadcast.publishTrack(name: "errors") let producer = try track.appendGroup() let consumer = try broadcast.consume() - let group = try await consumer.fetchGroup(name: "errors", sequence: 0) + let group = try await consumer.fetchGroup(name: "errors", start: 0) try producer.abort(errorCode: 404) do { _ = try await group.readFrame() @@ -104,12 +104,12 @@ final class SmokeTests: XCTestCase { ranges: [Subscription.Range(start: .relative(groups: 2))], order: .ascending )) - var sequences: [UInt64] = [] + var starts: [UInt64] = [] for _ in 0..<3 { let group = try await consumer.recvGroup() - sequences.append(try XCTUnwrap(group).sequence) + starts.append(try XCTUnwrap(group).start) } - XCTAssertEqual(sequences, [0, 1, 2]) + XCTAssertEqual(starts, [0, 1, 2]) } /// An error's description is the Rust error message. @@ -634,10 +634,10 @@ final class SmokeTests: XCTestCase { let consumer = try broadcast.consume() let fetched = try await consumer.fetchGroup( name: "events", - sequence: 0, + start: 0, options: FetchGroupOptions(priority: 3) ) - XCTAssertEqual(fetched.sequence, 0) + XCTAssertEqual(fetched.start, 0) let frame = try await fetched.readFrame() XCTAssertEqual(frame?.payload, Data("cached".utf8)) let end = try await fetched.readFrame() @@ -833,9 +833,9 @@ final class SmokeTests: XCTestCase { XCTAssertNil(frame.timestamp.scale) XCTAssertNil(consumer.info().timescale) // A group's frames carry that group's key, and only it. - let group = try track.createGroup(sequence: 1) + let group = try track.createGroup(start: 1) XCTAssertThrowsError(try group.writeFrame(Data("other".utf8), timestamp: .unscaled(2))) - try group.writeFrame(Data("grouped".utf8), timestamp: .unscaled(group.sequence)) + try group.writeFrame(Data("grouped".utf8), timestamp: .unscaled(group.start)) try group.finish() let grouped = try await consumer.readFrame() XCTAssertEqual(grouped?.timestamp, .unscaled(1)) @@ -960,13 +960,13 @@ final class SmokeTests: XCTestCase { func testSparseGroupsAndKnownEnd() throws { let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "sparse") - let group = try track.createGroup(sequence: 2) - XCTAssertEqual(group.sequence, 2) + let group = try track.createGroup(start: 2) + XCTAssertEqual(group.start, 2) try group.finish() try track.finish(at: 5) - try track.createGroup(sequence: 4).finish() - XCTAssertThrowsError(try track.createGroup(sequence: 5)) + try track.createGroup(start: 4).finish() + XCTAssertThrowsError(try track.createGroup(start: 5)) try track.finish() try broadcast.close() } diff --git a/test/interop/clients/python/sockets.py b/test/interop/clients/python/sockets.py index 2d6f55e5424..962a84ec3a6 100644 --- a/test/interop/clients/python/sockets.py +++ b/test/interop/clients/python/sockets.py @@ -33,10 +33,10 @@ async def exchange(stream: socket.TrackStream) -> None: for _ in range(3): group = stream.producer.append_group() for payload in PAYLOADS: - group.write_frame(payload, moq.Timestamp.unscaled(group.sequence)) + group.write_frame(payload, moq.Timestamp.unscaled(group.start)) group.finish() stream.producer.finish() - received = [(group.sequence, [frame.payload async for frame in group]) async for group in stream.consumer] + received = [(group.start, [frame.payload async for frame in group]) async for group in stream.consumer] assert received == [(sequence, PAYLOADS) for sequence in range(3)], received