cu/rarex.h: Read-Write Locks Optimised for Rarely Excluding Cases
[Utilities]

Defines
#define	cuP_RAREX_WRITE_MULTIPLIER   0x10000
#define	cu_rarex_cct   cu_rarex_init
Functions
void	cu_rarex_init (cu_rarex_t *rarex)
void	cu_rarex_lock_read (cu_rarex_t *rarex)
void	cu_rarex_unlock_read (cu_rarex_t *rarex)
cu_bool_t	cu_rarex_trylock_read (cu_rarex_t *rarex)
void	cu_rarex_lock_write (cu_rarex_t *rarex)
cu_bool_t	cu_rarex_trylock_write (cu_rarex_t *rarex)
void	cu_rarex_unlock_write (cu_rarex_t *rarex)
cu_bool_t	cu_rarex_try_promote (cu_rarex_t *rarex)

---

Detailed Description

Rarices are read-write locks implemented with a single word per lock (in addition to some per-thread data). They are cheap as long as they are read-locked, or write access do not conflict with another read or write, but significantly more expensive than mutices when they clog. In other words, use this only when two threads hardly ever compete for the same lock.

If each of N threads spends p of its time accessing the lock (exclusive or not), then is the probability that a thread can acquire a write lock without delay. Note the locking time is included in . For good efficiency keep .

If unsure, use pthread_mutex_t or similar instead.

---

Define Documentation

#define cu_rarex_cct   cu_rarex_init

Deprecated:

Use cu_rarex_init.

#define cuP_RAREX_WRITE_MULTIPLIER   0x10000

---

Function Documentation

void cu_rarex_init

(

cu_rarex_t *

rarex

)

Construct the rarex lock.

void cu_rarex_lock_read

(

cu_rarex_t *

rarex

)

Lock for non-exclusive access. May be called recursively, and should have matching calls to cu_rarex_unlock_read.

void cu_rarex_lock_write

(

cu_rarex_t *

rarex

)

Lock for exclusive access. Caller must not own any access to any cu_rarex_t locks advance.

cu_bool_t cu_rarex_try_promote

(

cu_rarex_t *

rarex

)

Attempts to promote a read lock to a write lock. Returns non-zero on success, otherwise the lock remains for read-access. Note that depending on the outcome, caller must either use cu_rarex_unlock_read or cu_rarex_unlock_write to unlock.

cu_bool_t cu_rarex_trylock_read

(

cu_rarex_t *

rarex

)

Try to lock for non-exclusive access without blocking. Returns true iff successful.

cu_bool_t cu_rarex_trylock_write

(

cu_rarex_t *

rarex

)

Try to lock for exclusive access without blocking. Returns true iff successful.

void cu_rarex_unlock_read

(

cu_rarex_t *

rarex

)

Unlock non-exclusive access.

void cu_rarex_unlock_write

(

cu_rarex_t *

rarex

)

Release exclusive access.