Document `become` keyword #113095

WaffleLapkin · 2023-06-27T12:48:55Z

The feature is not yet implemented, so I'm not sure if we should merge this right away, promoting an incomplete feature is probably not the best idea. But the docs can be reviewed while the implementation work is being done.

rustbot · 2023-06-27T12:49:01Z

r? @joshtriplett

(rustbot has picked a reviewer for you, use r? to override)

Rageking8

A few small nits.

library/std/src/keyword_docs.rs

Co-authored-by: Rageking8 <106309953+Rageking8@users.noreply.github.com>

rust-log-analyzer · 2023-06-28T15:11:00Z

The job x86_64-gnu-llvm-14 failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

---- src/keyword_docs.rs - become_keyword (line 1269) stdout ----
error: the feature `explicit_tail_calls` is incomplete and may not be safe to use and/or cause compiler crashes
##[error] --> src/keyword_docs.rs:1269:12
  |
3 | #![feature(explicit_tail_calls)]
  |
  = note: see issue #112788 <https://github.com/rust-lang/rust/issues/112788> for more information
note: the lint level is defined here
 --> src/keyword_docs.rs:1267:9
---

error: function cannot return without recursing
##[error] --> src/keyword_docs.rs:1273:1
  |
7 | fn halt() -> ! {
  | ^^^^^^^^^^^^^^ cannot return without recursing
8 |     become halt()
  |            ------ recursive call site
  |
  = help: a `loop` may express intention better if this is on purpose
  = note: `#[deny(unconditional_recursion)]` implied by `#[deny(warnings)]`
error: aborting due to 2 previous errors

Couldn't compile the test.
---- src/keyword_docs.rs - become_keyword (line 1238) stdout ----
---- src/keyword_docs.rs - become_keyword (line 1238) stdout ----
error: the feature `explicit_tail_calls` is incomplete and may not be safe to use and/or cause compiler crashes
##[error] --> src/keyword_docs.rs:1239:12
  |
3 | #![feature(explicit_tail_calls)]
  |
  = note: see issue #112788 <https://github.com/rust-lang/rust/issues/112788> for more information
note: the lint level is defined here
 --> src/keyword_docs.rs:1237:9
---
    src/keyword_docs.rs - become_keyword (line 1238)

test result: FAILED. 1120 passed; 2 failed; 17 ignored; 0 measured; 0 filtered out; finished in 15.90s

error: doctest failed, to rerun pass `-p std --doc`

workingjubilee · 2023-07-31T20:24:03Z

library/std/src/keyword_docs.rs

+/// is part of a recursive cycle in the call graph.
+///
+/// For example note that the functions `halt` and `halt_loop` below are
+/// identical, they both do nothing, forever. However, `stack_overflow` is


Suggested change

/// identical, they both do nothing, forever. However, `stack_overflow` is

/// identical: they both do nothing, forever. However, `stack_overflow` is

workingjubilee · 2023-07-31T20:25:04Z

library/std/src/keyword_docs.rs

+///
+/// For example note that the functions `halt` and `halt_loop` below are
+/// identical, they both do nothing, forever. However, `stack_overflow` is
+/// different from them, even though it is written almost identically to


Suggested change

/// different from them, even though it is written almost identically to

/// different from them. Even though it is written almost identically to

workingjubilee · 2023-07-31T20:28:48Z

library/std/src/keyword_docs.rs

+/// For example note that the functions `halt` and `halt_loop` below are
+/// identical, they both do nothing, forever. However, `stack_overflow` is
+/// different from them, even though it is written almost identically to
+/// `halt`, `stack_overflow` exhausts the stack and so causes a stack
+/// overflow, instead of running forever.
+///
+///
+/// ```
+/// #![feature(explicit_tail_calls)]
+///
+/// # #[allow(unreachable_code)]
+/// fn halt() -> ! {
+///     become halt()
+/// }
+///
+/// fn halt_loop() -> ! {
+///     loop {}
+/// }
+///
+/// # #[allow(unconditional_recursion)]
+/// fn stack_overflow() -> ! {
+///     stack_overflow() // implicit return
+/// }
+/// ```


This discusses a function that is "obviously wrong", which means it does not make it clear why one wants to use become in "real" code. I think we can do slightly better than this, as the documentation should focus on improving the good cases, like e.g. writing "natural" recursive merge-sorts. The example improvement can still be contrived, however.

That makes sense, hmm. I guess the problem (similarly to the discussions on the RFC) is that there is no concise example where using tail calls makes sense in rust — most, if not all, small examples can be written just as good with a loop.

Maybe it would make sense to have two examples? One a bit silly, maybe a slice fold, and the other longer one with something like an interpreter?

Reading it now I see that this is a bad example, but I'm not sure what example would be good.

A silly fold would be good! I'm not looking for "a loop wouldn't be just as good", just something that actually feels like something a human would want to write.

workingjubilee · 2023-07-31T20:30:24Z

library/std/src/keyword_docs.rs

+/// For example note that the functions `halt` and `halt_loop` below are
+/// identical, they both do nothing, forever. However, `stack_overflow` is
+/// different from them, even though it is written almost identically to
+/// `halt`, `stack_overflow` exhausts the stack and so causes a stack
+/// overflow, instead of running forever.


Isn't LLVM allowed to optimize stack_overflow() into loop { }? I know we don't allow it to remove infinite loops, but...

It is allowed, but it also is allowed not to.

Yeah. I guess it's allowed to do it in all these cases, right?

I guess what I'm concerned about is the example being so trivial that it doesn't hold up to even trivial examination.

workingjubilee · 2023-07-31T20:31:06Z

library/std/src/keyword_docs.rs

+//
+/// Perform a tail-call of a function.
+///
+/// A `become` transfers the execution flow to a function in such a way, that


Suggested change

/// A `become` transfers the execution flow to a function in such a way, that

/// A `become` transfers the execution flow to a function in such a way that

workingjubilee · 2023-07-31T20:32:34Z

Unsure about the direction of this documentation focusing on the absurd case.

@rustbot author
r? @workingjubilee

JohnCSimon · 2023-12-17T21:57:32Z

@WaffleLapkin
ping from triage - can you post your status on this PR? This PR has not received an update in a few months. Thank you!

WaffleLapkin · 2023-12-18T02:25:34Z

@JohnCSimon this is blocked on actually implementing the feature (it would be silly to document a feature one can't use). Also I need to address the review comments above.

Note for future self: example of fold, an explicit note about drop order (which llvm can't necessarily change).

Document become keyword

820c1c5

rustbot assigned joshtriplett Jun 27, 2023

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 27, 2023

WaffleLapkin mentioned this pull request Jun 27, 2023

Tracking Issue for Explicit Tail Calls #112788

Open

3 tasks

This comment has been minimized.

Sign in to view

Rageking8 reviewed Jun 27, 2023

View reviewed changes

library/std/src/keyword_docs.rs Outdated Show resolved Hide resolved

library/std/src/keyword_docs.rs Outdated Show resolved Hide resolved

library/std/src/keyword_docs.rs Outdated Show resolved Hide resolved

Fix typos

0888a94

Co-authored-by: Rageking8 <106309953+Rageking8@users.noreply.github.com>

workingjubilee reviewed Jul 31, 2023

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 31, 2023

rustbot assigned workingjubilee and unassigned joshtriplett Jul 31, 2023

WaffleLapkin added the S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. label Dec 18, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document `become` keyword #113095

Document `become` keyword #113095

WaffleLapkin commented Jun 27, 2023

rustbot commented Jun 27, 2023

This comment has been minimized.

Rageking8 left a comment

rust-log-analyzer commented Jun 28, 2023

workingjubilee Jul 31, 2023

workingjubilee Jul 31, 2023

workingjubilee Jul 31, 2023

WaffleLapkin Aug 1, 2023

workingjubilee Aug 1, 2023

workingjubilee Jul 31, 2023

WaffleLapkin Aug 1, 2023

workingjubilee Aug 1, 2023

workingjubilee Jul 31, 2023

workingjubilee commented Jul 31, 2023

JohnCSimon commented Dec 17, 2023

WaffleLapkin commented Dec 18, 2023

	/// identical, they both do nothing, forever. However, `stack_overflow` is
	/// identical: they both do nothing, forever. However, `stack_overflow` is

	/// different from them, even though it is written almost identically to
	/// different from them. Even though it is written almost identically to

	/// A `become` transfers the execution flow to a function in such a way, that
	/// A `become` transfers the execution flow to a function in such a way that

Document become keyword #113095

Are you sure you want to change the base?

Document become keyword #113095

Conversation

WaffleLapkin commented Jun 27, 2023

rustbot commented Jun 27, 2023

This comment has been minimized.

Rageking8 left a comment

Choose a reason for hiding this comment

rust-log-analyzer commented Jun 28, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

workingjubilee commented Jul 31, 2023

JohnCSimon commented Dec 17, 2023

WaffleLapkin commented Dec 18, 2023

Document `become` keyword #113095

Document `become` keyword #113095