Add comment explaining that RWTicketSpinLock<..., true> is not reentrant

Test Plan: no, it's a comment

Reviewed By: zanfur@fb.com

Subscribers: folly-diffs@

FB internal diff: D1752850

Tasks: 5823969

Signature: t1:1752850:1419043661:673c68c0daad28b3fde9709e767b528b0dec8ad1

diff --git a/folly/RWSpinLock.h b/folly/RWSpinLock.h
index f47def6023a77ed600c796cc4a70aa803ceb61cd..c6bec8df0a3bc9d5c58a30fbd7bf6235e04f2d90 100644 (file)
--- a/folly/RWSpinLock.h
+++ b/folly/RWSpinLock.h
@@ -46,6 +46,18 @@
  *    RWTicketSpinLock<64> only allows up to 2^16 - 1 concurrent
  *    readers and writers.
  *
+ *    RWTicketSpinLock<..., true> (kFavorWriter = true, that is, strict
+ *    writer priority) is NOT reentrant, even for lock_shared().
+ *
+ *    The lock will not grant any new shared (read) accesses while a thread
+ *    attempting to acquire the lock in write mode is blocked. (That is,
+ *    if the lock is held in shared mode by N threads, and a thread attempts
+ *    to acquire it in write mode, no one else can acquire it in shared mode
+ *    until these N threads release the lock and then the blocked thread
+ *    acquires and releases the exclusive lock.) This also applies for
+ *    attempts to reacquire the lock in shared mode by threads that already
+ *    hold it in shared mode, making the lock non-reentrant.
+ *
  *    RWSpinLock handles 2^30 - 1 concurrent readers.
  *
  * @author Xin Liu <xliux@fb.com>