Book section on FFI with nullable pointers doesn't explain None == null.

[eddyb]

The paragraph in question (https://doc.rust-lang.org/book/ffi.html#the-nullable-pointer-optimization):

The "nullable pointer optimization"

Certain types are defined to not be null. This includes references (&T,
&mut T), boxes (Box<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.

While the paragraph does a good job at explaining when this optimizations happens (although it's missing the fact that the optimization can now look for deeply nested fields to use), it doesn't explicitly mention that None represents the "NULL" value and that Some(function) is how you create non-"NULL" values, nor does it have a code example.

What this can lead to is code that transmutes because it might not be entirely clear that there's a safe way to create values of that type.

cc @steveklabnik

[steveklabnik]

I'm not really working on the old book anymore, but would love to take a patch for this if someone would like to write one.

[sanmai-NL]

@steveklabnik: could you point me to the new book?

[steveklabnik]

http://rust-lang.github.io/book

On Jun 13, 2016, 10:50 +0200, Sander Maijersnotifications@github.com, wrote:

@steveklabnik(https://github.com/steveklabnik): could you point me to the new book?

—
You are receiving this because you were mentioned.
Reply to this email directly,view it on GitHub(#34250 (comment)), ormute the thread(https://github.com/notifications/unsubscribe/AABsitYnLLzgpXoVLLAX5tX9Kd_-ZOTVks5qLRm7gaJpZM4Iz7G5).

[durka]

@eddyb it does say

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.

Do you just think it should more explicitly spell out that Option::None is an example of a "non-data variant", and include an example?

[eddyb]

@durka Yes, I think the description might not be clear without the definition of Option in sight.
Also, the description seems to talk about the type-parametrized Option, although that's not a requirement for triggering the optimization.

[durka]

@eddyb agreed, I'll mention that too. And IMO it's unfortunate to call this
an "optimization", since it is guaranteed, but I don't have a better term.

On Mon, Jun 13, 2016 at 12:54 PM, Eduard-Mihai Burtescu <
notifications@github.com> wrote:

@durka https://github.com/durka Yes, I think the description might not
be clear without the definition of Option in sight.
Also, the description seems to talk about the type-parametrized Option,
although that's not a requirement for triggering the optimization.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#34250 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAC3n4OPRVWg63ABOjqiGF5UScgXsoA1ks5qLYs9gaJpZM4Iz7G5
.

[durka]

see #34258

On Mon, Jun 13, 2016 at 1:03 PM, Alex Burka durka42@gmail.com wrote:

@eddyb agreed, I'll mention that too. And IMO it's unfortunate to call
this an "optimization", since it is guaranteed, but I don't have a better
term.

On Mon, Jun 13, 2016 at 12:54 PM, Eduard-Mihai Burtescu <
notifications@github.com> wrote:

@durka https://github.com/durka Yes, I think the description might not
be clear without the definition of Option in sight.
Also, the description seems to talk about the type-parametrized Option,
although that's not a requirement for triggering the optimization.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#34250 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAC3n4OPRVWg63ABOjqiGF5UScgXsoA1ks5qLYs9gaJpZM4Iz7G5
.