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"

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

library/std/src/keyword_docs.rs

+/// 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
+/// in the functions and be returned from it. This requirement is often broken
+/// by drop code for locals, which is run after computing the return expression:


Suggested change

/// by drop code for locals, which is run after computing the return expression:

/// by drop code for locals, which runs after computing the return expression:

Is run seems fine to me?

Yeah, looking at this now, this is fine as it is

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

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

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


Suggested change

/// // without `become`, on big inputs this could easily overflow the

/// // without `become`, on large inputs this could easily overflow the

Can you elaborate?

There is no actual rule for it, but I will try to explain this: both "big" and "large" are pretty the same in casual speech, but in techical/scientific writings "large" is more preffered term, it just sounds more neutral or formal

(https://langeek.co/en/grammar/course/1100/big-vs-large)

Kivooeo · 2025-08-05T10:22:42Z

library/std/src/keyword_docs.rs

+/// 1. callee and caller must have the same ABI, arguments and return type
+/// 2. callee and caller must not have varargs
+/// 3. callee and caller must not be marked with `#[track_caller]`
+/// 4. callee and caller cannot be a closure


Suggested change

/// 4. callee and caller cannot be a closure

/// 4. callee and caller cannot be a closures

Shouldn’t it be plural, since varargs above are plural? Not sure about this honestly

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

Document become keyword

46ffda7

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

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

	/// by drop code for locals, which is run after computing the return expression:
	/// by drop code for locals, which runs after computing the return expression:

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

	/// // without `become`, on big inputs this could easily overflow the
	/// // without `become`, on large inputs this could easily overflow the

	/// 4. callee and caller cannot be a closure
	/// 4. callee and caller cannot be a closures

Document become keyword #113095

Are you sure you want to change the base?

Document become keyword #113095

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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