Terminology for waiting in async

[jbe]

When I have a function async foo() whose returned future is ready after a network packet is received, for example, how is the correct terminology to describe that?

• foo is pending until …
• foo waits until …
• foo resolves when …
• The future returned by foo is ready when …
• foo().await is blocking until …
• foo().await returns when …
• …

Or do you just colloquially say "foo blocks until the network packet is received"?

What I find difficult in this matter is that it's not clear what's the "return value" of an async fn foo() -> R. Is it:

• the anonymous Future<Output=R>, or is it
• R?

It's clear when I have the desugared case of fn foo() -> impl Future<Output=R>: Here the return value is a future. But it's not so clear (to me) what the return value of async fn foo() is (due to the sugaring).

I'm entirely asking about terminology here. I understand what really happens, but I'm just unsure which wording to use.

[semicoleon]

"suspends until" is usually the terminology I see used in that context

[H2CO3]

• The one wording I would outright rule out is "blocks until". That's simply not true. The whole point of async is to prevent blocking.
• I find "foo().await returns" confusing, because it's not a function call expression, it's an await expression. Only functions "return"; other expressions might yield a value, too, but IMO it's not correct to call that "returning".
• "Resolve" is usually applied in the JavaScript ecosystem; while that might be familiar to JS programmers, I don't necessarily think it's a good choice, because Rust futures don't desugar to callbacks, so it suggests the wrong idea about the implementation and performance characteristics.
• "waits until" is… OK, although it's very generic, and it might imply to some people that it's blocking, which it is not.
• "pending until" and "the future returned is ready" seem the best formulations, since the states represented by Poll are called Pending and Ready. I can't decide between these two, because "pending until" is less verbose, so it may be preferable for the sake of practicality, but it's negative, so "the future is ready" might be preferable from a purely linguistic perspective.

[jbe]

@semicoleon

"suspends until" is usually the terminology I see used in that context

I like that word, I think I will use that.

@H2CO3

The one wording I would outright rule out is "blocks until". That's simply not true. The whole point of async is to prevent blocking.

Yeah, I agree.

@H2CO3

I find "foo().await returns" confusing, because it's not a function call expression, it's an await expression. Only functions "return"; other expressions might yield a value, too, but IMO it's not correct to call that "returning".

Oh, I wasn't aware of that, but it makes sense.

@H2CO3

"Resolve" is usually applied in the JavaScript ecosystem; while that might be familiar to JS programmers, I don't necessarily think it's a good choice, because Rust futures don't desugar to callbacks, so it suggests the wrong idea about the implementation and performance characteristics.

Ah, I might have catched the wording "resolved" from JavaScript, though I don't really work in JS currently.

@H2CO3

"pending until" and "the future returned is ready" seem the best formulations, since the states represented by Poll are called Pending and Ready. I can't decide between these two, because "pending until" is less verbose, so it may be preferable for the sake of practicality, but it's negative, so "the future is ready" might be preferable from a purely linguistic perspective.

Actually there are four options:

• foo is pending until …
• the future returned by foo is pending until …
• foo is ready when …
• the future returned by foo is ready when …

Plus @semicoleon's proposal:

• foo suspends until …

And maybe you could say:

• foo wakes up when …

?

[alice]

I usually use wait or sleep.

[simonbuchan]

Tokio is very inconsistent here:

Waits until duration has elapsed

for sleep in tokio::time - Rust

AsyncWriteExt in tokio::io - Rust is written as if the methods are synchronous.

this method will sleep until a message is sent or the channel is closed.

for Receiver in tokio::sync::mpsc - Rust

Locks this mutex, causing the current task to yield until the lock has been acquired.

for Mutex in tokio::sync - Rust

---

It's bad enough I feel like opening a bug report!

[alice]

@simonbuchan

AsyncWriteExt in tokio::io - Rust is written as if the methods are synchronous.

this method will sleep until a message is sent or the channel is closed.

I don't agree that this wording assumes that the method is synchronous.

[simonbuchan]

My formatting is confusing, sorry: the quotes are sourced afterwards. There's no quote for AsyncWriteExt as three nothing specific to quote.