The RwLock is the parallel equivalent of the RefCell we worked with in Chapter 5, Advanced Data Structures; Working with interior mutability. The big difference is that, while RefCell panics on a violation of Rust's ownership concept, RwLock simply blocks the current thread until the violation is over.

The analog of the borrow() method of RefCell is read() [17], which locks the resource for immutable access. The analog of borrow_mut() is write() [51], which locks the resource for mutable access. Makes sense, doesn't it?

These methods return a Result, which tells us whether the thread is poisoned. The meaning of poisoning is different for every lock. In an RwLock, it means that the thread that locked the resource for write access panicked. This way, you can react to panics in other threads and treat them in some way. One example where this can be useful is sending some logs to a server before a crash happens in order to diagnose the problem. In most cases, though, it will be okay if you simply panic along, as a panic usually stands for a critical failure that cannot be mended.

In our example, we demonstrate the concept by setting up two threads that request read access: reader_a [11] and reader_b [27]. Because an RwLock allows multiple readers, they will concurrently print out the value of our resource [19 and 35]. In the meantime, writer [45] tries to lock the resource for write access. It will have to wait until both reader_a and reader_b are currently not using the resource. By the same rules, when the writer gets their turn and mutates the resource [54], both reader_a and reader_b have to wait until it's done.

Because all of this happens roughly at the same time, every execution of this example is going to give you slightly different results. I encourage you to run the program multiple times and compare the output.