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:

• Zero-sized structs should be FFI-safe #17679
• Using #[repr(C)] on unit structs should warn #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.