Add description for LUB Coercion

[ldm0]

As requested in rust-lang/rust#71599. Also references the rust-lang/rust#48109 (comment)

[Havvy]

First off, thanks for writing this! That said, it looks very rushed and doesn't actually describe what these coercions actually are. I don't actually know the algorithm for the coercion, so just including that would be tremendously helpful, but I've listed extensive notes on my thoughts on the contents of this PR. How much you want to turn them into work for yourself is up to you, except again, we do need the actual algorithm.

[ldm0]

Notice I added explanation for LubCoerce with expected type in the end. That's because it's really how rustc currently works. You can check that by test these:

This compiles:

let esc: &[u8] = match true {
    true => b"ab", // &[u8; 2]
    false => b"c",  // &[u8; 1]
};

This failes to compile:

let esc = match true {
    true => b"ab",
    false => b"c",
};

Why?

1. Lub(&[u8], &[u8; 2]) == &[u8]
2. Lub(&[u8], &[u8; 1]) == &[u8]
3. Lub(&[u8; 2], &[u8; 1]) fails

[Havvy]

I've sent my review as a new PR @ ldm0#1

[Havvy]

Looking at @ehuss for final approval.

(Also, I think the algorithm might be better expressed in text than code after looking at it, but that can be done later)

[ehuss]

I also generally prefer to not introduce ad-hoc pseudo-code, since it is undefined and open to interpretation. However, I think something is better than nothing, so it's probably fine for now. I also suspect a truly formal definition would be a much greater effort.

I'm not qualified to comment on the actual rules, since I know nothing about type coercion. I would be more comfortable with a lang team member to approve.

[ldm0]

Waiting on a lang team member to approve. :D

To check the correctness of the pseudo code, reviewers can check CoerceMany::coerce_inner() and FnCtxt::try_find_coercion_lub(). To check how compiler processes the expected type, reviewers can check FnCtxt::check_match().

[nikomatsakis]

Gave this a first read. Sorry for the long delay. I'll try to offer some more concrete suggestions in a bit. I am wondering if we can do something less "pseduo-code" and a bit higher-level -- that said, the algorithm is kind of "operational" though.

[nikomatsakis]

Hmm this notation is kind of ad-hoc -- I expected to see an actual type here. I guess I might say something like:

The type of foo and bar is the result of applying the LUB coercion to the types of a, b, and c.

[nikomatsakis]

I wonder btw if we should incorporate mdbook-mermaid into the reference ... then we could use a flow-chart here -- not sure how much better that would be ;)

[ldm0]

cc @ehuss

[nikomatsakis]

Hmm, the actual code seems to have a bit more of a "bias", i.e., it has a notion of "old and new", and ordering I think maybe can matter. I wonder if we can write this section with a bit less specificity -- let me check how the coercion section is written.

[ldm0]

@nikomatsakis Thanks for reviewing. Does the "old and new" means the prev_ty and new_ty in the code? I think it's represented in this part:

LubCoerce(vars...):
  result = vars.get(0)
  for var in vars[1..]:
    result = Lub(result, var)
  return result

Where result represents the prev_ty and var represents the new_ty. If you mean other things with "old and new". Could you elaborate more?

But for the ordering, I re-thinked about it and found it do matters in some cases(some edge cases). I will remove the property 1 later.

[nikomatsakis]

Yes, old and new does correspond to prev and new.

[nikomatsakis]

So I guess an alternative would be to describe the LUB coercion more informally and less precisely. Something like the following (@ldm0 you would obviously want to amend this to include the coercion from FnDef/closures to fn pointers that started all of this). I'm curious @ehuss or others what you think of these two options.

I think I mildly prefer an informal description like this one, because I think that it is probably sufficient to give readers an intuition for what the compiler is trying to do, and I suspect that the more precise description is ultimately not sufficiently precise to be "authoratative" and hence we're better off leaving that job to the code itself.

---

In some contexts, the compiler must coerce together multiple types to try and find the most general type. This is called a "Least Upper Bound" coercion. Some examples where the LUB coercion algorithm is used are:

• to find the common type for a series of match arms; or
• to find the common type for the return type of a closure with multiple return statements.

In each such case, there are a set of types T0..Tn to be mutually coerced to some target type T_t, which is unknown to start. Computing the LUB coercion is done iteratively. The target type T_t begins as the type T0. For each new type Ti, we consider whether

• If Ti can be coerced to the current target type T_t, then no change is made.
• Otherwise, we check whether T_t can be coerced to Ti; if so, the T_t is changed to Ti. (This check is also conditioned on whether all of the source expressions considered thus far have implicit coercions.)
• If not, we try to compute a mutual supertype of T_t and Ti, which will become the new target type.

Examples

XXX give some interesting examples

Caveat

This description is obviously informal. Making it more precise is expected to proceed as part of a general effort to specify the Rust type checker more precisely.

[Havvy]

The list of where LUB coercions happen should at least be an exhaustive list, not just "examples where it is performed".

[Havvy]

Where are we with this?

[ldm0]

Sorry for the long delay. Rewrite done. Exhaustive list added

[nikomatsakis]

Thanks!