Document the correct FFI equivalent to a C opaque struct

[crumblingstatue]

With recent changes to the improper_ctypes lint, it now rejects #[repr(C)] struct Foo; for representing a C opaque struct.

#[repr(C)]
pub struct Foo;

extern "C" {
    pub fn foo(arg: *const Foo);
}

fn main() {
}

foo.rs:5:25: 5:28 warning: found zero-size struct in foreign module, consider adding a member to this struct, #[warn(improper_ctypes)] on by default
foo.rs:5    pub fn foo(arg: *const Foo);
                                   ^~~

On the #rust IRC channel, I have asked what is the proper way to represent a C opaque struct, but no definitive answer was reached.

Some of the answers were:

• struct Foo; is incorrect.
• struct Foo; is fine, but it can break certain LLVM optimizations.
• Use c_void instead. This isn't satisfactory when it is desirable to represent a C opaque struct as a distinct type in your API.
• Use a newtype wrapper around c_void. Someone said this might not be correct either.
• Rustc should allow #repr(C) enum Foo {}. It doesn't currently allow this.

This should be properly researched and then documented in the official documentation, so users know what to use for representing C opaque struct types in Rust when interfacing with C code.

Some relevant issues:

• #17679
• #20660

[geofft]

It looks like the canonical answer here is a #[repr(u8)] enum containing two private variants, like libc::c_void, as described in PR #11539. But it's not clear whether that is simply the optimized option, or the only ABI-valid option for void *. std::os::raw::c_void also provides its own copy of the structure.

But @crumblingstatue wants to newtype this for type safety, and it isn't clear whether newtyping this structure (struct Foo(c_void)) gives us something of the same ABI as c_void itself. The rust repo itself doesn't seem to ever do so, but has a few type aliases (type Foo = *mut libc::c_void), which provide worse type safety than C, since these pointers can be freely assigned to each other.

A few places in the rust repo, some external docs, and some projects (including Servo) use *mut () as a void-pointer type.

I can see few options here:

1. Stabilize the representation of a raw pointer to #[repr(C)] struct Foo; as ABI-compatible with C opaque struct pointers (which would incidentally stabilize *mut ()).
2. Stabilize #[repr(C)] enum Foo {}, which was suggested on #rust as better because you can't construct one. Right now that doesn't compile, so this is clearly backwards-compatible.
3. Ensure that the newtype approach, struct Foo(c_void), works, and stabilize it.
4. Document that people should make their own two-private-variant #[repr(u8)] enums. Maybe make a macro?

Whatever the answer, it should be documented in the book's FFI section as well as in the doc comment on libc::c_void.

[alexcrichton]

Note that the only reason c_void has two variants is to allow the #[repr(u8)] tag, and the only reason that's done is so LLVM can recognize malloc and free and enable the various optimizations around memory allocation. I don't believe there are any other optimizations you miss out on from something like struct Foo; or just a plain enum Foo {}.

I personally would not recommend struct Foo; as a pattern because it's not serving its purpose of an opaque type marker (you can construct an instance via Foo). In bindings I've written I typically use enum Foo {} (note the lack of repr) and it works when you only use *mut Foo in the FFI bindings.

[eefriedman]

The reason we don't accept #[repr(C)] struct Foo; is that it isn't laid out the same way as an empty struct in C++.

[tomjakubowski]

I personally would not recommend struct Foo; as a pattern because it's not serving its purpose of an opaque type marker (you can construct an instance via Foo). In bindings I've written I typically use enum Foo {} (note the lack of repr) and it works when you only use *mut Foo in the FFI bindings.

This is exactly what I've done in my projects, although I haven't tried with the newly rewritten improper-ctypes lint.

[Ms2ger]

Servo uses enum Foo {}.

[bluss]

@Ms2ger Doesn't the ffi-safe lint trigger on that too?

[tomjakubowski]

@bluss raw pointers to Sized types are always allowed in FFI signatures, AFAIK.

[goertzenator]

A consequence of using enums for opaque structs is that the generated documentation will move from the Structs section to the Enums section. This makes the documentation confusing and misleading especially when there are also "normal" structs and enums.

[nox]

Wouldn't struct Foo(Void) be better, for the problem mentioned by @goertzenator?

[geofft]

Oh yeah, I guess given the advice above that #[repr(u8)] isn't needed for correctness, just for the malloc and free optimization, I think you're right. (Making a newtype of libc::c_void was proposed above; the only objection was that the #[repr(u8)] wouldn't survive the newtype.)

It might be nice to have enum Void {} somewhere in libstd.

[nox]

Maybe not Void, but an empty enum named Opaque or something like that. There is a void crate with a Void type that implements various traits already. We don't want such a thing.

[shepmaster]

What about this to leave it named a "struct" in rustdoc:

struct Foo {
    marker: PhantomData<()>,
}

or perhaps

struct Foo {
    _unused: (),
}

Note that I'm avoiding struct Foo(PhantomData<()>) as Foo would still be a function you could attempt to call; the brace version fails earlier for let f = Foo.

[shepmaster]

What about this to leave it named a "struct" in rustdoc:

Nah, this isn't a better idea, as this type is actually constructible (although it takes a smidge more work).