Primitive Type fn

1.0.0 · [−]

Expand description

Function pointers, like fn(usize) -> bool.

See also the traits Fn, FnMut, and FnOnce.

Function pointers are pointers that point to code, not data. They can be called just like functions. Like references, function pointers are, among other things, assumed to not be null, so if you want to pass a function pointer over FFI and be able to accommodate null pointers, make your type Option<fn()> with your required signature.

Safety

Plain function pointers are obtained by casting either plain functions, or closures that don’t capture an environment:

fn add_one(x: usize) -> usize {
    x + 1
}

let ptr: fn(usize) -> usize = add_one;
assert_eq!(ptr(5), 6);

let clos: fn(usize) -> usize = |x| x + 5;
assert_eq!(clos(5), 10);

Run

In addition to varying based on their signature, function pointers come in two flavors: safe and unsafe. Plain fn() function pointers can only point to safe functions, while unsafe fn() function pointers can point to safe or unsafe functions.

fn add_one(x: usize) -> usize {
    x + 1
}

unsafe fn add_one_unsafely(x: usize) -> usize {
    x + 1
}

let safe_ptr: fn(usize) -> usize = add_one;

//ERROR: mismatched types: expected normal fn, found unsafe fn
//let bad_ptr: fn(usize) -> usize = add_one_unsafely;

let unsafe_ptr: unsafe fn(usize) -> usize = add_one_unsafely;
let really_safe_ptr: unsafe fn(usize) -> usize = add_one;

Run

ABI

On top of that, function pointers can vary based on what ABI they use. This is achieved by adding the extern keyword before the type, followed by the ABI in question. The default ABI is “Rust”, i.e., fn() is the exact same type as extern "Rust" fn(). A pointer to a function with C ABI would have type extern "C" fn().

extern "ABI" { ... } blocks declare functions with ABI “ABI”. The default here is “C”, i.e., functions declared in an extern {...} block have “C” ABI.

For more information and a list of supported ABIs, see the nomicon’s section on foreign calling conventions.

Variadic functions

Extern function declarations with the “C” or “cdecl” ABIs can also be variadic, allowing them to be called with a variable number of arguments. Normal Rust functions, even those with an extern "ABI", cannot be variadic. For more information, see the nomicon’s section on variadic functions.

Creating function pointers

When bar is the name of a function, then the expression bar is not a function pointer. Rather, it denotes a value of an unnameable type that uniquely identifies the function bar. The value is zero-sized because the type already identifies the function. This has the advantage that “calling” the value (it implements the Fn* traits) does not require dynamic dispatch.

This zero-sized type coerces to a regular function pointer. For example:

use std::mem;

fn bar(x: i32) {}

let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar`
assert_eq!(mem::size_of_val(&not_bar_ptr), 0);

let bar_ptr: fn(i32) = not_bar_ptr; // force coercion to function pointer
assert_eq!(mem::size_of_val(&bar_ptr), mem::size_of::<usize>());

let footgun = &bar; // this is a shared reference to the zero-sized type identifying `bar`

Run

The last line shows that &bar is not a function pointer either. Rather, it is a reference to the function-specific ZST. &bar is basically never what you want when bar is a function.

Casting to and from integers

You cast function pointers directly to integers:

let fnptr: fn(i32) -> i32 = |x| x+2;
let fnptr_addr = fnptr as usize;

Run

However, a direct cast back is not possible. You need to use transmute:

let fnptr = fnptr_addr as *const ();
let fnptr: fn(i32) -> i32 = unsafe { std::mem::transmute(fnptr) };
assert_eq!(fnptr(40), 42);

Run

Crucially, we as-cast to a raw pointer before transmuteing to a function pointer. This avoids an integer-to-pointer transmute, which can be problematic. Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.

Note that all of this is not portable to platforms where function pointers and data pointers have different sizes.

Trait implementations

In this documentation the shorthand fn (T₁, T₂, …, Tₙ) is used to represent non-variadic function pointers of varying length. Note that this is a convenience notation to avoid repetitive documentation, not valid Rust syntax.

Due to a temporary restriction in Rust’s type system, these traits are only implemented on functions that take 12 arguments or less, with the "Rust" and "C" ABIs. In the future, this may change:

The following traits are implemented for function pointers with any number of arguments and any ABI. These traits have implementations that are automatically generated by the compiler, so are not limited by missing language features:

In addition, all safe function pointers implement Fn, FnMut, and FnOnce, because these traits are specially known to the compiler.

Primitive Type fn

Trait Implementations

impl<Ret, T> Clone for fn (T₁, T₂, …, Tₙ) -> Ret

fn clone(&self) -> Self

fn clone_from(&mut self, source: &Self)

impl<Ret, T> Debug for extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<Ret, T> Debug for extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<Ret, T> Debug for fn (T₁, T₂, …, Tₙ) -> Ret

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<Ret, T> Debug for unsafe extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<Ret, T> Debug for unsafe extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<Ret, T> Debug for unsafe fn (T₁, T₂, …, Tₙ) -> Ret

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<Ret, T> Hash for extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn hash<HH>(&self, state: &mut HH) where HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,

impl<Ret, T> Hash for extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn hash<HH>(&self, state: &mut HH) where HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,

impl<Ret, T> Hash for fn (T₁, T₂, …, Tₙ) -> Ret

fn hash<HH>(&self, state: &mut HH) where HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,

impl<Ret, T> Hash for unsafe extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn hash<HH>(&self, state: &mut HH) where HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,

impl<Ret, T> Hash for unsafe extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn hash<HH>(&self, state: &mut HH) where HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,

impl<Ret, T> Hash for unsafe fn (T₁, T₂, …, Tₙ) -> Ret

fn hash<HH>(&self, state: &mut HH) where HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,

impl<Ret, T> Ord for extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn cmp(&self, other: &extern "C" fn(T, ...) -> Ret) -> Ordering

fn max(self, other: Self) -> Self

fn min(self, other: Self) -> Self

fn clamp(self, min: Self, max: Self) -> Self

impl<Ret, T> Ord for extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn cmp(&self, other: &extern "C" fn(T) -> Ret) -> Ordering

fn max(self, other: Self) -> Self

fn min(self, other: Self) -> Self

fn clamp(self, min: Self, max: Self) -> Self

impl<Ret, T> Ord for fn (T₁, T₂, …, Tₙ) -> Ret

fn cmp(&self, other: &fn(T) -> Ret) -> Ordering

fn max(self, other: Self) -> Self

fn min(self, other: Self) -> Self

fn clamp(self, min: Self, max: Self) -> Self

impl<Ret, T> Ord for unsafe extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn cmp(&self, other: &unsafe extern "C" fn(T, ...) -> Ret) -> Ordering

fn max(self, other: Self) -> Self

fn min(self, other: Self) -> Self

fn clamp(self, min: Self, max: Self) -> Self

impl<Ret, T> Ord for unsafe extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn cmp(&self, other: &unsafe extern "C" fn(T) -> Ret) -> Ordering

fn max(self, other: Self) -> Self

fn min(self, other: Self) -> Self

fn clamp(self, min: Self, max: Self) -> Self

impl<Ret, T> Ord for unsafe fn (T₁, T₂, …, Tₙ) -> Ret

fn cmp(&self, other: &unsafe fn(T) -> Ret) -> Ordering

fn max(self, other: Self) -> Self

fn min(self, other: Self) -> Self

fn clamp(self, min: Self, max: Self) -> Self

impl<Ret, T> PartialEq<extern "C" fn(T, ...) -> Ret> for extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn eq(&self, other: &extern "C" fn(T, ...) -> Ret) -> bool

fn ne(&self, other: &Rhs) -> bool

impl<Ret, T> PartialEq<extern "C" fn(T) -> Ret> for extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn eq(&self, other: &extern "C" fn(T) -> Ret) -> bool

fn ne(&self, other: &Rhs) -> bool

impl<Ret, T> PartialEq<fn(T) -> Ret> for fn (T₁, T₂, …, Tₙ) -> Ret

fn eq(&self, other: &fn(T) -> Ret) -> bool

fn ne(&self, other: &Rhs) -> bool

impl<Ret, T> PartialEq<unsafe extern "C" fn(T, ...) -> Ret> for unsafe extern "C" fn (T₁, T₂, …, Tₙ, ...) -> Ret

fn eq(&self, other: &unsafe extern "C" fn(T, ...) -> Ret) -> bool

fn ne(&self, other: &Rhs) -> bool

impl<Ret, T> PartialEq<unsafe extern "C" fn(T) -> Ret> for unsafe extern "C" fn (T₁, T₂, …, Tₙ) -> Ret

fn eq(&self, other: &unsafe extern "C" fn(T) -> Ret) -> bool

fn ne(&self, other: &Rhs) -> bool

fn hash<HH>(&self, state: &mut HH) where
HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,

fn hash<HH>(&self, state: &mut HH) where
HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,

fn hash<HH>(&self, state: &mut HH) where
HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,

fn hash<HH>(&self, state: &mut HH) where
HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,

fn hash<HH>(&self, state: &mut HH) where
HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,

fn hash<HH>(&self, state: &mut HH) where
HH: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,

fn partial_cmp(
&self,
other: &unsafe extern "C" fn(T, ...) -> Ret
) -> Option<Ordering>