Functions

Afunction consists of ablock (that’s thebody of the function),along with a name, a set of parameters, and an output type.Other than a name, all these are optional.

Functions are declared with the keywordfn which defines the given name in thevalue namespace of the module or block where it is located.

Functions may declare a set ofinputvariables as parameters, through which the caller passes arguments into the function, and theoutputtype of the value the function will return to its caller on completion.

If the output type is not explicitly stated, it is theunit type.

When referred to, afunction yields a first-classvalue of the corresponding zero-sizedfunction item type, which when called evaluates to a direct call to the function.

For example, this is a simple function:

#![allow(unused)]fn main() {fn answer_to_life_the_universe_and_everything() -> i32 {    return 42;}}

Thesafe function is semantically only allowed when used in anextern block.

Function parameters

Function parameters are irrefutablepatterns, so any pattern that is valid inan else-lesslet binding is also valid as a parameter:

#![allow(unused)]fn main() {fn first((value, _): (i32, i32)) -> i32 { value }}

If the first parameter is aSelfParam, this indicates that the function is amethod.

Functions with a self parameter may only appear as anassociatedfunction in atrait orimplementation.

A parameter with the... token indicates avariadic function, and may onlybe used as the last parameter of anexternal block function. The variadicparameter may have an optional identifier, such asargs: ....

Function body

The body block of a function is conceptually wrapped in another block that first binds theargument patterns and thenreturns the value of the function’s body. Thismeans that the tail expression of the block, if evaluated, ends up beingreturned to the caller. As usual, an explicit return expression withinthe body of the function will short-cut that implicit return, if reached.

For example, the function above behaves as if it was written as:

// argument_0 is the actual first argument passed from the callerlet (value, _) = argument_0;return {    value};

Functions without a body block are terminated with a semicolon. This formmay only appear in atrait orexternal block.

Generic functions

Ageneric function allows one or moreparameterized types to appear in itssignature. Each type parameter must be explicitly declared in anangle-bracket-enclosed and comma-separated list, following the function name.

#![allow(unused)]fn main() {// foo is generic over A and Bfn foo<A, B>(x: A, y: B) {}}

Inside the function signature and body, the name of the type parameter can beused as a type name.

Trait bounds can be specified for typeparameters to allow methods with that trait to be called on values of thattype. This is specified using thewhere syntax:

#![allow(unused)]fn main() {use std::fmt::Debug;fn foo<T>(x: T) where T: Debug {}}

When a generic function is referenced, its type is instantiated based on thecontext of the reference. For example, calling thefoo function here:

#![allow(unused)]fn main() {use std::fmt::Debug;fn foo<T>(x: &[T]) where T: Debug {    // details elided}foo(&[1, 2]);}

will instantiate type parameterT withi32.

The type parameters can also be explicitly supplied in a trailingpathcomponent after the function name. This might be necessary if there is notsufficient context to determine the type parameters. For example,mem::size_of::<u32>() == 4.

Extern function qualifier

Theextern function qualifier allows providing functiondefinitions that canbe called with a particular ABI:

extern "ABI" fn foo() { /* ... */ }

These are often used in combination withexternal block items which providefunctiondeclarations that can be used to call functions without providingtheirdefinition:

unsafe extern "ABI" {  unsafe fn foo(); /* no body */  safe fn bar(); /* no body */}unsafe { foo() };bar();

When"extern" Abi?* is omitted fromFunctionQualifiers in function items,the ABI"Rust" is assigned. For example:

#![allow(unused)]fn main() {fn foo() {}}

is equivalent to:

#![allow(unused)]fn main() {extern "Rust" fn foo() {}}

Functions can be called by foreign code, and using an ABI thatdiffers from Rust allows, for example, to provide functions that can becalled from other programming languages like C:

#![allow(unused)]fn main() {// Declares a function with the "C" ABIextern "C" fn new_i32() -> i32 { 0 }// Declares a function with the "stdcall" ABI#[cfg(any(windows, target_arch = "x86"))]extern "stdcall" fn new_i32_stdcall() -> i32 { 0 }}

Just as withexternal block, when theextern keyword is used and the"ABI"is omitted, the ABI used defaults to"C". That is, this:

#![allow(unused)]fn main() {extern fn new_i32() -> i32 { 0 }let fptr: extern fn() -> i32 = new_i32;}

is equivalent to:

#![allow(unused)]fn main() {extern "C" fn new_i32() -> i32 { 0 }let fptr: extern "C" fn() -> i32 = new_i32;}

Unwinding

Most ABI strings come in two variants, one with an-unwind suffix and one without. TheRust ABI always permits unwinding, so there is noRust-unwind ABI. The choice of ABI, together with the runtimepanic handler, determines the behavior when unwinding out of a function.

The table below indicates the behavior of an unwinding operation reaching each type of ABI boundary (function declaration or definition using the corresponding ABI string). Note that the Rust runtime is not affected by, and cannot have an effect on, any unwinding that occurs entirely within another language’s runtime, that is, unwinds that are thrown and caught without reaching a Rust ABI boundary.

Thepanic-unwind column refers topanicking via thepanic! macro and similar standard library mechanisms, as well as to any other Rust operations that cause a panic, such as out-of-bounds array indexing or integer overflow.

The “unwinding” ABI category refers to"Rust" (the implicit ABI of Rust functions not markedextern),"C-unwind", and any other ABI with-unwind in its name. The “non-unwinding” ABI category refers to all other ABI strings, including"C" and"stdcall".

Native unwinding is defined per-target. On targets that support throwing and catching C++ exceptions, it refers to the mechanism used to implement this feature. Some platforms implement a form of unwinding referred to as“forced unwinding”;longjmp on Windows andpthread_exit inglibc are implemented this way. Forced unwinding is explicitly excluded from the “Native unwind” column in the table.

Withpanic=unwind, when apanic is turned into an abort by a non-unwinding ABI boundary, either no destructors (Drop calls) will run, or all destructors up until the ABI boundary will run. It is unspecified which of those two behaviors will happen.

For other considerations and limitations regarding unwinding across FFI boundaries, see therelevant section in the Panic documentation.

Const functions

Functions qualified with theconst keyword areconst functions, as aretuple struct andtuple variant constructors.Const functions can be called from withinconst contexts.

Const functions may use theextern function qualifier.

Const functions are not allowed to beasync.

Async functions

Functions may be qualified as async, and this can also be combined with theunsafe qualifier:

#![allow(unused)]fn main() {async fn regular_example() { }async unsafe fn unsafe_example() { }}

Async functions do no work when called: instead, theycapture their arguments into a future. When polled, that future willexecute the function’s body.

An async function is roughly equivalent to a functionthat returnsimpl Future and with anasync move block asits body:

#![allow(unused)]fn main() {// Sourceasync fn example(x: &str) -> usize {    x.len()}}

is roughly equivalent to:

#![allow(unused)]fn main() {use std::future::Future;// Desugaredfn example<'a>(x: &'a str) -> impl Future<Output = usize> + 'a {    async move { x.len() }}}

The actual desugaring is more complex:

• The return type in the desugaring is assumed to capture all lifetimeparameters from theasync fn declaration. This can be seen in thedesugared example above, which explicitly outlives, and hencecaptures,'a.

• Theasync move block in the body captures all functionparameters, including those that are unused or bound to a_pattern. This ensures that function parameters are dropped in thesame order as they would be if the function were not async, exceptthat the drop occurs when the returned future has been fullyawaited.

For more information on the effect of async, seeasync blocks.

Combiningasync andunsafe

It is legal to declare a function that is both async and unsafe. Theresulting function is unsafe to call and (like any async function)returns a future. This future is just an ordinary future and thus anunsafe context is not required to “await” it:

#![allow(unused)]fn main() {// Returns a future that, when awaited, dereferences `x`.//// Soundness condition: `x` must be safe to dereference until// the resulting future is complete.async unsafe fn unsafe_example(x: *const i32) -> i32 {  *x}async fn safe_example() {    // An `unsafe` block is required to invoke the function initially:    let p = 22;    let future = unsafe { unsafe_example(&p) };    // But no `unsafe` block required here. This will    // read the value of `p`:    let q = future.await;}}

Note that this behavior is a consequence of the desugaring to afunction that returns animpl Future – in this case, the functionwe desugar to is anunsafe function, but the return value remainsthe same.

Unsafe is used on an async function in precisely the same way that itis used on other functions: it indicates that the function imposessome additional obligations on its caller to ensure soundness. As in anyother unsafe function, these conditions may extend beyond the initialcall itself – in the snippet above, for example, theunsafe_examplefunction took a pointerx as argument, and then (when awaited)dereferenced that pointer. This implies thatx would have to bevalid until the future is finished executing, and it is the caller’sresponsibility to ensure that.

Attributes on functions

Outer attributes are allowed on functions.Innerattributes are allowed directly after the{ inside its bodyblock.

This example shows an inner attribute on a function. The function is documentedwith just the word “Example”.

#![allow(unused)]fn main() {fn documented() {    #![doc = "Example"]}}

The attributes that have meaning on a function are:

• cfg_attr
• cfg
• cold
• deprecated
• doc
• export_name
• inline
• link_section
• must_use
• no_mangle
• Lint check attributes
• Procedural macro attributes
• Testing attributes

Attributes on function parameters

Outer attributes are allowed on function parameters and thepermittedbuilt-in attributes are restricted tocfg,cfg_attr,allow,warn,deny, andforbid.

#![allow(unused)]fn main() {fn len(    #[cfg(windows)] slice: &[u16],    #[cfg(not(windows))] slice: &[u8],) -> usize {    slice.len()}}

Inert helper attributes used by procedural macro attributes applied to items are alsoallowed but be careful to not include these inert attributes in your finalTokenStream.

For example, the following code defines an inertsome_inert_attribute attribute thatis not formally defined anywhere and thesome_proc_macro_attribute procedural macro isresponsible for detecting its presence and removing it from the output token stream.

#[some_proc_macro_attribute]fn foo_oof(#[some_inert_attribute] arg: u8) {}

1. Theasync qualifier is not allowed in the 2015 edition.↩

2. Relevant to editions earlier than Rust 2024: Withinextern blocks, thesafe orunsafe function qualifier is only allowedwhen theextern is qualified asunsafe.↩

3. Thesafe function qualifier is only allowed semantically withinextern blocks.↩

4. Function parameters with only a type are only allowedin an associated function of atrait item in the 2015 edition.↩