Mutability

Mutability is an effect that allows modifying a value, which is enforced by Rusts type system and guarantees the absence of data races. The name "mutability" is problematic, because types with interior mutability can be changed even when the value is immutable.

Mutability of owned values
By default, owned values are immutable, which means that they can't be modified:

Only mutable variables, declared with the  keyword, can be reassigned. To make an immutable variable mutable, it must be moved to a new variable:

It is possible to shadow a variable name to achieve something similar to mutability:

Note that this declares two distinct variables which just happen to have the same name. With shadowing, it is not possible to change the value of an immutable variable.

Function parameters and other bindings
bindings are patterns, as are function parameters. The  keyword is allowed in all patterns where a new binding is introduced, for example:

Note that a variable doesn't need to be mutable in order to pass it to a function or  block where it is bound mutably, because the variable is moved in that case.

Mutability of borrowed values
When borrowing a value, it can be borrowed either mutably or immutably. This is done by creating a mutable or immutable reference:

While you can create as many immutable reference to a value as you want, mutable references must be exclusive: At any point, there can be at most one mutable reference to a value. Furthermore, while a mutable reference exists, no immutable reference may exist. This ensures that a variable can't be accessed while it is being modified by someone else. Example:

This doesn't work because the value of  is mutably borrowed twice in line 8, by both   and. The compiler complains with the following error:

Shared and exclusive references
The term "mutability" is problematic, because a value behind an immutable reference can be mutated, if its type has interior mutability (see below). Therefore some people recommend to call immutable references "shared references" instead; mutable references should be called "exclusive references". This is less ambiguous and more in line with Rusts memory model: When a reference is exclusive, it has exclusive access to the data it refers to, even in the presence of interior mutability.

Mutating functions
It's possible to mutate a value in a function through a mutable reference, for example:

Note that  is equivalent to. If  isn't mutable, it can't be mutably borrowed, so its   method can't be called.

Interior mutability
See also: Reference – Interior mutability

It is possible to create types that can be mutated even if they're behind an immutable reference. This is done with the type. As the name already suggests, its usage is unsafe. However, it is possible to create safe abstractions on top of it. For example, the standard library contains the, , and  types, as well as  types. These use  internally, but perform runtime checks to ensure the absence of data races. This is only necessary if Rust is unable to guarantee the absence of data races at compile time.

The  type is the simplest type that allows interior mutability; it allows moving an new value into the. However, it doesn't allow taking a reference to the inner value, and isn't thread safe.

The  type is a more powerful version of , since it allows obtaining a mutable reference to the inner value, or multiple immutable references. Like, it isn't thread safe.

uses the guard pattern to check when the inner value is borrowed: The  method checks if the   is already borrowed mutably and panics if that is the case. Then it increments a counter and returns a  guard that acts as a mutable reference. When this guard goes out of scope, the counter is decremented again.

A thread-safe version of. Note that the inner value can't be borrowed immutably multiple times. To do that, use. Bear in mind that locking a  or   can deadlock.

Like, it uses the guard pattern. Note that  returns a, in case the mutex was poisoned. It's usually okay to just unwrap the result.

A read-write-lock. It is the most powerful, thread-safe type for interior mutability in the standard library. It can be mutably borrowed once or immutably borrowed multiple times. This is similar to, except that it has the   and   methods instead of.

types
The standard library contains several wrappers around primitive types, such as, , , etc. These allow accessing and mutating values shared across multiple threads. The underlying value can only be modified via their methods, which are atomic. There are five different strategies how these types can synchronize memory; these are enumerated in the struct.

Mutable static variables
Main article: Static variables

Static variables can be mutable. Since Rust can't prove the absence of data races of global mutable variables, accessing a static mutable variable is unsafe.