Ricardo Martins

Convenient and idiomatic conversions in Rust

2016-08-03T00:00:00-05:00

Key takeaways

The traits in std::convert provide a uniform API for converting values to other types
From<T> and Into are for conversions that cannot fail and consume the original value
From<T> for U converts a value of type T into one of type U
Into for T inverts From<T>’s subject-object relationship
Implementing From<T> for U gives us an automatically derived Into for T implementation
TryFrom<T> and TryInto are the equivalent traits for conversions that may fail
AsRef<T> and AsMut<T> represent cheap reference-to-reference conversions, with some similarities to Borrow<T> and BorrowMut<T>

Introduction

We all convert data from one representation to another with some regularity. There are several situations where this need pops up: converting a wide array of types into a more convenient type, converting “foreign” error types to our libraries’ error types, and encoding and decoding network packets of our custom protocols. The first situation is probably the most common. For instance, in some cases a plain Vec<T> is a convenient representation, so there are readily available ways to convert values of other types, such as VecDeque<T>, BinaryHeap<T>, &[T], and &str, into Vec<T>.

Naturally, there is more one way to convert types in Rust, each with advantages and disadvantages. We could:

build the target types ourselves with struct literals, but that’s tedious, repetitive and exposes implementation details;
create specialized constructors for each source type (e.g.: new_from_vec_deque, new_from_binary_heap, new_from_slice), but that’s just as tedious and we might miss some cases anyway;
write generic constructors that accept a certain trait, but that might still cover less cases than we need and require additional constructors;
cast enum variants to integers and vice-versa, but those conversions may have unexpected results;
…

You get the idea: there are myriad ways of converting types, but many of them suck. There has to be a better way!

In this article, we’ll explore how to do it in a more idiomatic way — and if you read the key takeaways you already know how 😉. The traits in the std::convert module — From<T>, Into, TryFrom<T>, TryInto, AsRef, and AsMut — have this exact purpose. Those traits provide a uniform API for type conversion, and we’ll be exploring how we can leverage them to achieve a consistent and ergonomic API. Once you know about them, you’ll start noticing them everywhere in the documentation. I hope that, by the end of this article you’ll probably appreciate them as much as I do.

`From` and `Into`

From<T> represents the conversion of a value of type T into a target type (impl From<T> for TargetType). This conversion may or may not be computationally expensive, but we can usually assume it isn’t cheap. Let’s have a look at its definition:

#[stable(feature = "rust1", since = "1.0.0")]
pub trait From<T>: Sized {
    /// Performs the conversion.
    #[stable(feature = "rust1", since = "1.0.0")]
    fn from(T) -> Self;
}

From<T> contains a single method signature, from(), which we’ll have to implement to perform the conversion. Inspecting from()’s signature, we can tell that it moves (or consumes) the argument. Its return value, Self, also clues us in to the fact that the conversion may not fail. Later in this article, we’ll look into TryFrom<T> for conversions that may fail. From<T> is also a reflexive trait, which means that conversion of a value into its own type (From<T> for T) is implemented and returns the argument without modification.

Reading on, we arrive at the symmetrical companion trait of From, Into<T>. Like From, Into has a short definition:

#[stable(feature = "rust1", since = "1.0.0")]
pub trait Into<T>: Sized {
    /// Performs the conversion.
    #[stable(feature = "rust1", since = "1.0.0")]
    fn into(self) -> T;
}

As we can see in the definition, Into::into() consumes self and returns T, the opposite of From::from(), which consumes an argument T and returning Self. Compare both ways of converting values:

// `from` can be called from either the `From` trait or the target type.
// Calling from the target type makes our intention clearer.
let converted_value = From::from(original_value);
let converted_value = TargetType::from(original_value);

// `into` is usually called directly on the original value, but we can
// also call it from the Into trait or the source type:
let converted_value = original_value.into();
let converted_value = Into::into(original_value);

While From::from() focuses on the target type, Into::into() focuses on the original value; yet both express the same conversion. All the conversions above are equivalent, choosing one of them is a matter of taste. Personally, I prefer using TargetType::from(value) and value.into(). The former makes our intention clearer, while the latter is shorter than Into::into(value). Note that we might need to add type annotations to disambiguate the intended target type if we opt any form other than TargetType::from(), which clearly indicates it.

A nice thing about implementing From<T> for U is that it implies Into for T, which means we get an automatic Into implementation for free (the opposite isn’t true):

// From implies Into
#[stable(feature = "rust1", since = "1.0.0")]
impl<T, U> Into<U> for T where U: From<T> {
    fn into(self) -> U {
        U::from(self)
    }
}

A secondary advantage of having an Into implementation (it doesn’t matter if it’s explicit or automatic) is that we can use it to broaden function arguments from a specific type to any type can be converted into the target type, as shown in the following example:

// Instead of targetting a specific type like this:
fn do_something(value: TargetType<T>) {
    // ...
}

// We can broaden the accepted types with the following:
fn do_something<U: Into<TargetType<T>>>(value: U) {
    let converted_value = value.into();
    // ...
}

Alright, that’s enough theory. A couple of examples will make it easier to understand how all this works in practice.

Example: `SortedVec<T>`

Suppose we have a sorted vector type, SortedVec<T>. Since it’s a general data structure, building a SortedVec<T> from slice- and list-like types makes sense, so we’ll implement those conversions:

/// Our simple sorted vector structure is just a wrapper around a Vec
struct SortedVec<T>(Vec<T>);

/// Converting slices into SortedVec is pretty much expected.
impl<'a, T: Ord + Clone> From<&'a [T]> for SortedVec<T> {
    fn from(slice: &[T]) -> Self {
        let mut vec = slice.to_owned();
        vec.sort();
        SortedVec(vec)
    }
}

/// Converting a Vec is also expected.
/// We can sort the vector in place and then put it inside SortedVec.
impl<T: Ord + Clone> From<Vec<T>> for SortedVec<T> {
    fn from(mut vec: Vec<T>) -> Self {
        vec.sort();
        SortedVec(vec)
    }
}

/// Converting a LinkedList also makes sense, but it has no
/// slice representation, so we'll have to rely on its iterator.
impl<T: Ord + Clone> From<LinkedList<T>> for SortedVec<T> {
    fn from(list: LinkedList<T>) -> Self {
        let mut vec: Vec<T> = list.iter().cloned().collect();
        vec.sort();
        SortedVec(vec)
    }
}

Now, you might protest that the conversion from Vec<T> is redundant, because we can get a slice from the vector and then convert the slice. That’s absolutely correct, dear reader. However, the implementation above avoids cloning the vector, and, in my opinion, hiding any intermediate steps leads to a more pleasant API.

As a result of the trait implementations above, we can call SortedVec::from() without caring if the argument is a slice, Vec or LinkedList.

let vec = vec![1u8, 2, 3];
// Convert a slice
let sorted = SortedVec::from(&vec[1..]);
// ... a vector
let sorted = SortedVec::from(vec);
// ... a linked list
let mut linked_list: LinkedList<u8> = LinkedList::new();
linked_list.extend(&[1, 2, 3]);
let sorted = SortedVec::from(linked_list);

We can also go in the opposite direction and implement conversions from SortedVec<T> into other types (for instance, into Vec<T>). However, there are some restrictions about implementing traits for non-local, generic types — check error 0210 and the related Rust RFC 1023. As a rule of thumb, if the non-local type isn’t generic over some type parameter, you can implement From for it.

Example: `PacketType`

Let’s take a different example. Suppose we are now implementing a library for a network protocol where the first byte in a packet header tells us the packet type. A reasonable solution is representing the packet types with an enumeration, where each variant maps to a packet type. For instance:

/// Represents a packet type.
/// Associated with each variant is its raw numeric representation.
enum PacketType {
    Data  = 0, // packet carries a data payload
    Fin   = 1, // signals the end of a connection
    State = 2, // signals acknowledgment of a packet
    Reset = 3, // forcibly terminates a connection
    Syn   = 4, // initiates a new connection with a peer
}

Given this representation, how shall we convert to and from the byte representation?

The traditional way, very common in C and C++ programs, is to simply cast the values from one type to another. That can also be done in Rust; for instance, converting PacketType::Data into a byte is as simple as PacketType::Data as u8. That seems to take care of encoding a PacketType into a byte representation, but we aren’t done yet.

Did you notice that each PacketType variant has an associated value? They define the variants’ representation in the generated code. If we followed the usual Rust style and didn’t assign the variants any values, the numeric representation of each variant would depend on the order they are declared, which can lead to errors if we simply cast enum variants into numeric types. A better way to convert the enum variants to the correct values is an explicit match:

impl From<PacketType> for u8 {
    fn from(original: PacketType) -> u8 {
        match original {
            PacketType::Data  => 0,
            PacketType::Fin   => 1,
            PacketType::State => 2,
            PacketType::Reset => 3,
            PacketType::Syn   => 4,
        }
    }
}

Pretty straightforward, right? Since the mapping from PacketType to u8 is contained in the implementation of From, we can remove the values assigned to PacketType’s variants, resulting in a cleaner enum definition.

What about the opposite conversion?

According to the Frequently Asked Questions, converting an enum into an integer can be achieved with a cast, as we saw. However, the opposite conversion can (and I argue that, in many cases, it should) be made with a match statement. For ease of use and better ergonomics, implementing From<T> for conversions in both directions is usually a good idea.

Casting a PacketType to u8 is generally safe and correct, with the caveats we saw before, because for every PacketType variant, there’s a corresponding representation compatible with u8. However, the reverse is decidedly not true: converting an u8 value without a corresponding PacketType variant is undefined behavior! Quoth the Rust reference:

Behavior considered undefined

Invalid values in primitive types, even in private fields/locals:

A discriminant in an enum not included in the type definition

Although we can map any PacketType variant into an u8 value, we can’t do the reverse and map any u8 into a PacketType: there are too many u8s and not enough PacketTypes!

So for the u8 to PacketType conversion, we can’t simply match on u8 value and return the appropriate PacketType variant like we did for the opposite conversion. We need a way to signal that the conversion failed, but calling panic!() is not an acceptable option. We need a fallible From.

“Do or do not; there is no `Try`”

We saw that the conversions made by From and Into must not fail. However, sometimes we deal with types that don’t fully map onto one another, so we need fallible versions of those traits. Fortunately, there’s both TryFrom and TryInto, which return a Result<TargetType, ErrorType>. Both live in std::convert along with their infallible siblings, but their exact details and implications are still under debate, which means they’re still marked as unstable. To use them, we can restrict ourselves to the nightly version of the compiler, use the try_from crate, or paste their definitions somewhere in our crates (they’re really short).

Let’s have a look at TryFrom’s definition (as of Rust 1.10.0):

#[unstable(feature = "try_from", issue = "33417")]
pub trait TryFrom<T>: Sized {
    /// The type returned in the event of a conversion error.
    type Err;

    /// Performs the conversion.
    fn try_from(T) -> Result<Self, Self::Err>;
}

First we have a stability attribute marking the trait as unstable, followed by the trait definition itself. We can see it has an associated type, Err, for the cases where the conversion fails. As expected, we have a try_from method instead of from, which returns Result<Self, Self::Err> instead of Self.

Keeping with our example, we would have:

impl TryFrom<u8> for PacketType {
    type Err = ParseError;
    fn try_from(original: u8) -> Result<Self, Self::Err> {
        match original {
            0 => Ok(PacketType::Data),
            1 => Ok(PacketType::Fin),
            2 => Ok(PacketType::State),
            3 => Ok(PacketType::Reset),
            4 => Ok(PacketType::Syn),
            n => Err(ParseError::InvalidPacketType(n))
        }
    }
}

In this example, we return the corresponding PacketType variant for values which can be mapped and an error for the remaining ones. This error type preserves the original value, which is potentially useful for debugging purposes, but we could just discard it instead.

`AsRef` and `AsMut`

Last but not least, we’re going to examine the remaining traits in the std::convert module: AsRef<T> and AsMut<T>. Like the other traits in this module, they are used to implement conversions among types. However, whereas the other traits consume values and may perform costly operations, AsRef<T> and AsMut<T> are used to implement cheap, reference-to-reference conversions.

As you have probably guessed from their names, AsRef<T> converts an immutable reference to a value into another immutable reference, while AsMut<T> does the same for mutable references.

Since they’re both very similar, we’re going to explore them at the same time. Let’s start with their definitions:

#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsRef<T: ?Sized> {
    /// Performs the conversion.
    #[stable(feature = "rust1", since = "1.0.0")]
    fn as_ref(&self) -> &T;
}

#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsMut<T: ?Sized> {
    /// Performs the conversion.
    #[stable(feature = "rust1", since = "1.0.0")]
    fn as_mut(&mut self) -> &mut T;
}

Both take references to self and return references to the target type with the same mutability as self. Using these traits requires no more than calling as_ref() or as_mut() on a value, depending on which conversion we need, like so: value.as_ref().

Implementing AsRef<T> and AsMut<T> is sensible and easy when the source type is a wrapper around the target type, like the SortedVec<T> example we used before. Since SortedVec<T> relies on a Vec<T>, implementing both traits is painless:

/// SortedVec<T> is a tuple struct, containing a single Vec<T>.
struct SortedVec<T>(Vec<T>);

/// Implementing AsRef<Vec<T>> for SortedVec<T> only requires
/// returning a reference to SortedVec<T>'s single field.
impl<T> AsRef<Vec<T>> for SortedVec<T> {
    fn as_ref(&self) -> &Vec<T> {
        &self.0
    }
}

/// Implementing AsMut<Vec<T>> is just as easy.
/// Note that this allows the user to mutate the underlying Vec
/// such that it's no longer sorted, so you might want to avoid
/// implementing this trait!
impl<T> AsMut<Vec<T>> for SortedVec<T> {
    fn as_mut(&mut self) -> &mut Vec<T> {
        &mut self.0
    }
}

AsRef<T> and AsMut<T> also allow us to broaden the argument type from a specific reference type to any type that can be cheaply converted to the target reference type, just like Into<T>:

fn manipulate_vector<T, V: AsRef<Vec<T>>>(vec: V) -> Result<usize, ()> {
    // ...
}

// Now we can call `manipulate_vector` with a Vec<T> or anything that can
// be cheaply converted to Vec<T>, such as SortedVec<T>.
let sorted_vec = SortedVec::from(vec![1u8, 2, 3]);
match manipulate_vector(sorted_vec) {
    // ...
}

AsRef<T> and AsMut<T> are very similar to Borrow<T> and BorrowMut<T>, but semantically different. The Rust Programming Language Book discusses those differences in detail, but as a rule of thumb, we choose AsRef<T> and AsMut<T> when we want to convert references or when writing generic code, and Borrow<T> and BorrowMut<T> when we wish to disregard whether a value is owned or borrowed (for instance, we might want a value to have the same hash independently of it being owned or not).

There are a few interesting generic implementations for AsRef<T> and AsMut<T>:

// As lifts over &
#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a T where T: AsRef<U> {
    fn as_ref(&self) -> &U {
        <T as AsRef<U>>::as_ref(*self)
    }
}

// As lifts over &mut
#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T: ?Sized, U: ?Sized> AsRef<U> for &'a mut T where T: AsRef<U> {
    fn as_ref(&self) -> &U {
        <T as AsRef<U>>::as_ref(*self)
    }
}

// AsMut lifts over &mut
#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T: ?Sized, U: ?Sized> AsMut<U> for &'a mut T where T: AsMut<U> {
    fn as_mut(&mut self) -> &mut U {
        (*self).as_mut()
    }
}

Those generic implementations may look intimidating, but looks are deceiving. Reading them slowly, we can see the traits are implemented for references to types that implement AsRef or AsMut (&'a T where T: AsRef, &'a mut T where T: AsRef and &'a mut T where T: AsMut). We can also see that every implementation dereferences the argument, which is a reference.

The result is rather useful: these trait implementations make references to references (to references to references…) behave as if they were simple, direct references. That is to say, they make multiple-level deep references such as &&&&vec (in the case of the first implementation) and &&&& mut vec (in the case of the second) equivalent to &vec, while the third implementation makes &mut &mut vec equivalent to &mut vec. After those conversions, any compatible conversions we explicitly implemented can be applied.

Closing thoughts

In this article we dove into std::convert and explored how we can use its traits — From<T>, Into<T>, TryFrom<T>, TryInto<T>, AsRef<T> and AsMut<T> — to achieve a uniform type conversion API. The table below summarizes the characteristics of those traits.

	receives	returns	can fail?
`From<T>`	`T`	`Self`	❌
`TryFrom<T>`	`T`	`Result<Self, E>`	✅
`Into<T>`	`self`	`T`	❌
`TryInto<T>`	`self`	`Result<T, E>`	✅
`AsRef<T>`	`&self`	`&T`	❌
`AsMut<T>`	`&mut` `self`	`&mut` `T`	❌

In short:

From<T>, Into<T>, and their fallible counterparts, TryFrom<T> and TryInto<T>, operate on values and perform conversions that may be costly;
AsRef<T> and AsMut<T>, on the other hand, take references to values and perform cheap reference-to-reference conversions;
We can look at From::from() as if it were a woodchipper that we can feed with any of the approved types of wood;
From<T> for U implies Into for T, it’s usually preferable to implement only the former and get the other for free,
We can make our methods more general by using those traits as type constraints.

Now that you know about these traits, go ahead and use them in your crates. Your API will be more ergonomic and idiomatic, and its users will appreciate the convenience.

I hope you found this article useful! What should we explore next? Tell me on Twitter (@meqif) or send me an email (words@ricardomartins.cc). You can also discuss the article on reddit. If you don’t want to miss the next articles, sign up for my newsletter in the form below. 👇

Interior mutability in Rust, part 3: behind the curtain

2016-07-11T00:00:00-05:00

Key takeaways

UnsafeCell is the keystone for building interior mutability types (Cell, RefCell, RwLock and Mutex)
UnsafeCell wraps around a value and provides a raw mutable pointer to it
It depends on a special compiler path that avoids undefined behavior related to the raw pointer
It lacks synchronization primitives and has a very bare-bones API
Cell and RefCell provide convenient APIs to access their UnsafeCell’s inner value, with negligible-to-none run-time overhead
RwLock and Mutex provide synchronized access to UnsafeCell’s inner value
Avoid using UnsafeCell except when you’re absolutely sure you don’t want any of the other types

This article is part of a series about interior mutability in Rust. You can read part 1 here and part 2 here.

Introduction

In the previous articles, we looked at interior mutability in Rust from a practical standpoint, but we didn’t explore the magic that made it work. In this article we’ll pull back the curtain and stare at the man lurking behind.

A good place to start is reading the definition of Cell, RefCell, RwLock, and Mutex to gather some clues. Luckily, a pattern quickly emerges: all of them contain a field with a common type: UnsafeCell.^[1] We’ll first explore what it is, then figure out how it is used by those types.

What is `UnsafeCell`?

UnsafeCell is defined in the documentation as “the core primitive for interior mutability in Rust”. Indeed, we stumbled on it every time we looked at the definition of types that provide interior mutability. However, for all its apparent power, its definition seems rather boring:

#[lang = "unsafe_cell"]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct UnsafeCell<T: ?Sized> {
    value: T,
}

That’s it? The keystone for interior mutability looks like a newtype struct with some weird stuff before?

Those strange lines right above the structure definition are compiler attributes. We can mostly ignore the second, as it simply marks the function as stable since version 1.0.0 of the compiler, meaning it can be used in any channel (stable, beta, and nightly). The first one is more interesting: it’s a lang item, a sort of special wink and nudge to the compiler. I’ll get to it later.

Apart from new() and into_inner(), which are humdrum methods, there’s also a get() method:

pub fn get(&self) -> *mut T {
    &self.value as *const T as *mut T
}

Even though it’s a small method, we can tell it’s somewhat unusual: it takes an immutable reference to the inner value (&self.value) and then casts it twice: first into a raw constant pointer (*const T), and then into a raw mutable pointer (*mut T), which is returned to the caller.

Raw pointers, eh? That’s new. Let’s take a look.

Raw pointers

Raw pointers are similar to references, which we are used to. Both point to a memory address, but there are important differences. References are smart: they have safety guarantees (such as pointing to valid memory and never being null), borrow checking and lifetimes. Raw pointers, on the other hand, are… well, raw. They have none of those features, and simply point to a memory address, like pointers in C. Most importantly, they don’t have aliasing or mutability guarantees, unlike references. There are two kinds of raw pointers: constant (*const T) and mutable (*mut T). The difference between them is that mutation is not directly allowed on constant pointers, but we can easily cast them into mutable pointers and then mutate the value.

You might have noticed that get() isn’t marked unsafe, even though we are coercing an immutable reference into a raw mutable pointer and dropping Rust’s safety guarantees along the way. Shouldn’t this trip up some alarms?

Coercing (i.e., converting) an immutable reference into a raw constant pointer isn’t too bad. It could be argued that it’s safe, since the immutability of the reference is preserved and we’re starting from a reference, which has the safety guarantees we saw above, so the resulting raw pointer won’t be invalid or null. Going from a raw constant pointer to a raw mutable pointer, on the other hand, seems much worse, because we’re suddenly saying it’s fine to mutate a value we have no business mutating. Going from there back to a mutable reference is definitively bad.

Thinking some more about it, those conversions aren’t actually dangerous by themselves, as they have no side-effects on their own. It’s actually using (i.e., dereferencing) the raw pointers that’s potentially dangerous. As such, when we try to dereference the pointer returned by get() like in this example, the compiler tells us that we’re about to do something potentially dangerous:

error: dereference of raw pointer requires unsafe function or block [E0133]

Surrounding the dereference with an unsafe block signals to the compiler that we’re taking responsibility for all potential badness that may come. In the example, we know the pointer is safe because it was created from a reference and, most importantly, we didn’t mutate its value, so it’ll work as expected.

Even so, mutating non-mutable data is considered undefined behavior:

Mutating non-mutable data (that is, data reached through a shared reference or data owned by a let binding), unless that data is contained within an UnsafeCell.

So, we’re back at the beginning: what makes UnsafeCell special?

✨ A dash of magic ✨

Remember the lang item that preceded UnsafeCell’s definition? Here it is again:

#[lang = "unsafe_cell"]

It triggers special treatment by the compiler: UnsafeCell gets a special marker that follows it during the various compilation phases, until it finally triggers a particular code path. This section of code checks for the presence of that marker and, if it is present, avoids setting two LLVM attributes that get applied to regular types: namely, that the value is read-only and there are no aliases. Those attributes, when present, may allow some additional optimization by LLVM, which can interfere with the behavior we want for UnsafeCell.

Now, that doesn’t mean we absolutely can’t get similar results without the lang item — we can^[2], but that’s purely coincidental and relies on undefined behavior which may eat our laundry, depending on the compiler’s mood (i.e., the generated code may change unexpectedly).

That aside, notice that there is no synchronization inside get(), which makes UnsafeCell unsafe to be used by multiple threads and is thus marked !Sync.

A little experiment shows that using an UnsafeCell incurs no run-time costs after compiler optimization, and is nearly indistinguishable from a “raw” variable, as expected from Rust’s zero-overhead abstractions.

And that’s it for UnsafeCell. It’s a little amazing, but this tiny structure with a very simple method and some compiler support is enough to build upon and create all the other interior mutability types we explored before. A dash of magic is enough. ✨

How is it used?

Now that we know what UnsafeCell is like, let’s explore how the other types build upon it.

`Cell`

Let’s start with Cell, the simplest of the bunch. Its definition is exceedingly succinct:

pub struct Cell<T> {
    value: UnsafeCell<T>,
}

This suggests that Cell merely provides a nicer API to access the inner value contained in UnsafeCell. If we take a gander at Cell::get and Cell::set, we can see that UnsafeCell::get() is enough to implement both methods, and that the implementation details, such as the unsafe blocks, are hidden from the user:

pub fn get(&self) -> T {
    unsafe{ *self.value.get() }
}

pub fn set(&self, value: T) {
    unsafe {
        *self.value.get() = value;
    }
}

There’s an important detail in Cell’s impl declaration: it’s restricted to Copy types.

impl<T:Copy> Cell<T> {

Without this restriction, we would be able to create instances of Cell around !Copy types, such as &mut T (mutable references), which is a terrible idea: doing so would create aliased mutable references and break the aliasing rules.

`RefCell`

RefCell is only slightly more complicated than Cell. It contains an UnsafeCell field with the inner value, just like Cell, and a Cell with a borrow flag to track the borrow state:

pub struct RefCell<T: ?Sized> {
    borrow: Cell<BorrowFlag>,
    value: UnsafeCell<T>,
}

We saw in the first article of the series that we need to call borrow or borrow_mut on RefCell before accessing the value inside. Both methods have similar implementations and convert the raw pointer they get from UnsafeCell::get() to the value back into a reference with &*. For brevity’s sake, we’ll look at just RefCell::borrow(), since RefCell::borrow_mut() is very similar.

pub fn borrow(&self) -> Ref<T> {
    match BorrowRef::new(&self.borrow) {
        Some(b) => Ref {
            value: unsafe { &*self.value.get() },
            borrow: b,
        },
        None => panic!("RefCell<T> already mutably borrowed"),
    }
}

There’s the call to UnsafeCell::get() and conversion back into a reference. Where’s the update to RefCell’s borrow state, though?

Reading BorrowRef::new() makes things clear. Roughly, when that method is called, it checks RefCell’s borrow field (which it received as argument) and updates it if the value can be borrowed. Since the borrow field is a Cell, BorrowRef can mutate it, even though it received an immutable reference to it!

RefCell::borrow_mut() is very similar, except that it calls BorrowRefMut::new() instead of BorrowRef::new(), and returns a mutable reference (to be precise, it returns a RefMut, which implements DerefMut).

We can conclude, then, that Cell and RefCell are lightweight wrappers around UnsafeCell, giving us a convenient API to access UnsafeCell’s inner value and shielding us from dangerous pointer dereferences. In the case of Cell, there’s no run-time cost after optimization, while RefCell’s dynamic borrow checking mechanism incurs a small overhead. Additionally, Cell and RefCell are “tainted” by UnsafeCell’s !Sync marker.

`RwLock` and `Mutex`

In contrast to Cell and RefCell, RwLock and Mutex are more complex data structures which provide synchronized access to the inner value, allowing them to implement Sync and honor that guarantee. We won’t be diving deep into them, but looking at RwLock::read() we can see similarities to RefCell::borrow():

pub fn read(&self) -> LockResult<RwLockReadGuard<T>> {
    unsafe {
        self.inner.lock.read();
        RwLockReadGuard::new(&*self.inner, &self.data)
    }
}

Untangling that a little, we can see that first an inner lock^[3] is locked, then a ReadLockReadGuard is created. Similarly to what BorrowRef does for RefCell, RwLockReadGuard::new() converts the raw pointer it got after calling UnsafeCell::get() into a reference:

unsafe fn new(lock: &'rwlock StaticRwLock, data: &'rwlock UnsafeCell<T>)
              -> LockResult<RwLockReadGuard<'rwlock, T>> {
    poison::map_result(lock.poison.borrow(), |_| {
        RwLockReadGuard {
            __lock: lock,
            __data: &*data.get(),
        }
    })
}

Both RwLock::write() and Mutex::lock() follow a similar pattern to RwLock::read(), so there’s no need to explore them individually.

Wrapping up

In this article we learned that far from relying on arcane magic, interior mutability is achieved thanks to UnsafeCell, a neat little structure that allows the creation of more ergonomic abstractions on top of it.

Since its API involves unsafe operations, using it directly is a little cumbersome. In nearly every case where we need interior mutability, we are better served by Cell, RefCell, RwLock, and Mutex instead. There are a few cases where you might want to avoid the overhead of those types by UnsafeCell directly, such as implementing new locks and concurrent data structures, but those aren’t common tasks unless you work in academia. 😉

Whew! This concludes the series on interior mutability. I hope you enjoyed it! Special thanks to everyone who has commented on both this and the previous articles. Your support and corrections are deeply appreciated. 💜

What should we explore next? Tell me on Twitter (@meqif) or send me an email (words@ricardomartins.cc). You can also discuss the article on reddit. If you don’t want to miss the next articles, sign up for my newsletter in the form below. 👇

Many other types depend on UnsafeCell, such as Condvar, the Sender and Receiver structures used created by std::sync::mpsc::channel, thread-local variables (created with the thread_local macro), private data structures used in the compiler implementation, and some others I won’t bother to list. ↩
Compare the result when running this example in debug mode and release mode. In release mode the compiler assumed that the value is never changed, so the call to println! doesn’t show the update! Thanks to /u/derKha and /u/notriddle for their examples. ↩
That inner lock is actually a native OS lock. You can read the implementation for the Unix one and the Windows one. Both rely on UnsafeCell as well. ↩

Interior mutability in Rust, part 2: thread safety

2016-06-25T00:00:00-05:00

Key takeaways

We can have thread-safe interior mutability through Mutex, RwLock and the various Atomic* types in std::sync
Mutex allows only one thread at a time, has no direct thread-unsafe counterpart, but can be thought of as only giving &mut T references
RwLock is equivalent to RefCell, and also allows multiple readers or one writer
The Atomic types are equivalent to Cell
std::sync::Arc is the thread-safe version of std::rc::Rc, necessary to share references among threads
These thread-safe types have additional run-time cost compared to their unsynchronized counterparts
In Rust, we lock/protect data, not code

This article is part of a series about interior mutability in Rust. You can read part 1 here and part 3 here.

Introduction

In the previous article, we looked into Cell and RefCell as a way to achieve interior mutability—the ability to mutate particular fields in a structure regardless of its exterior (explicit or declared) mutability.

However, neither Cell nor RefCell are appropriate to share data among threads. Since Cell has no borrow checking mechanisms and its operations aren’t atomic, it’s possible to have race conditions where we read outdated values and lose updates. RefCell, on the other hand, has run-time borrow checking, but will panic when there are conflicting borrows, such as borrowing a mutably borrowed value. Additionally, RefCell uses a Cell to keep track of the borrow state. This means that even if you were careful and checked it before borrowing, you would risk mutably borrowing the value in multiple threads simultaneously, because its run-time borrow checks aren’t atomic either.

Because of those issues, both Cell and RefCell are marked !Sync, which means they’re unsafe to be used in more than one thread.^[1]

Additionally, we need to share references to the cell among threads, but the reference counter type we explored previously, Rc, is also not appropriate to be used in this scenario. The reference counter fields inside Rc are wrapped by Cell, so they would get erroneous values in a threaded program sooner or later. The presence of !Sync fields is “infectious”. Since Rc contains two Cell fields, their !Sync markers propagate to the entire Rc structure. Rc is also marked !Send — unsafe to send (move) to other threads. Likewise, !Send is just as “infectious” as !Sync.

We could implement both traits ourselves in our types, but since those traits are rather important, they’re marked as unsafe. So, we need to tell the Rust compiler we know what we’re doing by prefixing their impl declarations with the unsafe keyword. For instance, if we wanted to make the nodes in the example of the previous article Send and Sync:

unsafe impl<T> Send for Node<T> {}
unsafe impl<T> Sync for Node<T> {}

This does make the compiler shut up and allows us to get on with it, but what does it mean?

Send and Sync are automatically derived by the compiler for most types. If a type contains a !Send or !Sync field, the “taint” always spreads to the parent types. By explicitly implementing those traits, we’re implicitly telling the user of our API that our types are thread-safe (Sync) and that they can be moved between threads safely (Send).

When we say our types are Send and Sync without actually introducing synchronization mechanisms, we’re disrespecting the “contracts” associated with those traits and misleading the user. They’d get run-time panics or bad results due to race conditions. Not a happy situation, at all.

Thread-safe interior mutability

Fortunately, Rust gives us good tools to achieve interior mutability in a thread-safe way without much effort. More than that, it does so in such a way that the borrow checker will have our backs most of the time, so we can’t shoot ourselves in the feet.

One of the really nice aspects about Rust is that once you get the hang of the borrow system, you can use the same reasoning with interior mutability in a single thread (Cell and RefCell) and in concurrent programs.

For `Copy` values

For Copy values (eg., integers), instead of Cell, we have Atomic types (std::sync::atomic::*) that rely on assembly instructions to prevent data races:

AtomicBool, a boolean type,
AtomicIsize, a signed integer type,
AtomicUsize, an unsigned integer type, and
AtomicPtr, a raw pointer type.

Even though there are only four types, you can can build on AtomicPtr to implement additional ones. Alternatively, you can use crates, such as the atom crate, to do so with a simple API. Quick disclaimer: I haven’t tried atom but the example in its README looks nice, and a quick glance at the source code looks exactly like what I would expect.

Using an atomic type is a bit more involved than doing the same with a Cell. Taking again the naive reference counter example of the previous article, using an AtomicUsize we’d have:

use std::sync::atomic::{AtomicUsize, Ordering};

struct NaiveRc<T> {
    reference_count: AtomicUsize,
    inner_value: T,
}

impl<T> Clone for NaiveRc<T> {
    fn clone(&self) -> Self {
        self.reference_count.fetch_add(1, Ordering::Relaxed);
        // ...
    }
}

As you can see, instead of simply assigning a new value to reference_count, we called fetch_add to atomically increment it. The first parameter is the increment size, while the second is new. An Ordering tells the compiler (and the CPU) how much freedom it has to reorder instructions. I won’t delve into that, as the official documentation explains it in sufficient detail.

For non-Copy values

For non-copy values, std::sync::RwLock is the counterpart to RefCell. Like RefCell, RwLock has semantics very similar to our old friend the borrow system, and allows either several “readers” or one “writer”, but not both at the same time, nor several “writers”.

Unlike RefCell, however, RwLock doesn’t panic when there are incompatible borrows: if a thread needs a mutable reference, it will just have to wait until the other threads release the lock (i.e., stop using the borrowed values).

We can get shared, read-only references with read (equivalent to borrow in RefCell), or exclusive, mutable references with write (borrow_mut, respectively).^[2]

Converting the graph example in the previous article to use RwLock instead of RefCell is straightforward: replace RefCell declarations with RwLock, change borrow to read and borrow_mut to write. We also need to replace Rc with Arc to be able to move references to other threads, but I’ll describe that later.

use std::thread;
use std::sync::{Arc, RwLock};

// Represents a reference to a node.
// This makes the code less repetitive to write and easier to read.
type NodeRef<T> = Arc<RwLock<_Node<T>>>;

// The private representation of a node.
struct _Node<T> {
    inner_value: T,
    adjacent: Vec<NodeRef<T>>,
}

// The public representation of a node, with some syntactic sugar.
struct Node<T>(NodeRef<T>);

impl<T> Node<T> {
    // Creates a new node with no edges.
    fn new(inner: T) -> Node<T> {
        let node = _Node { inner_value: inner, adjacent: vec![] };
        Node(Arc::new(RwLock::new(node)))
    }

    // Adds a directed edge from this node to other node.
    fn add_adjacent(&self, other: &Node<T>) {
        self.0
            .write()
            .expect("Failed to acquire a write lock on node")
            .adjacent.push(other.0.clone());
    }
}

struct Graph<T> {
    nodes: Vec<Node<T>>,
}

impl<T> Graph<T> {
    fn with_nodes(nodes: Vec<Node<T>>) -> Self {
        Graph { nodes: nodes }
    }
}

fn main() {
    // Create some nodes
    let node_1 = Node::new(1);
    let node_2 = Node::new(2);
    let node_3 = Node::new(3);

    // Connect some of the nodes (with directed edges)
    node_1.add_adjacent(&node_2);
    node_1.add_adjacent(&node_3);
    node_2.add_adjacent(&node_1);
    node_3.add_adjacent(&node_1);

    // Add nodes to graph
    let graph = Arc::new(Graph::with_nodes(vec![node_1, node_2, node_3]));

    // Spawn a new thread that will print information about every node in the
    // graph.
    // The new scope makes this block more obviously different from the code
    // surrounding it and lets us group variables that will be moved into the
    // new thread, such as "graph".
    let guard = {
        let graph = graph.clone();
        let message = "Failed to acquire a read lock";
        thread::spawn(move || {
            for _ in 0..10 {
                // Show every node in the graph and list their neighbors
                for node in &graph.nodes {
                    let node = node.0.read().expect(&message);
                    let value = node.inner_value;
                    let neighbours = node.adjacent
                        .iter()
                        .map(|n| n.read().expect(&message).inner_value)
                        .collect::<Vec<_>>();
                    println!("node ({}) is connected to: {:?}", value, neighbours);
                }
                println!("-------------");
                // Give the main thread a chance to run
                thread::yield_now();
            }
        })
    };

    for _ in 0..10 {
        // Update the value of every node in the graph
        for node in &graph.nodes {
            let mut node = node.0.write().expect("Failed to acquire a write lock");
            node.inner_value += 10;
        }
        // Give the other thread a chance to run
        thread::yield_now();
    }

    // Wait for the other thread to end
    guard.join().expect("Error joining thread");
}

You can view the differences between the single- and multi-threaded versions in this gist.

Apart from creating a new thread that prints the graph’s information and a new loop in the main thread that updates the node’s values, the only important differences are:

Arc<RwLock<_>> instead of Rc<RefCell<_>>
Every call to borrow and borrow_mut was replaced with read and write, respectively.

I encourage you to make these changes yourself starting from the previous article’s code. Making small, incremental changes and compiling the intermediate versions usually helps me get an intuitive feel for how the API works.

Note that, unlike borrow and borrow_mut, read and write return a LockResult, which is a type alias for Result<Guard, PoisonError<Guard>>, and requires us to match, unwrap or expect it. The Guard is automatically coerced into a reference, so we can pretty much ignore it.

In my experience, you rarely need to deal with the error case for either read or write, as it only happens if another thread with a mutable reference (i.e., a successful write) panics. In that case, you have a more serious bug elsewhere that you need to take care of.

Both read and write will block the thread until it gets the requested lock. Since you may not want to wait indefinitely, you can also call try_read and try_write instead, which won’t block and return an error if they couldn’t get a lock.

Besides RwLock, there is also std::sync::Mutex, whose name comes from “mutual exclusion”, because it guarantees mutually exclusive access to the wrapped value, i.e., only one thread can access it at a time. Because of this, it’s always safe to mutate the value once you get access to it.

We can look at Mutex as if it were an RwLock without read, only able to give the caller mutable references. In this sense, it’s more constraining than the regular borrow system or an RwLock, which allow either multiple simultaneous readers (with immutable references) or only one writer (a mutable reference) at a time. Even if we want an innocent immutable reference, we must get full permission to the inner value.

As there is only one kind of borrow for Mutex values, read and write are replaced by a single lock method, which will block the thread until the current lock owner releases it (i.e., the other borrow ends). Like with RwLock, if you don’t want to block the thread when the value isn’t available, you can call try_lock instead, which will either give you the lock/mutable reference or an error (Err).^[3]

Reference counting

As I mentioned earlier, std::rc::Rc lacks synchronization control, which makes it unsafe to be used by multiple threads. Its thread-safe counterpart is Arc, which lives in std::sync, along with RwLock and Mutex.

Arc is very similar to Rc but relies on AtomicUsize for the reference counter, which makes it safe to be updated by more than one thread, unlike Rc, which uses Cell<usize>.

pub struct Rc<T: ?Sized> {
    ptr: Shared<RcBox<T>>,
}

struct RcBox<T: ?Sized> {
    strong: Cell<usize>,
    weak: Cell<usize>,
    value: T,
}

pub struct Arc<T: ?Sized> {
    ptr: Shared<ArcInner<T>>,
}

struct ArcInner<T: ?Sized> {
    strong: atomic::AtomicUsize,
    weak: atomic::AtomicUsize,
    data: T,
}

Arc’s API is identical to Rc’s, which makes replacing one with the other a simple matter of searching and replacing the name and correcting the import.

Closing thoughts

In the previous article, we learned that interior mutability in Rust can be achieved through Cell and RefCell in single-threaded programs, supported by Rc where necessary. In this article, we saw the same can be done in a safe way in concurrent programs with Atomic types and RwLock, with the help of Arc.

	Single thread	Multiple threads
Copy value	`Cell`	`Atomic*`
Non-Copy value	`RefCell`	`RwLock`, `Mutex`
Reference counter	`Rc`	`Arc`

The table above summarizes the types to be used in single- and multi-threaded scenarios.

Type of access	Borrow checker	`RefCell`	`RwLock`	`Mutex`
shared / read-only	`&T`	`borrow`	`read`	-
exclusive / writable	`&mut T`	`borrow_mut`	`write`	`lock`

This second table highlights the similarities between the borrow checker, RefCell, RwLock and, to a lesser degree, Mutex.

You could ask, “Why bother opting for RefCell and Rc if RwLock and Arc have identical semantics and very similar APIs?”

Unfortunately, the types we explored in this article (Atomic types, RwLock, Mutex and Arc) depend on synchronization primitives with higher run-time overhead than their naive counterparts, and we’ll want to avoid them whenever possible.

We can have a regular Rc and RefCell combination for variables that aren’t shared with other threads, and their synchronized versions for the bits you want to parallelize. Because the API and semantics are similar in both cases, we will have little cognitive overhead using both.

Another important point we must also pay attention to, is the semantics of the wrapping. For instance, Arc<Vec<RwLock<T>>> is different from Arc<RwLock<Vec<T>>>. With the first, we can’t concurrently mutate the vector itself, but we can mutate its stored values. This is a consequence of Arc implementing Deref but not DerefMut, meaning we can only get immutable references to the vector (which contains lockable elements). With the second form, we get an immutable reference to RwLock, but since it can give us both kinds of references through read and write, we can mutate the vector, adding or removing elements. However, we lose the ability to concurrently mutate the values: once a thread gets a mutable reference to the vector, the others will have to wait, while the first form allows us to have one thread mutating each element in parallel.

In short, Arc<Vec<RwLock<T>>> allows us to mutate all elements of the vector in parallel if we wish to do so, while Arc<RwLock<Vec<T>>> allows only one thread to modify the vector (and its values), leaving other threads waiting for the lock.

If T is itself wrapped by Arc, we would be unable to mutate the stored values at all (because Arc coerces only to immutable references). We would need a monstrosity like Arc<RwLock<Vec<Arc<RwLock<T>>>>> to be able to concurrently mutate both the vector and its elements, but we should take this a hint to rethink how you want to parallelize your code.

Exploring interior mutability in a concurrent environment made me realize that Rust is different from other languages regarding locks. Whereas in other languages we use locks to protect code fragments, in Rust we use them to protect access to data.

In addition, locks are so similar in use to Rust’s borrow mechanisms that they feel like a thread-safe generalization of those mechanisms. Personally, I find this way much easier to reason about than the classic, C way.

Finally, I know it’s tempting, but don’t throw interior mutability everywhere just to make the borrow checker shut up. Consider carefully whether the situation really calls for interior mutability or a refactor of your data structures. This goes doubly so for concurrent programs, not only because RwLock, Mutex and Arc incur additional run-time costs, but also because synchronization is easy to mess up and leave you with race conditions. Fortunately, Rust’s borrow checker gives us precious guidance and makes them much less likely. Race conditions are nasty to debug, be especially careful about dropping your locks as soon as possible.

That’s it. Now you know enough to effectively employ interior mutability in your programs, whether they are single- or multi-threaded. Well done! 🎉

My thanks to /u/Manishearth, /u/Steel_Neuron, and /u/diwic for their feedback.

I hope you found this article useful and/or interesting. As always, if you found a mistake or have any questions, please ping me on Twitter (@meqif) or send me an email (words@ricardomartins.cc). You can also join the discussion on reddit.

We can implement a marker trait or its negation for a type. Currently this only works with marker traits, such as Sync and Send, which don’t have associated methods but provide useful type information. There is work being done toward generalizing this feature, called negative traits, to any trait (rust-lang/rust #13231). ↩
Actually, read and write will return Result<RwLockReadGuard> or Result<RwLockWriteGuard>, respectively. RwLockReadGuard implements Deref, and RwLockWriteGuard implements both Deref and DerefMut, which are transparently coerced into mutable (&T) and immutable (&mut T) references, respectively. ↩
Similarly to RwLock, calling lock on a Mutex will return a Result<MutexGuard>, which implements both Deref and DerefMut, and can be coerced into &T or &mut T, respectively. ↩

Interior mutability in Rust: what, why, how?

2016-06-08T00:00:00-05:00

Rust is like doing parkour while suspended on strings & wearing protective gear. Yes, it will sometimes look a little ridiculous, but you’ll be able to do all sorts of cool moves without hurting yourself. – llogiq on reddit

Key takeaways

Interior mutability is when you have an immutable reference (&T) but you can mutate the destination
It’s useful when you need mutable fields inside immutable data structures
std::cell::Cell<T> and std::cell::RefCell<T> can be used to achieve interior mutability
Cell wraps Copy values and doesn’t have borrow checking
RefCell wraps any kind of value, has run-time borrow checking, and requires “locking” with borrow or borrow_mut, which give you an immutable or mutable reference, respectively
Neither are safe to be directly used in a multi-threaded environment. Use Mutex or RwLock instead.

This article is part of a series about interior mutability in Rust. You can read part 2 here and part 3 here.

Introduction

Sometimes data structures need to mutate one or more of their fields even when they are declared immutable. This may sound surprising at first, but you’ve probably relied on this behavior before, like when you clone a reference counted wrapper such as Rc, or when you lock a Mutex. However, in Rust, mutability is an all-or-nothing attribute: either a variable is declared as mutable and all of its fields are also mutable (if it is a struct), or it’s declared immutable and so are all of its fields. How do we get selective field mutability? Something mysterious is afoot.

Have you ever wondered how Rc is implemented? Let’s have a try! A naive first solution would be something like the following:

struct NaiveRc<T> {
    reference_count: usize,
    inner_value: T,
}

impl Clone for NaiveRc<T> {
    fn clone(&self) -> Self {
        self.reference_count += 1;
        // ...
    }
}

You probably spotted the problem right away: clone takes a read-only reference to self, so the reference count can’t be updated! Dang it.

We could implement a special, differently-named cloning function that takes &mut self, but that is awful for usability (because it defies the convention of simply checking if a type implements Clone), and forces the user of our API to always declare mutable instances of that type. We also know that the reference counted wrappers in the standard library (std::rc::Rc and std::sync::Arc) don’t rely on that solution, which suggests there’s another way.

So, how did they solve this problem in Rc and Arc? Does the standard library rely on some sort of specially nasty magic? Not at all!

This is an instance of interior mutability, and the Rust language provides you with tools to easily and cleanly solve this sort of situation.

What?

Interior mutability is a concept that many programmers new to Rust have never come across before or haven’t had to explicitly think about. It’s also more visible in Rust than in most other programming languages because we have to think about the mutability or not of variables and function arguments. This is even more evident when we look at immutable vs. mutable as shared vs. exclusive access to objects. The unspoken heuristic is that avoiding mutability when possible is good.

And yet, in some cases you need a few mutable fields in data structures, whether they’re mutable or not. Interior mutability gives you that additional flexibility and allows you to hide implementation details from the user of your API, while preserving (some measure of) access safety.

To explain what interior mutability is, it’s better to step back a little and start with something you’re familiar about: exterior mutability.

Exterior mutability is the sort of mutability you get from mutable references (&mut T). The type of declaration, &T or &mut T, makes it clear if you’re free to update a variable or call mutating methods on objects. Exterior mutability is checked and enforced at compile-time, as you know:

struct Foo { x: u32 };

let foo = Foo { x: 1 };
// The borrow checker will complain about this and abort compilation
foo.x = 2;

let mut bar = Foo { x: 1 };
// 'bar' is mutable, so you can change the content of any of its fields
bar.x = 2;

If you have an immutable reference, you can’t change the value. Conversely, because there is no field-level mutability in Rust, if you want to mutate a single field, you need to make the entire structure mutable, and that’s it. Or is it? Not so fast.

Interior mutability, in contrast, is when you have an immutable reference (i.e., &T) but you can mutate the data structure. As I mentioned before, that’s what happens when you clone an Rc or lock a Mutex (both Mutex::lock and Mutex::try_lock work in immutable instances).

A simple example will make the difference clearer. Suppose we have a simple structure like the following:

struct Point { x: i32, y: i32 }

An immutable Point can be seen as an immutable memory chunk, whose fields (sections of the memory chunk) can’t have their content changed at all. When you declare an immutable Point your hands are tied.

Consider now a slightly different, magically-enhanced MagicPoint:

struct MagicPoint { x: i32, y: Magic<i32> }

For now, ignore how Magic works, and think of it as a pointer to a mutable memory address, a new layer of indirection. Like previously, if you have an immutable MagicPoint, you can’t assign new values to any of its fields. However, in this case you don’t need to change the content of y, only the destination of that magical pointer, i.e., the other memory chunk, and that one is mutable!^[1]

To be clear, even though the API for Magic will make it seem as if you’re relying on indirection to access and update the wrapped value, the memory representation of MagicPoint will actually be flat.

Note that when you rely on interior mutability, you are giving up the compile-time safety guarantees that exterior mutability gives you. As we’ll see next, it’s not that bad, provided you’re careful.

How?

So, how can we get magical mutable pointers? Fortunately for us, the Rust standard library provides two wrappers, std::cell::Cell and std::cell::RefCell, that allow us to introduce interior mutability in externally immutable instances of data structures. With Cell<T> and RefCell<T> in our collective toolbelts, we can harness the power of interior mutability.

Both wrappers provide interior mutability and give up compile-time borrow checking on the inner value, but give different safety guarantees and serve different purposes. The most obvious difference between them is that RefCell makes run-time borrow checks, while Cell does not.

Cell is quite simple to use: you can read and write a Cell’s inner value by calling get or set on it. Since there are no compile-time or run-time checks, you do have to be careful to avoid some bugs the borrow checker would stop you from writing, such as accidentally overwriting the wrapped value:

use std::cell::Cell;

fn foo(cell: &Cell<u32>) {
    let value = cell.get();
    cell.set(value * 2);
}

fn main() {
    let cell = Cell::new(0);
    let value = cell.get();
    let new_value = cell.get() + 1;
    foo(&cell);
    cell.set(new_value); // oops, we clobbered the work done by foo
}

In contrast, a RefCell requires you to call borrow or borrow_mut (immutable and mutable borrows) before using it, yielding a pointer to the value. Its borrow semantics are identical to externally mutable variables: you can have either a mutable borrow on the inner value or several immutable borrows, so the kind of bug I mentioned earlier is detected in run-time.

use std::cell::Cell;

struct NaiveRc<T> {
    inner_value: T,
    references: Cell<usize>,
}

impl<T> NaiveRc<T> {
    fn new(inner: T) -> Self {
        NaiveRc {
            inner_value: inner,
            references: Cell::new(1),
        }
    }

    fn references(&self) -> usize {
        self.references.get()
    }
}

impl<T: Clone> Clone for NaiveRc<T> {
    fn clone(&self) -> Self {
        self.references.set(self.references.get() + 1);
        NaiveRc {
            inner_value: self.inner_value.clone(),
            references: self.references.clone(),
        }
    }
}

fn main() {
    let wrapped = NaiveRc::new("Hello!");
    println!("references before cloning: {:?}", wrapped.references());
    let wrapped_clone = wrapped.clone();
    println!("references after cloning: {:?}", wrapped.references());
    println!("clone references: {:?}", wrapped_clone.references());
}

Calling borrow or borrow_mut on a mutably borrowed RefCell will cause a panic, as will calling borrow_mut on a immutably borrowed value. This aspect makes RefCell unsuitable to be used in a parallel scenario; you should use a thread-safe type (like a Mutex or a RwLock, for example) instead.

A RefCell will stay “locked” until the pointer you received falls out of scope, so you might want to declare a new block scope (ie., { ... }) while working with the borrowed value, or even explicitly drop the borrowed value when you’re done with it, to avoid unpleasant surprises.

Another significant difference between Cell and RefCell is that Cell<T> requires that the inner value T implements Copy, while RefCell<T> has no such restriction. Often, you won’t want copy semantics on your wrapped types, so you’ll have to use RefCell.

Put succinctly, Cell has Copy semantics and provides values, while RefCell has move semantics and provides references.

Why?

There are a few general cases that call for interior mutability, such as:

Introducing mutability inside of something immutable
Mutating implementations of Clone
Implementation details of logically immutable methods
Mutating reference-counted variables

Introducing mutability inside of something immutable

Returning to the NaiveRc example in the introduction, reference-counting pointers, like Rc and Arc, need internal mutability. When you clone those pointers, the reference counter inside them has to be updated, whether they’re mutable or not. Without interior mutability, you would be forced to always use mutable pointers, which would allow mutation of the inner value and may be undesired.

For instance, consider the following naive reference counted wrapper:

use std::cell::Cell;

struct NaiveRc<'a, T: 'a> {
    inner_value: &'a T,
    references: Cell<usize>
}

let x = NaiveRc { inner_value: &1, references: Cell::new(1) };
x.references.set(2); // it works!
x.inner_value = &2;  // beep boop, x is immutable,
                     // you can't assign a new value to any of its fields!

Mutating implementations of `Clone`

Way back in the introduction, we noticed that cloning a reference-counted value (Rc<T>) needs to increment the reference counter. This is simply a special case of the previous point, but it deserves reiterating.

On the other hand, dropping such a value requires decrementing the reference counter, but drop works with mutable references (fn drop(&mut self)), so there’s no problem there.

Implementation details of logically immutable methods

For instance, you might want to amortize the running time of an expensive algorithm operating on your data structure by using a cache inside it. The cache must be able to be updated even when the data structure itself is immutable.

Mutating reference-counted variables

Suppose we need multiple references to some objects. For example, when connecting nodes in a graph. “Oh, that’s easy”, you think. “I’ll just wrap my nodes in Rc or Arc and call it a day”. That a perfectly reasonable line of though, and it would work… if you never, ever needed to mutate nodes. Once you try building the graph by incrementally adding and connecting nodes, the compiler will give you grief. Oh no, what is going on? Unfortunately for us, Rc preserves safety by only giving you shared (i.e., immutable) references when you call clone. Quoth the std::rc module documentation:

The Rc<T> type provides shared ownership of an immutable value. Destruction is deterministic, and will occur as soon as the last owner is gone.

You could call get_mut to receive an Option<&mut T>, but that would work only once: get_mut only returns a mutable reference as if there is only one “strong” reference to the value.^[2] Foiled again!

Fortunately, you can use interior mutability here: use Rc<Cell<T>> or Rc<RefCell<T>>. That way you can clone the reference-counted wrapper as much as you want and still modify the innermost value wrapped by Cell or RefCell.

You can see a first try at a solution in this example in the Rust Playground. As you can see, the problem is solved, but the solution is verbose and ugly. Not only that, the user of our API is aware of implementation details! What gives? Where’s the elegant abstraction I promised a few paragraphs above?

Now that you’ve seen and understood how this works, I can show you a cleaner version:

use std::cell::RefCell;
use std::rc::Rc;

// A graph can be represented in several ways. For the sake of illustrating how
// interior mutability works in practice, let's go with the simplest
// representation: a list of nodes.
// Each node has an inner value and a list of adjacent nodes it is connected to
// (through a directed edge).
// That list of adjacent nodes cannot be the exclusive owner of those nodes, or
// else each node would have at most one edge to another node and the graph
// couldn't also own these nodes.
// We need to wrap Node with a reference-counted box, such as Rc or Arc. We'll
// go with Rc, because this is a toy example.
// However, Rc<T> and Arc<T> enforce memory safety by only giving out shared
// (i.e., immutable) references to the wrapped object, and we need mutability to
// be able to connect nodes together.
// The solution for this problem is wrapping Node in either Cell or RefCell, to
// restore mutability. We're going to use RefCell because Node<T> doesn't
// implement Copy (we don't want to have independent copies of nodes!).

// Represents a reference to a node.
// This makes the code less repetitive to write and easier to read.
type NodeRef<T> = Rc<RefCell<_Node<T>>>;

// The private representation of a node.
struct _Node<T> {
    inner_value: T,
    adjacent: Vec<NodeRef<T>>,
}

// The public representation of a node, with some syntactic sugar.
struct Node<T>(NodeRef<T>);

impl<T> Node<T> {
    // Creates a new node with no edges.
    fn new(inner: T) -> Node<T> {
        let node = _Node { inner_value: inner, adjacent: vec![] };
        Node(Rc::new(RefCell::new(node)))
    }

    // Adds a directed edge from this node to other node.
    fn add_adjacent(&self, other: &Node<T>) {
        (self.0.borrow_mut()).adjacent.push(other.0.clone());
    }
}

struct Graph<T> {
    nodes: Vec<Node<T>>,
}

impl<T> Graph<T> {
    fn with_nodes(nodes: Vec<Node<T>>) -> Self {
        Graph { nodes: nodes }
    }
}

fn main() {
    // Create some nodes
    let node_1 = Node::new(1);
    let node_2 = Node::new(2);
    let node_3 = Node::new(3);

    // Connect some of the nodes (with directed edges)
    node_1.add_adjacent(&node_2);
    node_1.add_adjacent(&node_3);
    node_2.add_adjacent(&node_1);
    node_3.add_adjacent(&node_1);

    // Add nodes to graph
    let graph = Graph::with_nodes(vec![node_1, node_2, node_3]);

    // Show every node in the graph and list their neighbors
    for node in graph.nodes.iter().map(|n| n.0.borrow()) {
        let value = node.inner_value;
        let neighbours = node.adjacent.iter()
            .map(|n| n.borrow().inner_value)
            .collect::<Vec<_>>();
        println!("node ({}) is connected to: {:?}", value, neighbours);
    }
}

If you ignore the loop that prints out the graph’s information, now the user doesn’t know how a Node is implemented. This version’s usability can still be improved by implementing the std::fmt::Debug trait for Node and Graph, for instance.

You can play with this example in the Rust Playground. Try changing some things yourself! I find breaking things helps me consolidate new knowledge. I suggest:

Replacing RefCell with Cell
Removing RefCell and using Rc<Node<T>>
Removing Rc and using RefCell<Node<T>>

You could also try replacing Rc with Arc, but you wouldn’t notice anything different. Arc is a thread-safe version of Rc, which comes with a performance cost and doesn’t really make sense in single-threaded programs.

An alternative solution could involve wrapping the adjacent node vector in a RefCell instead of wrapping the node itself. That can also work, depending on what you intend to do, but it is semantically different from the previous solution, as you would be unable to mutate a node’s inner value in addition to its list of adjacent nodes.

Which to pick?

If RefCell can explode in your face and shouldn’t be used “raw” in a multi-threaded program, why bother using it?

While Cell is a good choice for many cases, there are a few reasons you might want to use RefCell:

The wrapped value doesn’t implement Copy.
Only RefCell has run-time checks. In some scenarios you’d rather kill the program than risk corrupting data.
RefCell exposes pointers to the stored value, Cell doesn’t.

As a rule of thumb, choose Cell if your wrapped value implements Copy (such as primitive values, like integers and floats). If the wrapped value is a struct, doesn’t implement Copy or you need dynamically checked borrows, use RefCell instead.

Wrapping up

	Cell	RefCell
Semantics	Copy	Move
Provides	Values	References
Panics?	Never	Mixed borrows or more than one mutable borrow
Use with	Primitive types	Structures or non-Copy types

The table above summarizes what you learned in this blog post.

As Steve Klabnik, /u/critiqjo and /u/birkenfield kindly pointed out, Mutex and RwLock already have interior mutability, so there’s no need to put a Cell inside them. In multi-threaded scenarios you should use Mutex and RwLock without an additional Cell or RefCell.

/u/krdln suggested the alternative graph implementation above.

If you are familiar with C and this reminds you of const pointers (whose value also can’t change but the content at the destination memory address can), you are in the right track. y would be something like a int *const. ↩
I really don’t want to get into the strong and weak reference thing now. Suffice it to say that strong references stop objects from being destroyed, while weak references don’t. ↩

Practical differences between Rust closures and functions

2015-10-12T00:00:00-05:00

Elizabeth asks an interesting question: “What’s the difference between a function and a closure that doesn’t enclose any variable?”

When I read that question, I was intrigued. Using closures instead of functions tends to be more costly because closures capture some of the environment, and that has some overhead. In practice, we usually don’t think about the difference when programming, and the choice of one over the other comes down to personal preference and what feels right.

However, Rust has a reasonably smart compiler that can take advantage from a wide array of optimisations, and zero cost abstractions is one of Rust’s strengths, so it’s also reasonable to expect little difference between a function and a closure with no free variables (i.e., no enclosed variables) after optimisation.

This matter can be unfolded into several smaller questions, but for the sake of pragmatism I will be focusing on the differences in the code generated by the ~~current stable~~ nightly release of the compiler, rustc 1.5.0-nightly (7bf4c885f 2015-09-26). The easiest way to compare the generated assembly code is to compile the two different versions with rustc -C opt-level=2 --emit asm and check the differences with diff. Comparing only the optimised code will help us avoid drowning in inconsequential differences, since the debug builds are only useful for development and aren’t supposed to be used in production. 😉

Alright, let’s go ahead and compare the following two examples (adapted from Elizabeth’s question):

Function

fn double(x: i32) -> i32 {
    2 * x
}

fn main() {
    let v = vec!(1, 2, 3);
    let w = v.into_iter().map(double);
    // Make sure the result isn't optimised away
    println!("{:?}", w.collect::<Vec<i32>>());
}

Closure

fn main() {
    let v = vec!(1, 2, 3);
    let w = v.into_iter().map(|x| 2 * x);
    // Make sure the result isn't optimised away
    println!("{:?}", w.collect::<Vec<i32>>());
}

I made both versions available on the Rust playground: function and closure. If you want to see for yourself the output of running diff on the resulting files, here you go. Be warned: the diff is “noisy” because some CPU registers are used in one version but not in the other, and there is also name mangling.

Looking at the generated assembly code, the only significant difference is that the code corresponding to the body of the function/closure, 2 * x, is preceded by a call to __rust_allocate (std::rt::heap::allocate), and followed by a call to __rust_deallocate (std::rt::heap::deallocate), but only in the version where a closure is used.

~~That makes sense: the closure is actually an instance of `FnOnce`, which we can see being created and destroyed with `allocate` and `deallocate`, respectively.~~

EDIT: After I published this post, Huon Wilson and Björn Steinbrink took a look to the generated assembly code and concluded that the extra allocation is actually an instance of the vector v that isn’t being optimized away in the closure version, which is a little surprising. Björn suspects [1, 2] this is due to a different set of optimizations being applied in each version. Huon also pointed out that closures are never implicitly on the heap, as he explains in an excellent blog post about closures. Thanks for the precious feedback, Huon and Björn!

For more details about how closures are implemented in Rust, check the Closures chapter in the official book, as well as Huon Wilson’s blog post.

I also ran a small benchmark pitting both versions against each other, but there is no measurable difference between both versions.

The bottom line is, for most users there is no practical difference between functions and closures without captured variables. Use whatever seems right. Personally, I prefer using closures when they’re small and used in one place (like in the previous examples), and functions otherwise. Remember Harold Abelson’s advice:

“Programs must be written for people to read, and only incidentally for machines to execute.”

Bonus round: named closure

Before hitting “Publish”, I discussed that observation with a friend unfamiliar with Rust, and he thought it might be interesting to check if there was any difference between using a closure directly in the argument, as previously, and using a named closure, i.e., assigning the closure to a variable and passing it to map, like this:

fn main() {
    let double = |x| 2 * x;
    let v = vec!(1, 2, 3);
    let w = v.into_iter().map(double);
    // Make sure the result isn't optimised away
    println!("{:?}", w.collect::<Vec<i32>>());
}

Since both the Rust compiler and LLVM (the compiler infrastructure that powers the compiler) are smart, the intermediate variable is optimises away, generating exactly the same code for this version as it did for the one with an anonymous closure.

Update

Jake Goulding noticed I goofed up and used the nightly release of the compiler instead of the stable release I meant to use. I recompiled the examples with the current stable rustc 1.3.0 (9a92aaf19 2015-09-15) and generated a new diff. As you can see in this diff, the extra allocation is optimised away, just like it should. I apologize for the mistake. Thank you, Jake!

Bleeding hearts and sharp bits

2014-04-09T00:00:00-05:00

If you can’t dance, don’t blame the dance floor.

Heartbleed, as you’ve probably read by now, is a serious security issue resulting from a bug in OpenSSL which allows an attacker to freely read the memory of the affected servers. Serious 💩, indeed.

Some people were quick to point their fingers at the language used for implementation of the SSL standard in the OpenSSL project—that is to say, C—and are clamoring for a new implementation in what they deem a safer language, such as Rust and Go.

Now, C is an old language and in many aspects it’s little more than assembly language dressed up. It has sharp edges and people cut themselves on those very often — dealing explicitly with memory allocation and pointers is prone to error, even for experienced programmers. I agree that having to deal with all the minutiae is cumbersome and usually unnecessary in the modern day. However, I believe the problem isn’t so much that the language allows you to shoot yourself in the foot but that many programmers are careless.

Let’s have a look at the code before the fix:

int
dtls1_process_heartbeat(SSL *s)
    {
    unsigned char *p = &s->s3->rrec.data[0], *pl;
    unsigned short hbtype;
    unsigned int payload;
    unsigned int padding = 16; /* Use minimum padding */

Rather boring variable declaration, although the names could be better (what kind of mischievous monster names a length variable payload?).

That SSL type is rather opaque, but following the trail, one ends up with this structure:

typedef struct ssl3_record_st
    {
        int type;               /* type of record */
        unsigned int length;    /* How many bytes available */
        unsigned int off;       /* read/write offset into 'buf' */
        unsigned char *data;    /* pointer to the record data */
        unsigned char *input;   /* where the decode bytes are */
        unsigned char *comp;    /* only used with decompression - malloc()ed */
        unsigned long epoch;    /* epoch number, needed by DTLS1 */
        unsigned char seq_num[8]; /* sequence number, needed by DTLS1 */
    } SSL3_RECORD;

Anyway, the argument s is read as a SSL3 record and char p is left pointing to s’s data. So far, nothing unusual or interesting. Onwards!

/* Read type and payload length first */
hbtype = *p++;
n2s(p, payload);
pl = p;

Ok, let’s go through this slowly.

p is of type char, so they’re jumping over the first byte and copying the first two bytes to hbtype (which is a short). This is because the heartbeat extension sticks this stuff into the data portion of SSL3_RECORD, so some gymnastics is needed to access it.

n2s and s2n are defined in ssl/ssl_locl.h as follows:

#define n2s(c,s)	((s=(((unsigned int)(c[0]))<< 8)| \
			    (((unsigned int)(c[1]))    )),c+=2)
#define s2n(s,c)	((c[0]=(unsigned char)(((s)>> 8)&0xff), \
			  c[1]=(unsigned char)(((s)    )&0xff)),c+=2)

n2s is supposed to read two chars and return them inside an integer (or anything with at least 2 bytes). What it actually does is read two of whatever the c pointer says its size is and return the result of arithmetical OR between them. A pedantic detail but dangerous if misused. I suppose strong type checking could be useful here to prevent mistakes.

s2n is similar but does the opposite—dump two chars into an integer.

So, we read a couple of bytes, convert them to a short and assign that to payload, which is the payload length.

Then pl is changed to point to the payload data, including the two bytes indicating its supposed length.

What’s becomes apparent if you’re following the code carefully is that the heartbeat payload length hasn’t been checked for validity yet and, as we’ll later see, isn’t before it’s used. This is probably the most common kind of error in C, which makes it somewhat more appalling because it should be at the forefront of the programmer’s mental checks.

Later on, there’s this:

if (hbtype == TLS1_HB_REQUEST)
        {
        unsigned char *buffer, *bp;
        int r;

        /* Allocate memory for the response, size is 1 bytes
         * message type, plus 2 bytes payload length, plus
         * payload, plus padding
         */
        buffer = OPENSSL_malloc(1 + 2 + payload + padding);
        bp = buffer;

        /* Enter response type, length and copy payload */
        *bp++ = TLS1_HB_RESPONSE;
        s2n(payload, bp);
        memcpy(bp, pl, payload);
        bp += payload;

First a buffer for the response is allocated, then a region of memory is copied. Both their sizes depend on the payload length received earlier and it wasn’t bound-checked!

This allows an attacker to send a heartbeat with an arbitrary payload length (up to 64KB (2¹⁶ bytes) of memory) and a much smaller payload body, leading to reads beyond the SSL record. 64KB seems small but it’s enough to get SSL certificates, passwords, cookies, whatever is reachable.

I’m not entirely sure that this mistake is of the sort that a cleverer language would catch, since it’s likely that the memcpy will happen within the application’s memory. If it tried to reach outside, the kernel would take notice and kill it with a Segmentation Fault, turning this issue into a less threatening program termination bug.

I know I shouldn’t be surprised at how trusting most programmers are about user input, but these people are programming a cryptography library. They should know better. Scratch that, everyone trusts them to know better and to be paranoid. To say I’m disappointed is putting it lightly.

While I agree that it would benefit everyone if a safer language was used for this sort of software, I do not agree that the blame lies entirely with C. Careless mistakes can happen with any language. The language used may reduce the likelihood that a mistake comes up in places with serious consequences but vigilance is absolutely essential.

Reboot

2014-01-14T00:00:00-06:00

New layout, new almost everything.

This was mostly an excuse to start over and play with HTML5 and CSS. Nothing too fancy and somewhat responsive.

Since I tend to make parenthetical comments, I played a little with the aside tag, mostly in conjunction with CSS flexboxes for ease of positioning and responsive design. While they worked well in Chrome (both desktop and mobile), I ran into some issues in other browsers.

At the time of writing, the state of flexbox support across browsers isn’t very encouraging: most browsers support some version of flexbox but Chrome is the only one whose current (and most popular) version has support for the latest working draft, while Firefox has a sadly incomplete implementation even in the latest beta (27.0 at the time of writing). I guess I will have to wait some more time or come up with alternative solutions.

The current version of this blog makes use of the following code:

RSS and Atom templates courtesy of Dave Coyle.
Sitemap by Toni Uebernickel

Ricardo Martins

Convenient and idiomatic conversions in Rust

Key takeaways

Introduction

From and Into

Example: SortedVec<T>

Example: PacketType

What about the opposite conversion?

“Do or do not; there is no Try”

AsRef and AsMut

Closing thoughts

Interior mutability in Rust, part 3: behind the curtain

Key takeaways

Introduction

What is UnsafeCell?

Raw pointers

✨ A dash of magic ✨

How is it used?

Cell

RefCell

RwLock and Mutex

Wrapping up

Interior mutability in Rust, part 2: thread safety

Key takeaways

Introduction

Thread-safe interior mutability

For Copy values

For non-Copy values

Reference counting

Closing thoughts

Interior mutability in Rust: what, why, how?

Key takeaways

Introduction

What?

How?

Why?

Introducing mutability inside of something immutable

Mutating implementations of Clone

Implementation details of logically immutable methods

Mutating reference-counted variables

Which to pick?

Wrapping up

Practical differences between Rust closures and functions

Function

Closure

Bonus round: named closure

Update

Bleeding hearts and sharp bits

Reboot

`From` and `Into`

Example: `SortedVec<T>`

Example: `PacketType`

“Do or do not; there is no `Try`”

`AsRef` and `AsMut`

What is `UnsafeCell`?

`Cell`

`RefCell`

`RwLock` and `Mutex`

For `Copy` values

Mutating implementations of `Clone`