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 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).

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
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.

This is a thread-safe version of. Note that it can't be borrowed immutably multiple times. To do that, use.

Bear in mind that locking a  or   can deadlock.

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.

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.