Forem: Olivia

🕰️ Async Basics in Rustlang

Olivia — Fri, 14 Nov 2025 08:39:52 +0000

Async Rust has a reputation for being complex. You've probably encountered intimidating terms like Send, Sync, Future, Pin, and tokio. The terminology can feel overwhelming, but the core concepts are more straightforward than they appear. Understanding async programming in Rust is crucial for building performant applications that handle I/O operations efficiently - whether you're building web servers, database clients, or any application that needs to wait for external resources.

In this guide, we'll demystify async/await by building a practical example: a student transcript generator. Along the way, you'll learn what Futures really are, why traits like Send and Sync matter for thread safety, and the critical difference between concurrency and parallelism. We'll progress from blocking code to async implementations, exploring the trade-offs and design patterns that make async Rust powerful.

Here's a preview of the transformation we'll make - converting blocking, sequential code into concurrent async operations:

// Before: One transcript at a time (blocking)
fn generate_transcript_sync(student_id: u32) -> String {
    // Fetch courses, calculate GPA, format PDF
    std::thread::sleep(Duration::from_secs(3));
    format!("Transcript for Student {}: 3.8 GPA, 120 credits", student_id)
}

// After: Many transcripts at once (async)
async fn generate_transcript_async(student_id: u32) -> String {
    tokio::time::sleep(Duration::from_secs(3)).await;
    format!("Transcript for Student {}: 3.8 GPA, 120 credits", student_id)
}

The Problem with Blocking Code

To understand why async matters, let's first look at what happens when we use traditional blocking code. Imagine a university system where students request their academic transcripts. Each transcript generation involves several time-consuming steps: fetching data from a database, calculating GPAs, formatting PDFs, and saving files to disk.

Let's see what happens when 3 students request transcripts using traditional blocking code:

fn generate_transcripts_blocking() {
    let start = Instant::now();

    let transcript1 = generate_transcript_sync(101);
    let transcript2 = generate_transcript_sync(102);
    let transcript3 = generate_transcript_sync(103);

    println!("Total time: {:?}", start.elapsed());
    // Output: Total time: ~9 seconds (3s × 3)
}

This code has two major problems. First, everything executes sequentially - each student must wait for all previous transcripts to finish before theirs even begins. Second, if this code ran on an application's main thread, the UI would freeze for the entire 9 seconds while the thread sits idle, waiting.

What's Really Happening During Transcript Generation?

Behind the scenes, generating a transcript involves multiple distinct operations:

Network I/O: Call an API over the network to fetch the student's data
CPU work: Calculate averages and totals based on that data
File I/O: Generate a PDF in memory
Disk I/O: Save the PDF file to storage
More network I/O: Perhaps verify data with external services

Here's the key insight: not all of those 3 seconds represent actual computational work. Much of that time is spent waiting - waiting for network responses, waiting for disk writes, waiting for database queries. While we're waiting for one task's I/O operations to complete, we could be making progress on another task. This is where async shines.

The Async Solution

Now let's see the async version that handles all three transcripts concurrently:

async fn generate_transcripts_async() {
    let start = Instant::now();

    let (transcript1, transcript2, transcript3) = tokio::join!(
        generate_transcript_async(101),
        generate_transcript_async(102),
        generate_transcript_async(103)
    );

    println!("Total time: {:?}", start.elapsed());
    // Output: Total time: ~3 seconds (all run together!)
}

The transformation is dramatic: instead of 9 seconds (3 tasks × 3 seconds each), all three transcripts complete in approximately 3 seconds total. The tokio::join! macro runs all three futures concurrently, switching between them whenever one is waiting for I/O. This is concurrency in action - making progress on multiple tasks by efficiently utilizing wait time.

When to use this approach:

I/O-bound operations (network calls, file operations, database queries)
Applications that need to handle many simultaneous requests
Situations where tasks spend significant time waiting rather than computing

Understanding Futures: The Foundation of Async

When you write async fn in Rust, you're not creating a function that executes immediately. Instead, you're creating a function that returns a Future - a value that represents a computation that may not be ready yet but will complete at some point in the future. This is a fundamentally different model than synchronous programming, and understanding it is crucial to working effectively with async Rust.

Futures Are Lazy

One of the most important characteristics of Futures is that they are lazy - they do absolutely nothing until you explicitly ask them to run by calling .await:

// This doesn't run immediately! Just creates the future
let future = generate_transcript_async(101);

// At this point, nothing has happened yet. No database calls, no network requests.

// This starts execution and waits for completion
let result = future.await;

This lazy evaluation is a feature, not a bug. It allows you to compose futures together, pass them around, and decide exactly when and how to execute them. It also enables powerful combinators like join!, select!, and try_join! that can coordinate multiple futures efficiently.

Futures as State Machines

Behind the scenes, Rust compiles your async function into a state machine that can be paused at each .await point and resumed later. This is what enables cooperative multitasking - the runtime can switch between different tasks at well-defined suspension points.

The Future trait is the core abstraction that makes this possible:

pub trait Future {
    type Output;

    // Required method
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

pub enum Poll<T> {
    Ready(T),
    Pending,
}

When the runtime wants to make progress on a future, it calls the poll method. The future can respond in one of two ways:

Poll::Ready(T): The future has finished running and here's the output value
Poll::Pending: The future is still executing, check back later

This polling mechanism is what allows the runtime to efficiently schedule thousands of concurrent tasks. Each task is polled, makes some progress, and then either completes or yields control back to the runtime.

Thread Safety: Send and Sync

Async Rust introduces an additional layer of complexity because futures often need to move between threads. The async runtime might start executing your future on one thread, pause it, and then resume it on a completely different thread. This is where the Send and Sync traits become critical.

The Send Trait: Safe to Move Between Threads

Let's explore what happens when we try to return different types from async functions. This simple example works perfectly:

struct Transcript {
    student_name: String,
    courses: Vec<String>,
    gpa: f64,
}

async fn generate_full_transcript(student_id: u32) -> Transcript {
    let name = fetch_student_name(student_id).await;
    let courses = fetch_course_history(student_id).await;
    let gpa = calculate_gpa(student_id).await;

    Transcript { student_name: name, courses, gpa }
}

This works because String and Vec<String> both implement Send, which means they can be safely moved between threads. The async runtime can pause this future on one thread and resume it on another without any safety issues.

Now let's see what happens when we try to use Rc<String>, a reference-counted pointer that is explicitly not thread-safe:

use std::rc::Rc;

struct BadTranscript {
    student_name: Rc<String>, // ❌ Not Send!
    courses: Vec<String>,
}

// This won't compile:
async fn bad_generate_transcript(student_id: u32) -> BadTranscript {
    // Error: `Rc<String>` cannot be sent between threads safely
}

The compiler stops us dead in our tracks. Why? Because Rc<String> doesn't implement Send. Its reference counting is not thread-safe - multiple threads modifying the count concurrently would cause data races. Since BadTranscript contains an Rc<String>, it also doesn't implement Send, which means the async runtime cannot safely move this value between threads.

This is why the Send trait is crucial: it prevents thread safety bugs at compile time.

If you need a reference-counted pointer in async code, use Arc<String> (Atomic Reference Counted) instead, which implements Send because it uses atomic operations for thread-safe reference counting.

When to use Send-aware types:

Use Arc instead of Rc for shared ownership in async code
Use Mutex or RwLock from tokio::sync instead of std::sync for async-aware locking
Most standard types like String, Vec, and primitives are automatically Send

The Sync Trait: Safe to Share References

While Send is about moving values between threads, Sync is about sharing references between threads. A type T is Sync if &T (a reference to T) is Send - meaning it's safe to share references to that type across threads.

The relationship between Send and Sync is important: a type cannot be Sync unless it's also Send. This makes logical sense - you can't safely share references to something that can't be moved between threads in the first place.

The good news is that most types automatically implement both Send and Sync. Rust's compiler derives these traits for your types when it's safe to do so. In practice, for typical async code, you'll find that things "just work" most of the time:

struct StudentDatabase {
    students: HashMap<u32, String>, // Send + Sync ✅
}

// This works - we can share references safely
async fn lookup_student(db: &StudentDatabase, id: u32) -> Option<&String> {
    db.students.get(&id)
}

Because HashMap<u32, String> is both Send and Sync, our StudentDatabase is too. We can safely pass references to it across async boundaries without any compiler complaints.

The Async Runtime: Executing Futures

There's a crucial piece we haven't discussed yet: how do futures actually run? Unlike synchronous code that executes immediately when called, futures need something to drive their execution. This is the job of the async runtime.

The runtime is responsible for:

Polling futures: Repeatedly calling poll() on futures to make progress
Task scheduling: Deciding which futures to work on and when
I/O management: Handling network sockets, file operations, and timers
Thread pool management: Distributing work across CPU cores efficiently

The most popular runtime in the Rust ecosystem is Tokio, though alternatives like async-std and smol exist. Let's look at two ways to set up a runtime:

Setting Up a Tokio Runtime

First, add Tokio to your Cargo.toml:

[dependencies]
tokio = { version = "1", features = ["full"] }

Now you can create a runtime in two ways:

// Approach 1: Sync main with explicit runtime
fn main() {
    tokio::runtime::Runtime::new()
        .unwrap()
        .block_on(async {
            generate_transcript_async(101).await;
        });
}

// Approach 2: Async main with equivalent implicit runtime
#[tokio::main]
async fn main() {
    generate_transcript_async(101).await;
}

Both approaches create the same runtime behind the scenes. The #[tokio::main] attribute is syntactic sugar that expands to the explicit runtime creation shown in Approach 1. Most Rust developers prefer the cleaner syntax of Approach 2.

Cooperative Multitasking: The .await Discipline

A critical aspect of async Rust is that it uses cooperative multitasking. The runtime can only switch between tasks at .await points - it cannot preemptively interrupt a running task like an operating system can with threads.

This has an important implication: if a task never yields control (never hits an .await), it can block the entire runtime. Consider this problematic code:

async fn bad_cpu_intensive_work() {
    // This blocks the entire runtime!
    for i in 0..1_000_000_000 {
        // CPU-intensive work with no .await
    }
}

This task monopolizes the runtime thread, preventing other tasks from making progress. For CPU-intensive work, use threads or spawn blocking tasks with tokio::task::spawn_blocking.

Choosing the Right Tool: Async vs Threads

One of the most common questions when learning async Rust is: "When should I use async, and when should I use threads?" The answer lies in understanding the type of work you're doing.

Use Async for I/O-Bound Work

Async shines when your code spends most of its time waiting for external resources. This includes:

// Perfect for async: Waiting for external services
async fn verify_degree() {
    let transcript = fetch_from_database().await;  // I/O bound - database query
    let verification = call_external_api().await;  // I/O bound - network call
    generate_pdf(transcript).await;                // I/O bound - file operations
}

Why async is ideal here:

Tasks spend most of their time waiting for I/O
Can handle thousands of concurrent operations efficiently
Low memory overhead per task (compared to threads)
Excellent for web servers, API clients, database connections

Use Threads for CPU-Bound Work

When your code is doing heavy computation rather than waiting, threads are the better choice:

// Better with threads: CPU-intensive work
fn calculate_class_gpa(grades: Vec<f64>) -> f64 {
    grades.iter().sum::<f64>() / grades.len() as f64  // CPU bound
}

// For parallel CPU work, use rayon or spawn threads:
use rayon::prelude::*;

fn process_all_students(students: Vec<Student>) -> Vec<f64> {
    students.par_iter()  // Parallel iterator using thread pool
        .map(|s| calculate_complex_gpa(s))
        .collect()
}

Why threads are ideal here:

Actual CPU parallelism across multiple cores
No need for cooperative yielding
Better utilization of available CPU resources
Simpler mental model for compute-heavy tasks

Decision Guide

Here's a quick reference to help you choose:

Scenario	Use	Why
HTTP server handling many requests	Async	I/O-bound, need to handle thousands of concurrent connections efficiently
Database query aggregating millions of rows	Threads	CPU-bound computation, benefits from true parallelism
File system operations (reading/writing)	Async	I/O-bound, waiting for disk operations
Image processing or video encoding	Threads	CPU-intensive computation requiring all available cores
WebSocket server with many clients	Async	I/O-bound, mostly waiting for messages over network
Scientific computation or data analysis	Threads	CPU-bound mathematical operations
Making multiple API calls simultaneously	Async	I/O-bound, waiting for network responses

Key insight: Async provides concurrency (managing many tasks by switching between them during wait times), while threads provide parallelism (actually running multiple tasks simultaneously on different CPU cores). Choose async when you're waiting, choose threads when you're computing.

Conclusion

We've journeyed from blocking, sequential code to concurrent async operations, exploring the fundamental concepts that make async Rust powerful:

Futures as lazy state machines: They do nothing until you .await them, enabling flexible composition and efficient execution
The polling model: Futures return Poll::Ready when complete or Poll::Pending when they need more time, allowing the runtime to efficiently schedule work
Thread safety through Send and Sync: These traits ensure that values can be safely moved between threads and references can be shared, preventing data races at compile time
Async runtime orchestration: The runtime manages polling, scheduling, and I/O, providing the infrastructure that makes async code run
Cooperative multitasking discipline: Tasks yield at .await points, requiring careful consideration to avoid blocking the runtime

Async Rust might seem intimidating at first with its unfamiliar terminology and concepts. However, each piece serves a clear purpose: ensuring memory safety and thread safety while providing excellent performance for I/O-bound operations. The type system guides you toward correct concurrent code, catching potential bugs at compile time rather than at runtime.

Remember: start with async for I/O-heavy workloads like web servers and API clients. Use threads when you need true CPU parallelism for computation. Most importantly, let the compiler be your guide - when you encounter a Send or Sync error, it's catching a real concurrency issue before it becomes a bug.

Want to get better at Rust, 1% at a time? I send out a Rust fundamentals thread every Thursday - clear, practical examples, and beginner-friendly.

👉 Join the newsletter here

Error Handling in Rust: From Panic to anyhow and thiserror

Olivia — Fri, 31 Oct 2025 08:32:35 +0000

Error Handling in Rust: From Panic to anyhow and thiserror

Error handling in Rust can be a complex topic, especially for developers coming from languages with different error handling paradigms. Unlike languages that rely on exceptions, Rust provides several approaches to handling errors: from basic patterns like panic!, boolean returns, and Option types, to more sophisticated solutions using the Result enum, custom error types, and specialized crates like thiserror and anyhow.

In this comprehensive guide, we'll walk through the evolution of error handling in Rust, starting with simple approaches and progressively building up to production-ready patterns. By the end, you'll understand when to use each approach and how to implement robust error handling in your Rust applications.

Here's a preview of what we'll be building - a custom error type using thiserror that integrates seamlessly with anyhow:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum EnrollmentError {
    #[error("Invalid student name (expected non-empty, got {found:?})")]
    InvalidStudentName { found: String },
    #[error("Invalid course name (expected non-empty, got {found:?})")]
    InvalidCourseName { found: String },
    #[error("Student {student_id} is already enrolled in course {course_id}")]
    DuplicateEnrollment { student_id: u32, course_id: u32 },
}

The Example: A University Database

Throughout this guide, we'll use a practical example: a university database system that manages students, courses, and enrollments. This example provides realistic scenarios where different error handling approaches make sense.

Let's start by defining our base data structures:

use std::collections::HashMap;

pub struct Student {
    pub id: u32,
    pub name: String,
}

pub struct Course {
    pub id: u32,
    pub name: String,
}

pub struct Database {
    students: Vec<Student>,
    courses: Vec<Course>,
    // student_id -> course_ids
    enrollments: HashMap<u32, Vec<u32>>,
}

impl Database {
    pub fn new() -> Self {
        Database {
            students: Vec::new(),
            courses: Vec::new(),
            enrollments: HashMap::new(),
        }
    }
}

We have a Student and Course struct, each with an ID and name. The Database struct manages collections of students and courses, plus a HashMap tracking which students are enrolled in which courses.

Evolution from Panic to Result

Now let's explore three different approaches to handling errors when adding a student to our database. Each approach has its trade-offs, and understanding them will help you choose the right pattern for your use case.

Approach 1: Using panic! (Not Recommended for Most Cases)

The simplest but most aggressive approach is to use panic! when something goes wrong. When a panic occurs, the program crashes immediately:

pub fn add_student(&mut self, id: u32, name: String) {
    if self.students.iter().any(|s| s.id == id) {
        panic!("Student with id {} already exists", id);
    }

    let student = Student::new(id, name);
    self.students.push(student);
}

pub fn demonstrate() {
    let mut db = Database::new();
    db.add_student(1, "Alice".to_string());
    db.add_student(1, "Bob".to_string()); // This will panic
}
// OUTPUT
// Adding new student 1 Alice
// Student with id 1 added
// Adding new student 1 Bob

// thread 'main' panicked at src/main.rs:42:17:
// Student with id 1 already exists

Problems with this approach:

The entire program crashes on a recoverable error
No way for the caller to handle the error gracefully
Makes testing difficult since panics terminate the test
Not suitable for long-running services or applications

When to use it: Only for truly unrecoverable errors or during initial prototyping.

Approach 2: Returning Boolean Values

pub fn add_student(&mut self, id: u32, name: String) -> bool {
    println!("Adding new student {id} {name}");
    if self.students.iter().any(|s| s.id == id) {
        println!("Student with id {} already exists", id);
        return false;
    }

    let student = Student::new(id, name);
    self.students.push(student);
    return true;
}

pub fn demonstrate() {
    let mut db = Database::new();
    let added_alice = db.add_student(1, "Alice".to_string());
    let added_bob = db.add_student(1, "Bob".to_string());
    println!("Alice {}, Bob {}", added_alice, added_bob);
}
// OUTPUT
// Adding new student 1 Alice
// Adding new student 1 Bob
// Student with id 1 already exists
// Alice true, Bob false

Improvements:

The program doesn't crash
Caller can check if the operation succeeded
Suitable for simple success/failure scenarios

Problems:

No information about why it failed
Caller must log or handle errors separately
Not composable with Rust's ? operator

When to use it: Simple cases where you only need to know success/failure and the context is obvious.

Approach 3: Using Result for Detailed Error Information

This is Rust's recommended approach. The Result type allows you to return either a success value or detailed error information:

pub fn add_student(&mut self, id: u32, name: String) -> Result<Student, String> {
    println!("Adding new student {id} {name}");

    if self.students.iter().any(|s| s.id == id) {
        return Err(format!("Student with id {} already exists", id));
    }

    let student = Student::new(id, name);
    self.students.push(student.clone());
    return Ok(student);
}

pub fn demonstrate() {
    let mut db = Database::new();
    let result_1 = db.add_student(1, "Alice".to_string());
    let result_2 = db.add_student(1, "Bob".to_string());
    println!("{:?}", result_1);
    println!("{:?}", result_2);
}
// OUTPUT
// Adding new student 1 Alice
// Adding new student 1 Bob
// Ok(Student { id: 1, name: "Alice" })
// Err("Student with id 1 already exists")

Improvements:

Provides detailed error information to the caller
Works with Rust's ? operator for error propagation
Can be pattern matched for different error cases
Industry standard approach in Rust

Remaining limitations:

Using String for errors is not ideal (we'll improve this next)
No structured error types for programmatic handling

This Result approach is solid, but we can make it even better with specialized error handling crates.

Improving Error Handling with anyhow

The anyhow crate is designed for application code where you want excellent error messages and easy error propagation. Let's see how it improves our error handling.

Basic anyhow Usage

First, add anyhow to your Cargo.toml:

[dependencies]
anyhow = "1.0"

Now let's refactor our code to use anyhow::Result instead of Result<Student, String>:

use anyhow::Result;

pub fn add_student(&mut self, id: u32, name: String) -> Result<Student> {
    println!("Adding new student {id} {name}");

    if self.students.iter().any(|s| s.id == id) {
        return Err(anyhow::anyhow!("Student with id {} already exists", id));
    }

    let student = Student::new(id, name);
    self.students.push(student.clone());
    return Ok(student);
}

Why is this better?

Type flexibility: anyhow::Result can hold any error type, not just String
Better traits: Automatic implementation of Display, Debug, and other error traits
Composability: Can return different error types from the same function
Rich features: Sets us up to use anyhow's powerful context and chaining features

The real power of anyhow comes from its ability to add context to errors as they propagate up the call stack.

Adding Context with anyhow

One of anyhow's best features is the .context() method, which allows you to add contextual information as errors bubble up through your code. This is incredibly valuable for debugging complex systems.

Let's add input validation to our student addition function. First, we'll create a helper function to validate names:

We need to import the Context trait to use the .context() method:

use anyhow::{Result, Context};

Now let's implement our validation function and update add_student:

fn validate_name(name: &str) -> Result<()> {
    if name.trim().is_empty() {
        return Err(anyhow::anyhow!("Name cannot be empty"));
    }
    Ok(())
}

pub fn add_student(&mut self, id: u32, name: String) -> anyhow::Result<Student> {
    println!("Adding new student {id} {name}");

    Self::validate_name(&name).context(format!("Failed to add student with id {}", id))?;

    if self.students.iter().any(|s| s.id == id) {
        return Err(anyhow::anyhow!("Student with id {} already exists", id));
    }

    let student = Student::new(id, name);
    self.students.push(student.clone());
    return Ok(student);
}

pub fn demonstrate() {
    let mut db = Database::new();
    let result_1 = db.add_student(1, "Alice".to_string());
    println!("{:?}\n", result_1);

    let result_2 = db.add_student(1, "Bob".to_string());
    println!("{:?}\n", result_2);

    let result_3 = db.add_student(2, "   ".to_string());
    println!("{:?}\n", result_3);
}
// OUTPUT
// Adding new student 1 Alice
// Ok(Student { id: 1, name: "Alice" })
//
// Adding new student 1 Bob
// Err(Student with id 1 already exists)
//
// Adding new student 2
// Err(Failed to add student with id 2
//
// Caused by:
//     Name cannot be empty)

Notice how the error output now shows a hierarchy:

Top-level context: "Failed to add student with id 2"
Root cause: "Name cannot be empty"

This layered approach is incredibly helpful when debugging complex applications. Each layer of the call stack can add its own context, making it easy to understand not just what failed, but where and why.

Building Complex Error Chains

Let's look at a more realistic scenario: enrolling a student in a course. This operation involves multiple steps, each of which could fail:

Ensure the student exists (or create them)
Ensure the course exists (or create it)
Check for duplicate enrollments
Record the enrollment

Here's how we can use context at multiple levels to make errors maximally informative:

pub fn process_enrollment(
    &mut self,
    student_id: u32,
    student_name: String,
    course_id: u32,
    course_name: String,
) -> Result<()> {
    // Add student if needed
    if !self.students.iter().any(|s| s.id == student_id) {
        self.add_student(student_id, student_name)
            .context("Failed to add student during enrollment")?;
    }

    // Add course if needed
    if !self.courses.iter().any(|c| c.id == course_id) {
        self.add_course(course_id, course_name)
            .context("Failed to add course during enrollment")?;
    }

    // Check for duplicate enrollment
    let enrolled_courses = self.enrollments
        .entry(student_id).or_insert_with(Vec::new);

    if enrolled_courses.contains(&course_id) {
        return Err(anyhow::anyhow!(
            "Student {} is already enrolled in course {}",
            student_id, course_id
        )).context("Enrollment already exists");
    }

    enrolled_courses.push(course_id);
    Ok(())
}

When errors occur, we see the full context chain:

// Example: Trying to enroll with invalid student name
db.process_enrollment(2, "   ".to_string(), 101, "Rust 101".to_string());

// OUTPUT:
// Err(Failed to add student during enrollment
// Caused by:
//     0: Failed to add student with id 2
//     1: Name cannot be empty)

// Example: Trying to duplicate enrollment
db.process_enrollment(1, "Alice".to_string(), 101, "Rust 101".to_string());

// OUTPUT:
// Err(Enrollment already exists
// Caused by:
//     Student 1 is already enrolled in course 101)

The context chain builds naturally as errors propagate up:

The deepest error tells us what went wrong ("Name cannot be empty")
Middle layers tell us what operation was being attempted ("Failed to add student with id 2")
Top layer tells us the high-level operation ("Failed to add student during enrollment")

This makes debugging production issues much easier - you can see the entire context of what the application was trying to do when the error occurred.

When anyhow Isn't Enough: Custom Error Types with thiserror

While anyhow is excellent for application code, it has a limitation: errors are type-erased. This means consumers of your code can't match on specific error types to handle them differently.

This is fine for applications (where you typically just log errors), but problematic for libraries where users need to programmatically handle different error cases.

Introducing thiserror

The thiserror crate makes it easy to create custom error types with minimal boilerplate. Instead of writing manual implementations of the Error, Display, and other traits, you can derive them automatically.

First, add thiserror to your Cargo.toml:

[dependencies]
thiserror = "1.0"

Now let's create a custom error enum for our enrollment system:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum EnrollmentError {
    #[error("Invalid student name (expected non-empty, got {found:?})")]
    InvalidStudentName { found: String },
    #[error("Invalid course name (expected non-empty, got {found:?})")]
    InvalidCourseName { found: String },
    #[error("Student {student_id} is already enrolled in course {course_id}")]
    DuplicateEnrollment { student_id: u32, course_id: u32 },
    #[error("Student with id {0} already exists")]
    DuplicateStudent(u32),
    #[error("Course with id {0} already exists")]
    DuplicateCourse(u32),
}

Let's break down what's happening here:

#[derive(Error, Debug)]: Automatically implements the Error and Debug traits
#[error("...")]: Defines the Display message for each variant
Named fields ({found:?}): Allow you to include data in error messages
Tuple variants (DuplicateStudent(u32)): Provide a concise syntax for single-field errors

Using Custom Error Types

Now we need to update our functions to return Result<T, EnrollmentError> instead of anyhow::Result. Note that we can no longer use .context() (that's an anyhow-specific feature), so our error variants themselves need to be descriptive:

fn validate_name(name: &str) -> Result<(), EnrollmentError> {
    if name.trim().is_empty() {
        return Err(EnrollmentError::InvalidStudentName {
            found: name.to_string(),
        });
    }
    Ok(())
}

pub fn add_student(&mut self, id: u32, name: String) -> Result<Student, EnrollmentError> {
    // This now returns EnrollmentError so we can use ? directly
    Self::validate_name(&name)?;

    if self.students.iter().any(|s| s.id == id) {
        return Err(EnrollmentError::DuplicateStudent(id));
    }

    let student = Student::new(id, name);
    self.students.push(student.clone());
    return Ok(student);
}

pub fn add_course(&mut self, id: u32, name: String) -> Result<Course, EnrollmentError> {
    if name.trim().is_empty() {
        return Err(EnrollmentError::InvalidCourseName {
            found: name.to_string(),
        });
    }

    if self.courses.iter().any(|c| c.id == id) {
        return Err(EnrollmentError::DuplicateCourse(id));
    }

    let course = Course::new(id, name);
    self.courses.push(course);
    return Ok(self.courses.last().unwrap().clone());
}

pub fn process_enrollment(
    &mut self,
    student_id: u32,
    student_name: String,
    course_id: u32,
    course_name: String,
) -> Result<(), EnrollmentError> {
    if !self.students.iter().any(|s| s.id == student_id) {
        self.add_student(student_id, student_name)?;
    }

    if !self.courses.iter().any(|c| c.id == course_id) {
        self.add_course(course_id, course_name)?;
    }

    let enrolled_courses = self.enrollments
        .entry(student_id).or_insert_with(Vec::new);

    if enrolled_courses.contains(&course_id) {
        return Err(EnrollmentError::DuplicateEnrollment {
            student_id,
            course_id,
        });
    }

    enrolled_courses.push(course_id);
    Ok(())
}

pub fn demonstrate() {
    let mut db = Database::new();

    let result_1 = db.process_enrollment(1, "Alice".to_string(), 101, "Rust 101".to_string());
    println!("{:?}\n", result_1);

    let result_2 = db.process_enrollment(1, "Alice".to_string(), 102, "Advanced Rust".to_string());
    println!("{:?}\n", result_2);

    let result_3 = db.process_enrollment(2, "   ".to_string(), 101, "Rust 101".to_string());
    println!("{:?}\n", result_3);

    let result_4 = db.process_enrollment(1, "Alice".to_string(), 101, "Rust 101".to_string());
    println!("{:?}\n", result_4);
}
// OUTPUT
// Ok(())
//
// Ok(())
//
// Err(InvalidStudentName { found: "   " })
//
// Err(DuplicateEnrollment { student_id: 1, course_id: 101 })

Benefits of Custom Error Types

The error messages are now structured and actionable. More importantly, library consumers can handle different errors programmatically:

match db.process_enrollment(2, "   ".to_string(), 101, "Rust 101".to_string()) {
    Ok(()) => println!("Enrollment successful"),
    Err(EnrollmentError::InvalidStudentName { found }) => {
        println!("Please provide a valid student name, got: {:?}", found);
        // Show user a helpful error message
    }
    Err(EnrollmentError::DuplicateEnrollment { student_id, course_id }) => {
        println!("Student {} is already enrolled in course {}", student_id, course_id);
        // Maybe redirect to the course page instead of erroring
    }
    Err(e) => {
        println!("Unexpected error: {}", e);
        // Generic error handling
    }
}

With custom error types, library clients can:

Pattern match on specific error variants
Access error fields programmatically (like student_id, course_id)
Make informed decisions based on error type
Provide targeted error messages to end users

When to Use Each Approach

Here's a quick decision guide:

Scenario	Recommended Approach	Why
Quick prototyping	`panic!` or `unwrap()`	Fast iteration, acceptable for throwaway code
Simple success/failure	`bool`	Minimal overhead when details don't matter
Application error handling	`anyhow`	Great error messages, easy context chaining
Library public API	`thiserror`	Type-safe, allows consumers to handle errors programmatically
Internal application code	`Result<T, String>` or `anyhow`	Balance of simplicity and information

Key insight: anyhow is perfect for applications where you control the entire error handling flow. thiserror shines when you're building libraries where consumers need to handle your errors programmatically.

Combining anyhow and thiserror

In practice, many projects use both crates together:

Library code: Use thiserror to define public error types
Application code: Use anyhow to add context and handle errors from multiple libraries
The boundary: anyhow can wrap any error type (including thiserror errors), giving you the best of both worlds

// In your library (using thiserror)
pub fn risky_operation() -> Result<Value, MyLibraryError> { /* ... */ }

// In your application (using anyhow)
fn main() -> anyhow::Result<()> {
    let value = risky_operation()
        .context("Failed during application startup")?;
    // anyhow automatically wraps MyLibraryError and adds context
    Ok(())
}

Conclusion

Error handling in Rust evolves as your code matures:

Start simple: Use Result with String errors or even panic! for prototypes
Add structure: Graduate to anyhow for better error messages and context
Think about consumers: Use thiserror when building libraries that others will use
Combine approaches: Use both crates together in larger projects

The Rust error handling ecosystem might seem complex at first, but each tool has a clear purpose. By understanding the progression from basic patterns to sophisticated error types, you can choose the right approach for each situation.

Remember: good error messages save hours of debugging. Invest in error handling early, and your future self (and your users) will thank you.

Want to get better at Rust, 1% at a time? I send out a Rust fundamentals thread every Thursday - clear, practical examples, and beginner-friendly.

👉 Join the newsletter here

Rust for Beginners: 8 Practical Tips to Get Started

Olivia — Wed, 03 Sep 2025 06:02:39 +0000

Intro

I've been learning and writing Rust for about 7 years now, but I still remember the beginner frustration where everything felt really difficult and I was constantly fighting the compiler even to do basic things. Getting started with Rust can be challenging but teaching a lot of beginners over the last few years, I started to see some common pitfalls or patterns that you can start using today to improve your learning curve.

Tip 1: Use unwrap for Options and Results liberally at first

Options and Results are new for someone coming from a language without them. Focus on making stuff work first by unwrapping to make your code work. Then learn about how to deal with them idiomatically later. Also you're most likely writing some throw-away code initially, trying to make something work so error handling won't be your first priority, so I'd recommend unwrapping liberally, then doing a second pass to improve error handling, something like this.

impl Database {
    pub fn find_student(&self, name: &str) -> Option<&Student> {
        /// ...
    }
}

pub fn main() {
    // Load database with all students 
    let database = Database::new();

    // Find a specific student and print their id
    let student_id = database.find_student("Bob").unwrap().id;
    println!("Bob's id is {}", student_id);
}

Then in the second iteration this code becomes something like this.

Once your code is working and you understand the error cases better, transition away from unwrap() in production code where unexpected panics could crash your application - that's when proper error handling with match, if let, or the ? operator becomes important for robustness. Here we use a match.

pub fn main() {
    // Load database with all students 
    let database = Database::new();

    // Find a specific student and print their id
    match database.find_student("Bob") {
        Some(bob) => println!("Bob's id is {}", bob.id);
        None => println!("Didn't find Bob");
    }
}

Tip 2: Learn the difference between String and &str

This is fundamental to understand, and don't be afraid to use String only at first even if it's terribly inefficient. You can optimize later once you understand the concepts better.

Understanding slices will also help here - slices are essentially borrowed views into contiguous sequences of data. Think of &str as a string slice that references existing string data without owning it. For example, &s[0..5] creates a slice that references the first 5 characters of string s without copying them. This concept applies to both strings and arrays/vectors (where &[T] is an array slice). Start by using them to reference parts of existing data, and you'll gradually understand how they help with memory efficiency.

fn main() {
    // String - owned, heap-allocated, mutable
    let mut owned_string = String::from("Hello");
    owned_string.push_str(" World"); // Can modify

    // &str - borrowed reference to string data, immutable
    let string_slice: &str = "Hello World"; // String literal
    let borrowed_slice: &str = &owned_string; // Borrowing from String

    // Function that takes &str can accept both
    print_message(&owned_string); // String automatically converts to &str
    print_message(string_slice);  // &str passed directly
}

fn print_message(msg: &str) {
    println!("{}", msg);
}

Tip 3: Clone liberally (but do not Copy)

At first you'll get the compiler shouting at you a lot because you're moving stuff without knowing you're moving it. Add a Clone derive annotation, call .clone() and move on to the next problem! Then as a second pass come back and optimize.

#[derive(Clone)]
struct Student {
    name: String,
    id: u32,
}

fn process_student(student: Student) {
    println!("Processing student: {}", student.name);
}

fn main() {
    let alice = Student {
        name: "Alice".to_string(),
        id: 12345,
    };

    process_student(alice.clone()); // Clone so we don't move alice
    println!("Alice is still available: {}", alice.name); // This works!
}

Tip 4: Avoid Storing References in Structs

As soon as you do this you'll need to get into lifetimes and if you're still learning the basics, I'd avoid this. Just store owned types, and pass everything else as arguments to functions.

// AVOID
struct Course<'a> {
    student: &'a Student, // Borrowed, needs explicit lifetimes
}

// GOOD
struct Course {
    student: Student, // Owns the data
}

Tip 5: Avoid linked lists and trees

As soon as you get into this you need to understand borrowing and Box/Rc/Arc which you will struggle with as a beginner. Once you feel comfortable with the basics, then dive deeper into these advanced data structures. There is even a whole book about writing many flavours of linked lists: Learn Rust With Entirely Too Many Linked Lists which I'd recommend reading only after you learn at least some of the core rust pointer types.

Tip 6: Consider Ordering and Use Scope Blocks

This is my favourite trick, if you plan to do multiple mutations, or a read, write then read again, ordering plus creating a new scope block for each can save the day as it releases the borrow.

struct Student {
    name: String,
    grade: u8,
}

impl Student {
    pub fn new(name: &str) -> Self {
        Self {
            name: name.to_string(),
            grade: 100,
        }
    }

    pub fn grade_mut(&mut self) -> &mut u8 {
        &mut self.grade
    }

    pub fn name(&self) -> &str {
        &self.name
    }
}

fn main() {
    let mut student = Student::new("Alice");

    {
        let grade = student.grade_mut();
        *grade += 1;
    } // grade's mutable borrow is dropped here

    let name = student.name();  // Now this works
    println!("Name: {}", name);
}

/// WORKS!!

Compare this to the problematic version:

fn main() {
    let mut student = Student::new("Alice");

    let grade = student.grade_mut(); // First mutable borrow
    let name = student.name();       // Try to borrow immutably immediately
    *grade += 1;                     // Still using mutable borrow

    println!("Name: {}, Grade: {}", name, grade);
}

// Error: cannot borrow `student` as immutable because it is also borrowed as mutable

Tip 7: Use Option::take() to Move Values Safely

If you need to move a value out of a struct, Option<T>::take() prevents borrowing conflicts:

struct Database {
    student: Option<Student>,
}

impl Database {
    fn remove_student(&mut self) -> Option<Student> {
        self.student.take() // ✅ Replaces with None, avoiding borrowing issues
    }
}

let mut db = Database { student: Some(Student::new("Charlie")) };
let removed_student = db.remove_student(); // ✅ Student is safely moved out

Tip 8: Pass Data as Function Arguments Instead of Storing It

The extra step of storing owned values is not storing values at all. Instead of holding a reference/owned value inside a struct, pass data when needed, and when it makes sense. It's also easier to pass references around without dealing with lifetimes.

struct Course;

impl Course {
    fn process(student: &mut Student) {
        println!("{} is processed!", student.name);
    }
}

let alice = Student::new("Alice");
Course::process(&mut alice); // ✅ Passes a reference instead of storing it

Conclusion

These practical tips worked for me initially, and as I got more comfortable with the language, I started going deeper into each of these topics and learning how to do something in the most idiomatic and efficient way.

Want to get better at Rust, 1% at a time? I send out a Rust fundamentals thread every Thursday - clear, practical examples, and beginner-friendly.

👉 Join the newsletter here