OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Document the nullable pointer optimization in the FFI guide

Browse Source 
Closes #8748
This commit is contained in:
Corey Richardson 2014-04-10 20:29:09 -04:00
parent 5bcb76181a
commit eabf78c7b9
1 changed files with 13 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
src/doc/guide-ffi.md
View File

@ -496,3 +496,16 @@ NUL-terminated string for interoperability with C, you should use the `c_str::to
The standard library includes type aliases and function definitions for the C standard library in
the `libc` module, and Rust links against `libc` and `libm` by default.
# The "nullable pointer optimization"
Certain types are defined to not be `null`. This includes references (`&T`,
`&mut T`), owning pointers (`~T`), and function pointers (`extern "abi"
fn()`). When interfacing with C, pointers that might be null are often used.
As a special case, a generic `enum` that contains exactly two variants, one of
which contains no data and the other containing a single field, is eligible
for the "nullable pointer optimization". When such an enum is instantiated
with one of the non-nullable types, it is represented as a single pointer,
and the non-data variant is represented as the null pointer. So
`Option<extern "C" fn(c_int) -> c_int>` is how one represents a nullable
function pointer using the C ABI.