What is the purpose of parking_lot::RawMutex for building custom synchronization primitives?
parking_lot::RawMutex is a low-level mutex primitive that provides only the bare essentials for mutual exclusion without any associated data or high-level safety wrappers, making it suitable for building custom synchronization primitives like condition variables, semaphores, read-write locks, and other concurrency constructs. Unlike the high-level Mutex<T> which wraps data and provides safe access, RawMutex exposes raw lock/unlock operations that require manual safety management but enable building custom primitives with precise control over blocking behavior and thread parking.
The Standard Mutex Abstraction
use std::sync::Mutex;
use parking_lot::Mutex as PlMutex;
fn standard_mutex() {
// Standard library Mutex wraps data
let mutex = Mutex::new(42);
// Lock returns a guard that provides access to data
let guard = mutex.lock().unwrap();
println!("Value: {}", *guard);
// Guard automatically unlocks on drop
drop(guard);
// parking_lot::Mutex is similar but without poisoning
let pl_mutex = PlMutex::new(42);
let guard = pl_mutex.lock();
println!("Value: {}", *guard);
}The standard Mutex<T> is a complete abstraction: it holds data, provides safe access through guards, and handles locking automatically.
What RawMutex Provides
use parking_lot::RawMutex;
fn raw_mutex_basics() {
// RawMutex holds NO data - just the lock state
let mutex = RawMutex::new();
// Low-level lock/unlock operations
mutex.lock(); // Block until acquired
// ... critical section ...
mutex.unlock(); // Manual unlock - no guard!
// No data access, no guards, just raw synchronization
}RawMutex provides only the locking mechanism without data, guards, or automatic unlock management.
No Associated Data
use parking_lot::RawMutex;
fn no_data() {
// RawMutex has no generic type parameter for data
let mutex: RawMutex = RawMutex::new();
// Contrast with Mutex<T>:
// let mutex: Mutex<i32> = Mutex::new(42);
// You cannot store data inside a RawMutex
// It's purely a synchronization primitive
// To use it for data protection:
let mutex = RawMutex::new();
let mut data = 42; // Data stored separately
mutex.lock();
// Access data while holding lock
data += 1;
mutex.unlock();
// SAFETY: You must ensure data is only accessed when locked
}RawMutex has no data storage; it's purely a lock state manager for building higher-level abstractions.
Manual Lock and Unlock Operations
use parking_lot::RawMutex;
fn manual_operations() {
let mutex = RawMutex::new();
// Blocking lock
mutex.lock(); // Wait until lock is available
// Non-blocking try_lock
if mutex.try_lock() {
// Lock acquired
mutex.unlock();
} else {
// Lock not available
}
// Timed lock (available on RawMutex)
if mutex.try_lock_for(std::time::Duration::from_secs(5)) {
// Acquired within 5 seconds
mutex.unlock();
}
// No automatic unlock - must call unlock() manually!
// This is dangerous but enables custom guard implementations
}RawMutex exposes lock, try_lock, and timed variants, but never automatically unlocksâyou must manage this manually.
Building a Custom Mutex
use parking_lot::RawMutex;
use std::cell::UnsafeCell;
use std::ops::{Deref, DerefMut};
// Custom Mutex that wraps data like std::sync::Mutex
struct MyMutex<T> {
raw: RawMutex,
data: UnsafeCell<T>,
}
// Guard that provides safe access
struct MyMutexGuard<'a, T> {
mutex: &'a MyMutex<T>,
}
impl<T> MyMutex<T> {
fn new(data: T) -> Self {
MyMutex {
raw: RawMutex::new(),
data: UnsafeCell::new(data),
}
}
fn lock(&self) -> MyMutexGuard<'_, T> {
self.raw.lock();
MyMutexGuard { mutex: self }
}
}
impl<T> Drop for MyMutexGuard<'_, T> {
fn drop(&mut self) {
self.mutex.raw.unlock();
}
}
impl<T> Deref for MyMutexGuard<'_, T> {
type Target = T;
fn deref(&self) -> &T {
// SAFETY: Guard exists only while lock is held
unsafe { &*self.mutex.data.get() }
}
}
impl<T> DerefMut for MyMutexGuard<'_, T> {
fn deref_mut(&mut self) -> &mut T {
// SAFETY: Guard exists only while lock is held
unsafe { &mut *self.mutex.data.get() }
}
}
// Now we have a safe Mutex<T> built on RawMutex
fn custom_mutex() {
let mutex = MyMutex::new(42);
let mut guard = mutex.lock();
*guard += 1;
// Automatic unlock on drop
}RawMutex provides the locking primitive; you combine it with UnsafeCell to build safe data access patterns.
Building a Condition Variable
use parking_lot::RawMutex;
use std::sync::atomic::{AtomicBool, Ordering};
use std::collections::VecDeque;
// Condition variable using RawMutex
struct Condvar {
waiters: AtomicBool, // Simplified; real impl uses thread parking
}
impl Condvar {
fn new() -> Self {
Condvar {
waiters: AtomicBool::new(false),
}
}
fn wait(&self, mutex: &RawMutex) {
// Release mutex while waiting
mutex.unlock();
// Wait for signal (simplified - real impl uses parking_lot::Condvar)
// In practice, use thread::park() or condvar primitives
// Re-acquire mutex after wakeup
mutex.lock();
}
fn notify_one(&self) {
// Wake one waiting thread
self.waiters.store(true, Ordering::Release);
}
}
// Usage pattern for condition variables
fn condvar_usage() {
let mutex = RawMutex::new();
let condvar = Condvar::new();
let mut queue: VecDeque<i32> = VecDeque::new();
mutex.lock();
// Wait for condition
while queue.is_empty() {
// condvar.wait(&mutex); // Releases mutex, waits, re-acquires
}
// Process queue...
mutex.unlock();
}RawMutex enables building condition variables that need precise control over when the mutex is released and re-acquired.
Building a Semaphore
use parking_lot::RawMutex;
use std::sync::atomic::{AtomicUsize, Ordering};
// Counting semaphore using RawMutex
struct Semaphore {
mutex: RawMutex,
count: AtomicUsize,
max_count: usize,
}
impl Semaphore {
fn new(max_count: usize) -> Self {
Semaphore {
mutex: RawMutex::new(),
count: AtomicUsize::new(0),
max_count,
}
}
fn acquire(&self) {
loop {
self.mutex.lock();
if self.count.load(Ordering::Acquire) < self.max_count {
self.count.fetch_add(1, Ordering::AcqRel);
self.mutex.unlock();
return;
}
// Count at max, wait and retry
self.mutex.unlock();
// In real implementation, use thread parking
std::thread::yield_now();
}
}
fn release(&self) {
self.mutex.lock();
if self.count.load(Ordering::Acquire) > 0 {
self.count.fetch_sub(1, Ordering::AcqRel);
}
self.mutex.unlock();
}
}
fn semaphore_usage() {
let sem = Semaphore::new(3); // Max 3 concurrent access
sem.acquire();
// ... critical section ...
sem.release();
}RawMutex protects the semaphore's internal state while allowing custom acquire/release semantics.
Building a Read-Write Lock
use parking_lot::RawMutex;
use std::sync::atomic::{AtomicUsize, Ordering};
// Simplified read-write lock using RawMutex
struct RwLock {
mutex: RawMutex,
readers: AtomicUsize,
writer_held: AtomicBool,
}
impl RwLock {
fn new() -> Self {
RwLock {
mutex: RawMutex::new(),
readers: AtomicUsize::new(0),
writer_held: AtomicBool::new(false),
}
}
fn read_lock(&self) {
loop {
self.mutex.lock();
if !self.writer_held.load(Ordering::Acquire) {
self.readers.fetch_add(1, Ordering::AcqRel);
self.mutex.unlock();
return;
}
self.mutex.unlock();
std::thread::yield_now();
}
}
fn read_unlock(&self) {
self.readers.fetch_sub(1, Ordering::AcqRel);
}
fn write_lock(&self) {
loop {
self.mutex.lock();
if self.readers.load(Ordering::Acquire) == 0
&& !self.writer_held.load(Ordering::Acquire)
{
self.writer_held.store(true, Ordering::Release);
self.mutex.unlock();
return;
}
self.mutex.unlock();
std::thread::yield_now();
}
}
fn write_unlock(&self) {
self.writer_held.store(false, Ordering::Release);
}
}RawMutex protects the internal state of the read-write lock while allowing multiple readers or exclusive writers.
Thread Parking Integration
use parking_lot::RawMutex;
// parking_lot provides efficient thread parking
// RawMutex integrates with this for blocking behavior
fn thread_parking() {
let mutex = RawMutex::new();
// RawMutex::lock() uses parking_lot's thread parking
// This is more efficient than spin-waiting
// When a thread calls lock() on a held mutex:
// 1. Thread is parked (put to sleep)
// 2. When mutex is unlocked, one parked thread is unparked
// This avoids CPU spinning while waiting
// Custom primitives can use parking_lot::parking_lot::
// - thread::park() to sleep current thread
// - thread::unpark() to wake specific thread
// - ParkToken for priority-based parking
}RawMutex uses parking_lot's efficient thread parking mechanism instead of spin-waiting, making it suitable for building blocking primitives.
RawMutex vs Mutex
use parking_lot::{RawMutex, Mutex};
fn comparison() {
// RawMutex: Low-level, no data, manual unlock
// Use for: Building custom primitives
let raw = RawMutex::new();
raw.lock();
// ... critical section ...
raw.unlock(); // Manual
// Mutex<T>: High-level, wraps data, automatic unlock
// Use for: Protecting shared data
let mutex = Mutex::new(42);
{
let guard = mutex.lock();
*guard += 1;
// Automatic unlock on drop
}
// Key differences:
// | Aspect | RawMutex | Mutex<T> |
// |--------|----------|----------|
// | Data storage | No | Yes |
// | Guard | No | Yes |
// | Auto-unlock | No | Yes |
// | Use case | Custom primitives | Data protection |
}RawMutex is for building primitives; Mutex<T> is for using them directly on data.
Safety Requirements
use parking_lot::RawMutex;
fn safety_requirements() {
let mutex = RawMutex::new();
let data = 42; // Data separate from lock
// SAFETY REQUIREMENTS:
// 1. Always unlock after lock
mutex.lock();
// Access data
mutex.unlock();
// 2. Never unlock twice
// WRONG:
// mutex.lock();
// mutex.unlock();
// mutex.unlock(); // UB: double unlock
// 3. Never access protected data without holding lock
// WRONG:
// mutex.lock();
// mutex.unlock();
// println!("{}", data); // UB: accessing without lock
// 4. Lock must outlive any guards you build
// The RawMutex must not be dropped while locked
}Using RawMutex requires strict adherence to lock/unlock discipline; violations cause undefined behavior.
RawMutex in the parking_lot Ecosystem
use parking_lot::{RawMutex, Mutex, ReentrantMutex, RwLock};
fn ecosystem() {
// parking_lot provides multiple mutex types:
// RawMutex: Primitive for building other types
let raw = RawMutex::new();
// Mutex<T>: Uses RawMutex internally
// type Mutex<T> = lock_api::Mutex<RawMutex, T>;
// ReentrantMutex: Uses RawReentrantMutex internally
// Allows same thread to lock multiple times
// RwLock: Uses RawRwLock internally
// Multiple readers, single writer
// All high-level types use RawMutex-like primitives
// RawMutex is the foundation for the entire ecosystem
}RawMutex is the foundational primitive; Mutex<T>, RwLock, and others are built on top of similar raw primitives.
Const Initialization
use parking_lot::RawMutex;
fn const_init() {
// RawMutex can be initialized in const context
// This enables static mutexes
static GLOBAL_MUTEX: RawMutex = RawMutex::new();
static mut GLOBAL_DATA: i32 = 0;
// Use in static context
fn increment_global() {
GLOBAL_MUTEX.lock();
unsafe {
GLOBAL_DATA += 1;
}
GLOBAL_MUTEX.unlock();
}
// This is useful for global synchronization primitives
// std::sync::Mutex requires lazy initialization for static
}RawMutex::new() is const, enabling static mutex initialization without lazy_static or once_cell.
Performance Characteristics
use parking_lot::RawMutex;
fn performance() {
// RawMutex is optimized for:
// 1. Small memory footprint
// RawMutex is just a few bytes (atomic state + parking info)
// 2. Fast uncontended operations
// Lock/unlock on uncontended mutex is very fast
// 3. Efficient contention handling
// Uses thread parking instead of spin-waiting
// 4. No poisoning overhead
// Unlike std::sync::Mutex, no poisoning checks
// 5. No data wrapper overhead
// Mutex<T> has guard allocation overhead
// RawMutex has no guard - you create your own
// Benchmark considerations:
// - RawMutex overhead is minimal
// - Main cost is in contention handling
// - For custom primitives, your guard implementation matters
}RawMutex is highly optimized for both contended and uncontended scenarios with minimal overhead.
When to Use RawMutex
use parking_lot::RawMutex;
fn when_to_use() {
// Use RawMutex when:
// 1. Building custom synchronization primitives
// - Condition variables
// - Semaphores
// - Read-write locks
// - Barrier primitives
// 2. Need const initialization for static
// static LOCK: RawMutex = RawMutex::new();
// 3. Implementing lock_api traits
// Building types that implement lock_api::RawMutex
// 4. Custom guard semantics
// Need different unlock behavior than standard Mutex
// DON'T use RawMutex when:
// 1. Simple data protection
// Use Mutex<T> instead
// 2. Don't need custom primitives
// Mutex<T> is safer and easier
// 3. Can't guarantee lock/unlock discipline
// RawMutex requires careful management
}Use RawMutex for building custom primitives; use Mutex<T> for standard data protection.
Implementing lock_api::RawMutex Trait
use parking_lot::RawMutex;
use lock_api::RawMutex as RawMutexTrait;
// parking_lot::RawMutex implements lock_api::RawMutex
// This trait enables generic lock implementations
fn lock_api_trait() {
// The lock_api::RawMutex trait requires:
// - INIT: const initializer
// - lock(): acquire mutex
// - unlock(): release mutex
// - try_lock(): non-blocking acquire
// RawMutex provides these implementations
// so it can be used with lock_api abstractions:
// lock_api::Mutex<RawMutex, T> is equivalent to parking_lot::Mutex<T>
// lock_api::ReentrantMutex<RawMutex, T, ...>
// etc.
// This trait abstraction enables:
// - Generic code working with any raw mutex
// - Custom mutex types with standard interfaces
}RawMutex implements lock_api::RawMutex, enabling it to work with generic lock abstractions.
Summary
use parking_lot::RawMutex;
fn summary() {
// RawMutex is:
// 1. A low-level mutex primitive (no data, no guard)
let mutex = RawMutex::new();
// 2. Manual lock/unlock (no automatic unlock)
mutex.lock();
mutex.unlock();
// 3. Const-initializable (static mutexes)
static STATIC_MUTEX: RawMutex = RawMutex::new();
// 4. Foundation for custom primitives
// Combine with UnsafeCell, atomics, etc.
// 5. Integrates with parking_lot thread parking
// Efficient blocking instead of spinning
// | Use | Primitive |
// |-----|----------|
// | Custom condition variables | RawMutex + Condvar |
// | Custom semaphores | RawMutex + AtomicUsize |
// | Custom RwLock | RawMutex + state tracking |
// | Custom Mutex<T> | RawMutex + UnsafeCell<T> |
}Synthesis
Quick reference:
use parking_lot::RawMutex;
fn quick_reference() {
// RawMutex: Bare mutex for building custom primitives
let mutex = RawMutex::new();
// Low-level operations (no guard):
mutex.lock(); // Block until acquired
mutex.unlock(); // Release (manual!)
// Non-blocking:
if mutex.try_lock() {
// Acquired
mutex.unlock();
}
// Timed:
if mutex.try_lock_for(std::time::Duration::from_secs(1)) {
mutex.unlock();
}
// Use for: custom Mutex<T>, Condvar, Semaphore, RwLock, etc.
// Don't use for: simple data protection (use Mutex<T> instead)
}Key insight: parking_lot::RawMutex exists as a foundation layer for building custom synchronization primitives by providing only the essential mutex state and operationsâlock, unlock, try_lock, and timed variantsâwithout any data wrapper, guard type, or automatic unlock mechanism. This minimal design enables implementers to combine RawMutex with other primitives like UnsafeCell for data storage, AtomicUsize for state tracking, and thread parking mechanisms to create sophisticated synchronization constructs like condition variables (which need precise control over when the lock is released during wait), semaphores (which need to track a count alongside the lock), and read-write locks (which need to distinguish between reader and writer states). The RawMutex uses parking_lot's efficient thread parking mechanism for blocking operations, avoiding CPU spinning while waiting for the lock, and its const initialization enables static mutex declarations without lazy initialization. Unlike Mutex<T> which handles data protection, poisoning, and automatic unlock through guards, RawMutex requires the caller to manage all safety invariants manuallyâevery lock() must be paired with an unlock(), protected data must be stored separately and accessed only while holding the lock, and the lock must not be destroyed while held. This places RawMutex squarely in the "building block" category: use it to create the high-level primitives your application needs, but use Mutex<T> directly for standard data protection scenarios.