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

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).

xacrimon · 2025-07-22T17:10:30Z

@WaffleLapkin With #144232 merged, time to get back to this?

WaffleLapkin · 2025-07-25T14:48:12Z

@xacrimon #144232 isn't merged, but yes ^^'

WaffleLapkin · 2025-08-02T01:10:34Z

@workingjubilee I rewrote the documentation, could you do a general vibe check? does this direction seem better than the old one?

Kivooeo

Some nits

Kivooeo · 2025-08-05T10:12:16Z

library/std/src/keyword_docs.rs

+/// This means that as long as a loop in a call graph only uses tail calls, the
+/// stack growth will be bounded.
+///
+/// This is useful for writing functional-style code (since it prevent recursion


Suggested change

/// This is useful for writing functional-style code (since it prevent recursion

/// This is useful for writing functional-style code (since it prevents recursion

Kivooeo · 2025-08-05T10:12:34Z

library/std/src/keyword_docs.rs

+/// fn fold<T: Copy, S>(slice: &[T], init: S, f: impl Fn(S, T) -> S) -> S {
+///     match slice {
+///         // without `become`, on big inputs this could easily overflow the
+///         // stack. using a tail call guarantees that the stack will not grow unboundly


Suggested change

/// // stack. using a tail call guarantees that the stack will not grow unboundly

/// // stack. using a tail call guarantees that the stack will not grow unboundedly

Kivooeo · 2025-08-05T10:13:01Z

library/std/src/keyword_docs.rs

+/// }
+/// ```
+///
+/// Compiler can already perform "tail call optimization" -- it can replace


Suggested change

/// Compiler can already perform "tail call optimization" -- it can replace

/// The compiler can already perform "tail call optimization" -- it can replace

I'm not sure I agree with this, can you elaborate?

"compiler" is singular and countable, I believe such nouns require a determiner

but if we drop the formalities, I just feel that way and sentence does looks more complete with "the"

It could also be "Compilers"

library/std/src/keyword_docs.rs

Kivooeo · 2025-08-05T10:17:12Z

library/std/src/keyword_docs.rs

+/// fn help() {}
+/// ```
+///
+/// For this reason `become` also changes the drop order, such that locals are


Suggested change

/// For this reason `become` also changes the drop order, such that locals are

/// For this reason, `become` also changes the drop order, such that locals are

Kivooeo · 2025-08-05T10:20:30Z

library/std/src/keyword_docs.rs

+///
+/// In order to guarantee that the compiler can perform a tail call, `become`
+/// currently has these requirements:
+/// 1. callee and caller must have the same ABI, arguments and return type


Suggested change

/// 1. callee and caller must have the same ABI, arguments and return type

/// 1. callee and caller must have the same ABI, arguments, and return type

I believe it is Serial comma case here

library/std/src/keyword_docs.rs

workingjubilee

Yes, thank you. Some nits, but otherwise that's much more "something I would actually expect to use become on" without shoving e.g. sample code for a heavily-optimized interpreter into the codebase.

View changes since this review

library/std/src/keyword_docs.rs

workingjubilee · 2025-09-12T19:27:05Z

library/std/src/keyword_docs.rs

+/// }
+/// ```
+///
+/// Compiler can already perform "tail call optimization" -- it can replace


It could also be "Compilers"

workingjubilee · 2025-09-12T19:27:34Z

library/std/src/keyword_docs.rs

+/// ```
+///
+/// Compiler can already perform "tail call optimization" -- it can replace
+/// normal calls with tail calls (although no guarantees if it will perform it).


Suggested change

/// normal calls with tail calls (although no guarantees if it will perform it).

/// normal calls with tail calls, although nothing guarantees this will be done.

workingjubilee · 2025-09-12T19:28:37Z

library/std/src/keyword_docs.rs

+///
+/// Compiler can already perform "tail call optimization" -- it can replace
+/// normal calls with tail calls (although no guarantees if it will perform it).
+/// However, to perform TCO, the call needs to be the last thing that happens


I believe we should prefer "tail-call elimination" over "TCO", since it's not really an "optimization" per se but rather a guaranteed behavior of the compiler.

Suggested change

/// However, to perform TCO, the call needs to be the last thing that happens

/// However, to perform tail-call elimination, the call needs to be the last thing that happens

Ah, I missed that this phrase was used earlier due to wading through the comments a bit. I don't have any issue with using an initialism after introducing the phrase, mind.

library/std/src/keyword_docs.rs

WaffleLapkin · 2025-09-13T17:47:21Z

@rustbot review

rustbot · 2025-09-13T17:48:26Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

workingjubilee · 2025-09-13T19:23:07Z

Thanks! This looks much better as-is and any further documentation haggling can be on top of it.

@bors r+ rollup

bors · 2025-09-13T19:23:10Z

📌 Commit f13c8c2 has been approved by workingjubilee

It is now in the queue for this repository.

Rollup of 8 pull requests Successful merges: - #113095 (Document `become` keyword) - #146159 (Some hygiene doc improvements) - #146171 (tidy: check that error messages don't start with a capitalized letter) - #146419 (Update the arm-* and aarch64-* platform docs.) - #146473 (Revert "Constify SystemTime methods") - #146506 (Fix small typo in check-cfg.md) - #146517 (fix Condvar::wait_timeout docs) - #146521 (document `core::ffi::VaArgSafe`) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #113095 - WaffleLapkin:document_becoming_unuwuable, r=workingjubilee Document `become` keyword 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 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

26 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

This comment has been minimized.

Sign in to view

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

WaffleLapkin force-pushed the document_becoming_unuwuable branch from 0888a94 to 46ffda7 Compare August 2, 2025 01:08

Kivooeo reviewed Aug 5, 2025

View reviewed changes

workingjubilee added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-blocked Status: Blocked on something else such as an RFC or other implementation work. labels Sep 10, 2025

workingjubilee approved these changes Sep 12, 2025

View reviewed changes

workingjubilee 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 Sep 12, 2025

WaffleLapkin force-pushed the document_becoming_unuwuable branch from 46ffda7 to 8e699c5 Compare September 13, 2025 17:45

This comment has been minimized.

Sign in to view

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

WaffleLapkin added 2 commits September 13, 2025 19:48

Document become keyword

cc92254

fixup become kw documentation wrt #[track_caller]

f13c8c2

WaffleLapkin force-pushed the document_becoming_unuwuable branch from 8e699c5 to f13c8c2 Compare September 13, 2025 17:48

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 13, 2025

jhpratt mentioned this pull request Sep 13, 2025

Rollup of 8 pull requests #146526

Merged

bors merged commit e9c80c7 into rust-lang:master Sep 14, 2025
10 checks passed

rustbot added this to the 1.91.0 milestone Sep 14, 2025

WaffleLapkin deleted the document_becoming_unuwuable branch September 14, 2025 02:52

	/// 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

	/// This is useful for writing functional-style code (since it prevent recursion
	/// This is useful for writing functional-style code (since it prevents recursion

	/// // stack. using a tail call guarantees that the stack will not grow unboundly
	/// // stack. using a tail call guarantees that the stack will not grow unboundedly

	/// Compiler can already perform "tail call optimization" -- it can replace
	/// The compiler can already perform "tail call optimization" -- it can replace

	/// For this reason `become` also changes the drop order, such that locals are
	/// For this reason, `become` also changes the drop order, such that locals are

	/// 1. callee and caller must have the same ABI, arguments and return type
	/// 1. callee and caller must have the same ABI, arguments, and return type

	/// normal calls with tail calls (although no guarantees if it will perform it).
	/// normal calls with tail calls, although nothing guarantees this will be done.

	/// However, to perform TCO, the call needs to be the last thing that happens
	/// However, to perform tail-call elimination, the call needs to be the last thing that happens

Document become keyword #113095

Document become keyword #113095

Uh oh!

Conversation

WaffleLapkin commented Jun 27, 2023

Uh oh!

rustbot commented Jun 27, 2023

Uh oh!

This comment has been minimized.

Rageking8 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WaffleLapkin Jun 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Robbepop Jun 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

workingjubilee commented Jul 31, 2023

Uh oh!

JohnCSimon commented Dec 17, 2023

Uh oh!

WaffleLapkin commented Dec 18, 2023

Uh oh!

xacrimon commented Jul 22, 2025

Uh oh!

WaffleLapkin commented Jul 25, 2025

Uh oh!

WaffleLapkin commented Aug 2, 2025

Uh oh!

Kivooeo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Document `become` keyword #113095

Document `become` keyword #113095

WaffleLapkin Jun 19, 2024 •

edited

Loading

Robbepop Jun 19, 2024 •

edited

Loading

Kivooeo left a comment •

edited

Loading

workingjubilee left a comment •

edited

Loading