Correct errors in the reference of extern functions definitions and declarations

[gnzlbg]

The current reference of extern functions definitions is incorrect. It doesn't take into account that all "normal" Rust functions are extern "Rust" fn.

The section about external blocks specifies that only "non-Rust functions" (whatever that means) can be declared in external blocks. This is incorrect, since both an extern "C" Rust function, and a function with the "Rust" ABI, can be declared in external blocks.

[gnzlbg]

@eddyb would you be able to review these changes as well ? Particularly, I've added that some ABIs are equivalent to "Rust" and documented this for some of them. Would like to triple-check that this is indeed actually the case.

[gnzlbg]

@Centril I also have the feeling that talking about function definitions/declarations is maybe too "C/C++ speak".

Is there a better and clearer way to talk about these in "Rust speak" ? The only thing that comes to mind is to consistently use "function item" for "definitions" (fn foo() {}), "external function item" for "declarations" (extern { fn foo(); }), and "extern-qualified function item" or "function item with an extern qualifier" for a "definition" that uses the extern qualifier (extern fn foo() {}). However, I feel that it is too easy to confuse "external function item" with "extern-qualified function item" when discussing this part of the language.

[Centril]

@Centril I also have the feeling that talking about function definitions/declarations is maybe too "C/C++ speak".

See https://doc.rust-lang.org/nightly/reference/items/traits.html#traits
You'll note:

TraitFunc :
      TraitFunctionDecl ( ; | BlockExpression )

I think it's fine to use "declaration" for function signatures and definitions for declarations enhanced with a block expression.

[gnzlbg]

I think it's fine to use "declaration" for function signatures and definitions for declarations enhanced with a block expression.

Makes sense, I'll keep the text that uses definition/declarations then.

Maybe we could open an issue about updating the extern-block section to use "ExternalFunctionDeclaration" instead of "ExternalFunctionItem". I am not sure if such a change makes sense, or whether there are other places where we might want to take this into account. Probably should be consistent with the grammar as well, although maybe the grammar calls these something different, no idea.

[Centril]

Let's do that in a follow up if so; we'll need to make sure that we have no stale references to/in the grammar if we change.

[eddyb]

I think this could be more explicit that these are "imports" of a sort.

[gnzlbg]

I've tried to clarify that.

[Centril]

Nit: "sort of like" reads rather like spoken English (not something you'd find in an IEEE paper, which is the sort of style we should shoot for imo...).

[gnzlbg]

I didn't intend to take @eddyb feedback literally here, but that's the best I could come up with.

These blocks declare that something exists in a particular way. If you "use" (call, access, etc.) it and it doesn't exist, or it exists in a way that's different than how you declared it: boom. If you don't actually use it, whether it exists doesn't matter, and if it doesn't, that's ok.

OTOH, to me, an import is an operation that brings something into scope that exists. If it doesn't exist, then you can't import it. So I'm not sure what would be the best way to make an analogy with imports here.

Maybe something like

Declarations are similar to imports, in that they bring an item into scope. The main difference is that an import requires an item to exist, while a declaration states that an item exists with a particular type signature, attributes, etc. at a particular path. In contrast with imports, a declaration only needs to exist when it is "used" (for a function, called, for a static, accessed). This allows, for example, declaring a dynamically-linked function unconditionally and copying its function type around even when the dynamic library that links it isn't actually linked. The function is only required to exist (e.g. the dynamic library to be linked) when the program actually calls the function.

?

[gnzlbg]

Maybe with an example like this:

extern "C" { fn foo(); }

fn main() {
    let x = foo;
    if symbol_of_foo_not_linked() {
         link_symbol_of_foo();
    }
    unsafe { x() };
}

?

[Centril]

@eddyb @ehuss wdyt about the wording ^-- ?

[eddyb]

I use "FFI import" to mean something different from what the use item does in Rust, so I'm not comparing the two but rather using the more general meaning of "import".

Also, not sure that where the function comes from in terms of linkage is that important, compared to the fact that it likely isn't even written in Rust, hence "FFI".

[Havvy]

A couple small nits; Given the number of eyes and the number of changes, I'd like to see this land, and a new PR open for more changes. Don't let perfect be the enemy of good.

[Havvy]

This is a run-on sentence, or at least feels like one. Also, "Rust's functions". And what does "foreign code" here mean differently than code from other programming languages?

[Centril]

Rust code exposed with a C ABI.

[gnzlbg]

I'm not sure how to improve this.

[gnzlbg]

cc @Gankra

[Gankra]

Since most of the discussion is collapsed and there's 14 commits of history, it's hard for me to tell what happened here.

I just want to get a clarification as to what has happened here with rust-call/rust-intrinsic/platform-intrinsic. They were never properly documented so it's unclear to be exactly what they imply (rust-intrinsic is only clearish one to me).

Are these things stricken from the record as pure perma-unstable implementation details that no one should ever have to think about? Is there another document somewhere that stdlib and rustc devs can refer to for the meaning of them? (rustc/std should be the most active users of a reference, after all)

In particular it is slightly interesting to me as to whether callers of rust-intrinsic and platform-intrinsic methods can rely on them never unwinding (I assume rust-call must in fact be allowed to unwind).

[gnzlbg]

I just want to get a clarification as to what has happened here with rust-call/rust-intrinsic/platform-intrinsic. [...] Are these things stricken from the record as pure perma-unstable implementation details that no one should ever have to think about?

IIUC, the reference is only intended (at least for the time being), to document stable Rust. All unstable Rust information should be documented in the Unstable Book.

Now, the information that this PR removes is about perma-unstable features that are not intended to ever be stabilized. Most people, including most of those hacking in the standard library, shouldn't have to know about this. Knowledge about these is only required if you are touching standard library code that requires special compiler support. So the ideal place to document these would probably be the rustc book.

The information that this PR removes wasn't great either, and it is a bit out-of-date. For example, most "platform-intrinsic" (thousands of them) were removed from rustc a while ago, and now AFAICT this ABI is only used for generic SIMD intrinsics... for no good reason. As @eddyb pointed out here, we probably want to just change these to be extern "Rust" and handle their "magicness" somehow else.

In particular it is slightly interesting to me as to whether callers of rust-intrinsic and platform-intrinsic methods can rely on them never unwinding

They can't. These are essentially extern "Rust" which can unwind. Whether these unwind or not, would depend on the concrete intrinsic that we are dealing with (I don't have any concrete intrinsic in mind that actually unwinds, but this doesn't mean there isn't one).

[Gankra]

I expect whatever primitive operation integer addition lowers to is a fine canonical example of an unwinding intrinsic.

[gnzlbg]

@Havvy @Centril I'm uncertain of which changes are still required here.

addressed