Skip to content

Say where await_io_and_run() first polls its future - #8398

Merged
littledivy merged 1 commit into
mainfrom
littledivy/2026-11-12-await-io-first-poll-doc
Nov 12, 2026
Merged

littledivy merged 1 commit into
mainfrom
littledivy/2026-11-12-await-io-first-poll-doc

Conversation

@littledivy

Copy link
Copy Markdown
Member

await_io_and_run()'s doc says the future is polled without the isolate lock and with no IoContext current. Its first poll actually runs inside the call, under the lock and with the request current, because kj-rs polls a future as soon as it is added to the task set (FuturePollEvent::onReady). await_io and await_io_value inherit the same doc.

This matches C++, where the KJ promise passed to awaitIo() has already run up to its first wait in the caller. In this patch the doc says the first poll happens in the call and only later polls run from the event loop without the lock. Doc only, no behaviour change.

The doc said the future is polled without the isolate lock and with
no IoContext current. Its first poll actually runs inside the call,
under the lock and with the IoContext current, because kj-rs polls a
future as soon as it is added to the IoContext's task set.

That matches C++: the KJ promise passed to awaitIo() has already run
up to its first wait in the caller. Only the later polls run from the
event loop without the lock, so the doc now says that.
@littledivy
littledivy requested review from a team as code owners November 12, 2026 16:20

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

✅ Approved — A documentation-only correction to the await_io_and_run() doc. It matches the call path through io_context_await_io_and_run and awaitIoAndRun(), and I found no issues.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

Only doc comments in src/workerd/io/io-context/lib.rs change. The new text fits the call path: io_context_await_io_and_run gets the current IoContext, and awaitIoAndRun() requires the current context and lock, so a first poll during the call happens under the lock. The reworded Send explanation still holds, because later polls run without the lock.


📝 Documentation: ✅ LGTM

The doc wording is accurate and describes the current behaviour, as the repository's comment guidelines ask.


Reviewed commit: e3055c28

@littledivy
littledivy merged commit 7ce29be into main Nov 12, 2026
35 of 37 checks passed
@littledivy
littledivy deleted the littledivy/2026-11-12-await-io-first-poll-doc branch November 12, 2026 18:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants