This addresses the need for clarification brought up in an issue.
Specifically, it notes that some implementations may choose to panic if
they detect deadlock situations during recursive locking attempts for
both `read()` and `write()` calls.
* Provide an example highlighting that multiple read locks can be
held across different threads simultaneously.
* Remove the example that shows a situation that can potentially deadlock.
(as demonstrated in the very same documentation a few paragraphs
above)
* Improve documentation regarding the possibility of panics during
recursive read or write lock attempts.
Issues: Ambiguity in RwLock documentation about multiple read() calls...
Signed-off-by: Henner Zeller <h.zeller@acm.org>
27f97d7f71