per-thread-mutex

Synchronization lock intended for thread unsafe C libraries.

Rationale

When working with certain C libraries, concurrent accesses are not safe. It can be problematic to model this at the Rust level largely because language level support can't enforce everything that's necessary to maintain safety in all cases.

Send/Sync can ensure that data structures are not used and sent across threads which provides part of the puzzle. However for certain cases thread-unsafe libraries can be used in a multithreaded context provided two conditions are upheld.

1. Data structures are thread-localized, meaning any resource that is created in a thread is never sent or used by another thread. This can be handled by Send/Sync.
2. There can be no concurrent calls into the library. This is not addressed by Rust language level features.

This crate aims to address requirement 2.

How is it used?

The intended use of this mutex is with lazy_static as a global variable in Rust bindings for thread-unsafe C code. The mutex should be locked before each call into the library. This ensures that there are never any concurrent accesses from separate threads which could lead to unsafe behavior.

How does it work?

The lock keeps track of two pieces of data: the thread ID of the thread that currently has the lock acquisition and the number of acquisitions currently active on the lock. Acquisitions from the same thread ID are allowed at the same time and the lock available once all acquisitions of the lock are released.

Why is the same thread permitted to acquire the mutex multiple times?

This largely stems from C's heavy use of callbacks. If a callback is built into a C API, it is typical in Rust bindings to write the callback in Rust and to write a C shim to convert from C to Rust data types. Consider the case of an API call that, in its implementation, calls a callback where the callback also calls a Rust-wrapped API call. This is a safe usage of the library, but would result in a double acquisition of a traditional mutex guarding calls into the library. This lock allows both of those acquisitions to succeed without blocking, preventing the deadlock that would be caused by a traditional mutex while still guard against unsafe accesses of the library.