@@ -1058,6 +1058,8 @@ mod prim_ref {}
10581058/// not be null, so if you want to pass a function pointer over FFI and be able to accommodate null
10591059/// pointers, make your type `Option<fn()>` with your required signature.
10601060///
1061+ /// ### Safety
1062+ ///
10611063/// Plain function pointers are obtained by casting either plain functions, or closures that don't
10621064/// capture an environment:
10631065///
@@ -1095,23 +1097,60 @@ mod prim_ref {}
10951097/// let really_safe_ptr: unsafe fn(usize) -> usize = add_one;
10961098/// ```
10971099///
1098- /// On top of that, function pointers can vary based on what ABI they use. This is achieved by
1099- /// adding the `extern` keyword to the type name, followed by the ABI in question. For example,
1100- /// `fn()` is different from `extern "C" fn()`, which itself is different from `extern "stdcall"
1101- /// fn()`, and so on for the various ABIs that Rust supports. Non-`extern` functions have an ABI
1102- /// of `"Rust"`, and `extern` functions without an explicit ABI have an ABI of `"C"`. For more
1103- /// information, see [the nomicon's section on foreign calling conventions][nomicon-abi].
1100+ /// ### ABI
1101+ ///
1102+ /// On top of that, function pointers can vary based on what ABI they use. This
1103+ /// is achieved by adding the `extern` keyword before the type, followed by the
1104+ /// ABI in question. The default ABI is "Rust", i.e., `fn()` is the exact same
1105+ /// type as `extern "Rust" fn()`. A pointer to a function with C ABI would have
1106+ /// type `extern "C" fn()`.
1107+ ///
1108+ /// `extern "ABI" { ... }` blocks declare functions with ABI "ABI". The default
1109+ /// here is "C", i.e., functions declared in an `extern {...}` block have "C"
1110+ /// ABI.
1111+ ///
1112+ /// For more information and a list of supported ABIs, see [the nomicon's
1113+ /// section on foreign calling conventions][nomicon-abi].
11041114///
1105- /// [nomicon-abi]: ../nomicon/ffi.html#foreign-calling-conventions
1115+ /// ### Variadic functions
11061116///
11071117/// Extern function declarations with the "C" or "cdecl" ABIs can also be *variadic*, allowing them
1108- /// to be called with a variable number of arguments. Normal rust functions, even those with an
1118+ /// to be called with a variable number of arguments. Normal Rust functions, even those with an
11091119/// `extern "ABI"`, cannot be variadic. For more information, see [the nomicon's section on
11101120/// variadic functions][nomicon-variadic].
11111121///
11121122/// [nomicon-variadic]: ../nomicon/ffi.html#variadic-functions
11131123///
1114- /// These markers can be combined, so `unsafe extern "stdcall" fn()` is a valid type.
1124+ /// ### Creating function pointers
1125+ ///
1126+ /// When `bar` is the name of a function, then the expression `bar` is *not* a
1127+ /// function pointer. Rather, it denotes a value of an unnameable type that
1128+ /// uniquely identifies the function `bar`. The value is zero-sized because the
1129+ /// type already identifies the function. This has the advantage that "calling"
1130+ /// the value (it implements the `Fn*` traits) does not require dynamic
1131+ /// dispatch.
1132+ ///
1133+ /// This zero-sized type *coerces* to a regular function pointer. For example:
1134+ ///
1135+ /// ```rust
1136+ /// use std::mem;
1137+ ///
1138+ /// fn bar(x: i32) {}
1139+ ///
1140+ /// let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar`
1141+ /// assert_eq!(mem::size_of_val(¬_bar_ptr), 0);
1142+ ///
1143+ /// let bar_ptr: fn(i32) = not_bar_ptr; // force coercion to function pointer
1144+ /// assert_eq!(mem::size_of_val(&bar_ptr), mem::size_of::<usize>());
1145+ ///
1146+ /// let footgun = &bar; // this is a shared reference to the zero-sized type identifying `bar`
1147+ /// ```
1148+ ///
1149+ /// The last line shows that `&bar` is not a function pointer either. Rather, it
1150+ /// is a reference to the function-specific ZST. `&bar` is basically never what you
1151+ /// want when `bar` is a function.
1152+ ///
1153+ /// ### Traits
11151154///
11161155/// Function pointers implement the following traits:
11171156///
0 commit comments