From 4b21a22108670824f2473ef4f91fd1e8ca7bf89d Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Thu, 29 Oct 2026 12:00:31 +0800 Subject: [PATCH 01/13] livekit-ffi: acknowledge polled outgoing batches after delivery The polled outgoing adapter acknowledged on_packets_available as soon as the packets were buffered. That broke the delegate contract: send_* and write resolved before anything reached the transport, transport errors were lost, and nothing slowed a producer down. next_packets() is replaced by next_batch(), which hands out an OutgoingPacketBatch. The delegate call now waits for the host to complete or fail that batch. A batch released without an outcome, or a closed queue, fails the pending send. The manager already awaits each delegate call, so at most one batch is pending and the queue no longer needs depth tracking. --- .changeset/polled_outgoing_batch_ack.md | 5 + .../src/core_modules/data_stream/polled.rs | 126 +++++++++++++----- .../src/core_modules/data_stream/tests.rs | 96 +++++++++++-- 3 files changed, 177 insertions(+), 50 deletions(-) create mode 100644 .changeset/polled_outgoing_batch_ack.md diff --git a/.changeset/polled_outgoing_batch_ack.md b/.changeset/polled_outgoing_batch_ack.md new file mode 100644 index 0000000000..2ac60d5f6e --- /dev/null +++ b/.changeset/polled_outgoing_batch_ack.md @@ -0,0 +1,5 @@ +--- +livekit-ffi: major +--- + +The `core-modules` polled outgoing data stream adapter now waits for the host to report each batch's outcome. `OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`, which returns an `OutgoingPacketBatch` with `packets()`, `complete()` and `fail(reason)`. A `send_*`/`write` call resolves only once its batch is completed, and fails when the batch fails, is released without an outcome, or the queue is closed. Before, the adapter acknowledged sends as soon as the packets were buffered, so send errors were lost and producers had no backpressure. diff --git a/livekit-ffi/src/core_modules/data_stream/polled.rs b/livekit-ffi/src/core_modules/data_stream/polled.rs index 2c21c5f287..f15a2a306c 100644 --- a/livekit-ffi/src/core_modules/data_stream/polled.rs +++ b/livekit-ffi/src/core_modules/data_stream/polled.rs @@ -29,6 +29,10 @@ //! invocation still happens on a tokio thread, which is fine precisely because the implementation //! is Rust. //! +//! The outgoing side also keeps the delegate's acknowledgement contract. Each delegate call becomes +//! an [`OutgoingPacketBatch`] that the foreign side resolves once its packets are on the wire, so a +//! send still waits for the transport and still fails when the transport does. +//! //! Note that [`RemoteParticipantRegistryDelegate`] needs no adapter: it is only ever called //! synchronously inside a `send_*` future, so it already runs on the polling thread. //! @@ -40,7 +44,7 @@ use std::sync::Arc; use bytes::Bytes; use tokio::sync::mpsc::{unbounded_channel, UnboundedReceiver, UnboundedSender}; -use tokio::sync::Mutex; +use tokio::sync::{oneshot, Mutex}; use tokio_util::sync::CancellationToken; use super::common::PacketDeliveryError; @@ -67,68 +71,118 @@ fn warn_if_deep(kind: &str, depth: usize) { // MARK: - Outgoing -/// Buffers outbound packets so they can be pulled instead of pushed. +/// One delegate call's worth of outbound packets, pulled by the foreign side. +/// +/// The `send_*`/`write` call that produced it stays pending until the foreign side reports the +/// outcome with [`Self::complete`] or [`Self::fail`], which keeps the delegate contract: a send +/// resolves only once its packets are on the transport, and a transport failure fails it. A batch +/// released without an outcome fails the send, so dropping one can never acknowledge packets that +/// were not sent. +#[derive(uniffi::Object)] +pub struct OutgoingPacketBatch { + packets: Vec, + outcome: std::sync::Mutex>>>, +} + +impl OutgoingPacketBatch { + fn resolve(&self, result: Result<(), PacketDeliveryError>) { + let sender = self.outcome.lock().unwrap_or_else(|poisoned| poisoned.into_inner()).take(); + if let Some(sender) = sender { + // The send may already be gone (its manager shut down), in which case nobody is waiting. + let _ = sender.send(result); + } + } +} + +impl Drop for OutgoingPacketBatch { + fn drop(&mut self) { + self.resolve(Err(PacketDeliveryError::Failed { + reason: "packet batch released without an outcome".to_string(), + })); + } +} + +#[uniffi::export] +impl OutgoingPacketBatch { + /// Encoded `livekit.DataPacket`s to put on the wire, in order. + pub fn packets(&self) -> Vec { + self.packets.clone() + } + + /// Reports every packet as handed to the transport, resolving the originating send. + /// + /// Only the first of [`Self::complete`] and [`Self::fail`] counts. + pub fn complete(&self) { + self.resolve(Ok(())); + } + + /// Reports that the packets could not be delivered, failing the originating send. + /// + /// Only the first of [`Self::complete`] and [`Self::fail`] counts. + pub fn fail(&self, reason: String) { + self.resolve(Err(PacketDeliveryError::Failed { reason })); + } +} + +/// Hands outbound packets to the foreign side one batch at a time. /// -/// Implements [`OutgoingDataStreamManagerDelegate`] in Rust; see the module docs. +/// Implements [`OutgoingDataStreamManagerDelegate`] in Rust; see the module docs. The manager +/// awaits each delegate call before making the next, and each call waits for its batch's outcome, +/// so at most one batch is pending at a time. #[derive(uniffi::Object)] pub struct OutgoingPacketQueue { - tx: UnboundedSender, - rx: Mutex>, - depth: AtomicUsize, + tx: UnboundedSender, + rx: Mutex>, shutdown: CancellationToken, } impl OutgoingPacketQueue { fn new() -> Self { let (tx, rx) = unbounded_channel(); - Self { - tx, - rx: Mutex::new(rx), - depth: AtomicUsize::new(0), - shutdown: CancellationToken::new(), - } + Self { tx, rx: Mutex::new(rx), shutdown: CancellationToken::new() } } } +fn queue_closed() -> PacketDeliveryError { + PacketDeliveryError::Failed { reason: "outgoing packet queue closed".to_string() } +} + #[async_trait::async_trait] impl OutgoingDataStreamManagerDelegate for OutgoingPacketQueue { - // Acknowledges once buffered: a pull adapter has no synchronous transport feedback, so send - // failures observed while draining must be handled host-side. async fn on_packets_available(&self, packets: Vec) -> Result<(), PacketDeliveryError> { - for packet in packets { - if self.tx.send(packet).is_ok() { - warn_if_deep("outgoing packet", self.depth.fetch_add(1, Ordering::Relaxed) + 1); - } + let (outcome_tx, outcome_rx) = oneshot::channel(); + let batch = + OutgoingPacketBatch { packets, outcome: std::sync::Mutex::new(Some(outcome_tx)) }; + self.tx.send(batch).map_err(|_| queue_closed())?; + tokio::select! { + _ = self.shutdown.cancelled() => Err(queue_closed()), + // An error here means the batch was dropped without resolving, which its `Drop` + // already turns into a failure, so this only covers the queue itself going away. + outcome = outcome_rx => outcome.unwrap_or_else(|_| Err(queue_closed())), } - Ok(()) } } #[uniffi::export(async_runtime = "tokio")] impl OutgoingPacketQueue { - /// Awaits the next batch of encoded `livekit.DataPacket`s to put on the wire. + /// Awaits the next batch of packets to put on the wire. /// - /// Returns `None` once the manager has shut down, which ends the caller's drain loop. - /// Everything already queued is returned together, so a burst costs one FFI crossing rather - /// than one per packet. - pub async fn next_packets(&self) -> Option> { + /// Report the outcome on the returned batch once its packets are sent (or have failed); the + /// next batch is not produced until then. Returns `None` once the queue is closed, which ends + /// the caller's drain loop. + pub async fn next_batch(&self) -> Option> { let mut rx = self.rx.lock().await; - let first = tokio::select! { - _ = self.shutdown.cancelled() => return None, - received = rx.recv() => received?, - }; - let mut batch = vec![first]; - while let Ok(next) = rx.try_recv() { - batch.push(next); + tokio::select! { + _ = self.shutdown.cancelled() => None, + received = rx.recv() => received.map(Arc::new), } - self.depth.fetch_sub(batch.len(), Ordering::Relaxed); - Some(batch) } - /// Wakes a pending [`Self::next_packets`] with `None` so the caller's drain loop can exit. + /// Wakes a pending [`Self::next_batch`] with `None` so the caller's drain loop can exit, and + /// fails any send still waiting on a batch. /// - /// Call this before releasing the queue: a caller blocked in `next_packets` is holding a - /// pointer to it, so freeing it first is a use-after-free. + /// Call this before releasing the queue: a caller blocked in `next_batch` is holding a pointer + /// to it, so freeing it first is a use-after-free. pub fn close(&self) { self.shutdown.cancel(); } diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 0f229a6289..8151d1b6b4 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -27,7 +27,7 @@ use tokio::sync::{mpsc, oneshot}; use super::common::{ ClientCapability, DataStreamError, EncryptionType, PacketDeliveryError, StreamByteOptions, - StreamProgress, StreamTextOptions, + StreamProgress, StreamTextOptions, TextStreamInfo, }; use super::incoming::{ ByteStreamReader, IncomingDataStreamManager, IncomingDataStreamManagerDelegate, @@ -921,20 +921,26 @@ async fn polled_roundtrip( destination_identities: vec!["bob".to_string()], ..Default::default() }; - outgoing.manager.send_text(text.to_string(), options).await.expect("send_text should succeed"); - - // send_text only resolves once every packet has been queued, so draining terminates rather - // than blocking. - let mut packet_count = 0; - while let Ok(Some(packets)) = - tokio::time::timeout(std::time::Duration::from_millis(200), outgoing.packets.next_packets()) - .await - { - for packet in packets { - packet_count += 1; - incoming.manager.handle_packet_received(packet, EncryptionType::None); + // send_text waits for each batch's outcome, so drain alongside it rather than after. + let send = outgoing.manager.send_text(text.to_string(), options); + let drain = async { + let mut packet_count = 0; + while let Ok(Some(batch)) = tokio::time::timeout( + std::time::Duration::from_millis(200), + outgoing.packets.next_batch(), + ) + .await + { + for packet in batch.packets() { + packet_count += 1; + incoming.manager.handle_packet_received(packet, EncryptionType::None); + } + batch.complete(); } - } + packet_count + }; + let (sent, packet_count) = tokio::join!(send, drain); + sent.expect("send_text should succeed"); let opened = incoming.streams.next_opened_stream().await.expect("a stream should open"); let reader = opened.text_reader.expect("expected a text stream"); @@ -959,3 +965,65 @@ fn polled_falls_back_to_legacy_framing_for_pre_v2_recipients() { assert_eq!(text, "hello world"); }); } + +/// Starts a `send_text` through a polled outgoing manager and returns the first batch it produces. +async fn polled_send_and_pull() -> ( + super::polled::PolledOutgoingDataStreamManager, + tokio::task::JoinHandle>, + Arc, +) { + let outgoing = super::polled::polled_outgoing_data_stream_manager(Arc::new(AllV2Registry)); + let manager = outgoing.manager.clone(); + let send = tokio::spawn(async move { + let options = StreamTextOptions { + topic: "chat".to_string(), + destination_identities: vec!["bob".to_string()], + ..Default::default() + }; + manager.send_text("hello".to_string(), options).await + }); + let batch = outgoing.packets.next_batch().await.expect("send_text should produce a batch"); + (outgoing, send, batch) +} + +#[test] +fn polled_send_waits_for_the_batch_outcome() { + crate::runtime::runtime().block_on(async { + let (_outgoing, send, batch) = polled_send_and_pull().await; + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + assert!(!send.is_finished(), "send_text must stay pending until the batch is resolved"); + + batch.complete(); + send.await.unwrap().expect("a completed batch should resolve the send"); + }); +} + +#[test] +fn polled_failed_batch_fails_the_send() { + crate::runtime::runtime().block_on(async { + let (_outgoing, send, batch) = polled_send_and_pull().await; + batch.fail("wire down".to_string()); + // Resolving twice must not panic, and only the first outcome counts. + batch.complete(); + assert!(send.await.unwrap().is_err(), "a failed batch should fail the send"); + }); +} + +#[test] +fn polled_dropped_batch_fails_the_send() { + crate::runtime::runtime().block_on(async { + let (_outgoing, send, batch) = polled_send_and_pull().await; + drop(batch); + assert!(send.await.unwrap().is_err(), "a batch released unresolved should fail the send"); + }); +} + +#[test] +fn polled_close_fails_a_pending_send() { + crate::runtime::runtime().block_on(async { + let (outgoing, send, _batch) = polled_send_and_pull().await; + outgoing.packets.close(); + assert!(send.await.unwrap().is_err(), "closing the queue should fail a pending send"); + assert!(outgoing.packets.next_batch().await.is_none()); + }); +} From f03ff49856c3fa118f89f7fe3290761b56b9f38a Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:14:44 +0800 Subject: [PATCH 02/13] livekit-ffi: stop waiting on the delegate when the manager shuts down The forwarding task awaited on_packets_available outside the race with its cancellation token. The polled delegate now waits for the host, so a manager dropped while a batch sat unpulled left the task holding the queue and the batch forever. The call is raced against shutdown, and a test drops the manager with an unpulled batch and checks the queue is released. --- .../src/core_modules/data_stream/outgoing.rs | 13 ++++---- .../src/core_modules/data_stream/tests.rs | 30 +++++++++++++++++++ 2 files changed, 38 insertions(+), 5 deletions(-) diff --git a/livekit-ffi/src/core_modules/data_stream/outgoing.rs b/livekit-ffi/src/core_modules/data_stream/outgoing.rs index 7a189feaff..1c9706e0f0 100644 --- a/livekit-ffi/src/core_modules/data_stream/outgoing.rs +++ b/livekit-ffi/src/core_modules/data_stream/outgoing.rs @@ -129,11 +129,14 @@ impl OutgoingDataStreamManager { .iter() .map(|packet| Bytes::from(packet.encode_to_vec())) .collect(); - let result = delegate - .on_packets_available(encoded) - .await - .map_err(|_| ds_api::SendError); - let _ = responder.respond(result); + // A delegate may wait on the host for as long as it likes, so the + // call is raced against shutdown. Otherwise a manager dropped mid + // call would leave this task holding the delegate forever. + let result = tokio::select! { + _ = forward_token.cancelled() => break, + result = delegate.on_packets_available(encoded) => result, + }; + let _ = responder.respond(result.map_err(|_| ds_api::SendError)); } Err(_) => break, } diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 8151d1b6b4..5bd4a080fe 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -1027,3 +1027,33 @@ fn polled_close_fails_a_pending_send() { assert!(outgoing.packets.next_batch().await.is_none()); }); } + +#[test] +fn polled_manager_drop_releases_an_unpulled_batch() { + crate::runtime::runtime().block_on(async { + let outgoing = super::polled::polled_outgoing_data_stream_manager(Arc::new(AllV2Registry)); + let manager = outgoing.manager.clone(); + let send = tokio::spawn(async move { + let options = StreamTextOptions { + topic: "chat".to_string(), + destination_identities: vec!["bob".to_string()], + ..Default::default() + }; + manager.send_text("hello".to_string(), options).await + }); + // Let the batch reach the queue, then cancel the send without ever pulling it. + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + send.abort(); + assert!(send.await.unwrap_err().is_cancelled()); + + let queue = Arc::downgrade(&outgoing.packets); + drop(outgoing); + for _ in 0..100 { + if queue.upgrade().is_none() { + return; + } + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + } + panic!("the forwarding task still holds the queue after the manager was dropped"); + }); +} From e97b51a45fee1a740b18ae53c4ed5f79689892f1 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:31:16 +0800 Subject: [PATCH 03/13] Revert "livekit-ffi: stop waiting on the delegate when the manager shuts down" This reverts commit f03ff49856c3fa118f89f7fe3290761b56b9f38a. The forwarding task is shared with hosts that pass their own delegate, and they do not have the leak. The fix moves into the polled adapter. --- .../src/core_modules/data_stream/outgoing.rs | 13 ++++---- .../src/core_modules/data_stream/tests.rs | 30 ------------------- 2 files changed, 5 insertions(+), 38 deletions(-) diff --git a/livekit-ffi/src/core_modules/data_stream/outgoing.rs b/livekit-ffi/src/core_modules/data_stream/outgoing.rs index 1c9706e0f0..7a189feaff 100644 --- a/livekit-ffi/src/core_modules/data_stream/outgoing.rs +++ b/livekit-ffi/src/core_modules/data_stream/outgoing.rs @@ -129,14 +129,11 @@ impl OutgoingDataStreamManager { .iter() .map(|packet| Bytes::from(packet.encode_to_vec())) .collect(); - // A delegate may wait on the host for as long as it likes, so the - // call is raced against shutdown. Otherwise a manager dropped mid - // call would leave this task holding the delegate forever. - let result = tokio::select! { - _ = forward_token.cancelled() => break, - result = delegate.on_packets_available(encoded) => result, - }; - let _ = responder.respond(result.map_err(|_| ds_api::SendError)); + let result = delegate + .on_packets_available(encoded) + .await + .map_err(|_| ds_api::SendError); + let _ = responder.respond(result); } Err(_) => break, } diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 5bd4a080fe..8151d1b6b4 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -1027,33 +1027,3 @@ fn polled_close_fails_a_pending_send() { assert!(outgoing.packets.next_batch().await.is_none()); }); } - -#[test] -fn polled_manager_drop_releases_an_unpulled_batch() { - crate::runtime::runtime().block_on(async { - let outgoing = super::polled::polled_outgoing_data_stream_manager(Arc::new(AllV2Registry)); - let manager = outgoing.manager.clone(); - let send = tokio::spawn(async move { - let options = StreamTextOptions { - topic: "chat".to_string(), - destination_identities: vec!["bob".to_string()], - ..Default::default() - }; - manager.send_text("hello".to_string(), options).await - }); - // Let the batch reach the queue, then cancel the send without ever pulling it. - tokio::time::sleep(std::time::Duration::from_millis(50)).await; - send.abort(); - assert!(send.await.unwrap_err().is_cancelled()); - - let queue = Arc::downgrade(&outgoing.packets); - drop(outgoing); - for _ in 0..100 { - if queue.upgrade().is_none() { - return; - } - tokio::time::sleep(std::time::Duration::from_millis(10)).await; - } - panic!("the forwarding task still holds the queue after the manager was dropped"); - }); -} From e1bb5099d7517df82a16c63e1fe023c32178a886 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:31:55 +0800 Subject: [PATCH 04/13] livekit-ffi: split the polled outgoing queue into two halves The queue held both ends of its channel and was also the delegate the manager's forwarding task owns. A batch nobody pulled could then never be dropped: the task waited on its outcome while keeping the queue, and so the batch, alive. The manager now gets a sending half and the host keeps the receiving half. Releasing the queue drops an unpulled batch, which fails its send and lets the task finish. --- .../src/core_modules/data_stream/polled.rs | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/livekit-ffi/src/core_modules/data_stream/polled.rs b/livekit-ffi/src/core_modules/data_stream/polled.rs index f15a2a306c..37ac224017 100644 --- a/livekit-ffi/src/core_modules/data_stream/polled.rs +++ b/livekit-ffi/src/core_modules/data_stream/polled.rs @@ -126,20 +126,32 @@ impl OutgoingPacketBatch { /// Hands outbound packets to the foreign side one batch at a time. /// -/// Implements [`OutgoingDataStreamManagerDelegate`] in Rust; see the module docs. The manager -/// awaits each delegate call before making the next, and each call waits for its batch's outcome, -/// so at most one batch is pending at a time. +/// This is the receiving half, held by the foreign side. The manager holds the sending half, +/// [`OutgoingPacketSink`]. The manager awaits each delegate call before making the next, and each +/// call waits for its batch's outcome, so at most one batch is pending at a time. #[derive(uniffi::Object)] pub struct OutgoingPacketQueue { - tx: UnboundedSender, rx: Mutex>, shutdown: CancellationToken, } +/// The sending half of an [`OutgoingPacketQueue`], which implements +/// [`OutgoingDataStreamManagerDelegate`] in Rust; see the module docs. +/// +/// The halves are separate objects so that the manager's forwarding task, which holds this one, +/// does not keep the receiving half alive. Releasing the queue then drops any batch nobody pulled, +/// which fails its send and lets the task finish. +pub(super) struct OutgoingPacketSink { + tx: UnboundedSender, + shutdown: CancellationToken, +} + impl OutgoingPacketQueue { - fn new() -> Self { + pub(super) fn pair() -> (Arc, Arc) { let (tx, rx) = unbounded_channel(); - Self { tx, rx: Mutex::new(rx), shutdown: CancellationToken::new() } + let shutdown = CancellationToken::new(); + let sink = OutgoingPacketSink { tx, shutdown: shutdown.clone() }; + (Arc::new(sink), Arc::new(Self { rx: Mutex::new(rx), shutdown })) } } @@ -148,7 +160,7 @@ fn queue_closed() -> PacketDeliveryError { } #[async_trait::async_trait] -impl OutgoingDataStreamManagerDelegate for OutgoingPacketQueue { +impl OutgoingDataStreamManagerDelegate for OutgoingPacketSink { async fn on_packets_available(&self, packets: Vec) -> Result<(), PacketDeliveryError> { let (outcome_tx, outcome_rx) = oneshot::channel(); let batch = @@ -204,8 +216,8 @@ pub struct PolledOutgoingDataStreamManager { pub fn polled_outgoing_data_stream_manager( registry: Arc, ) -> PolledOutgoingDataStreamManager { - let packets = Arc::new(OutgoingPacketQueue::new()); - let manager = OutgoingDataStreamManager::new(packets.clone(), registry); + let (sink, packets) = OutgoingPacketQueue::pair(); + let manager = OutgoingDataStreamManager::new(sink, registry); PolledOutgoingDataStreamManager { manager, packets } } From 37c59512f9cbafa6630aaf246d37a791055aa262 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:32:34 +0800 Subject: [PATCH 05/13] livekit-ffi: test that a released polled queue frees an unpulled batch A send is cancelled before its batch is pulled, then the manager and the queue are released. The forwarding task must finish and drop the sending half. --- .../src/core_modules/data_stream/tests.rs | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 8151d1b6b4..57e6414975 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -1027,3 +1027,36 @@ fn polled_close_fails_a_pending_send() { assert!(outgoing.packets.next_batch().await.is_none()); }); } + +#[test] +fn polled_released_queue_frees_an_unpulled_batch() { + crate::runtime::runtime().block_on(async { + let (sink, queue) = super::polled::OutgoingPacketQueue::pair(); + let sink_alive = Arc::downgrade(&sink); + let manager = OutgoingDataStreamManager::new(sink, Arc::new(AllV2Registry)); + let sender = manager.clone(); + let send = tokio::spawn(async move { + let options = StreamTextOptions { + topic: "chat".to_string(), + destination_identities: vec!["bob".to_string()], + ..Default::default() + }; + sender.send_text("hello".to_string(), options).await + }); + // Let the batch reach the queue, then cancel the send without ever pulling it. + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + send.abort(); + assert!(send.await.unwrap_err().is_cancelled()); + + drop(manager); + drop(queue); + // The forwarding task owns the sink, so the sink going away shows the task finished. + for _ in 0..100 { + if sink_alive.upgrade().is_none() { + return; + } + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + } + panic!("the forwarding task is still waiting on a batch nobody can pull"); + }); +} From 6902e15e01f9e0aaeb06a168ed0f8ffbb33afd69 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:36:43 +0800 Subject: [PATCH 06/13] Shorten the changeset --- .changeset/polled_outgoing_batch_ack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/polled_outgoing_batch_ack.md b/.changeset/polled_outgoing_batch_ack.md index 2ac60d5f6e..8125a5e217 100644 --- a/.changeset/polled_outgoing_batch_ack.md +++ b/.changeset/polled_outgoing_batch_ack.md @@ -2,4 +2,4 @@ livekit-ffi: major --- -The `core-modules` polled outgoing data stream adapter now waits for the host to report each batch's outcome. `OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`, which returns an `OutgoingPacketBatch` with `packets()`, `complete()` and `fail(reason)`. A `send_*`/`write` call resolves only once its batch is completed, and fails when the batch fails, is released without an outcome, or the queue is closed. Before, the adapter acknowledged sends as soon as the packets were buffered, so send errors were lost and producers had no backpressure. +The polled outgoing data stream adapter resolves a send once the host reports its batch as sent, and no longer when the packets are buffered. `OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`, whose `OutgoingPacketBatch` the host must `complete()` or `fail(reason)`. From baa2de739a456ecdb14043ab5774c96e6e33183c Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:13:43 +0800 Subject: [PATCH 07/13] livekit-ffi: hand a polled batch its packets by value A batch was an object whose packets() cloned the list on every call, and because the batch kept the originals, lowering each packet copied its payload. A batch is now a record that owns the packets, with a separate OutgoingBatchOutcome object to report on. Dropping the outcome no longer builds an error when one was already reported. --- .../src/core_modules/data_stream/polled.rs | 81 +++++++++++-------- .../src/core_modules/data_stream/tests.rs | 12 +-- 2 files changed, 55 insertions(+), 38 deletions(-) diff --git a/livekit-ffi/src/core_modules/data_stream/polled.rs b/livekit-ffi/src/core_modules/data_stream/polled.rs index 37ac224017..4225f8839d 100644 --- a/livekit-ffi/src/core_modules/data_stream/polled.rs +++ b/livekit-ffi/src/core_modules/data_stream/polled.rs @@ -73,20 +73,31 @@ fn warn_if_deep(kind: &str, depth: usize) { /// One delegate call's worth of outbound packets, pulled by the foreign side. /// -/// The `send_*`/`write` call that produced it stays pending until the foreign side reports the -/// outcome with [`Self::complete`] or [`Self::fail`], which keeps the delegate contract: a send -/// resolves only once its packets are on the transport, and a transport failure fails it. A batch -/// released without an outcome fails the send, so dropping one can never acknowledge packets that -/// were not sent. -#[derive(uniffi::Object)] +/// The `send_*`/`write` call that produced it stays pending until the foreign side reports on +/// [`Self::outcome`], which keeps the delegate contract: a send resolves only once its packets are +/// handed to the transport, and a transport failure fails it. +#[derive(uniffi::Record)] pub struct OutgoingPacketBatch { - packets: Vec, - outcome: std::sync::Mutex>>>, + /// Encoded `livekit.DataPacket`s to hand to the transport, in order. + pub packets: Vec, + /// Where to report what happened to them. + pub outcome: Arc, +} + +type OutcomeSender = oneshot::Sender>; + +/// Reports what happened to the packets of an [`OutgoingPacketBatch`]. +/// +/// Released without an outcome it fails the send, so dropping a batch can never acknowledge packets +/// that were not sent. +#[derive(uniffi::Object)] +pub struct OutgoingBatchOutcome { + sender: std::sync::Mutex>, } -impl OutgoingPacketBatch { +impl OutgoingBatchOutcome { fn resolve(&self, result: Result<(), PacketDeliveryError>) { - let sender = self.outcome.lock().unwrap_or_else(|poisoned| poisoned.into_inner()).take(); + let sender = self.sender.lock().unwrap_or_else(|poisoned| poisoned.into_inner()).take(); if let Some(sender) = sender { // The send may already be gone (its manager shut down), in which case nobody is waiting. let _ = sender.send(result); @@ -94,21 +105,19 @@ impl OutgoingPacketBatch { } } -impl Drop for OutgoingPacketBatch { +impl Drop for OutgoingBatchOutcome { fn drop(&mut self) { - self.resolve(Err(PacketDeliveryError::Failed { - reason: "packet batch released without an outcome".to_string(), - })); + let sender = self.sender.get_mut().unwrap_or_else(|poisoned| poisoned.into_inner()).take(); + if let Some(sender) = sender { + let _ = sender.send(Err(PacketDeliveryError::Failed { + reason: "packet batch released without an outcome".to_string(), + })); + } } } #[uniffi::export] -impl OutgoingPacketBatch { - /// Encoded `livekit.DataPacket`s to put on the wire, in order. - pub fn packets(&self) -> Vec { - self.packets.clone() - } - +impl OutgoingBatchOutcome { /// Reports every packet as handed to the transport, resolving the originating send. /// /// Only the first of [`Self::complete`] and [`Self::fail`] counts. @@ -124,6 +133,12 @@ impl OutgoingPacketBatch { } } +/// A batch on its way from the sink to the queue, before the foreign side has pulled it. +struct PendingBatch { + packets: Vec, + outcome: OutcomeSender, +} + /// Hands outbound packets to the foreign side one batch at a time. /// /// This is the receiving half, held by the foreign side. The manager holds the sending half, @@ -131,7 +146,7 @@ impl OutgoingPacketBatch { /// call waits for its batch's outcome, so at most one batch is pending at a time. #[derive(uniffi::Object)] pub struct OutgoingPacketQueue { - rx: Mutex>, + rx: Mutex>, shutdown: CancellationToken, } @@ -142,7 +157,7 @@ pub struct OutgoingPacketQueue { /// does not keep the receiving half alive. Releasing the queue then drops any batch nobody pulled, /// which fails its send and lets the task finish. pub(super) struct OutgoingPacketSink { - tx: UnboundedSender, + tx: UnboundedSender, shutdown: CancellationToken, } @@ -163,13 +178,10 @@ fn queue_closed() -> PacketDeliveryError { impl OutgoingDataStreamManagerDelegate for OutgoingPacketSink { async fn on_packets_available(&self, packets: Vec) -> Result<(), PacketDeliveryError> { let (outcome_tx, outcome_rx) = oneshot::channel(); - let batch = - OutgoingPacketBatch { packets, outcome: std::sync::Mutex::new(Some(outcome_tx)) }; - self.tx.send(batch).map_err(|_| queue_closed())?; + self.tx.send(PendingBatch { packets, outcome: outcome_tx }).map_err(|_| queue_closed())?; tokio::select! { _ = self.shutdown.cancelled() => Err(queue_closed()), - // An error here means the batch was dropped without resolving, which its `Drop` - // already turns into a failure, so this only covers the queue itself going away. + // The sender is dropped unused only when the queue goes away with the batch unpulled. outcome = outcome_rx => outcome.unwrap_or_else(|_| Err(queue_closed())), } } @@ -182,12 +194,17 @@ impl OutgoingPacketQueue { /// Report the outcome on the returned batch once its packets are sent (or have failed); the /// next batch is not produced until then. Returns `None` once the queue is closed, which ends /// the caller's drain loop. - pub async fn next_batch(&self) -> Option> { + pub async fn next_batch(&self) -> Option { let mut rx = self.rx.lock().await; - tokio::select! { - _ = self.shutdown.cancelled() => None, - received = rx.recv() => received.map(Arc::new), - } + let pending = tokio::select! { + _ = self.shutdown.cancelled() => return None, + received = rx.recv() => received?, + }; + let sender = std::sync::Mutex::new(Some(pending.outcome)); + Some(OutgoingPacketBatch { + packets: pending.packets, + outcome: Arc::new(OutgoingBatchOutcome { sender }), + }) } /// Wakes a pending [`Self::next_batch`] with `None` so the caller's drain loop can exit, and diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 57e6414975..3144cdf424 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -931,11 +931,11 @@ async fn polled_roundtrip( ) .await { - for packet in batch.packets() { + for packet in batch.packets { packet_count += 1; incoming.manager.handle_packet_received(packet, EncryptionType::None); } - batch.complete(); + batch.outcome.complete(); } packet_count }; @@ -970,7 +970,7 @@ fn polled_falls_back_to_legacy_framing_for_pre_v2_recipients() { async fn polled_send_and_pull() -> ( super::polled::PolledOutgoingDataStreamManager, tokio::task::JoinHandle>, - Arc, + super::polled::OutgoingPacketBatch, ) { let outgoing = super::polled::polled_outgoing_data_stream_manager(Arc::new(AllV2Registry)); let manager = outgoing.manager.clone(); @@ -993,7 +993,7 @@ fn polled_send_waits_for_the_batch_outcome() { tokio::time::sleep(std::time::Duration::from_millis(50)).await; assert!(!send.is_finished(), "send_text must stay pending until the batch is resolved"); - batch.complete(); + batch.outcome.complete(); send.await.unwrap().expect("a completed batch should resolve the send"); }); } @@ -1002,9 +1002,9 @@ fn polled_send_waits_for_the_batch_outcome() { fn polled_failed_batch_fails_the_send() { crate::runtime::runtime().block_on(async { let (_outgoing, send, batch) = polled_send_and_pull().await; - batch.fail("wire down".to_string()); + batch.outcome.fail("wire down".to_string()); // Resolving twice must not panic, and only the first outcome counts. - batch.complete(); + batch.outcome.complete(); assert!(send.await.unwrap().is_err(), "a failed batch should fail the send"); }); } From b14b0af1371e5ebcbb65a20b5fcdc26903405c57 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:14:52 +0800 Subject: [PATCH 08/13] livekit-ffi: end the polled wait when its manager is dropped The sink waited on the queue's own token only, so a manager dropped while the host still held the queue or a pulled batch left the forwarding task waiting. The manager can now be built with the token it cancels on drop, and the sink watches it. The forwarding task itself is unchanged, so a host that passes its own delegate sees no difference. --- .../src/core_modules/data_stream/outgoing.rs | 19 +++- .../src/core_modules/data_stream/polled.rs | 21 +++-- .../src/core_modules/data_stream/tests.rs | 88 +++++++++++++------ 3 files changed, 94 insertions(+), 34 deletions(-) diff --git a/livekit-ffi/src/core_modules/data_stream/outgoing.rs b/livekit-ffi/src/core_modules/data_stream/outgoing.rs index 7a189feaff..0a82934c6f 100644 --- a/livekit-ffi/src/core_modules/data_stream/outgoing.rs +++ b/livekit-ffi/src/core_modules/data_stream/outgoing.rs @@ -105,14 +105,14 @@ impl lk_common::RemoteParticipantRegistry for ForeignRegistry { } } -#[uniffi::export(async_runtime = "tokio")] impl OutgoingDataStreamManager { - #[uniffi::constructor] - pub fn new( + /// Builds a manager that cancels `token` when it is dropped, for a delegate that has to know + /// when its manager is gone. + pub(super) fn with_shutdown( delegate: Arc, registry: Arc, + token: CancellationToken, ) -> Arc { - let token = CancellationToken::new(); let (manager, mut packet_rx) = ds::outgoing::Manager::new(); // Forward each outbound packet batch to the transport delegate, acknowledging the send @@ -145,6 +145,17 @@ impl OutgoingDataStreamManager { Arc::new(ForeignRegistry(registry)); Self { manager, registry, _guard: token.drop_guard() }.into() } +} + +#[uniffi::export(async_runtime = "tokio")] +impl OutgoingDataStreamManager { + #[uniffi::constructor] + pub fn new( + delegate: Arc, + registry: Arc, + ) -> Arc { + Self::with_shutdown(delegate, registry, CancellationToken::new()) + } /// Sends a complete text payload, returning info about the created stream. /// diff --git a/livekit-ffi/src/core_modules/data_stream/polled.rs b/livekit-ffi/src/core_modules/data_stream/polled.rs index 4225f8839d..ae537cc001 100644 --- a/livekit-ffi/src/core_modules/data_stream/polled.rs +++ b/livekit-ffi/src/core_modules/data_stream/polled.rs @@ -155,17 +155,22 @@ pub struct OutgoingPacketQueue { /// /// The halves are separate objects so that the manager's forwarding task, which holds this one, /// does not keep the receiving half alive. Releasing the queue then drops any batch nobody pulled, -/// which fails its send and lets the task finish. +/// which fails its send and lets the task finish. The task also finishes when the manager is +/// dropped, whatever the foreign side still holds. pub(super) struct OutgoingPacketSink { tx: UnboundedSender, shutdown: CancellationToken, + manager_shutdown: CancellationToken, } impl OutgoingPacketQueue { - pub(super) fn pair() -> (Arc, Arc) { + /// `manager_shutdown` is the token the manager cancels when it is dropped. + pub(super) fn pair( + manager_shutdown: CancellationToken, + ) -> (Arc, Arc) { let (tx, rx) = unbounded_channel(); let shutdown = CancellationToken::new(); - let sink = OutgoingPacketSink { tx, shutdown: shutdown.clone() }; + let sink = OutgoingPacketSink { tx, shutdown: shutdown.clone(), manager_shutdown }; (Arc::new(sink), Arc::new(Self { rx: Mutex::new(rx), shutdown })) } } @@ -174,6 +179,10 @@ fn queue_closed() -> PacketDeliveryError { PacketDeliveryError::Failed { reason: "outgoing packet queue closed".to_string() } } +fn manager_closed() -> PacketDeliveryError { + PacketDeliveryError::Failed { reason: "outgoing data stream manager closed".to_string() } +} + #[async_trait::async_trait] impl OutgoingDataStreamManagerDelegate for OutgoingPacketSink { async fn on_packets_available(&self, packets: Vec) -> Result<(), PacketDeliveryError> { @@ -181,6 +190,7 @@ impl OutgoingDataStreamManagerDelegate for OutgoingPacketSink { self.tx.send(PendingBatch { packets, outcome: outcome_tx }).map_err(|_| queue_closed())?; tokio::select! { _ = self.shutdown.cancelled() => Err(queue_closed()), + _ = self.manager_shutdown.cancelled() => Err(manager_closed()), // The sender is dropped unused only when the queue goes away with the batch unpulled. outcome = outcome_rx => outcome.unwrap_or_else(|_| Err(queue_closed())), } @@ -233,8 +243,9 @@ pub struct PolledOutgoingDataStreamManager { pub fn polled_outgoing_data_stream_manager( registry: Arc, ) -> PolledOutgoingDataStreamManager { - let (sink, packets) = OutgoingPacketQueue::pair(); - let manager = OutgoingDataStreamManager::new(sink, registry); + let manager_shutdown = CancellationToken::new(); + let (sink, packets) = OutgoingPacketQueue::pair(manager_shutdown.clone()); + let manager = OutgoingDataStreamManager::with_shutdown(sink, registry, manager_shutdown); PolledOutgoingDataStreamManager { manager, packets } } diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 3144cdf424..5ffff7195a 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -1028,35 +1028,73 @@ fn polled_close_fails_a_pending_send() { }); } +/// Starts a `send_text` on `manager` in its own task. +fn spawn_polled_send( + manager: Arc, +) -> tokio::task::JoinHandle> { + tokio::spawn(async move { + let options = StreamTextOptions { + topic: "chat".to_string(), + destination_identities: vec!["bob".to_string()], + ..Default::default() + }; + manager.send_text("hello".to_string(), options).await + }) +} + +/// A polled manager and queue with a send that was cancelled after its batch reached the queue. +/// The forwarding task owns the sink, so the sink going away shows that the task finished. +async fn polled_with_an_abandoned_batch() -> ( + std::sync::Weak, + Arc, + Arc, +) { + let shutdown = tokio_util::sync::CancellationToken::new(); + let (sink, queue) = super::polled::OutgoingPacketQueue::pair(shutdown.clone()); + let sink_alive = Arc::downgrade(&sink); + let manager = OutgoingDataStreamManager::with_shutdown(sink, Arc::new(AllV2Registry), shutdown); + let send = spawn_polled_send(manager.clone()); + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + send.abort(); + assert!(send.await.unwrap_err().is_cancelled()); + (sink_alive, manager, queue) +} + +async fn assert_forwarding_task_finished(sink: std::sync::Weak) { + for _ in 0..100 { + if sink.upgrade().is_none() { + return; + } + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + } + panic!("the forwarding task is still waiting on a batch"); +} + #[test] fn polled_released_queue_frees_an_unpulled_batch() { crate::runtime::runtime().block_on(async { - let (sink, queue) = super::polled::OutgoingPacketQueue::pair(); - let sink_alive = Arc::downgrade(&sink); - let manager = OutgoingDataStreamManager::new(sink, Arc::new(AllV2Registry)); - let sender = manager.clone(); - let send = tokio::spawn(async move { - let options = StreamTextOptions { - topic: "chat".to_string(), - destination_identities: vec!["bob".to_string()], - ..Default::default() - }; - sender.send_text("hello".to_string(), options).await - }); - // Let the batch reach the queue, then cancel the send without ever pulling it. - tokio::time::sleep(std::time::Duration::from_millis(50)).await; - send.abort(); - assert!(send.await.unwrap_err().is_cancelled()); - + let (sink, manager, queue) = polled_with_an_abandoned_batch().await; drop(manager); drop(queue); - // The forwarding task owns the sink, so the sink going away shows the task finished. - for _ in 0..100 { - if sink_alive.upgrade().is_none() { - return; - } - tokio::time::sleep(std::time::Duration::from_millis(10)).await; - } - panic!("the forwarding task is still waiting on a batch nobody can pull"); + assert_forwarding_task_finished(sink).await; + }); +} + +#[test] +fn polled_manager_drop_ends_the_wait_for_an_unpulled_batch() { + crate::runtime::runtime().block_on(async { + let (sink, manager, _queue) = polled_with_an_abandoned_batch().await; + drop(manager); + assert_forwarding_task_finished(sink).await; + }); +} + +#[test] +fn polled_manager_drop_ends_the_wait_for_a_held_batch() { + crate::runtime::runtime().block_on(async { + let (sink, manager, queue) = polled_with_an_abandoned_batch().await; + let _batch = queue.next_batch().await.expect("the abandoned batch is still queued"); + drop(manager); + assert_forwarding_task_finished(sink).await; }); } From 4b45c93dc437aa0c8c905dcfb6b26fb7dd40509c Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:14:55 +0800 Subject: [PATCH 09/13] livekit-ffi: share the send setup between the polled tests --- .../src/core_modules/data_stream/tests.rs | 38 ++++++++----------- 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 5ffff7195a..0360dffca4 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -966,6 +966,20 @@ fn polled_falls_back_to_legacy_framing_for_pre_v2_recipients() { }); } +/// Starts a `send_text` on `manager` in its own task. +fn spawn_polled_send( + manager: Arc, +) -> tokio::task::JoinHandle> { + tokio::spawn(async move { + let options = StreamTextOptions { + topic: "chat".to_string(), + destination_identities: vec!["bob".to_string()], + ..Default::default() + }; + manager.send_text("hello".to_string(), options).await + }) +} + /// Starts a `send_text` through a polled outgoing manager and returns the first batch it produces. async fn polled_send_and_pull() -> ( super::polled::PolledOutgoingDataStreamManager, @@ -973,15 +987,7 @@ async fn polled_send_and_pull() -> ( super::polled::OutgoingPacketBatch, ) { let outgoing = super::polled::polled_outgoing_data_stream_manager(Arc::new(AllV2Registry)); - let manager = outgoing.manager.clone(); - let send = tokio::spawn(async move { - let options = StreamTextOptions { - topic: "chat".to_string(), - destination_identities: vec!["bob".to_string()], - ..Default::default() - }; - manager.send_text("hello".to_string(), options).await - }); + let send = spawn_polled_send(outgoing.manager.clone()); let batch = outgoing.packets.next_batch().await.expect("send_text should produce a batch"); (outgoing, send, batch) } @@ -1028,20 +1034,6 @@ fn polled_close_fails_a_pending_send() { }); } -/// Starts a `send_text` on `manager` in its own task. -fn spawn_polled_send( - manager: Arc, -) -> tokio::task::JoinHandle> { - tokio::spawn(async move { - let options = StreamTextOptions { - topic: "chat".to_string(), - destination_identities: vec!["bob".to_string()], - ..Default::default() - }; - manager.send_text("hello".to_string(), options).await - }) -} - /// A polled manager and queue with a send that was cancelled after its batch reached the queue. /// The forwarding task owns the sink, so the sink going away shows that the task finished. async fn polled_with_an_abandoned_batch() -> ( From 4138f422267b60668cada173b2ff4164aa4a7d38 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:15:10 +0800 Subject: [PATCH 10/13] livekit-ffi: bring the polled adapter docs in line with next_batch --- livekit-ffi/src/core_modules/data_stream/polled.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/livekit-ffi/src/core_modules/data_stream/polled.rs b/livekit-ffi/src/core_modules/data_stream/polled.rs index ae537cc001..022981247f 100644 --- a/livekit-ffi/src/core_modules/data_stream/polled.rs +++ b/livekit-ffi/src/core_modules/data_stream/polled.rs @@ -30,8 +30,8 @@ //! is Rust. //! //! The outgoing side also keeps the delegate's acknowledgement contract. Each delegate call becomes -//! an [`OutgoingPacketBatch`] that the foreign side resolves once its packets are on the wire, so a -//! send still waits for the transport and still fails when the transport does. +//! an [`OutgoingPacketBatch`] whose outcome the foreign side reports once its packets are handed to +//! the transport, so a send still waits for the transport and still fails when the transport does. //! //! Note that [`RemoteParticipantRegistryDelegate`] needs no adapter: it is only ever called //! synchronously inside a `send_*` future, so it already runs on the polling thread. @@ -199,10 +199,10 @@ impl OutgoingDataStreamManagerDelegate for OutgoingPacketSink { #[uniffi::export(async_runtime = "tokio")] impl OutgoingPacketQueue { - /// Awaits the next batch of packets to put on the wire. + /// Awaits the next batch of packets to hand to the transport. /// - /// Report the outcome on the returned batch once its packets are sent (or have failed); the - /// next batch is not produced until then. Returns `None` once the queue is closed, which ends + /// Report on the batch's `outcome` once its packets are sent (or have failed); the next batch + /// is not produced until then. Returns `None` once the queue is closed, which ends /// the caller's drain loop. pub async fn next_batch(&self) -> Option { let mut rx = self.rx.lock().await; @@ -332,7 +332,7 @@ impl IncomingStreamQueue { /// Awaits the next stream opened by a remote participant. /// /// Returns `None` once the manager has shut down, which ends the caller's drain loop. Unlike - /// [`OutgoingPacketQueue::next_packets`] this yields one at a time: each carries a reader the + /// [`OutgoingPacketQueue::next_batch`] this yields one at a time: each carries a reader the /// caller has to route to a handler, so batching would only defer that work. pub async fn next_opened_stream(&self) -> Option { let mut rx = self.rx.lock().await; From 651740d4ab9b3a2b714bcb88c83f4e88deb02154 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:15:10 +0800 Subject: [PATCH 11/13] Update the changeset for the batch record --- .changeset/polled_outgoing_batch_ack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/polled_outgoing_batch_ack.md b/.changeset/polled_outgoing_batch_ack.md index 8125a5e217..83212a6897 100644 --- a/.changeset/polled_outgoing_batch_ack.md +++ b/.changeset/polled_outgoing_batch_ack.md @@ -2,4 +2,4 @@ livekit-ffi: major --- -The polled outgoing data stream adapter resolves a send once the host reports its batch as sent, and no longer when the packets are buffered. `OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`, whose `OutgoingPacketBatch` the host must `complete()` or `fail(reason)`. +The polled outgoing data stream adapter resolves a send once the host reports its batch as sent, and no longer when the packets are buffered. `OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`, which returns the packets and an `outcome` the host must `complete()` or `fail(reason)`. From 9f3717c3806118ea8e4e69c6a490a912f2bc8730 Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:30:10 +0800 Subject: [PATCH 12/13] livekit-ffi: name the batch's reporting object ack --- .changeset/polled_outgoing_batch_ack.md | 2 +- .../src/core_modules/data_stream/polled.rs | 18 +++++++++--------- .../src/core_modules/data_stream/tests.rs | 8 ++++---- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.changeset/polled_outgoing_batch_ack.md b/.changeset/polled_outgoing_batch_ack.md index 83212a6897..265eef7a57 100644 --- a/.changeset/polled_outgoing_batch_ack.md +++ b/.changeset/polled_outgoing_batch_ack.md @@ -2,4 +2,4 @@ livekit-ffi: major --- -The polled outgoing data stream adapter resolves a send once the host reports its batch as sent, and no longer when the packets are buffered. `OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`, which returns the packets and an `outcome` the host must `complete()` or `fail(reason)`. +The polled outgoing data stream adapter resolves a send once the host reports its batch as sent, and no longer when the packets are buffered. `OutgoingPacketQueue.next_packets()` is replaced by `next_batch()`, which returns the packets and an `ack` the host must `complete()` or `fail(reason)`. diff --git a/livekit-ffi/src/core_modules/data_stream/polled.rs b/livekit-ffi/src/core_modules/data_stream/polled.rs index 022981247f..8604a69862 100644 --- a/livekit-ffi/src/core_modules/data_stream/polled.rs +++ b/livekit-ffi/src/core_modules/data_stream/polled.rs @@ -30,7 +30,7 @@ //! is Rust. //! //! The outgoing side also keeps the delegate's acknowledgement contract. Each delegate call becomes -//! an [`OutgoingPacketBatch`] whose outcome the foreign side reports once its packets are handed to +//! an [`OutgoingPacketBatch`] that the foreign side acknowledges once its packets are handed to //! the transport, so a send still waits for the transport and still fails when the transport does. //! //! Note that [`RemoteParticipantRegistryDelegate`] needs no adapter: it is only ever called @@ -74,14 +74,14 @@ fn warn_if_deep(kind: &str, depth: usize) { /// One delegate call's worth of outbound packets, pulled by the foreign side. /// /// The `send_*`/`write` call that produced it stays pending until the foreign side reports on -/// [`Self::outcome`], which keeps the delegate contract: a send resolves only once its packets are +/// [`Self::ack`], which keeps the delegate contract: a send resolves only once its packets are /// handed to the transport, and a transport failure fails it. #[derive(uniffi::Record)] pub struct OutgoingPacketBatch { /// Encoded `livekit.DataPacket`s to hand to the transport, in order. pub packets: Vec, /// Where to report what happened to them. - pub outcome: Arc, + pub ack: Arc, } type OutcomeSender = oneshot::Sender>; @@ -91,11 +91,11 @@ type OutcomeSender = oneshot::Sender>; /// Released without an outcome it fails the send, so dropping a batch can never acknowledge packets /// that were not sent. #[derive(uniffi::Object)] -pub struct OutgoingBatchOutcome { +pub struct OutgoingBatchAck { sender: std::sync::Mutex>, } -impl OutgoingBatchOutcome { +impl OutgoingBatchAck { fn resolve(&self, result: Result<(), PacketDeliveryError>) { let sender = self.sender.lock().unwrap_or_else(|poisoned| poisoned.into_inner()).take(); if let Some(sender) = sender { @@ -105,7 +105,7 @@ impl OutgoingBatchOutcome { } } -impl Drop for OutgoingBatchOutcome { +impl Drop for OutgoingBatchAck { fn drop(&mut self) { let sender = self.sender.get_mut().unwrap_or_else(|poisoned| poisoned.into_inner()).take(); if let Some(sender) = sender { @@ -117,7 +117,7 @@ impl Drop for OutgoingBatchOutcome { } #[uniffi::export] -impl OutgoingBatchOutcome { +impl OutgoingBatchAck { /// Reports every packet as handed to the transport, resolving the originating send. /// /// Only the first of [`Self::complete`] and [`Self::fail`] counts. @@ -201,7 +201,7 @@ impl OutgoingDataStreamManagerDelegate for OutgoingPacketSink { impl OutgoingPacketQueue { /// Awaits the next batch of packets to hand to the transport. /// - /// Report on the batch's `outcome` once its packets are sent (or have failed); the next batch + /// Report on the batch's `ack` once its packets are sent (or have failed); the next batch /// is not produced until then. Returns `None` once the queue is closed, which ends /// the caller's drain loop. pub async fn next_batch(&self) -> Option { @@ -213,7 +213,7 @@ impl OutgoingPacketQueue { let sender = std::sync::Mutex::new(Some(pending.outcome)); Some(OutgoingPacketBatch { packets: pending.packets, - outcome: Arc::new(OutgoingBatchOutcome { sender }), + ack: Arc::new(OutgoingBatchAck { sender }), }) } diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 0360dffca4..156b327bd9 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -935,7 +935,7 @@ async fn polled_roundtrip( packet_count += 1; incoming.manager.handle_packet_received(packet, EncryptionType::None); } - batch.outcome.complete(); + batch.ack.complete(); } packet_count }; @@ -999,7 +999,7 @@ fn polled_send_waits_for_the_batch_outcome() { tokio::time::sleep(std::time::Duration::from_millis(50)).await; assert!(!send.is_finished(), "send_text must stay pending until the batch is resolved"); - batch.outcome.complete(); + batch.ack.complete(); send.await.unwrap().expect("a completed batch should resolve the send"); }); } @@ -1008,9 +1008,9 @@ fn polled_send_waits_for_the_batch_outcome() { fn polled_failed_batch_fails_the_send() { crate::runtime::runtime().block_on(async { let (_outgoing, send, batch) = polled_send_and_pull().await; - batch.outcome.fail("wire down".to_string()); + batch.ack.fail("wire down".to_string()); // Resolving twice must not panic, and only the first outcome counts. - batch.outcome.complete(); + batch.ack.complete(); assert!(send.await.unwrap().is_err(), "a failed batch should fail the send"); }); } From 13ed4d6c913297bf3f1910635a2164ee8dbefcaf Mon Sep 17 00:00:00 2001 From: Hiroshi Horie <548776+hiroshihorie@users.noreply.github.com> Date: Wed, 18 Nov 2026 16:54:34 +0800 Subject: [PATCH 13/13] livekit-ffi: test that polled acks are released across repeated sends Two hundred sends go through a polled manager, each ending one of four ways: the ack completes, it fails, it is released without an outcome, or the send is cancelled before the ack reports. Every round checks the ack is freed, and the manager and queue are dropped at the end. --- .../src/core_modules/data_stream/tests.rs | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 156b327bd9..a244c75b97 100644 --- a/livekit-ffi/src/core_modules/data_stream/tests.rs +++ b/livekit-ffi/src/core_modules/data_stream/tests.rs @@ -1090,3 +1090,52 @@ fn polled_manager_drop_ends_the_wait_for_a_held_batch() { assert_forwarding_task_finished(sink).await; }); } + +#[test] +fn polled_acks_are_released_across_repeated_sends() { + crate::runtime::runtime().block_on(async { + let shutdown = tokio_util::sync::CancellationToken::new(); + let (sink, queue) = super::polled::OutgoingPacketQueue::pair(shutdown.clone()); + let sink_alive = Arc::downgrade(&sink); + let manager = + OutgoingDataStreamManager::with_shutdown(sink, Arc::new(AllV2Registry), shutdown); + + for round in 0..200 { + let mut send = spawn_polled_send(manager.clone()); + let batch = queue.next_batch().await.expect("send_text should produce a batch"); + let ack_alive = Arc::downgrade(&batch.ack); + // What the send should see, or `None` when it was cancelled before the ack reported. + let expect_ok = match round % 4 { + 0 => { + batch.ack.complete(); + Some(true) + } + 1 => { + batch.ack.fail("wire down".to_string()); + Some(false) + } + // Released without an outcome below, which fails the send. + 2 => Some(false), + _ => { + send.abort(); + assert!((&mut send).await.unwrap_err().is_cancelled()); + batch.ack.complete(); + None + } + }; + drop(batch); + assert!(ack_alive.upgrade().is_none(), "round {round} left its ack alive"); + match expect_ok { + Some(true) => { + send.await.unwrap().expect("a completed ack should resolve the send"); + } + Some(false) => assert!(send.await.unwrap().is_err(), "round {round} should fail"), + None => {} + } + } + + drop(manager); + drop(queue); + assert_forwarding_task_finished(sink_alive).await; + }); +}