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.

How about a basic fibonacci sequence example? Technically this is a simple fold.

The first version presented could be the naive recursive version that is extremely inefficient and quickly hits a wall:

/// Returns the n-th fibonacci number. (using recursion) fn fib_rec(n: i64) -> i64 { if n <= 1 { return n } fib_rec(n - 1) + fib_rec(n - 2) }

Then we could introduce a tail-call based version that is way more efficient:

/// Returns the n-th fibonacci number. (using tail-calls) fn fib_tail(n: i64) -> i64 { fn fib_tail_acc(n: i64, a: i64, b: i64) -> i64 { if n == 0 { return a } become fib_tail_acc(n - 1, b, a + b) } become fib_tail_acc(n, 0, 1) }

Note that a naive iteration based version isn't much more concise:

/// Returns the n-th fibonacci number. (using iteration) fn fib_iter(n: i64) -> i64 { if n <= 1 { return n } let mut a = 1; let mut b = 1; for _ in 2..n { let tmp = a + b; a = b; b = tmp; } b }

Finally test that everything works:

#[test] fn test_fib() { for n in 0..30 { assert_eq!(fib_iter(n), fib_tail(n)); assert_eq!(fib_iter(n), fib_rec(n)); } }

I don't think you would write fib_rec like that, specifically because it re-does a lot of work. A more fare comparison would be to

fn fib_rec(n: i64) -> i64 { fn fib_rec_acc(n: i64, a: i64, b: i64) -> i64 { if n == 0 { return a } fib_rec_acc(n - 1, b, a + b) } fib_rec_acc(n, 0, 1) }

At which point it's all a bit moot... But either way it's not like we can actually show the problem with stack overflow in these simple examples.

I usually prefer factorial, because it's less awkward since it doesn't require two previous values. But factorial grows so fast that stack overflowing is not an actual problem soo idk...

Also just a nitpick: become in fib_tail won't compile since the signatures don't match :')

I was previously thinking of writing a fold, but 🤷
I think whatever example we put, it won't be perfect and the difference would need additional explanation of "this may stack overflow and this can't".

What we surely need is an example that shows difference in drop order and explains how without it LLVM/the optimizer can't necessarily do this as an optimization.

I don't think you would write fib_rec like that, specifically because it re-does a lot of work.

Yes, the more comparable solution was indeed the fib_iter to start with.

Also just a nitpick: become in fib_tail won't compile since the signatures don't match :')

Good catch!

So a fold like this could serve as an example?

pub fn fold<T, U>(init: T, mut f: impl FnMut(T, U) -> T, iter: impl IntoIterator<Item = U>) -> T { let mut iter = iter.into_iter(); match iter.next() { None => init, Some(item) => fold(f(init, item), f, iter), } }

I just tested it locally and with sufficiently large iterators it causes a stack overflow on my system whereas tail calls would prevent this by putting become in front of the recursive fold call. I tested the above fold with this little function:

#[test] fn test_fold() { let iterations = 100_000; let output = fold( String::new(), |mut s, n| { const HEX: [char; 16] = [ '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F', ]; s.push(HEX[n % HEX.len()]); s }, (0..).take(iterations), ); assert_eq!(output.len(), iterations); }

I was thinking more of something like

pub fn fold<T, B>(slice: &[T], init: B, mut f: impl FnMut(B, &T) -> B) -> B { match slice { [] => init, [first, rest @ ..] => fold(rest, f(init, first), f), } }

recursion + slice patterns looks nice

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

6 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: Blocked on something else such as an RFC or other implementation work. label Dec 18, 2023

Dylan-DPC removed the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Jul 29, 2024

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

Robbepop Jun 19, 2024

WaffleLapkin Jun 19, 2024 •

edited

Loading

WaffleLapkin Jun 19, 2024

Robbepop Jun 19, 2024 •

edited

Loading

WaffleLapkin Jun 19, 2024

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

WaffleLapkin Jun 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Robbepop Jun 19, 2024 • edited Loading

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

WaffleLapkin Jun 19, 2024 •

edited

Loading

Robbepop Jun 19, 2024 •

edited

Loading