parking_lot

Compact and efficient synchronization primitives for Rust. Also provides an API for creating custom synchronization primitives.

2,689

212

2,689

View on GitHub View on NPM

Top Related Projects

rpcx

8,066

Best microservices framework in Go, like alibaba Dubbo, but with more features, Scale easily. Try it. Test it. If you feel it's better, use it! 𝐉𝐚𝐯𝐚有𝐝𝐮𝐛𝐛𝐨, 𝐆𝐨𝐥𝐚𝐧𝐠有𝐫𝐩𝐜𝐱! build for cloud!

grpc

41,549

The C based gRPC (C++, Python, Ruby, Objective-C, PHP, C#)

fasthttp

21,607

Fast HTTP package for Go. Tuned for high performance. Zero memory allocations in hot paths. Up to 10x faster than net/http

ion

3,822

Real-Distributed RTC System by pure Go and Flutter

twirp

7,115

A simple RPC framework with protobuf service definitions

Quick Overview

The parking_lot crate is a Rust library that provides a set of synchronization primitives for concurrent programming. It is designed to be a drop-in replacement for the standard library's std::sync module, offering improved performance and additional features.

Pros

High Performance: The parking_lot crate is optimized for performance, with benchmarks showing significant improvements over the standard library's primitives.
Flexible API: The library provides a wide range of synchronization primitives, including mutexes, RwLocks, Condvars, and Semaphores, allowing developers to choose the most appropriate tool for their needs.
Customizable Behavior: The parking_lot crate allows developers to customize the behavior of its primitives, such as setting the fairness policy for mutexes or the number of permits for Semaphores.
Comprehensive Documentation: The project has detailed documentation, including examples and benchmarks, making it easy for developers to understand and use the library.

Cons

Dependency on Unstable Features: The parking_lot crate relies on some unstable Rust features, which may limit its compatibility with certain Rust versions or environments.
Increased Complexity: The flexibility and customization options provided by the parking_lot crate may add complexity for developers who just need basic synchronization primitives.
Potential for Misuse: The advanced features of the parking_lot crate could lead to more complex synchronization bugs if not used correctly.
Limited Ecosystem Integration: While the parking_lot crate is widely used, it may not be as well-integrated with the broader Rust ecosystem as the standard library's std::sync module.

Code Examples

Here are a few examples of how to use the parking_lot crate:

Mutex:

use parking_lot::Mutex;

let mutex = Mutex::new(0);
{
    let mut guard = mutex.lock();
    *guard += 1;
} // The guard is automatically released when it goes out of scope.

RwLock:

use parking_lot::RwLock;

let rwlock = RwLock::new(0);
{
    let read_guard = rwlock.read();
    println!("Value: {}", *read_guard);
}
{
    let mut write_guard = rwlock.write();
    *write_guard += 1;
}

Condvar:

use parking_lot::{Condvar, Mutex};
use std::sync::Arc;

let pair = Arc::new((Mutex::new(false), Condvar::new()));
let (lock, cvar) = Arc::get_mut(&pair).unwrap();

// Notify the condition variable
*lock.lock() = true;
cvar.notify_one();

// Wait for the condition variable
let (lock, cvar) = &*pair;
let mut started = lock.lock();
while !*started {
    started = cvar.wait(started).unwrap();
}

Semaphore:

use parking_lot::Semaphore;

let semaphore = Semaphore::new(2);
{
    let permit = semaphore.acquire();
    // Do something with the permit
}

Getting Started

To use the parking_lot crate in your Rust project, add the following to your Cargo.toml file:

[dependencies]
parking_lot = "0.12.1"

Then, in your Rust code, you can import the necessary modules and use the provided synchronization primitives:

use parking_lot::{Mutex, RwLock, Condvar, Semaphore};

Refer to the project's documentation for more detailed information on how to use the various synchronization primitives and customize their behavior.

Competitor Comparisons

rpcx

8,066

Pros of rpcx

rpcx is a high-performance, distributed RPC framework that supports multiple protocols, such as HTTP, gRPC, and WebSocket.
rpcx provides a rich set of features, including service discovery, load balancing, and fault tolerance, making it suitable for building complex distributed systems.
rpcx has a large and active community, with regular updates and a wide range of plugins and extensions available.

Cons of rpcx

rpcx may have a steeper learning curve compared to Parking Lot, as it is a more feature-rich and complex framework.
rpcx may have a higher overhead and resource requirements compared to Parking Lot, as it is designed for distributed systems rather than a single-process use case.

Code Comparison

Parking Lot (Amanieu/parking_lot):

let park = parking_lot::Mutex::new(());
let guard = park.lock();
// critical section
drop(guard);

rpcx (smallnest/rpcx):

server := rpcx.NewServer()
server.RegisterName("Arith", new(Arith))
err := server.Serve("tcp", ":8972")
if err != nil {
    log.Fatal(err)
}

grpc

41,549

The C based gRPC (C++, Python, Ruby, Objective-C, PHP, C#)

Pros of grpc/grpc

Supports a wide range of programming languages, including C++, Java, Python, and more, making it a versatile choice for cross-platform development.
Provides a robust and efficient RPC (Remote Procedure Call) framework, enabling efficient communication between distributed systems.
Offers advanced features like load balancing, authentication, and encryption, making it suitable for enterprise-level applications.

Cons of grpc/grpc

Steeper learning curve compared to Amanieu/parking_lot, as it requires understanding of the gRPC protocol and its ecosystem.
May have a higher overhead and complexity compared to a simpler concurrency library like Amanieu/parking_lot, depending on the specific use case.

Code Comparison

Amanieu/parking_lot (Rust):

use parking_lot::Mutex;

let mutex = Mutex::new(0);
let guard = mutex.lock();
*guard += 1;

grpc/grpc (C++):

#include <grpcpp/grpcpp.h>

class GreeterServiceImpl final : public Greeter::Service {
  Status SayHello(ServerContext* context, const HelloRequest* request,
                  HelloReply* reply) override {
    reply->set_message("Hello " + request->name());
    return Status::OK;
  }
};

fasthttp

21,607

Fast HTTP package for Go. Tuned for high performance. Zero memory allocations in hot paths. Up to 10x faster than net/http

Pros of fasthttp

Significantly faster than the standard Go HTTP library, with up to 10x performance improvements in some cases.
Provides a simple and lightweight API for building high-performance HTTP servers and clients.
Supports HTTP/2 and WebSockets out of the box.

Cons of fasthttp

Slightly less feature-rich than the standard Go HTTP library, with some advanced features missing.
May have a steeper learning curve for developers familiar with the standard library.
Requires more manual handling of low-level details, such as request/response headers and body parsing.

Code Comparison

Amanieu/parking_lot

let mutex = Mutex::new(0);
let guard = mutex.lock().unwrap();
*guard += 1;

valyala/fasthttp

req := fasthttp.AcquireRequest()
defer fasthttp.ReleaseRequest(req)

req.SetRequestURI("https://example.com")
resp := fasthttp.AcquireResponse()
defer fasthttp.ReleaseResponse(resp)

err := fasthttp.Do(req, resp)
if err != nil {
    // handle error
}

ion

3,822

Real-Distributed RTC System by pure Go and Flutter

Pros of Ion

Ion is a modern, high-performance web framework for Rust, providing a more comprehensive set of features compared to Parking Lot.
Ion offers a built-in HTTP server, middleware support, and a flexible routing system, making it easier to build complex web applications.
Ion's documentation is well-organized and provides detailed examples, making it more approachable for developers new to Rust web development.

Cons of Ion

Parking Lot is a more focused and lightweight library, which may be more suitable for projects with simpler requirements or where performance is critical.
The Ion project is relatively newer compared to Parking Lot, and may have a smaller community and fewer third-party integrations available.
Depending on the specific requirements of your project, the additional features provided by Ion may not be necessary, making Parking Lot a more suitable choice.

Code Comparison

Parking Lot:

use parking_lot::Mutex;

let mutex = Mutex::new(0);
{
    let mut guard = mutex.lock();
    *guard += 1;
}

Ion:

use ion::prelude::*;

#[ion::main]
async fn main() -> Result<(), ion::Error> {
    let app = ion::Application::new().await?;
    app.get("/", |_| async { "Hello, World!" });
    app.run().await
}

twirp

7,115

A simple RPC framework with protobuf service definitions

Pros of Twirp

Simplicity: Twirp is a lightweight and straightforward RPC framework, making it easy to set up and use.
Language Agnostic: Twirp supports multiple programming languages, including Go, Python, and JavaScript, allowing for cross-platform development.
Protobuf Integration: Twirp uses Protocol Buffers (Protobuf) for defining service interfaces, which provides a clear and efficient way to define and communicate data structures.

Cons of Twirp

Limited Ecosystem: Compared to Parking Lot, Twirp has a smaller ecosystem and community, which may limit the availability of third-party libraries and tools.
Dependency on Protobuf: Twirp's reliance on Protobuf may be a drawback for developers who prefer a more flexible or language-native approach to defining service interfaces.

Code Comparison

Parking Lot (Rust):

use parking_lot::{Mutex, RwLock};

let mutex = Mutex::new(0);
let guard = mutex.lock();
*guard += 1;

Twirp (Go):

import (
    "context"
    "example/proto"
    "github.com/twitchtv/twirp"
)

func (s *ExampleServer) DoSomething(ctx context.Context, req *proto.SomeRequest) (*proto.SomeResponse, error) {
    // Implement the service logic here
    return &proto.SomeResponse{}, nil
}

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

parking_lot

Documentation (synchronization primitives)

Documentation (core parking lot API)

Documentation (type-safe lock API)

This library provides implementations of Mutex, RwLock, Condvar and Once that are smaller, faster and more flexible than those in the Rust standard library, as well as a ReentrantMutex type which supports recursive locking. It also exposes a low-level API for creating your own efficient synchronization primitives.

When tested on x86_64 Linux, parking_lot::Mutex was found to be 1.5x faster than std::sync::Mutex when uncontended, and up to 5x faster when contended from multiple threads. The numbers for RwLock vary depending on the number of reader and writer threads, but are almost always faster than the standard library RwLock, and even up to 50x faster in some cases.

Features

The primitives provided by this library have several advantages over those in the Rust standard library:

Mutex and Once only require 1 byte of storage space, while Condvar and RwLock only require 1 word of storage space. On the other hand on some platforms (macOS and a few others) the standard library primitives require a dynamically allocated Box to hold OS-specific synchronization primitives. The small size of Mutex in particular encourages the use of fine-grained locks to increase parallelism.
Uncontended lock acquisition and release is done through fast inline paths which only require a single atomic operation.
Microcontention (a contended lock with a short critical section) is efficiently handled by spinning a few times while trying to acquire a lock.
The locks are adaptive and will suspend a thread after a few failed spin attempts. This makes the locks suitable for both long and short critical sections.
Condvar, RwLock and Once work on Windows XP, unlike the standard library versions of those types.
RwLock takes advantage of hardware lock elision on processors that support it, which can lead to huge performance wins with many readers. This must be enabled with the hardware-lock-elision feature.
RwLock uses a task-fair locking policy, which avoids reader and writer starvation, whereas the standard library version makes no guarantees.
Condvar is guaranteed not to produce spurious wakeups. A thread will only be woken up if it timed out or it was woken up by a notification.
Condvar::notify_all will only wake up a single thread and requeue the rest to wait on the associated Mutex. This avoids a thundering herd problem where all threads try to acquire the lock at the same time.
RwLock supports atomically downgrading a write lock into a read lock.
Mutex and RwLock allow raw unlocking without a RAII guard object.
Mutex<()> and RwLock<()> allow raw locking without a RAII guard object.
Mutex and RwLock support eventual fairness which allows them to be fair on average without sacrificing performance.
A ReentrantMutex type which supports recursive locking.
An experimental deadlock detector that works for Mutex, RwLock and ReentrantMutex. This feature is disabled by default and can be enabled via the deadlock_detection feature.
RwLock supports atomically upgrading an "upgradable" read lock into a write lock.
Optional support for serde. Enable via the feature serde. NOTE! this support is for Mutex, ReentrantMutex, and RwLock only; Condvar and Once are not currently supported.
Lock guards can be sent to other threads when the send_guard feature is enabled.

The parking lot

To keep these primitives small, all thread queuing and suspending functionality is offloaded to the parking lot. The idea behind this is based on the Webkit WTF::ParkingLot class, which essentially consists of a hash table mapping of lock addresses to queues of parked (sleeping) threads. The Webkit parking lot was itself inspired by Linux futexes, but it is more powerful since it allows invoking callbacks while holding a queue lock.

Nightly vs stable

There are a few restrictions when using this library on stable Rust:

The wasm32-unknown-unknown target is only fully supported on nightly with -C target-feature=+atomics in RUSTFLAGS and -Zbuild-std=panic_abort,std passed to cargo. parking_lot will work mostly fine on stable, the only difference is it will panic instead of block forever if you hit a deadlock. Just make sure not to enable -C target-feature=+atomics on stable as that will allow wasm to run with multiple threads which will completely break parking_lot's concurrency guarantees.

To enable nightly-only functionality, you need to enable the nightly feature in Cargo (see below).

Usage

Add this to your Cargo.toml:

[dependencies]
parking_lot = "0.12"

To enable nightly-only features, add this to your Cargo.toml instead:

[dependencies]
parking_lot = { version = "0.12", features = ["nightly"] }

The experimental deadlock detector can be enabled with the deadlock_detection Cargo feature.

To allow sending MutexGuards and RwLock*Guards to other threads, enable the send_guard option.

Note that the deadlock_detection and send_guard features are incompatible and cannot be used together.

Hardware lock elision support for x86 can be enabled with the hardware-lock-elision feature. This requires Rust 1.59 due to the use of inline assembly.

The core parking lot API is provided by the parking_lot_core crate. It is separate from the synchronization primitives in the parking_lot crate so that changes to the core API do not cause breaking changes for users of parking_lot.

Minimum Rust version

The current minimum required Rust version is 1.56. Any change to this is considered a breaking change and will require a major version bump.

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot