diff --git a/cpp/moq/README.md b/cpp/moq/README.md index 598ed7e2c2a..05d266719c9 100644 --- a/cpp/moq/README.md +++ b/cpp/moq/README.md @@ -30,7 +30,7 @@ Every generated type lives in `namespace moq`. Objects are `std::shared_ptr`; re - A fallible call returns `moq::expected`, which is `std::expected` on C++23 and a bundled `tl::expected` below it. The generated sources and every includer must agree on which, so `moq/moq.hpp` references a symbol named for the one it sees and `src/moq.cpp` defines the one it was built with: a mismatch fails to link. - An async call returns `moq::Future`. Block on it with `get()` or `wait_for()`, attach a continuation with `std::move(future).then(executor, callback)`, which returns a `moq::Continuation`, or `co_await` it on C++20. -- `moq::Error` is a value holding a `std::variant` of its cases, and `to_string()` gives Rust's `Display` message. Nothing throws. A Rust panic or a misused future aborts with a message on stderr. +- `moq::Error` is a value holding a `std::variant` of its cases, and `to_string()` gives Rust's `Display` message. Nothing throws. A Rust panic aborts with a message on stderr, and so does reading an invalid future (see [Cancellation](#cancellation)). - Futures are polled and continuations run on one process-wide executor thread unless the application installs its own with `moq::set_executor` before the first async call. `moq::shutdown()` stops the moq-ffi runtime thread (`moq_ffi_shutdown`), then the executor, before unloading the code a continuation could call into. ## C++ standard @@ -39,6 +39,8 @@ The installed package compiles `moq.cpp` inside the consumer's project, at its ` ## Cancellation -Cancelling a future (`cancel()`, destroying it, destroying the `moq::Continuation` returned by `then`, or destroying a coroutine suspended on it) drops the Rust future. Native moq-ffi runs each async call as a spawned task that holds an `AbortOnDrop` on it (`rs/moq-ffi/src/ffi.rs`), so dropping the future aborts the work at its next await point instead of letting it finish unobserved. The continuation of a cancelled future never runs, and `get()` on it aborts. +Cancelling a future (`cancel()`, destroying it, destroying the `moq::Continuation` returned by `then`, or destroying a coroutine suspended on it) drops the Rust future. Native moq-ffi runs each async call as a spawned task that holds an `AbortOnDrop` on it (`rs/moq-ffi/src/ffi.rs`), so dropping the future aborts the work at its next await point instead of letting it finish unobserved. The continuation of a cancelled future never runs. + +Like `std::future`, `valid()` is false once `get()`, `then()`, `cancel()`, or a move took the future's state. Reading an invalid future aborts with "it was consumed or cancelled", so check `valid()` first when a future may have been cancelled, consumed, or moved from. The abort discards the operation, not the handle it ran on, so the next call on that object works. Where a method keeps partial progress, its doc comment says so. For example, a cancelled `read_frame` leaves the current group for the next read. Every write in moq-ffi (`write_frame`, `finish`, `abort`) is synchronous, so cancelling a future can never tear a write. Only the async operations (reads, subscribes, connects, accepts, and `reject`) can be cut short. diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index 53236e90dc8..daefef507a0 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -138,13 +138,25 @@ int main() { // Cancel a read that has nothing to deliver yet. auto pending = consumer->read_frame(); CHECK(pending.wait_for(50ms) == std::future_status::timeout); + CHECK(pending.valid()); pending.cancel(); CHECK(!pending.valid()); + // A move takes the state, so the source is invalid and the destination is not. + { + auto source = consumer->read_frame(); + CHECK(source.valid()); + auto destination = std::move(source); + CHECK(!source.valid()); + CHECK(destination.valid()); + } + // The consumer survives the cancelled read and delivers the next frame. auto reading = consumer->read_frame(); ok(track->write_frame({bytes("hello"), 1000}), "write_frame"); auto frame = ok(reading.get(), "read_frame"); + // get() consumed the state. + CHECK(!reading.valid()); CHECK(frame.has_value()); CHECK(frame->payload == bytes("hello")); CHECK(frame->timestamp_us == 1000); @@ -153,10 +165,13 @@ int main() { { Latch done; std::optional received; - auto continuation = consumer->read_frame().then(moq::inline_executor, [&](moq::expected> result) { + auto reading_next = consumer->read_frame(); + auto continuation = std::move(reading_next).then(moq::inline_executor, [&](moq::expected> result) { received = ok(std::move(result), "then read_frame"); done.set(); }); + // then() took the future's state. + CHECK(!reading_next.valid()); ok(track->write_frame({bytes("then"), 2000}), "write_frame"); CHECK(done.wait_for(5s)); CHECK(received && received->payload == bytes("then")); diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index d258337f706..02b7ac40236 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -111,6 +111,9 @@ An async call returns `moq::Future`, which delivers a `moq::expected`: - **Cancel** by calling `cancel()` or destroying the future. The Rust future is dropped at its next await point; the object it ran on stays usable, so the next call works. A cancelled future's continuation never runs. +- **Check** `valid()` before reading a future that may be cancelled, consumed, or + moved from. It is false once `get()`, `then()`, `cancel()`, or a move took the + future's state, and reading an invalid future aborts. ```cpp auto reading = (*media)->next(); diff --git a/quest/m1/cpp/README.md b/quest/m1/cpp/README.md index 81112b0f8c2..45679e5d9c8 100644 --- a/quest/m1/cpp/README.md +++ b/quest/m1/cpp/README.md @@ -72,7 +72,6 @@ Confirmed in [#4100](https://github.com/moq-dev/moq/pull/4100): - [Session report parity](/quest/m1/cpp/session-report.md) - a session reports its negotiated draft and reconnect failures, so the OBS dock shows them again - [Catalog switch](/quest/m1/cpp/catalog-switch.md) - a catalog update keeps OBS playback running until the replacement track is decoding - [OBS stats race test](/quest/m1/cpp/stats-race.md) - a test against the generated bindings proves a retired session's stats are refused -- [Cancel](/quest/m1/cpp/cancel.md) - a cancelled or consumed future reports `valid() == false`, like `std::future`, and a read of it aborts with a message naming the misuse ## Related diff --git a/quest/m1/cpp/cancel.md b/quest/m1/cpp/cancel.md deleted file mode 100644 index 8faad9eacfe..00000000000 --- a/quest/m1/cpp/cancel.md +++ /dev/null @@ -1,26 +0,0 @@ -# [XS] A cancelled future says so before it is read - -## Goal - -Callers are told to check `valid()` before reading a future that may be -cancelled, consumed, or moved from, and the tests prove it goes false in each -case. - -## Plan - -The fork half is done on the line: the `-kixelated.2` generator's -`uniffi::Future` has `valid()`, false once `get()`, `then()`, `cancel()`, or a -move took its state, like `std::future`, and a read of an invalid future aborts -with "it was consumed or cancelled". `cpp/moq/test/probe.cpp` checks `valid()` -after `cancel()`. Decided in the #4307 review; `&&`-qualifying `cancel()` and an -error-returning `get()` stay rejected. - -What remains: - -- `cpp/moq/README.md` (the Error and Cancellation sections) still only says a - misused future aborts; point callers at `valid()` instead. -- Extend the probe to check `valid()` after `then()` and after a move. -- Check the in-tree callers that can hold a cancelled future (`cpp/moq`, - `cpp/obs`) against `valid()`. - -Public API: none beyond the unreleased C++ package's `valid()`. Wire: none.