diff --git a/.changeset/polled_outgoing_batch_ack.md b/.changeset/polled_outgoing_batch_ack.md new file mode 100644 index 0000000000..265eef7a57 --- /dev/null +++ b/.changeset/polled_outgoing_batch_ack.md @@ -0,0 +1,5 @@ +--- +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 `ack` the host must `complete()` or `fail(reason)`. 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 2c21c5f287..8604a69862 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 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 //! 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,157 @@ 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 on +/// [`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 ack: Arc, +} + +type OutcomeSender = oneshot::Sender>; + +/// Reports what happened to the packets of an [`OutgoingPacketBatch`]. /// -/// Implements [`OutgoingDataStreamManagerDelegate`] in Rust; see the module docs. +/// 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 OutgoingBatchAck { + sender: std::sync::Mutex>, +} + +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 { + // The send may already be gone (its manager shut down), in which case nobody is waiting. + let _ = sender.send(result); + } + } +} + +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 { + let _ = sender.send(Err(PacketDeliveryError::Failed { + reason: "packet batch released without an outcome".to_string(), + })); + } + } +} + +#[uniffi::export] +impl OutgoingBatchAck { + /// 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 })); + } +} + +/// 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, +/// [`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>, - depth: AtomicUsize, + 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. 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 { - fn new() -> Self { + /// `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(); - Self { - tx, - rx: Mutex::new(rx), - depth: AtomicUsize::new(0), - shutdown: CancellationToken::new(), - } + let shutdown = CancellationToken::new(); + let sink = OutgoingPacketSink { tx, shutdown: shutdown.clone(), manager_shutdown }; + (Arc::new(sink), Arc::new(Self { rx: Mutex::new(rx), shutdown })) } } +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 OutgoingPacketQueue { - // Acknowledges once buffered: a pull adapter has no synchronous transport feedback, so send - // failures observed while draining must be handled host-side. +impl OutgoingDataStreamManagerDelegate for OutgoingPacketSink { 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(); + 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())), } - 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 hand to the transport. /// - /// 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 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 { let mut rx = self.rx.lock().await; - let first = tokio::select! { + let pending = 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); - } - self.depth.fetch_sub(batch.len(), Ordering::Relaxed); - Some(batch) + let sender = std::sync::Mutex::new(Some(pending.outcome)); + Some(OutgoingPacketBatch { + packets: pending.packets, + ack: Arc::new(OutgoingBatchAck { sender }), + }) } - /// 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(); } @@ -150,8 +243,9 @@ 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 manager_shutdown = CancellationToken::new(); + let (sink, packets) = OutgoingPacketQueue::pair(manager_shutdown.clone()); + let manager = OutgoingDataStreamManager::with_shutdown(sink, registry, manager_shutdown); PolledOutgoingDataStreamManager { manager, packets } } @@ -238,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; diff --git a/livekit-ffi/src/core_modules/data_stream/tests.rs b/livekit-ffi/src/core_modules/data_stream/tests.rs index 0f229a6289..a244c75b97 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.ack.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,177 @@ fn polled_falls_back_to_legacy_framing_for_pre_v2_recipients() { assert_eq!(text, "hello world"); }); } + +/// 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, + tokio::task::JoinHandle>, + super::polled::OutgoingPacketBatch, +) { + let outgoing = super::polled::polled_outgoing_data_stream_manager(Arc::new(AllV2Registry)); + 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) +} + +#[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.ack.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.ack.fail("wire down".to_string()); + // Resolving twice must not panic, and only the first outcome counts. + batch.ack.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()); + }); +} + +/// 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, manager, queue) = polled_with_an_abandoned_batch().await; + drop(manager); + drop(queue); + 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; + }); +} + +#[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; + }); +}