| name | rust-systems-programming |
| description | Complete guide for Rust systems programming including ownership, borrowing, concurrency, async programming, unsafe code, and performance optimization |
| tags | rust, systems-programming, ownership, concurrency, async, memory-safety, performance |
| tier | tier-1 |
Rust Systems Programming
A comprehensive skill for building high-performance, memory-safe systems software using Rust. This skill covers ownership, borrowing, concurrency, async programming, unsafe code, FFI, and performance optimization for systems-level development.
When to Use This Skill
Use this skill when:
- Building systems software requiring memory safety without garbage collection
- Developing high-performance applications with zero-cost abstractions
- Writing concurrent or parallel programs with data race prevention
- Creating async/await applications for I/O-bound workloads (web servers, databases)
- Working with low-level code, FFI, or hardware interfaces
- Replacing C/C++ code with safer alternatives
- Building command-line tools, network services, or embedded systems
- Optimizing performance-critical sections of applications
- Creating libraries that guarantee memory safety at compile time
- Developing WebAssembly modules for near-native performance
Core Concepts
The Ownership Model
Rust's ownership system is the foundation of its memory safety guarantees:
Ownership Rules:
- Each value in Rust has exactly one owner
- When the owner goes out of scope, the value is dropped
- Ownership can be transferred (moved) to new owners
Move Semantics:
struct MyStruct { s: u32 }
fn main() {
let mut x = MyStruct{ s: 5u32 };
let y = x; // Ownership moved from x to y
// x.s = 6; // ERROR: x is no longer valid
// println!("{}", x.s); // ERROR: cannot use x after move
}
When a type doesn't implement Copy, assignment moves ownership rather than copying. This prevents double-free errors and use-after-move bugs at compile time.
For Copy Types:
let x = 5; // i32 implements Copy
let y = x; // x is copied, not moved
println!("{}", x); // OK: x is still valid
Borrowing and References
Borrowing allows temporary access to data without taking ownership:
Immutable Borrowing:
fn main() {
let s1 = String::from("hello");
let len = calculate_length(&s1); // Borrow s1 immutably
println!("The length of '{}' is {}.", s1, len); // s1 still valid
}
fn calculate_length(s: &String) -> usize {
s.len() // Can read but not modify
}
Mutable Borrowing:
Rust enforces exclusive mutable access to prevent data races:
fn main() {
let mut value = 3;
let borrow = &mut value; // Mutable borrow
*borrow += 1;
println!("{}", borrow); // 4
// value is accessible again after borrow ends
}
Borrowing Rules:
- You can have either one mutable reference OR any number of immutable references
- References must always be valid (no dangling pointers)
- Mutable and immutable borrows cannot coexist
Common Borrowing Error:
fn main() {
let mut value = 3;
// Create a mutable borrow of `value`.
let borrow = &mut value;
let _sum = value + 1; // ERROR: cannot use `value` because
// it was mutably borrowed
println!("{}", borrow);
}
Lifetimes
Lifetimes ensure references are always valid:
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
if x.len() > y.len() {
x
} else {
y
}
}
The 'a lifetime parameter tells the compiler that the returned reference will be valid as long as both input references are valid.
Ownership Patterns for Sharing
Rc (Reference Counted) for Single-threaded Shared Ownership:
use std::cell::RefCell;
use std::rc::Rc;
struct MyStruct { s: u32 }
fn main() {
let mut x = Rc::new(RefCell::new(MyStruct{ s: 5u32 }));
let y = x.clone(); // Increment reference count
x.borrow_mut().s = 6; // Interior mutability via RefCell
println!("{}", x.borrow().s);
}
Rc<T> provides shared ownership with reference counting. RefCell<T> enables interior mutability, enforcing borrow rules at runtime rather than compile time.
Arc (Atomic Reference Counted) for Thread-safe Sharing:
use std::sync::Arc;
use std::thread;
struct FancyNum {
num: u8,
}
fn main() {
let fancy_ref1 = Arc::new(FancyNum { num: 5 });
let fancy_ref2 = fancy_ref1.clone();
let x = thread::spawn(move || {
// `fancy_ref1` can be moved and has a `'static` lifetime
println!("child thread: {}", fancy_ref1.num);
});
x.join().expect("child thread should finish");
println!("main thread: {}", fancy_ref2.num);
}
Arc<T> is the thread-safe version of Rc<T>, using atomic operations for reference counting.
Box for Heap Allocation
Box<T>
Box<T> is an owning pointer that allocates T on the heap. Useful for:
- Recursive types with known size
- Large values that should not be copied on the stack
- Trait objects with dynamic dispatch
Concurrency Patterns
Threads and Message Passing
Rust prevents data races at compile time through its ownership system:
use std::thread;
use std::sync::mpsc;
fn main() {
let (tx, rx) = mpsc::channel();
thread::spawn(move || {
tx.send("Hello from thread").unwrap();
});
let message = rx.recv().unwrap();
println!("{}", message);
}
Shared State with Mutex
use std::sync::{Arc, Mutex};
use std::thread;
fn main() {
let counter = Arc::new(Mutex::new(0));
let mut handles = vec![];
for _ in 0..10 {
let counter = Arc::clone(&counter);
let handle = thread::spawn(move || {
let mut num = counter.lock().unwrap();
*num += 1;
});
handles.push(handle);
}
for handle in handles {
handle.join().unwrap();
}
println!("Result: {}", *counter.lock().unwrap());
}
Key Concurrency Types:
Mutex<T>: Mutual exclusion lock for shared mutable stateRwLock<T>: Reader-writer lock allowing multiple readers or one writerArc<T>: Atomic reference counting for thread-safe sharingmpsc: Multi-producer, single-consumer channels
Data Race Prevention
ThreadSanitizer Example:
static mut A: usize = 0;
fn main() {
let t = std::thread::spawn(|| {
unsafe { A += 1 };
});
unsafe { A += 1 };
t.join().unwrap();
}
This code has a data race. ThreadSanitizer (enabled with RUSTFLAGS=-Zsanitizer=thread) detects concurrent access to static mutable data:
WARNING: ThreadSanitizer: data race (pid=10574)
Read of size 8 at 0x5632dfe3d030 by thread T1:
Previous write of size 8 at 0x5632dfe3d030 by main thread:
Async Programming
Async/Await Basics
Async programming in Rust allows concurrent I/O without blocking threads:
async fn foo(n: usize) {
if n > 0 {
Box::pin(foo(n - 1)).await;
}
}
Recursive async functions require Box::pin() to give the future a known size.
Async Closures
Async Closure with Move Semantics:
fn force_fnonce<T: async FnOnce()>(t: T) -> T { t }
let x = String::new();
let c = force_fnonce(async move || {
println!("{x}");
});
When constrained to AsyncFnOnce, the closure captures by move to ensure proper ownership.
Async Closure Borrowing:
let x = &1i32; // Lifetime '1
let c = async move || {
println!("{:?}", *x);
// Even though the closure moves x, we're only capturing *x,
// so the inner coroutine can reborrow the data for its original lifetime.
};
Mutable Borrowing in Async Closures:
let mut x = 1i32;
let c = async || {
x = 1;
// The parent borrows `x` mutably.
// When we call `c()`, we implicitly autoref for `AsyncFnMut::async_call_mut`.
// The inner coroutine captures with the lifetime of the coroutine-closure.
};
Common Async Errors
E0373: Async block capturing short-lived variable:
use std::future::Future;
async fn f() {
let v = vec![1, 2, 3i32];
spawn(async { //~ ERROR E0373
println!("{:?}", v) // v might go out of scope before async block runs
});
}
fn spawn<F: Future + Send + 'static>(future: F) {
unimplemented!()
}
Solution: Move the variable into the async block:
spawn(async move {
println!("{:?}", v)
})
Unsafe Code and FFI
When to Use Unsafe
Rust's unsafe keyword allows operations that the compiler cannot verify:
- Dereferencing raw pointers
- Calling unsafe functions or methods
- Accessing or modifying mutable static variables
- Implementing unsafe traits
- Accessing fields of unions
Unsafe Dereference Example:
macro_rules! unsafe_deref {
() => {
*(&() as *const ())
};
}
Memory Safety with Unsafe
Unsafe Sync Implementation:
use std::cell::Cell;
struct NotThreadSafe<T> {
value: Cell<T>,
}
unsafe impl<T> Sync for NotThreadSafe<T> {}
static A: NotThreadSafe<usize> = NotThreadSafe { value : Cell::new(1) };
static B: &'static NotThreadSafe<usize> = &A; // ok!
This is unsafe because you must manually ensure thread safety. Cell is not Sync by default, so this implementation requires careful reasoning.
FFI (Foreign Function Interface)
Calling C Functions from Rust:
use std::mem;
#[link(name = "foo")]
extern "C" {
fn do_twice(f: unsafe extern "C" fn(i32) -> i32, arg: i32) -> i32;
}
unsafe extern "C" fn add_one(x: i32) -> i32 {
x + 1
}
unsafe extern "C" fn add_two(x: i64) -> i64 {
x + 2
}
fn main() {
let answer = unsafe { do_twice(add_one, 5) };
println!("The answer is: {}", answer);
// Type-mismatched call (unsafe):
println!("With CFI enabled, you should not see the next answer");
let f: unsafe extern "C" fn(i32) -> i32 = unsafe {
mem::transmute::<*const u8, unsafe extern "C" fn(i32) -> i32>(add_two as *const u8)
};
let next_answer = unsafe { do_twice(f, 5) };
println!("The next answer is: {}", next_answer);
}
Control Flow Integrity (CFI): With CFI enabled, the type-mismatched transmute causes program termination, preventing control flow hijacking.
Inline Assembly for System Calls:
static UNMAP_BASE: usize;
const MEM_RELEASE: usize;
static VirtualFree: usize;
const OffPtr: usize;
const OffFn: usize;
core::arch::asm!("
push {free_type}
push {free_size}
push {base}
mov eax, fs:[30h]
mov eax, [eax+8h]
add eax, {off_fn}
mov [eax-{off_fn}+{off_ptr}], eax
push eax
jmp {virtual_free}
",
off_ptr = const OffPtr,
off_fn = const OffFn,
free_size = const 0,
free_type = const MEM_RELEASE,
virtual_free = sym VirtualFree,
base = sym UNMAP_BASE,
options(noreturn),
);
This demonstrates direct system calls using inline assembly for Windows memory deallocation.
Error Handling
Result and Option Types
Rust uses Result<T, E> and Option<T> for error handling:
fn divide(a: i32, b: i32) -> Result<i32, String> {
if b == 0 {
Err("Division by zero".to_string())
} else {
Ok(a / b)
}
}
fn main() {
match divide(10, 2) {
Ok(result) => println!("Result: {}", result),
Err(e) => println!("Error: {}", e),
}
}
The ? Operator
fn process_file(path: &str) -> Result<String, std::io::Error> {
let content = std::fs::read_to_string(path)?;
Ok(content.to_uppercase())
}
The ? operator propagates errors up the call stack, similar to exceptions but explicit in the type signature.
Custom Error Types
use std::fmt;
#[derive(Debug)]
enum AppError {
IoError(std::io::Error),
ParseError(std::num::ParseIntError),
Custom(String),
}
impl fmt::Display for AppError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
AppError::IoError(e) => write!(f, "IO error: {}", e),
AppError::ParseError(e) => write!(f, "Parse error: {}", e),
AppError::Custom(msg) => write!(f, "Error: {}", msg),
}
}
}
impl std::error::Error for AppError {}
Memory Safety and Sanitizers
AddressSanitizer
Detecting Stack Buffer Overflow:
fn main() {
let xs = [0, 1, 2, 3];
let _y = unsafe { *xs.as_ptr().offset(4) };
}
Build with AddressSanitizer:
$ export RUSTFLAGS=-Zsanitizer=address RUSTDOCFLAGS=-Zsanitizer=address
$ cargo run -Zbuild-std --target x86_64-unknown-linux-gnu
Output:
==37882==ERROR: AddressSanitizer: stack-buffer-overflow on address 0x7ffe400e6250
READ of size 4 at 0x7ffe400e6250 thread T0
#0 0x5609a841fb1f in example::main::h628ffc6626ed85b2 /.../src/main.rs:3:23
Address 0x7ffe400e6250 is located in stack of thread T0 at offset 48 in frame
This frame has 1 object(s):
[32, 48) 'xs' (line 2) <== Memory access at offset 48 overflows this variable
Detecting Heap Buffer Overflow:
fn main() {
let xs = vec![0, 1, 2, 3];
let _y = unsafe { *xs.as_ptr().offset(4) };
}
Detecting Use-After-Scope:
static mut P: *mut usize = std::ptr::null_mut();
fn main() {
unsafe {
{
let mut x = 0;
P = &mut x;
}
std::ptr::write_volatile(P, 123); // P points to dropped variable
}
}
AddressSanitizer output:
==39249==ERROR: AddressSanitizer: stack-use-after-scope on address 0x7ffc7ed3e1a0
WRITE of size 8 at 0x7ffc7ed3e1a0 thread T0
Performance Optimization
Zero-Cost Abstractions
Rust provides high-level abstractions without runtime overhead:
// Iterator chains are optimized to simple loops
let sum: i32 = (1..100)
.filter(|x| x % 2 == 0)
.map(|x| x * x)
.sum();
The compiler optimizes this to a tight loop equivalent to manual iteration.
Inlining and Monomorphization
Generic functions are monomorphized (specialized) for each concrete type:
#[inline]
fn add<T: std::ops::Add<Output = T>>(a: T, b: T) -> T {
a + b
}
let x = add(5, 3); // Specialized for i32
let y = add(5.0, 3.0); // Specialized for f64
Smart Pointer Overhead
Different smart pointers have different costs:
Box<T>: Single heap allocation, no overheadRc<T>: Reference counting, small overhead per clone/dropArc<T>: Atomic reference counting, higher overhead for thread safetyMutex<T>: Lock acquisition overheadRefCell<T>: Runtime borrow checking overhead
Avoiding Allocations
// Bad: Allocates a new String
fn greet_bad(name: &str) -> String {
format!("Hello, {}", name)
}
// Good: Returns a reference, no allocation
fn greet_good(name: &str) -> impl std::fmt::Display + '_ {
format_args!("Hello, {}", name)
}
Common Patterns and Idioms
Builder Pattern
struct Config {
host: String,
port: u16,
timeout: u64,
}
impl Config {
fn builder() -> ConfigBuilder {
ConfigBuilder::default()
}
}
#[derive(Default)]
struct ConfigBuilder {
host: Option<String>,
port: Option<u16>,
timeout: Option<u64>,
}
impl ConfigBuilder {
fn host(mut self, host: impl Into<String>) -> Self {
self.host = Some(host.into());
self
}
fn port(mut self, port: u16) -> Self {
self.port = Some(port);
self
}
fn build(self) -> Config {
Config {
host: self.host.unwrap_or_else(|| "localhost".to_string()),
port: self.port.unwrap_or(8080),
timeout: self.timeout.unwrap_or(30),
}
}
}
Newtype Pattern
struct UserId(u64);
struct PostId(u64);
fn get_user(id: UserId) -> User { /* ... */ }
// This won't compile: type safety!
// get_user(PostId(42));
RAII (Resource Acquisition Is Initialization)
struct FileGuard {
file: std::fs::File,
}
impl FileGuard {
fn new(path: &str) -> std::io::Result<Self> {
Ok(FileGuard {
file: std::fs::File::create(path)?,
})
}
}
impl Drop for FileGuard {
fn drop(&mut self) {
println!("File closed automatically");
}
}
Closure Patterns and Errors
E0500: Closure Borrowing Conflict
Problem:
fn you_know_nothing(jon_snow: &mut i32) {
let nights_watch = &jon_snow;
let starks = || {
*jon_snow = 3; // error: closure requires unique access to `jon_snow`
// but it is already borrowed
};
println!("{}", nights_watch);
}
Solution:
fn you_know_nothing(jon_snow: &mut i32) {
let nights_watch = &jon_snow;
println!("{}", nights_watch); // Use the borrow first
// Borrow ends here (non-lexical lifetimes)
let starks = || {
*jon_snow = 3; // Now OK
};
}
E0502: Mutable and Immutable Borrows
Problem:
fn bar(x: &mut i32) {}
fn foo(a: &mut i32) {
let y = &a;
bar(a); // Error: cannot borrow as mutable while borrowed as immutable
println!("{}", y);
}
Solution:
fn bar(x: &mut i32) {}
fn foo(a: &mut i32) {
bar(a); // Mutable borrow first
let y = &a; // Immutable borrow after mutable borrow ends
println!("{}", y);
}
E0505: Move of Borrowed Value
Problem:
struct Value {}
fn borrow(val: &Value) {}
fn eat(val: Value) {}
fn main() {
let x = Value{};
let _ref_to_val: &Value = &x;
eat(x); // Error: cannot move x while borrowed
borrow(_ref_to_val);
}
E0524: Concurrent Mutable Borrows in Closures
Problem:
fn set(x: &mut isize) {
*x += 4;
}
fn dragoooon(x: &mut isize) {
let mut c1 = || set(x);
let mut c2 = || set(x); // error: two closures trying to borrow mutably
c2();
c1();
}
Solution 1: Sequential Execution (Non-Lexical Lifetimes)
fn set(x: &mut isize) {
*x += 4;
}
fn dragoooon(x: &mut isize) {
{
let mut c1 = || set(&mut *x);
c1();
} // `c1` has been dropped here so we're free to use `x` again!
let mut c2 = || set(&mut *x);
c2();
}
Solution 2: Rc + RefCell for Shared Mutable Access
use std::rc::Rc;
use std::cell::RefCell;
fn set(x: &mut isize) {
*x += 4;
}
fn dragoooon(x: &mut isize) {
let x = Rc::new(RefCell::new(x));
let y = Rc::clone(&x);
let mut c1 = || { let mut x2 = x.borrow_mut(); set(&mut x2); };
let mut c2 = || { let mut x2 = y.borrow_mut(); set(&mut x2); };
c2();
c1();
}
E0507: Moving Borrowed Content
Problem:
use std::cell::RefCell;
struct TheDarkKnight;
impl TheDarkKnight {
fn nothing_is_true(self) {}
}
fn main() {
let x = RefCell::new(TheDarkKnight);
x.borrow().nothing_is_true(); // Error: cannot move out of borrowed content
}
Solution 1: Take a Reference
impl TheDarkKnight {
fn nothing_is_true(&self) {} // Change to &self
}
fn main() {
let x = RefCell::new(TheDarkKnight);
x.borrow().nothing_is_true(); // OK
}
Solution 2: Reclaim Ownership
fn main() {
let x = RefCell::new(TheDarkKnight);
let x = x.into_inner(); // Reclaim ownership
x.nothing_is_true(); // OK
}
Production Patterns
Structured Logging
use tracing::{info, warn, error, instrument};
#[instrument]
async fn process_request(id: u64) -> Result<(), Error> {
info!(request_id = id, "Processing request");
match do_work(id).await {
Ok(_) => {
info!("Request completed successfully");
Ok(())
}
Err(e) => {
error!(error = ?e, "Request failed");
Err(e)
}
}
}
Configuration Management
use serde::Deserialize;
#[derive(Deserialize)]
struct AppConfig {
database_url: String,
server_port: u16,
log_level: String,
}
fn load_config() -> Result<AppConfig, config::ConfigError> {
config::Config::builder()
.add_source(config::File::with_name("config"))
.add_source(config::Environment::with_prefix("APP"))
.build()?
.try_deserialize()
}
Graceful Shutdown
use tokio::signal;
async fn shutdown_signal() {
let ctrl_c = async {
signal::ctrl_c()
.await
.expect("failed to install Ctrl+C handler");
};
#[cfg(unix)]
let terminate = async {
signal::unix::signal(signal::unix::SignalKind::terminate())
.expect("failed to install signal handler")
.recv()
.await;
};
#[cfg(not(unix))]
let terminate = std::future::pending::<()>();
tokio::select! {
_ = ctrl_c => {},
_ = terminate => {},
}
println!("Shutdown signal received, starting graceful shutdown");
}
Connection Pooling
use deadpool_postgres::{Config, Pool, Runtime};
use tokio_postgres::NoTls;
async fn create_pool() -> Pool {
let mut cfg = Config::new();
cfg.host = Some("localhost".to_string());
cfg.dbname = Some("mydb".to_string());
cfg.create_pool(Some(Runtime::Tokio1), NoTls)
.expect("Failed to create pool")
}
async fn query_user(pool: &Pool, id: i64) -> Result<User, Error> {
let client = pool.get().await?;
let row = client
.query_one("SELECT * FROM users WHERE id = $1", &[&id])
.await?;
Ok(User::from_row(row))
}
Best Practices
API Design
- Use References by Default: Accept
&Tinstead ofTunless you need ownership - Return Owned Types: Return
Stringinstead of&strfor simpler APIs - Implement Standard Traits:
Debug,Clone,PartialEq,Send,Sync - Use
Into<T>for Flexibility:fn set_name(&mut self, name: impl Into<String>) - Leverage the Type System: Use newtypes, enums, and Result for correctness
Testing Patterns
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_addition() {
assert_eq!(add(2, 2), 4);
}
#[test]
#[should_panic(expected = "division by zero")]
fn test_divide_by_zero() {
divide(10, 0);
}
#[tokio::test]
async fn test_async_function() {
let result = fetch_data().await;
assert!(result.is_ok());
}
}
Documentation
/// Calculates the sum of two numbers.
///
/// # Examples
///
/// ```
/// let result = add(2, 2);
/// assert_eq!(result, 4);
/// ```
///
/// # Panics
///
/// This function will panic if the result overflows.
pub fn add(a: i32, b: i32) -> i32 {
a.checked_add(b).expect("overflow in add")
}
Dependency Management
[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
tracing = "0.1"
[dev-dependencies]
criterion = "0.5"
[profile.release]
lto = true
codegen-units = 1
Troubleshooting
Common Borrow Checker Issues
Issue: "Cannot borrow as mutable because it is also borrowed as immutable" Solution: Ensure mutable and immutable borrows don't overlap in scope
Issue: "Cannot move out of borrowed content"
Solution: Clone the value, take a reference, or use Rc<RefCell<T>>
Issue: "Lifetime issues with references" Solution: Add explicit lifetime annotations or restructure code to avoid complex lifetimes
Performance Issues
Issue: Slow compilation times
Solution: Use incremental compilation, reduce generic instantiations, use cargo check
Issue: Runtime performance slower than expected
Solution: Profile with perf, enable LTO, check for unnecessary allocations/clones
Issue: High memory usage Solution: Use references instead of clones, consider streaming data, profile with Valgrind
Concurrency Issues
Issue: Deadlocks with multiple mutexes
Solution: Always acquire locks in the same order, use try_lock with timeout
Issue: Data races in unsafe code Solution: Run with ThreadSanitizer, carefully review unsafe blocks
Issue: Async tasks not making progress
Solution: Check for blocking operations in async code, use spawn_blocking for CPU-bound work
Quick Reference
Smart Pointer Cheat Sheet
Box<T> - Heap allocation, single owner
Rc<T> - Reference counted, single-threaded
Arc<T> - Atomic reference counted, thread-safe
Mutex<T> - Mutual exclusion lock
RwLock<T> - Reader-writer lock
RefCell<T> - Runtime borrow checking
Cell<T> - Interior mutability for Copy types
Common Trait Implementations
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct MyStruct {
field: String,
}
impl Default for MyStruct {
fn default() -> Self {
Self {
field: String::new(),
}
}
}
impl std::fmt::Display for MyStruct {
fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
write!(f, "MyStruct({})", self.field)
}
}
Async Runtime Comparison
Tokio: Full-featured, most popular, excellent ecosystem
async-std: Mirrors std library API, simpler for beginners
smol: Lightweight, minimal dependencies
Resources
- The Rust Book: https://doc.rust-lang.org/book/
- Rust by Example: https://doc.rust-lang.org/rust-by-example/
- The Rustonomicon (unsafe Rust): https://doc.rust-lang.org/nomicon/
- Async Book: https://rust-lang.github.io/async-book/
- Rust Performance Book: https://nnethercote.github.io/perf-book/
- Crate Documentation: https://docs.rs/
Skill Version: 1.0.0 Last Updated: October 2025 Skill Category: Systems Programming, Performance, Memory Safety Context7 Integration: Rust documentation and error code examples