async-await initial reference material #635

nikomatsakis · 2019-07-10T21:27:03Z

I'm not sure what the best reviewing process is here.

cc @cramertj @withoutboats @Centril @joshtriplett @pnkfelix @scottmcm @pnkfelix @eddyb (I think that's the lang team, did I miss anybody?)

cc #634 rust-lang/rust#62566

src/items/functions.md

src/expressions/await-expr.md

src/expressions/async-block-expr.md

nikomatsakis · 2019-07-10T22:48:24Z

So I get a bunch of errors from the examples like

error[E0670]: `async fn` is not permitted in the 2015 edition
 --> /tmp/mdbookaDvS38/items/functions.md:198:1
  |
3 | async fn regular_example() { }
  | ^^^^^
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `unsafe`
 --> /tmp/mdbookaDvS38/items/functions.md:199:7
  |
4 | async unsafe fn unsafe_example() { }
  |       ^^^^^^ expected one of 8 possible tokens here
error[E0425]: cannot find value `async` in this scope
 --> /tmp/mdbookaDvS38/items/functions.md:199:1
  |
4 | async unsafe fn unsafe_example() { }
  | ^^^^^ not found in this scope
error[E0658]: async fn is unstable
 --> /tmp/mdbookaDvS38/items/functions.md:198:1
  |
3 | async fn regular_example() { }
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: for more information, see https://github.com/rust-lang/rust/issues/50547
  = help: add #![feature(async_await)] to the crate attributes to enable

Any tips on how to address these? :)

nikomatsakis · 2019-07-10T22:48:37Z

(Especially the edition flag)

Centril · 2019-07-10T22:49:02Z

I'm not sure what the best reviewing process is here.

Not sure either, but the current process is basically: "@Centril and @ehuss reviews, we approve, and then we merge".

Centril · 2019-07-10T22:50:35Z

(Especially the edition flag)

I think you can follow these examples: https://github.com/rust-lang-nursery/reference/search?q=edition2018&unscoped_q=edition2018

Centril · 2019-07-10T22:53:38Z

Speaking of editions; I think it was not mentioned in the PR that the new stuff only works in edition 2018. Would be good to work that in (see https://github.com/rust-lang-nursery/reference/search?q=edition&unscoped_q=edition for examples).

Havvy · 2019-07-10T23:54:58Z

src/expressions/await-expr.md

+
+More specifically, a `f.await` expression has the following effect.
+
+1. evaluate `f` to a future `tmp` using the `IntoFuture:into_future` method;


Suggested change

1. evaluate `f` to a future `tmp` using the `IntoFuture:into_future` method;

1. evaluate `f` to a future temporary variable `tmp` using the `IntoFuture:into_future` method;

I don't like "future" there, but don't really see a better way to succinctly convey the information. It should probably link to the Future trait as well.

src/expressions/await-expr.md

src/expressions/block-expr.md

Havvy · 2019-07-11T00:13:47Z

Given that the semantics of move and ? are affected the same in a closure as in an async block, we could get a name for these psuedo-function boundaries and put information on capturing groups in there, the propagation boundary for ? can refer to it, and we can just say closures and async blocks are both whatever we call these psuedo-function boundaries, linking to that.

If we don't want to do that, then we should say move behaves the same way as on closures, linking to that, and in the capturing groups section on the closures page, say that the section applies to both closures and async blocks, linking back to async blocks.

eddyb · 2019-07-11T11:55:18Z

Nit: the title doesn't mention async/await.

nikomatsakis · 2019-07-11T15:36:16Z

Given that the semantics of move and ? are affected the same in a closure as in an async block, we could get a name for these psuedo-function boundaries and put information on capturing groups in there, the propagation boundary for ? can refer to it, and we can just say closures and async blocks are both whatever we call these psuedo-function boundaries, linking to that.

I did link to closures to explain capture modes. I did not do so for ? but I agree that there is some concept that is similar between them.

nikomatsakis · 2019-07-11T18:48:17Z

Note to self: document async unsafe behavior

ehuss

I pushed some changes which I think should be uncontroversial, though feel free to revert/change it.

I think we'll need to add a note that trait functions/methods cannot be async (probably somewhere in items/traits.md?). FunctionQualifiers is reused and I think it should be explicit where it is and is not allowed there.

Also, this causes a problem with the definition of BareFunctionType. Syntactically it cannot have async (AFAIK), so that will need to stop using FunctionQualifiers.

We normally only merge once things are stable on master, so the broken test should pass once that happens. I left a note on the other broken test.

FYI, we're still stuck on mdbook 0.1 here. The links are relative to the root of the book. Hopefully we'll get to upgrade soon.

Also, we use relative links between books (like std), so that they point to the correct version (on doc.rust-lang.org).

src/expressions/block-expr.md

src/items/functions.md

Havvy · 2019-07-13T07:52:51Z

src/expressions/await-expr.md

+
+```rust,ignore
+loop {
+    let tmp = /* <expr> */;


Shouldn't this line be outside of the loop? tmp isn't re-evaluated every single time, right? Also, should probably call it awaited and not tmp.

ehuss · 2019-07-16T22:26:56Z

Just a heads up, I have rebased this PR on latest master to resolve the conflicts, so be careful updating locally.

The reference has migrated to mdbook 0.3. This means that links should use the .md extension, and are relative to the page they are on (previously they were relative to the root of the book). Please don't hesitate to ask if you have any questions or any trouble updating. Sorry for the interruption!

cramertj · 2019-07-23T17:24:23Z

Are there remaining blockers to landing this?

ehuss · 2019-07-23T17:46:37Z

Are there remaining blockers to landing this?

The reference only includes stable features, so normally we wait until it is stabilized on nightly. IIUC, it is currently waiting on FCP in rust-lang/rust#62149?

There are also some unresolved comments above. I'll take care of the formatting issue, but I don't know enough about async to do much else. Is there someone who can pick it up since Niko isn't around?

There's an unresolved issue about "unsafe" being undocumented, but I personally think it would be ok to land that separately. Others may disagree, though.

nikomatsakis · 2019-07-25T16:56:32Z

I pushed two commits -- one addresses @Havvy's nit, the other documents async unsafe. I'm not sure what remaining things are left to be done.

src/items/functions.md

src/expressions/await-expr.md

src/items/functions.md

src/expressions.md

Centril · 2019-08-16T17:44:12Z

@nikomatsakis Btw, you can apply suggestions in bulk as a single commit if you go to the "Files changed" tab. Use the "Add suggestion to batch" button when you are there.

Centril · 2019-08-21T09:55:33Z

@nikomatsakis Since the stabilization PR landed, want to make the finishing touches and then squash? Let's merge after that.

nikomatsakis · 2019-08-27T20:15:51Z

@Centril addressed (I think) all nits, squashed, and rebased

Centril · 2019-08-27T20:19:25Z

Yep, thanks! We'll have to remember to adjust this if we adjust the lowering wrt. the temporary lifetime stuff.

Update cargo, books ## cargo 8 commits in 22f7dd0495cd72ce2082d318d5a9b4dccb9c5b8c..fe0e5a48b75da2b405c8ce1ba2674e174ae11d5d 2019-08-27 16:10:51 +0000 to 2019-09-04 00:51:27 +0000 - Rename `--all` to `--workspace` (rust-lang/cargo#7241) - Basic standard library support. (rust-lang/cargo#7216) - Allow using 'config.toml' instead of just 'config' files. (rust-lang/cargo#7295) - Retry on SSL Connect Error. (rust-lang/cargo#7318) - minimal-copy `deserialize` for `InternedString` (rust-lang/cargo#7310) - Fix typo in cargo vendor examples (rust-lang/cargo#7320) - Fixes around multiple `[patch]` per crate (rust-lang/cargo#7303) - Improve error messages on mkdir failure (rust-lang/cargo#7306) ## reference 7 commits in d191a0c..090c015 2019-08-15 08:42:23 +0200 to 2019-09-03 13:59:28 -0700 - Fix rust-lang/reference#664: Review Oxford comma usage. (rust-lang/reference#668) - Fix some links. (rust-lang/reference#667) - Remove trait object warning. (rust-lang/reference#666) - Specify pattern types in `let` statements and `for` expressions (rust-lang/reference#663) - Fix loop expression link. (rust-lang/reference#662) - async-await initial reference material (rust-lang/reference#635) - Correct errors in the reference of extern functions definitions and declarations (rust-lang/reference#652) ## rust-by-example 1 commits in 580839d90aacd537f0293697096fa8355bc4e673..e76be6b2dc84c6a992e186157efe29d625e29b94 2019-08-17 23:17:50 -0300 to 2019-09-03 07:42:26 -0300 - Change link to russian translation repository (rust-lang/rust-by-example#1245) ## embedded-book 1 commits in 432ca26686c11d396eed6a59499f93ce1bf2433c..5ca585c4a7552efb546e7681c3de0712f4ae4fdc 2019-08-09 23:20:22 +0000 to 2019-08-27 13:39:14 +0000 - Fixup book CI (rust-embedded/book#205)

Centril suggested changes Jul 10, 2019

View reviewed changes

Centril requested a review from ehuss July 10, 2019 22:43

Havvy reviewed Jul 10, 2019

View reviewed changes

src/expressions/await-expr.md Outdated Show resolved Hide resolved

Havvy reviewed Jul 11, 2019

View reviewed changes

src/expressions/block-expr.md Outdated Show resolved Hide resolved

nikomatsakis changed the title ~~initial reference material~~ async-await initial reference material Jul 11, 2019

ehuss reviewed Jul 12, 2019

View reviewed changes

src/expressions/block-expr.md Outdated Show resolved Hide resolved

src/items/functions.md Show resolved Hide resolved

Havvy reviewed Jul 13, 2019

View reviewed changes

ehuss force-pushed the async-await branch from baf2d4e to d2162b3 Compare July 16, 2019 22:23

Centril reviewed Jul 25, 2019

View reviewed changes

src/expressions/await-expr.md Outdated Show resolved Hide resolved

src/items/functions.md Outdated Show resolved Hide resolved

F001 reviewed Aug 1, 2019

View reviewed changes

src/expressions.md Outdated Show resolved Hide resolved

skade mentioned this pull request Aug 7, 2019

include material on async fn in the Rust reference rust-lang/rust#62566

Closed

async-await reference material (squashed)

e0b5db6

nikomatsakis force-pushed the async-await branch from 8c56b41 to e0b5db6 Compare August 27, 2019 20:15

Centril approved these changes Aug 27, 2019

View reviewed changes

Centril merged commit b1844a2 into rust-lang:master Aug 27, 2019

ehuss mentioned this pull request Sep 4, 2019

Update cargo, books rust-lang/rust#64150

Merged

ehuss mentioned this pull request May 25, 2021

Tracking issue for async/await rust-lang/edition-guide#170

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

async-await initial reference material #635

async-await initial reference material #635

nikomatsakis commented Jul 10, 2019 •

edited

Loading

nikomatsakis commented Jul 10, 2019

nikomatsakis commented Jul 10, 2019

Centril commented Jul 10, 2019

Centril commented Jul 10, 2019

Centril commented Jul 10, 2019

Havvy Jul 10, 2019

Havvy commented Jul 11, 2019

eddyb commented Jul 11, 2019

nikomatsakis commented Jul 11, 2019

nikomatsakis commented Jul 11, 2019

ehuss left a comment •

edited

Loading

Havvy Jul 13, 2019

ehuss commented Jul 16, 2019

cramertj commented Jul 23, 2019

ehuss commented Jul 23, 2019 •

edited

Loading

nikomatsakis commented Jul 25, 2019

Centril commented Aug 16, 2019

Centril commented Aug 21, 2019

nikomatsakis commented Aug 27, 2019

Centril commented Aug 27, 2019


		More specifically, a `f.await` expression has the following effect.

		1. evaluate `f` to a future `tmp` using the `IntoFuture:into_future` method;

	1. evaluate `f` to a future `tmp` using the `IntoFuture:into_future` method;
	1. evaluate `f` to a future temporary variable `tmp` using the `IntoFuture:into_future` method;

async-await initial reference material #635

async-await initial reference material #635

Conversation

nikomatsakis commented Jul 10, 2019 • edited Loading

nikomatsakis commented Jul 10, 2019

nikomatsakis commented Jul 10, 2019

Centril commented Jul 10, 2019

Centril commented Jul 10, 2019

Centril commented Jul 10, 2019

Havvy Jul 10, 2019

Choose a reason for hiding this comment

Havvy commented Jul 11, 2019

eddyb commented Jul 11, 2019

nikomatsakis commented Jul 11, 2019

nikomatsakis commented Jul 11, 2019

ehuss left a comment • edited Loading

Choose a reason for hiding this comment

Havvy Jul 13, 2019

Choose a reason for hiding this comment

ehuss commented Jul 16, 2019

cramertj commented Jul 23, 2019

ehuss commented Jul 23, 2019 • edited Loading

nikomatsakis commented Jul 25, 2019

Centril commented Aug 16, 2019

Centril commented Aug 21, 2019

nikomatsakis commented Aug 27, 2019

Centril commented Aug 27, 2019

nikomatsakis commented Jul 10, 2019 •

edited

Loading

ehuss left a comment •

edited

Loading

ehuss commented Jul 23, 2019 •

edited

Loading