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
6 changes: 4 additions & 2 deletions cpp/moq/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Every generated type lives in `namespace moq`. Objects are `std::shared_ptr`; re

- A fallible call returns `moq::expected<T>`, 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<T>`. 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
Expand All @@ -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.
17 changes: 16 additions & 1 deletion cpp/moq/test/probe.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -153,10 +165,13 @@ int main() {
{
Latch done;
std::optional<moq::Frame> received;
auto continuation = consumer->read_frame().then(moq::inline_executor, [&](moq::expected<std::optional<moq::Frame>> result) {
auto reading_next = consumer->read_frame();
auto continuation = std::move(reading_next).then(moq::inline_executor, [&](moq::expected<std::optional<moq::Frame>> result) {
received = ok(std::move(result), "then read_frame");
done.set();
});
// then() took the future's state.
CHECK(!reading_next.valid());
Comment on lines +173 to +174

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add the missing post-get validity check

The deleted quest says the tests must prove valid() becomes false for every consumption path, and the documentation now promises this for get(), but the new assertions cover only cancellation, moving, and then(). The existing reading.get() above is not followed by CHECK(!reading.valid()), so a generator regression that leaves a future valid after get() would pass this probe even though the quest is being retired. Add that post-get() assertion before considering the regression covered.

AGENTS.md reference: AGENTS.md:L18-L18

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6d0a4ca: CHECK(!reading.valid()) after reading.get().

(Written by Claude Opus 5.5)

ok(track->write_frame({bytes("then"), 2000}), "write_frame");
CHECK(done.wait_for(5s));
CHECK(received && received->payload == bytes("then"));
Expand Down
3 changes: 3 additions & 0 deletions doc/lib/cpp/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,9 @@ An async call returns `moq::Future<T>`, which delivers a `moq::expected<T>`:
- **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();
Expand Down
1 change: 0 additions & 1 deletion quest/m1/cpp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
26 changes: 0 additions & 26 deletions quest/m1/cpp/cancel.md

This file was deleted.

Loading