From 54bd9e6323742de87a526931a15558319db30604 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Sun, 25 May 2014 19:57:17 -0700 Subject: [PATCH] docs: don't claim struct layout is specified, but mention repr --- src/doc/guide-ffi.md | 18 +++++++++--------- src/doc/rust.md | 26 ++++++++++++++++++++------ 2 files changed, 29 insertions(+), 15 deletions(-) diff --git a/src/doc/guide-ffi.md b/src/doc/guide-ffi.md index 600a9019e6b..256bcb2949e 100644 --- a/src/doc/guide-ffi.md +++ b/src/doc/guide-ffi.md @@ -268,7 +268,7 @@ struct RustObject { // other members } -extern fn callback(target: *mut RustObject, a:i32) { +extern "C" fn callback(target: *mut RustObject, a:i32) { println!("I'm called from C with value {0}", a); unsafe { // Update the value in RustObject with the value received from the callback @@ -506,16 +506,16 @@ to define a block for all windows systems, not just x86 ones. # Interoperability with foreign code -Rust guarantees that the layout of a `struct` is compatible with the platform's representation in C. -A `#[packed]` attribute is available, which will lay out the struct members without padding. -However, there are currently no guarantees about the layout of an `enum`. +Rust guarantees that the layout of a `struct` is compatible with the platform's representation in C +only if the `#[repr(C)]` attribute is applied to it. `#[repr(C, packed)]` can be used to lay out +struct members without padding. `#[repr(C)]` can also be applied to an enum. -Rust's owned and managed boxes use non-nullable pointers as handles which point to the contained +Rust's owned boxes (`Box`) use non-nullable pointers as handles which point to the contained object. However, they should not be manually created because they are managed by internal -allocators. References can safely be assumed to be non-nullable pointers directly to the -type. However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so -prefer using raw pointers (`*`) if that's needed because the compiler can't make as many assumptions -about them. +allocators. References can safely be assumed to be non-nullable pointers directly to the type. +However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so prefer +using raw pointers (`*`) if that's needed because the compiler can't make as many assumptions about +them. Vectors and strings share the same basic memory layout, and utilities are available in the `vec` and `str` modules for working with C APIs. However, strings are not terminated with `\0`. If you need a diff --git a/src/doc/rust.md b/src/doc/rust.md index 206ec787d5e..ad459c57c86 100644 --- a/src/doc/rust.md +++ b/src/doc/rust.md @@ -1308,6 +1308,9 @@ struct Cookie; let c = [Cookie, Cookie, Cookie, Cookie]; ~~~~ +The precise memory layout of a structure is not specified. One can specify a +particular layout using the [`repr` attribute]( + By using the `struct_inherit` feature gate, structures may use single inheritance. A Structure may only inherit from a single other structure, called the _super-struct_. The inheriting structure (sub-struct) acts as if all fields in the super-struct were present in the sub-struct. Fields declared in a sub-struct @@ -1941,6 +1944,23 @@ interpreted: - `linkage` - on a static, this specifies the [linkage type](http://llvm.org/docs/LangRef.html#linkage-types). +On `enum`s: + +- `repr` - on C-like enums, this sets the underlying type used for + representation. Takes one argument, which is the primitive + type this enum should be represented for, or `C`, which specifies that it + should be the default `enum` size of the C ABI for that platform. Note that + enum representation in C is undefined, and this may be incorrect when the C + code is compiled with certain flags. + +On `struct`s: + +- `repr` - specifies the representation to use for this struct. Takes a list + of options. The currently accepted ones are `C` and `packed`, which may be + combined. `C` will use a C ABI comptible struct layout, and `packed` will + remove any padding between fields (note that this is very fragile and may + break platforms which require aligned access). + ### Miscellaneous attributes - `export_name` - on statics and functions, this determines the name of the @@ -1958,12 +1978,6 @@ interpreted: crate at compile-time and use any syntax extensions or lints that the crate defines. They can both be specified, `#[phase(link, plugin)]` to use a crate both at runtime and compiletime. -- `repr` - on C-like enums, this sets the underlying type used for - representation. Useful for FFI. Takes one argument, which is the primitive - type this enum should be represented for, or `C`, which specifies that it - should be the default `enum` size of the C ABI for that platform. Note that - enum representation in C is undefined, and this may be incorrect when the C - code is compiled with certain flags. - `simd` - on certain tuple structs, derive the arithmetic operators, which lower to the target's SIMD instructions, if any; the `simd` feature gate is necessary to use this attribute.