Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,6 @@ lite-07; bitrate enforcement is not part of this release.
- [QoS](/quest/m2/qos/README.md) - the relay's egress `lag` histogram and `dropped` counters on the stats totals and prefix tracks
- [Lazy retained HLS instances](/quest/m2/hls-lazy-instances.md) - a replaced HLS instance starts its watchers only when a request reaches it
- [HLS and DASH browser playback](/quest/m2/hls-player-test.md) - hls.js and dash.js play, reload, switch, and survive reconfiguration nightly
- [moq-hls export on kio](/quest/m2/hls-export-kio.md) - export watchers and the init build are owned kio tasks instead of tokio::spawn
- [Re-init retires timelines](/quest/m2/reinit-retire.md) - fMP4 and MKV re-inits retire the old timeline, so import state stays bounded
- [Replaced producers retire their records](/quest/m2/producer-retire.md) - encoders and bindings retire a replaced producer's HLS records
- [Broadcast fairness](/quest/m2/broadcast-fairness.md) - broadcasts share a cluster link fairly, so one tenant's priority never starves another's
Expand Down
21 changes: 0 additions & 21 deletions quest/m2/hls-export-kio.md

This file was deleted.

3 changes: 2 additions & 1 deletion quest/m2/spawn-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ Blocking OS threads are out of scope.
Planned 2026-10-25 with the maintainer as the follow-up to no-spawn. As of
`main` today the spawning library crates include moq-tokio (connection,
server, client), moq-relay (web, shutdown, uring), moq-mux's container
consumer, moq-hls export, moq-rtmp, moq-rtsp, moq-srt, moq-rtc, moq-transcode,
consumer, moq-hls's server (its path follower and each
broadcaster's driver), moq-rtmp, moq-rtsp, moq-srt, moq-rtc, moq-transcode,
moq-video's encode producer, moq-cli's play path, moq-bench, and qmux's
transport. Recount with `rg 'tokio::spawn|spawn_local|task::spawn'` outside
tests, benches, and binaries before starting.
Expand Down
3 changes: 2 additions & 1 deletion rs/moq-cli/src/hls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,8 @@ pub async fn export(origin: moq_net::origin::Consumer, args: ExportArgs, name: S
.await
.with_context(|| format!("failed to resolve broadcast `{name}`"))?;
let source = moq_mux::Source::new(scoped.clone(), broadcast);
let broadcaster = moq_hls::export::Broadcaster::new(source, config);
let (broadcaster, driver) = moq_hls::export::Broadcaster::new(source, config);
tokio::spawn(driver.run());
tracing::info!(%name, "recording HLS");
recording.run(&broadcaster).await
};
Expand Down
8 changes: 5 additions & 3 deletions rs/moq-cli/src/hls/record.rs
Original file line number Diff line number Diff line change
Expand Up @@ -637,9 +637,11 @@ mod tests {
}
}

fn broadcaster(&self) -> Arc<Broadcaster> {
fn broadcaster(&self) -> Broadcaster {
let source = moq_mux::Source::new(self.origin.consume(), self.broadcast.consume());
Broadcaster::new(source, moq_hls::export::Config::default())
let (broadcaster, driver) = Broadcaster::new(source, moq_hls::export::Config::default());
tokio::spawn(driver.run());
broadcaster
}

/// Write GOP `n`, two seconds from `2n`, to every rendition.
Expand Down Expand Up @@ -702,7 +704,7 @@ mod tests {
.collect()
}

fn spawn(dir: &Path, broadcaster: &Arc<Broadcaster>) -> tokio::task::JoinHandle<anyhow::Result<()>> {
fn spawn(dir: &Path, broadcaster: &Broadcaster) -> tokio::task::JoinHandle<anyhow::Result<()>> {
let recording = Recording::create(dir.to_path_buf()).unwrap();
let broadcaster = broadcaster.clone();
tokio::spawn(async move { recording.run(&broadcaster).await })
Expand Down
12 changes: 12 additions & 0 deletions rs/moq-hls/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ How to update your code for each breaking change, newest first.

## Unreleased

### `Broadcaster::new` returns a cloneable handle and its `Driver`

`Broadcaster::new(source, config)` returns `(Broadcaster, Driver)` instead of `Arc<Broadcaster>`.
`Broadcaster` is a cheap handle: clone it instead of an `Arc`, and compare two with `is_clone` instead of `Arc::ptr_eq`.
The export no longer spawns its background work: run the driver wherever you run tasks, for example `tokio::spawn(driver.run())`, or poll it with `Driver::poll`.
Nothing is watched until it runs.

```rust
let (broadcaster, driver) = moq_hls::export::Broadcaster::new(source, config);
tokio::spawn(driver.run());
```

### Renditions list their own HLS records

Each rendition reads the records its catalog `hls` field names, and segment `n` is its record `n`; a rendition without `hls` gets no playlist.
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-hls/src/export/archive_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ fn catalog() -> hang::Catalog {

/// An archive served back through an origin by a consumer, and a broadcaster exporting it.
struct Replay {
broadcaster: Arc<Broadcaster>,
broadcaster: Broadcaster,
/// Keeps the served broadcast's origin open.
_origin: moq_net::origin::Producer,
consumer: tokio::task::JoinHandle<moq_archive::Result<()>>,
Expand All @@ -284,7 +284,7 @@ impl Replay {
let consumer = tokio::spawn(consumer.run());
broadcast.announce(Default::default()).unwrap();

let broadcaster = Broadcaster::new(crate::resolved(&origin, "rec").await, Config::default());
let broadcaster = Broadcaster::spawned(crate::resolved(&origin, "rec").await, Config::default());
kio::clock::timeout(Duration::from_secs(5), broadcaster.ready())
.await
.expect("a rendition becomes playable or fails");
Expand Down
174 changes: 174 additions & 0 deletions rs/moq-hls/src/export/driver.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
//! The export's background work, as `kio` tasks one [`Driver`] polls.

use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::task::Poll;

/// Runs a [`Broadcaster`](super::Broadcaster)'s background work: its catalog watcher, each
/// rendition's record watcher, and the init builds.
///
/// Poll it, or [`run`](Self::run) it, for as long as the broadcaster serves. It finishes once
/// the broadcaster and every rendition it created have dropped and their tasks ended, so a
/// recording cursor that outlives the broadcaster keeps its rendition's records flowing.
/// Dropping it early stops all of that work.
#[must_use = "the broadcaster does nothing until its driver runs"]
pub struct Driver {
/// The catalog watcher, polled before the other tasks in every pass: a reconfigure must
/// retire its rendition before that rendition's watcher reads records published after it.
lead: Option<Job>,
inbox: kio::Queue<Job>,
tasks: kio::Tasks<Job>,
/// The inbox closed: every owner that could start a task has dropped.
closed: bool,
}

impl Driver {
/// Advance every task, ready once nothing is left to run.
pub fn poll(&mut self, waiter: &kio::Waiter) -> Poll<()> {
if let Some(lead) = &mut self.lead
&& kio::Task::poll(lead, waiter).is_ready()
{
self.lead = None;
}
while !self.closed {
match self.inbox.poll_pop(waiter) {
Poll::Ready(Ok(job)) => self.tasks.push(job),
Poll::Ready(Err(kio::Closed)) => self.closed = true,
Poll::Pending => break,
}
}
match self.tasks.poll(waiter) {
Poll::Ready(()) if self.closed && self.lead.is_none() => Poll::Ready(()),
_ => Poll::Pending,
}
}

/// Run `task` ahead of every other task (see [`lead`](Self::lead)), until it finishes or the
/// returned [`Owner`] drops.
pub(crate) fn lead(&mut self, task: impl Future<Output = ()> + Send + 'static) -> Owner {
let (job, owner) = Job::new(task);
self.lead = Some(job);
owner
}

/// [`poll`](Self::poll) until it is ready.
pub async fn run(mut self) {
kio::wait(|waiter| self.poll(waiter)).await
}
}

impl Drop for Driver {
fn drop(&mut self) {
// Later starts are refused instead of queueing work nothing will run, and queued ones drop
// now, releasing what they hold (such as an init build's lock).
self.inbox.close();
while let Ok(Some(_)) = self.inbox.try_pop() {}
}
}

/// Starts tasks on its [`Driver`]. Clones share it; the driver's inbox closes with the last.
#[derive(Clone)]
pub(crate) struct Spawner {
inbox: Arc<Inbox>,
}

struct Inbox(kio::Queue<Job>);

impl Drop for Inbox {
fn drop(&mut self) {
self.0.close();
}
}

impl Spawner {
/// A spawner and the driver that runs what it starts.
pub fn new() -> (Self, Driver) {
let inbox = kio::Queue::new();
let driver = Driver {
lead: None,
inbox: inbox.clone(),
tasks: kio::Tasks::new(),
closed: false,
};
(
Self {
inbox: Arc::new(Inbox(inbox)),
},
driver,
)
}

/// Run `task` on the driver until it finishes or the returned [`Owner`] drops.
pub fn spawn(&self, task: impl Future<Output = ()> + Send + 'static) -> Owner {
let (job, owner) = Job::new(task);
// Refused once the driver is gone, which drops the task unrun.
let _ = self.inbox.0.try_push(job);
owner
}
}

/// Ends its task when dropped.
pub(crate) struct Owner(#[expect(dead_code, reason = "held only to close on drop")] kio::Producer<()>);

/// A task and the [`Owner`] that ends it.
struct Job {
owner: kio::Consumer<()>,
task: Pin<Box<dyn Future<Output = ()> + Send>>,
}

impl Job {
fn new(task: impl Future<Output = ()> + Send + 'static) -> (Self, Owner) {
let owner = kio::Producer::new(());
let job = Self {
owner: owner.consume(),
task: Box::pin(task),
};
(job, Owner(owner))
}
}

impl kio::Task for Job {
type Output = ();

fn poll(&mut self, waiter: &kio::Waiter) -> Poll<()> {
if self.owner.poll_closed(waiter).is_ready() {
return Poll::Ready(());
}
waiter.poll_future(self.task.as_mut())
}
}

#[cfg(test)]
mod tests {
use super::*;

// The driver finishes once every spawner and task is gone, and an owner's drop ends its task
// without waiting for the task to finish on its own.
#[test]
fn tasks_end_with_their_owner() {
let (spawner, mut driver) = Spawner::new();
let waiter = kio::Waiter::noop();
let forever = spawner.spawn(std::future::pending());
let lead = driver.lead(std::future::pending());
drop(spawner);
assert!(driver.poll(&waiter).is_pending(), "the owned tasks still run");
drop(lead);
assert!(driver.poll(&waiter).is_pending(), "the owned task still runs");
drop(forever);
assert!(driver.poll(&waiter).is_ready(), "the task ended with its owner");
}

// Dropping the driver drops the tasks it never polled, so nothing they hold leaks.
#[test]
fn a_dropped_driver_drops_queued_tasks() {
let (spawner, driver) = Spawner::new();
let held = Arc::new(());
let _owner = spawner.spawn({
let held = held.clone();
async move { drop(held) }
});
drop(driver);
assert_eq!(Arc::strong_count(&held), 1, "the queued task was dropped");
}
}
Loading