parking_lot_core

parking_lot_core provides the foundational building blocks for implementing custom synchronization primitives in Rust. It's the layer beneath parking_lot's faster mutexes and RwLocks. Day-to-day usage involves careful handling of parker/unparker pairs and understanding subtle memory ordering requirements. The API is minimal and unsafe-heavy by design, which is appropriate given its role as a building block.

From a security perspective, the library is well-maintained with responsive CVE handling (when applicable at this level). It has minimal dependencies, reducing supply chain risk significantly. The unsafe code is concentrated and auditable, though you must be extremely careful about memory ordering and avoiding deadlocks in your own implementations. Error handling is sparse because failures at this level are typically unrecoverable (OOM, invalid states).

The documentation assumes you understand lock-free programming and OS-level synchronization concepts. There's limited hand-holding, which makes sense for an advanced API but means mistakes can lead to hard-to-debug race conditions or deadlocks. The thread parker implementation is sound, but misuse in custom primitives can expose timing vulnerabilities or denial-of-service conditions if not carefully designed.

parking_lot_core is the low-level backbone behind parking_lot's excellent lock implementations. If you're building custom sync primitives, this is your toolkit. The API is minimal but extremely well-designed: park/unpark operations with token validation prevent spurious wakeups, and the hash-based parking mechanism means zero per-object memory overhead. In production, I've used it to build specialized work-stealing queue primitives that needed precise control over thread parking behavior.

Performance is exceptional - the parking lot approach scales significantly better than standard library primitives under contention. The timeout handling is precise and the futex-based implementation on Linux means minimal syscall overhead. Resource management is automatic with proper RAII guards. One gotcha: the API is deliberately unsafe and low-level, so you need to deeply understand memory ordering and be meticulous about token validation to avoid deadlocks or missed wakeups.

Observability is limited since it's so low-level - you'll need to build your own instrumentation on top. Documentation assumes you understand lock-free programming concepts. Breaking changes between 0.8 and 0.9 required careful migration, but the improvements were worth it.

parking_lot_core provides the foundation for building custom synchronization primitives in Rust, and it does this job exceptionally well. The API is minimal and focused: you get park/unpark operations with timeout support and validation callbacks. However, this is decidedly not a beginner-friendly crate. You're working directly with unsafe code, raw pointers, and need to deeply understand memory ordering guarantees.

The documentation includes critical safety requirements but assumes significant prior knowledge of lock-free programming and Rust's unsafe semantics. Error messages when things go wrong are typically runtime panics or undefined behavior rather than helpful compile-time guidance. There's no hand-holding here—you must already understand what you're building.

In practice, most developers should use the higher-level `parking_lot` crate instead. I've only reached for `parking_lot_core` when building truly custom synchronization primitives that don't fit standard patterns. When you do need it, the API is well-designed and the validation hooks help catch bugs, but expect a steep learning curve and extensive testing.