Method call reference: major rewrite

[adetaylor]

This section of the reference has been oversimplistic for some time (#1018 and #1534) and various rewrites have been attempted (e.g. #1394, #1432). Here's another attempt!

My approach here is:

• Stop trying to keep it short and concise
• Document what actually happens in the code, step by step

This does result in a long explanation, because we're trying to document nearly 2400 lines of code in probe.rs, but doing otherwise feels as though we'll continue to run into criticisms of oversimplification.

This rewrite documents the post-arbitrary-self-types v2 situation, i.e. it assumes rust-lang/rust#135881 has landed. We should not merge this until or unless that lands.

This PR was inspired by discussion in #1699. If we go ahead with this approach, #1699 becomes irrelevant. There was also discussion at rust-lang/cargo#15117 (comment)

Tracking:

• Tracking issue for RFC 3519: arbitrary_self_types rust#44874

[madsmtm]

Fully agree that it's better to list this out in detail than trying to condense it down to unreadable, and what you've written here is phenomenal!

[madsmtm]

Nit: is "tyings" a typo or jargon?

[madsmtm]

And what does incoherent mean here? Is it in terms of Trait Implementation Coherence?

[madsmtm]

Ah, are we talking the fake "Integer" type the literal 42 has before it turns into i32?

[adetaylor]

"tyings" was a typo.
I don't know what "incoherent" means here - I was rather hoping that this was obvious to all possible readers except me :) Sadly not, I'll look it up and expand this bit!

[traviscross]

We don't generally document unstable features, but this is the kind of case that makes me pretty sad about taking it out, as the comprehensiveness here is nice. Wish we had a way to conditionalize this somehow.

cc @nikomatsakis as an example for us to think about.

[traviscross]

Overall, this is fantastic. Very much an improvement. Thanks @adetaylor.

[traviscross]

Is there any way for stable Rust code to be affected by this, e.g. by how this is applied to the Error trait or the CStr type?

[adetaylor]

Good question, this is another thing I'll need to go and figure out

[rustbot]

☔ The latest upstream changes (possibly 4249fb4) made this pull request unmergeable. Please resolve the merge conflicts.

[tmandry]

Should one of these say "trait"? I'm a little confused what is meant by "object" vs "type". I know one of them is the dyn Trait type, but not sure which it is.

[adetaylor]

Fair, I'll try to figure it out myself and amend this!

[traviscross]

You're of course the expert here, but is this parenthetical, and are the parentheticals added below, correct?

To me, it seems that what probe.rs considers to be an "inherent candidate" is (something in the vicinity of) one that can be deduced exclusively from the signature, including WCs, whereas an "extension candidate" is one that considers the traits in scope. So, e.g., in...

impl<F: FnPtr> hash::Hash for F {
    fn hash<HH: hash::Hasher>(&self, state: &mut HH) {
        state.write_usize(self.addr() as _)
    }
}

(From library/core/src/ptr/mod.rs.)

...the hash::Hasher::write_usize method is an "inherent candidate" even though it is from a trait, and it is not an "extension candidate" because Hasher is not in scope.

This is, I surmise, what answers @tmandry's question in the other thread about what it means to find inherent candidates on type parameters.

Anyway, if you would, have a look and see what's correct here. We should probably somewhere just clearly define what we mean by "inherent candidate" and "extension candidate" and lean into the model used by probe.rs.

Also cc @nikomatsakis who seems to have written much of this way back when.

[mattheww]

Note there's another description of the method lookup process in the
rustc-dev-guide.

[mattheww]

As I understand it, the "further search for extension candidates for traits in scope." happens once, not once for each candidate type, so I suggest putting this after the bulleted list rather than as part of it.

Perhaps mention the special case described in #630 (comment) here?

[mattheww]

One thing that makes this business difficult to document is that method lookup happens when type inference is not yet complete (and the results of method lookup participate in type inference).

All the writeups I've seen gloss over this by writing "the receiver type" and then proceeding to describe what happens as if that type was fully determined.

I'm not sure how much detail it makes sense to go into on this page as long as the Reference has very little to say in general about type inference. But I think it might be worth mentioning that:

• At this point the receiver type might be something like Vec<?>, which I think explains how the "If there are multiple candidates from traits, they may in fact be identical" case can happen.

• If the type isn't constrained at all by the code coming before the method call, method resolution will just give up (even if there's only one possible type for which the method call could work).

[mattheww]

It might also be worth noting explicitly that the types of parameters in the method call expression aren't taken into account in method resolution. Even the number of parameters is ignored. So the following won't compile, because the method from NoParameter is found earlier in the picking process even though it's "obviously" the wrong one.

trait NoParameter {
    fn method(self);
}

trait OneParameter {
    fn method(&self, jj: i32);
}

impl NoParameter for char {
    fn method(self) {}
}

impl OneParameter for char {
    fn method(&self, jj: i32) {}
}

fn f() {
    'x'.method(123);
}

[obi1kenobi]

Wow, this example is very surprising to me!

With my "cargo-semver-checks maintainer" hat on, it's extremely useful to have someplace where these details are written up with examples like this. The better I can understand these nuances, the better our rules for discovering breakage will be.

I will leave to you all the question of whether the reference or some other location is the best place to document these behaviors.