Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document become keyword #113095

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+63 −0
Open

Document become keyword #113095

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
820c1c5
Document `become` keyword
WaffleLapkin May 10, 2023
0888a94
Fix typos
WaffleLapkin Jun 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions library/std/src/keyword_docs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1228,6 +1228,69 @@ mod ref_keyword {}
/// ```
mod return_keyword {}

#[doc(keyword = "become")]
//
/// Perform a tail-call of a function.
///
/// A `become` transfers the execution flow to a function in such a way, that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

/// returning from the callee returns to the caller of the current function:
///
/// ```
/// #![feature(explicit_tail_calls)]
///
/// fn a() -> u32 {
/// become b();
/// }
///
/// fn b() -> u32 {
/// return 2; // this return directly returns to the main ---+
/// } // |
/// // |
/// fn main() { // |
/// let res = a(); // <--------------------------------------+
/// assert_eq!(res, 2);
/// }
/// ```
///
/// This is an optimization that allows function calls to not exhaust the stack.
/// This is most useful for (mutually) recursive algorithms, but may be used in
/// other cases too.
///
/// It is guaranteed that the call will not cause unbounded stack growth if it
/// 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// different from them, even though it is written almost identically to
/// 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.
Comment on lines +1262 to +1266
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

///
///
/// ```
/// #![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
/// }
/// ```
Comment on lines +1262 to +1285
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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));
    }
}

Copy link
Member Author

@WaffleLapkin WaffleLapkin Jun 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :')

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@Robbepop Robbepop Jun 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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);
}

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

///
/// Note that from an algorithmic standpoint, loops and tail-calls are
/// interchangeable, you can always rewrite a loop to use tail-calls
/// instead and vice versa. They are, however, very different in the code
/// structure, so sometimes one approach can make more sense than the other.
#[cfg(not(bootstrap))]
mod become_keyword {}

#[doc(keyword = "self")]
//
/// The receiver of a method, or the current module.
Expand Down