When are Rust's `const fn`s executed?

2025-03-11T00:00:00+00:00
I've been playing with const fn</code>s in Rust recently and kept wondering when they are executed. In this post, I'm going to take a closer look at them. </p>
First, some background on regular functions and const fn</code>s:</p>
Regular functions</h2>
Regular (non-const) functions in Rust are compiled into machine code and are executed at runtime. They can take any kind of arguments, both constants and non-constants. The result of a regular function can only be used in non-const contexts though. Using a regular function in a constant context (for example in a constant or as the length of an array) leads to a compiler error.</p>
The following example shows a simple regular function square</code>. It can be used with const and non-const arguments, but its result cannot be used in a constant.</p>
fn </span>square</span>(x</span>: </span>usize</span>) </span>-> </span>usize </span>{
</span>    x </span>*</span> x
</span>}
</span>
</span>pub fn </span>main</span>() {
</span>    </span>// called with constants
</span>    </span>const </span>CONST_ARG</span>: </span>usize = </span>2</span>;
</span>    </span>let</span> res_a </span>= </span>square</span>(CONST_ARG)</span>;
</span>
</span>    </span>// called with non-consts
</span>    </span>let</span> runtime_arg</span>: </span>usize = </span>std</span>::</span>env</span>::</span>args()</span>.</span>len</span>()</span>;
</span>    </span>let</span> res_b </span>= </span>square</span>(runtime_arg)</span>;
</span>    
</span>    </span>// const RES_CONST: usize = square(5);
</span>    </span>// error: cannot call non-const fn `square` in constants
</span>}
</span></code></pre>
const fn</h2>
const fn</code>s in Rust are declared like regular functions, the only difference is that the const</code> keyword is added to the beginning of the declaration. const fn</code>s can be used in constant contexts and can also be compiled and executed like regular functions.</p>
The following example contains the same square</code> function, but now it's a const fn</code>. Compared to the regular function we've had before, square</code> can now be used in a constant!</p>
const fn </span>square</span>(x</span>: </span>usize</span>) </span>-> </span>usize </span>{
</span>    x </span>*</span> x
</span>}
</span>
</span>pub fn </span>main</span>() {
</span>    </span>// called with constants
</span>    </span>const </span>CONST_ARG</span>: </span>usize = </span>2</span>;
</span>    </span>let</span> res_a </span>= </span>square</span>(CONST_ARG)</span>;
</span>
</span>    </span>// called with non-const arg
</span>    </span>let</span> runtime_arg</span>: </span>usize = </span>std</span>::</span>env</span>::</span>args()</span>.</span>len</span>()</span>;
</span>    </span>let</span> res_b </span>= </span>square</span>(runtime_arg)</span>;
</span>    
</span>    </span>// evaluated at compile time
</span>    </span>const </span>RES_CONST</span>: </span>usize = </span>square</span>(</span>5</span>)</span>;
</span>}
</span></code></pre>
You can think of const fn</code>s as being generic over whether they're evaluated at compile time or executed at runtime. By adding the const</code> keyword to a function, we declare that in addition to being compiled and executed at runtime, the code we've written can also be evaluated at compile time. </p>
This additional use-case comes with some restrictions though. Not everything we're allowed to do in a regular function can also be done in a const fn</code>. For example, you cannot allocate memory in a const fn</code>. The subset of Rust that's usable in const fn</code>s is documented in the Rust Reference</a> and continuously expanded by the Rust developers.</p>
By the way: changing a regular function into a const fn</code> is a backwards-compatible change! Existing (non-const) uses of the function will continue to work, but additionally, the function can now be used in constant contexts as well. Many functions in Rust's standard library are already const fn</code>s and new releases of Rust often contain functions that were changed into const fn</code>s.</em></p>
Now that we know what const fn</code>s are and how they're different from regular functions, we can look into the real question:</p>
Compile time or runtime?</h2>
Whether a const fn</code> is evaluated at compile time or executed at runtime depends on the arguments passed to the function as well as the context in which it is called. In fact, the same function can be used in multiple places, some of which are evaluated at compile time and others being executed at runtime.</p>
For each usage of a const fn</code>, we can ask the following two questions to determine when it is run:</p>

Are all arguments available at compile time (only const</code> arguments)?</li>
Is the result of the function needed at compile time (function called within a constant context)?</li>
</ul>
These two simple yes/no questions generate four different cases which we will look at individually:</p>
non-const arguments && non-const context</h3>
The simplest and most common case is a function that takes non-const arguments and that is used in a non-const context. In this case, the function needs to be executed at runtime because the arguments can't be known at compile time. </p>
The following example uses the same square</code> constant function as above and passes the number of command line arguments to it. The number of arguments the program is called with cannot be known at compile time, so the function can only be executed at runtime. That's fine because the result (res_b</code>) is also a runtime variable and its value isn't needed during compilation.</p>
pub fn </span>main</span>() {
</span>    </span>// called with non-const args
</span>    </span>let</span> runtime_arg</span>: </span>usize = </span>std</span>::</span>env</span>::</span>args()</span>.</span>len</span>()</span>;
</span>    </span>let</span> res_b </span>= </span>square</span>(runtime_arg)</span>;
</span>}
</span></code></pre>
const arguments && const context</h3>
If the function is used in a constant context and used with constant arguments, it is guaranteed to be evaluated at compile time. Evaluating it at compile time is possible because all arguments are also constants and therefore available during compilation.</p>
In the example below, square</code> is called with a constant argument CONST_ARG</code> and the result of the evaluation becomes the constant RES_CONST</code>.</p>
pub fn </span>main</span>() {
</span>    </span>const </span>CONST_ARG</span>: </span>usize = </span>2</span>;
</span>    </span>const </span>RES_CONST</span>: </span>usize = </span>square</span>(CONST_ARG)</span>;
</span>}
</span></code></pre>
non-const arguments && const context</h3>
Using a const fn</code> in a constant context and providing non-const arguments leads to a compile error. The constant context means that the function would need to be evaluated at compile time, but the arguments aren't available until runtime:</p>
pub fn </span>main</span>() {
</span>    </span>// called with non-const args
</span>    </span>let</span> runtime_arg</span>: </span>usize = </span>std</span>::</span>env</span>::</span>args()</span>.</span>len</span>()</span>;
</span>    </span>const </span>RES_CONST</span>: </span>usize = </span>square</span>(runtime_arg)</span>;
</span>    </span>// error: attempt to use a non-constant value in a constant
</span>}
</span></code></pre>
const arguments && non-const context</h3>
Lastly, what happens is the function is used in a non-const context, but with const arguments?</p>
pub fn </span>main</span>() {
</span>    </span>const </span>CONST_ARG</span>: </span>usize = </span>2</span>;
</span>    </span>let</span> res </span>= </span>square</span>(CONST_ARG)</span>;
</span>}
</span></code></pre>
All arguments are known at compile time, so the function could be evaluated during compilation. The result is only needed at runtime though, so it would also be possible to compile the function and execute it at runtime.</p>
Looking at the code, it's not obvious what the Rust compiler will do here. Let's do some experiments!</p>
Inspecting compiler output</h2>
To see what's going on, we're going to look at the assembly code generated by the compiler.</p>
Assembly code quickly becomes huge and difficult to read, so we're going to take a look at a minimal example that's adapted to generate simple assembly code:</p>
const fn </span>square</span>(x</span>: </span>i32</span>) </span>-> </span>i32 </span>{
</span>    x</span>.</span>wrapping_mul</span>(x)
</span>}
</span>
</span>pub fn </span>main</span>() {
</span>    std</span>::</span>process</span>::</span>exit(</span>square</span>(</span>10</span>))</span>;
</span>}
</span></code></pre>
The example program simply calls the square</code> function with a hard-coded constant value of 10 and exits with the value returned from the function call. I'm using wrapping_mul</code> and std::process::exit</code> here to make the resulting assembly code simpler. </p>
There are a couple of ways to view assembly code, but my favorite is the godbolt.org compiler explorer</a>. </p>
Entering our example program and selecting the latest stable Rust compiler (1.80) generates the following output (godbolt.org</a>):</p>
example::square:
</span>        </span>mov     </span>eax, edi
</span>        </span>imul    </span>eax, eax
</span>        </span>ret
</span>
</span>example::main:
</span>        </span>push    </span>rax
</span>        </span>mov     </span>edi, 10
</span>        </span>call    </span>example::square
</span>        </span>mov     </span>edi, eax
</span>        </span>mov     </span>rax, </span>qword ptr </span>[rip + </span>std</span>::process::exit@GOTPCREL</span>]
</span>        </span>call    </span>rax
</span></code></pre>
Looking at the assembly of the main</code> function, we can see that the square</code> function is called at runtime. Interesting!</p>
Let's try again, this time with optimizations enabled (-C opt-level=3</code>, godbolt.org</a>):</p>
example::main:
</span>        </span>push    </span>rax
</span>        </span>mov     </span>edi, 100
</span>        </span>call    </span>qword ptr </span>[rip + </span>std</span>::process::exit@GOTPCREL</span>]
</span></code></pre>
Now, the call to square</code> and the square</code> function itself aren't present anymore. Instead, the program simply returns a constant 100</code>, which happens to be the result of out square(10)</code> call. The function call has been evaluated at compile time.</p>
It seems like the compiler's evaluation of const fn</code>s depends on the optimization mode (debug / release). Just to make sure, let's try the same example with optimizations, but this time using a non-const square</code> function (godbolt.org</a>):</p>
example::main:
</span>        </span>push    </span>rax
</span>        </span>mov     </span>edi, 100
</span>        </span>call    </span>qword ptr </span>[rip + </span>std</span>::process::exit@GOTPCREL</span>]
</span></code></pre>
It's the same output as before! Our regular function square</code> has been evaluated at compile time. What's going on here?</p>
Constant propagation</h2>
We're seeing compiler optimizations in action here, most likely function inlining</a> and constant propagation</a>. The Rust compiler uses llvm to generate machine code and when compiling in release mode, llvm applies lots of clever optimizations to the code it is given. These are general optimization techniques and for them to work it doesn't matter whether we declared the function as const</code> or not. The downside of these optimizations is that in general, we can't rely on the optimization to work. The outcome depends on optimization flags (as we've seen before) and might also change when updating to another version of the compiler. For simple programs like the example we've used, these optimizations are very likely to work, but they probably won't be able to handle more complex cases.</p>
Let's try this with a function that's a bit more complex: </p>
const fn </span>fib</span>(n</span>: </span>i32</span>) </span>-> </span>i32 </span>{
</span>    </span>if</span> n </span>< </span>2 </span>{
</span>        </span>return</span> n</span>;
</span>    }
</span>    </span>fib</span>(n</span>-</span>1</span>) </span>+ </span>fib</span>(n</span>-</span>2</span>)
</span>}
</span>
</span>pub fn </span>main</span>() {
</span>    std</span>::</span>process</span>::</span>exit(</span>fib</span>(</span>10</span>))</span>;
</span>}
</span></code></pre>
Compiling this code with optimizations enabled, we get the following main</code> function (godbolt.org</a>):</p>
example::main:
</span>        </span>push    </span>rax
</span>        </span>mov     </span>edi, 10
</span>        </span>call    </span>example::fib
</span>        </span>mov     </span>edi, eax
</span>        </span>call    </span>qword ptr </span>[rip + </span>std</span>::process::exit@GOTPCREL</span>]
</span></code></pre>
This time, the compiler optimizations were't able to evaluate the function call at compile time.</p>
We can still force the compile time evaluation by calling the function in a constant context:</p>
pub fn </span>main</span>() {
</span>    </span>const </span>RES</span>: </span>i32 = </span>fib</span>(</span>10</span>)</span>;
</span>    std</span>::</span>process</span>::</span>exit(RES)</span>;
</span>}
</span></code></pre>
Compiling with optimizations (godbolt.org</a>):</p>
example::main:
</span>        </span>push    </span>rax
</span>        </span>mov     </span>edi, 55
</span>        </span>call    </span>qword ptr </span>[rip + </span>std</span>::process::exit@GOTPCREL</span>]
</span></code></pre>
This time, the function has been evaluated at compile time and the main function simply returns the result of the fib(10)</code> call, which is 55</code>.</p>
Rust's const eval policy</h2>
The Constant evaluation</a> chapter in the Rust reference</a> contains the following statement regarding compile time evaluation (emphasis mine):</p>

Certain forms of expressions, called constant expressions, can be evaluated at compile time. In const contexts, these are the only allowed expressions, and are always evaluated at compile time. In other places, such as let statements, constant expressions may be, but are not guaranteed to be, evaluated at compile time.</strong></p>
</blockquote>
This means that when calling a const fn</code> with const arguments and in a non-const context, Rust is free to decide whether to do compile time evaluation or not. From what I've seen and have been told, the Rust compiler currently</em> doesn't do compile time evaluation in these cases, but that might change in the future. </p>
Enforcing compile time evaluation</h2>
What if we want to make sure that a call to a const fn</code> is evaluated at compile time? </p>
One way to do it is to assign the result of the function call to a constant. This forces the function to be evaluated at compile time and I've used this trick in previous examples.</p>
Instead of directly using the function from a non-const context</p>
pub fn </span>main</span>() {
</span>    std</span>::</span>process</span>::</span>exit(</span>fib</span>(</span>10</span>))</span>;
</span>}
</span></code></pre>
you simply write assign the result of the function to a constant and use the constant's value in the non-const context:</p>
pub fn </span>main</span>() {
</span>    </span>const </span>RES</span>: </span>i32 = </span>fib</span>(</span>10</span>)</span>;
</span>    std</span>::</span>process</span>::</span>exit(RES)</span>;
</span>}
</span></code></pre>
This has been the only way to ensure compile time evaluation for a long time, but has two downsides. It introduces an extra declaration and since it's a constant, you're required to explicitly state the type.</p>
Fortunately, Rust 1.79 (release in June 2024) introduced inline const</code> expressions</a>. Using them, it's easy to force compile time evaluation:</p>
pub fn </span>main</span>() {
</span>    std</span>::</span>process</span>::</span>exit(</span>const </span>{ </span>fib</span>(</span>10</span>) })</span>;
</span>}
</span></code></pre>
Summary</h2>
Here's a short TL;DR of the post:</p>

const fn</code>s in Rust can be evaluated at compile time, but can also be compiled and executed at runtime just like regular functions.</li>
What happens depends on the arguments and the context in which a const fn</code> is used.</li>
For function calls that could either be compile time evaluated or not, the Rust compiler currently</em> seems to be conservative and doesn't seem to do compile time evaluation.</li>
General code optimization passes in the compiler backend (llvm) can do inlining and constant propagation though, which can have the same effect on the output. </li>
To make sure that a function call is evaluated at compile time, wrap it with a constant declaration or use inline const</code> expressions</a>.</li>
</ul>
Thanks to oli_obk for answering my questions and providing feedback on an earlier version of this post!</p>
Discussion on reddit</a>.</p>
felixwrt.dev

When are Rust's `const fn`s executed?

Hello World²

felixwrt.dev

When are Rust's `const fn`s executed?

non-const arguments && const context</h3> Using a const fn</code> in a constant context and providing non-const arguments leads to a compile error. The constant context means that the function would need to be evaluated at compile time, but the arguments aren't available until runtime:</p>

Summary</h2> Here's a short TL;DR of the post:</p>

Hello World²
