Add opaque structs to TRPL:FFI

[steveklabnik]

Fixes #27303

[rust-highfive]

r? @nikomatsakis

(rust_highfive has picked a reviewer for you, use r? to override)

[steveklabnik]

r? @alexcrichton

[geofft]

It would be nice if you mentioned the C headers/prototypes that are being bound here, e.g.

struct Foo; /* Foo is a structure, but its contents are not part of the public interface */
struct Bar;
void foo(struct Foo *arg);
void bar(struct Bar *arg);

so that people know what an opaque struct looks like in C. This is something you don't really have to pay attention to a library user, so the terminology might be unclear (especially the distinction from the C++ or nonstandard C syntax struct Foo {/* no members */};.)

Which brings up one quibble I have here: if the original C API actually does use opaque structs, instead of void pointers, then C users of that API are type-safe. C compilers will warn you about casts between pointers of different types, unless void * is involved. So the first set of Rust bindings in these docs is less type-safe than C, which is probably not a thing we want to encourage. The phrasing "we can at least get type-safety on the Rust side" is a bit misleading here.

I guess you were envisioning binding a C API that uses void * in its public declarations, but I think that lots of C APIs make good use of pointers to opaque structs for this very reason, and that's the use case that #27303 was getting at. Maybe it's worth mentioning both styles of C prototype, and making it clear that you can do the type-safe thing in Rust, whether or not the original C API is type-safe.

[geofft]

This seems to imply that in order to create an opaque type that we can't instantiate, we must not annotate it with repr(C), which is a bit confusing since #[repr(C)] enum Foo {} doesn't compile. Maybe you want something more like

"By using an enum with no variants, we create an opaque type that we can't instantiate. (Note that we don't annotate it with repr(C), which isn't valid syntax for enums.)"

[alexcrichton]

This is actually one of the special cases where #[repr(C)] on an enum is invalid, but there are cases where that's useful:

#[repr(C)]
enum Foo {
    Bar,
    Baz = 3,
    Foobar,
}

I believe you just need to have at least 2 variants and none of the variants can have a data payload.

[steveklabnik]

yeah, i'll just take that bit out, as it's more distracting

[steveklabnik]

Try this new version on for size.

[geofft]

Unclear what "this" is -- did it get lost in refactoring? Did you want to say that foo and bar take different types of arguments?

[alexcrichton]

@bors: r+ 8c4dc18 rollup