Smart pointers

let b = Box::new(String::from("abc"));
let n = b.len();               // method of String, called on a Box<String>
let s: &str = &b;              // &Box<String> becomes &String then &str

Deref says "I can be seen as a reference to Target". The compiler then inserts the conversions by itself (deref coercion), as many times as needed.

use std::ops::Deref;

struct Wrapper<T> {
    value: T,
    reads: std::cell::Cell<u32>,
}

impl<T> Deref for Wrapper<T> {
    type Target = T;
    fn deref(&self) -> &T {
        self.reads.set(self.reads.get() + 1);
        &self.value
    }
}

let w = Wrapper { value: vec![1, 2, 3], reads: std::cell::Cell::new(0) };
println!("{}", w.len());       // method of Vec

DerefMut does the same for &mut.

struct Connection { name: String }

impl Drop for Connection {
    fn drop(&mut self) {
        println!("closing {}", self.name);
    }
}

fn main() {
    let _c = Connection { name: "database".into() };
    println!("working");
}
// working
// closing database

drop is called automatically when the value goes out of scope, even if the program panics (stack unwinding). It is used to release what Rust does not know about: file, lock, connection, temporary file, counter to decrement.

struct Name(&'static str);
impl Drop for Name {
    fn drop(&mut self) { println!("drop {}", self.0); }
}

struct Pair { a: Name, b: Name }

fn main() {
    let _x = Name("x");
    let _y = Name("y");
    let _p = Pair { a: Name("a"), b: Name("b") };
}
// drop a, drop b      (fields: declaration order, after the drop of Pair itself)
// drop y, drop x      (variables: reverse declaration order)

let c = Connection { name: "database".into() };
// c.drop();               // ERROR E0040: explicit use of destructor method
drop(c);                   // OK: std::mem::drop takes the value

You cannot call the drop method yourself (it would be called again at the end of the block, so two drops). drop(c) moves c into an empty function that frees it.

use std::sync::Mutex;

let m = Mutex::new(0);
{
    let mut guard = m.lock().unwrap();   // lock taken
    *guard += 1;
}                                        // guard dropped: lock released

let mut guard = m.lock().unwrap();
*guard += 1;
drop(guard);                             // release before a long operation
// long_operation();

The lock of a Mutex is a MutexGuard whose Drop releases the lock. Keeping a guard longer than necessary blocks all the other threads.

struct OnExit<F: FnMut()>(F);

impl<F: FnMut()> Drop for OnExit<F> {
    fn drop(&mut self) { (self.0)(); }
}

fn process(fail: bool) -> Result<(), String> {
    let _cleanup = OnExit(|| println!("temporary file removed"));
    if fail {
        return Err("failure in the middle".into());   // the cleanup runs anyway
    }
    Ok(())
}

let a = String::from("shared");
let list1 = vec![a];
// let list2 = vec![a];      // ERROR: a has already been moved

Sometimes a value must belong to several structures at once (a node referenced by several parents, a configuration shared by several components).

use std::rc::Rc;

let a = Rc::new(String::from("shared"));
let b = Rc::clone(&a);         // same String, counter at 2
let c = a.clone();             // same thing, shorter to write
println!("{}", Rc::strong_count(&a));   // 3
drop(b);
println!("{}", Rc::strong_count(&a));   // 2
// the String is freed when the last Rc disappears

Rc::clone does not copy the value: it increments a counter. Rc::clone(&a) is preferred to a.clone() in most code, so that it is obvious at first glance that this is not an expensive copy.

let r = Rc::new(vec![1, 2]);
// r.push(3);                 // ERROR: cannot borrow data in an `Rc` as mutable

Several owners that could all modify: this is exactly what the borrowing rules forbid. To modify, you need interior mutability (section 8).

let r = Rc::new(String::from("x"));
match Rc::try_unwrap(r) {
    Ok(s) => println!("sole owner: {s}"),     // possible if the counter is 1
    Err(r) => println!("still shared"),
}

use std::sync::Arc;
use std::thread;

let config = Arc::new(vec!["a", "b"]);
let mut handles = Vec::new();
for i in 0..3 {
    let c = Arc::clone(&config);
    handles.push(thread::spawn(move || println!("{i}: {:?}", c)));
}
for h in handles {
    h.join().unwrap();
}

use std::cell::Cell;

struct Counter {
    calls: Cell<u32>,
}

impl Counter {
    fn count(&self) {                        // &self, not &mut self
        self.calls.set(self.calls.get() + 1);
    }
}

let c = Counter { calls: Cell::new(0) };
c.count();
c.count();
println!("{}", c.calls.get());   // 2

use std::cell::RefCell;

let v = RefCell::new(vec![1, 2]);
v.borrow_mut().push(3);                  // temporary mutable borrow
println!("{:?}", v.borrow());            // temporary shared borrow

RefCell applies the same borrowing rules (one write or several reads), but at runtime instead of compile time.

let v = RefCell::new(vec![1]);
let read = v.borrow();
// let write = v.borrow_mut();       // PANIC: already borrowed: BorrowMutError
drop(read);
let write = v.borrow_mut();           // OK

match v.try_borrow_mut() {
    Ok(mut w) => w.push(4),
    Err(_) => println!("already borrowed elsewhere"),
}

let data = RefCell::new(vec![1, 2, 3]);

// Risky: the borrow lives for the whole block
{
    let read = data.borrow();
    for x in read.iter() {
        // data.borrow_mut().push(*x);   // panics
    }
}

// Safe: copy what you need, then release
let copy: Vec<i32> = data.borrow().clone();
for x in copy {
    data.borrow_mut().push(x);
}

The borrows of RefCell (Ref, RefMut) are released at the end of their scope, like a lock.

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

#[derive(Debug)]
struct Account { balance: i64 }

let account = Rc::new(RefCell::new(Account { balance: 100 }));
let holder = Rc::clone(&account);
let bank = Rc::clone(&account);

holder.borrow_mut().balance -= 30;
bank.borrow_mut().balance += 5;
println!("{:?}", account.borrow());      // Account { balance: 75 }

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

struct Node {
    next: RefCell<Option<Rc<Node>>>,
}

let a = Rc::new(Node { next: RefCell::new(None) });
let b = Rc::new(Node { next: RefCell::new(Some(Rc::clone(&a))) });
*a.next.borrow_mut() = Some(Rc::clone(&b));    // a -> b -> a
// at the end of the block, each counter stays at 1: neither is ever freed

Rust prevents invalid accesses, not leaks: a cycle of Rc is safe but never frees its memory.

use std::rc::{Rc, Weak};

let strong = Rc::new(5);
let weak: Weak<i32> = Rc::downgrade(&strong);

println!("{:?}", weak.upgrade());   // Some(5): the value still exists
drop(strong);
println!("{:?}", weak.upgrade());   // None: freed

A Weak does not count toward freeing. upgrade() returns an Rc if the value still exists, None otherwise.

use std::cell::RefCell;
use std::rc::{Rc, Weak};

#[derive(Debug)]
struct Node {
    value: i32,
    parent: RefCell<Weak<Node>>,          // weak: the child does not retain the parent
    children: RefCell<Vec<Rc<Node>>>,     // strong: the parent retains its children
}

let leaf = Rc::new(Node { value: 3, parent: RefCell::new(Weak::new()), children: RefCell::new(vec![]) });
let branch = Rc::new(Node {
    value: 5,
    parent: RefCell::new(Weak::new()),
    children: RefCell::new(vec![Rc::clone(&leaf)]),
});
*leaf.parent.borrow_mut() = Rc::downgrade(&branch);

let parent = leaf.parent.borrow().upgrade().map(|p| p.value);   // Some(5)

Rule: links that go downward (owner → owned) are strong, those that go back up are weak.

use std::collections::HashMap;
use std::sync::{LazyLock, OnceLock};

// 1. LazyLock (Rust 1.80+): the initialisation function is given at the declaration
static COUNTRIES: LazyLock<HashMap<&str, &str>> = LazyLock::new(|| {
    HashMap::from([("fr", "France"), ("be", "Belgium")])
});

// 2. OnceLock: the value is set later, only once
static CONFIG: OnceLock<String> = OnceLock::new();

fn init(url: String) {
    CONFIG.set(url).expect("configuration already initialised");
}

fn config() -> &'static str {
    CONFIG.get().map(String::as_str).unwrap_or("not configured")
}

// 3. OnceLock with get_or_init: computed on first request, from anywhere
fn email_regex() -> &'static regex::Regex {
    static R: OnceLock<regex::Regex> = OnceLock::new();
    R.get_or_init(|| regex::Regex::new(r"^[^@\s]+@[^@\s]+$").unwrap())
}

fn main() {
    println!("{}", COUNTRIES["fr"]);
    init("postgres://...".into());
    println!("{}", config());
}

These types replace the lazy_static and once_cell crates in recent code.

use std::cell::OnceCell;

struct Document {
    text: String,
    word_count: OnceCell<usize>,          // computed on first request, then kept
}

impl Document {
    fn word_count(&self) -> usize {
        *self.word_count.get_or_init(|| self.text.split_whitespace().count())
    }
}

use std::rc::Rc;

let mut a = Rc::new(vec![1, 2, 3]);
let b = Rc::clone(&a);

Rc::make_mut(&mut a).push(4);      // a is shared: the value is COPIED then modified
println!("{:?} {:?}", a, b);       // [1, 2, 3, 4] [1, 2, 3]

Rc::make_mut(&mut a).push(5);      // a is now alone: modified in place, no copy

use std::cell::RefCell;
use std::collections::HashMap;
use std::rc::{Rc, Weak};

// 1. Rc + RefCell + Weak: pointers between nodes
struct User1 {
    name: String,
    follows: RefCell<Vec<Weak<User1>>>,
}

// 2. Indexes in a Vec: a single owner, numbers as links
struct Network2 {
    names: Vec<String>,
    follows: Vec<Vec<usize>>,          // follows[i] = indexes of the people followed by i
}

impl Network2 {
    fn add(&mut self, name: &str) -> usize {
        self.names.push(name.to_string());
        self.follows.push(Vec::new());
        self.names.len() - 1
    }
    fn follow(&mut self, who: usize, target: usize) {
        self.follows[who].push(target);
    }
}

// 3. Identifiers in a HashMap: like in a database
struct Network3 {
    users: HashMap<u64, String>,
    follows: HashMap<u64, Vec<u64>>,
}

impl Drop for T { fn drop(&mut self) { .. } }     drop(x)
impl Deref for T { type Target = U; fn deref(&self) -> &U { .. } }

Rc::new(v)   Rc::clone(&r)   Rc::strong_count(&r)   Rc::downgrade(&r)   Rc::try_unwrap(r)   Rc::make_mut(&mut r)
Arc::new(v)  Arc::clone(&a)
weak.upgrade()                                     // Option<Rc<T>>
Cell::new(v)   c.get()   c.set(v)   c.replace(v)   c.take()
RefCell::new(v)   r.borrow()   r.borrow_mut()   r.try_borrow_mut()
OnceLock::new()   o.set(v)   o.get()   o.get_or_init(|| v)
static X: LazyLock<T> = LazyLock::new(|| v);