prwlock.h File Reference

Read-write lock. More...

#include <pmacros.h>
#include <ptypes.h>

Go to the source code of this file.

Typedefs
typedef struct PRWLock_	PRWLock
	Read-write lock opaque data structure.

Functions
P_LIB_API PRWLock *	p_rwlock_new (void)
	Creates a new PRWLock object.
P_LIB_API pboolean	p_rwlock_reader_lock (PRWLock *lock)
	Locks a read-write lock for reading.
P_LIB_API pboolean	p_rwlock_reader_trylock (PRWLock *lock)
	Tries to lock a read-write lock for reading immediately.
P_LIB_API pboolean	p_rwlock_reader_unlock (PRWLock *lock)
	Releases a locked for reading read-write lock.
P_LIB_API pboolean	p_rwlock_writer_lock (PRWLock *lock)
	Locks a read-write lock for writing.
P_LIB_API pboolean	p_rwlock_writer_trylock (PRWLock *lock)
	Tries to lock a read-write lock immediately.
P_LIB_API pboolean	p_rwlock_writer_unlock (PRWLock *lock)
	Releases a locked for writing read-write lock.
P_LIB_API void	p_rwlock_free (PRWLock *lock)
	Frees a PRWLock object.

Detailed Description

Read-write lock.

Author

Alexander Saprykin

A read-write lock is a synchronization primitive which allows access to a critical section to not only the one thread, but instead it splits all threads into the two groups:

• reader threads which perform only the reading operations without any shared data modifications;
• writer threads which may perform the shared data modifitcations as well as its reading.

When there are only the reader threads inside a critical section it is called a shared lock - actually you do not need any locking mechanism and all the threads share the lock. In this situation an arbitrary number of reader threads can perform shared data reading.

The situation changes when a writer thread requests access to the same critical section. It will wait until all the current readers finish executing the critical section before acquiring the lock in exclusive manner: no one else can access the critical section until the writer finishes with it. Even another writer thread will have to wait for the lock to be released by the first writer before entering the critical section.

To prevent writer startvation usually writers are in favor over readers, which is actually implementation dependent, though most operating systems try to follow this rule.

A read-write lock is usually used when the writing operations are not performed too frequently, or when the number of reader threads is a way more than writer ones.

A reader enters a critical section with p_rwlock_reader_lock() or p_rwlock_reader_trylock() and exits with p_rwlock_reader_unlock().

A writer enters the critical section with p_rwlock_writer_lock() or p_rwlock_writer_trylock() and exits with p_rwlock_writer_unlock().

Definition in file prwlock.h.

Typedef Documentation

PRWLock

typedef struct PRWLock_ PRWLock

Read-write lock opaque data structure.

Definition at line 79 of file prwlock.h.

Function Documentation

p_rwlock_free()

P_LIB_API void p_rwlock_free

(

PRWLock *

lock

)

Frees a PRWLock object.

Parameters

lock	PRWLock to free.

Since

0.0.1

Warning

It doesn't unlock the lock before freeing memory, so you should do it manually.

p_rwlock_new()

P_LIB_API PRWLock * p_rwlock_new

(

void

)

Creates a new PRWLock object.

Returns

Pointer to a newly created PRWLock object.

Since

0.0.1

p_rwlock_reader_lock()

P_LIB_API pboolean p_rwlock_reader_lock

(

PRWLock *

lock

)

Locks a read-write lock for reading.

Parameters

lock	PRWLock to lock.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).

Forces the calling thread to sleep until the lock becomes available for locking.

p_rwlock_reader_trylock()

P_LIB_API pboolean p_rwlock_reader_trylock

(

PRWLock *

lock

)

Tries to lock a read-write lock for reading immediately.

Parameters

lock	PRWLock to lock.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).

Tries to lock the lock and returns immediately if it is not available for locking.

p_rwlock_reader_unlock()

P_LIB_API pboolean p_rwlock_reader_unlock

(

PRWLock *

lock

)

Releases a locked for reading read-write lock.

Parameters

lock	PRWLock to release.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not use this function on non-locked read-write locks - behavior may be unpredictable.

Do not use this function to unlock a read-write lock which was locked for writing.

If the lock was previously locked for reading then it becomes unlocked.

It's implementation dependent whether only the same thread can lock and unlock the same read-write lock.

p_rwlock_writer_lock()

P_LIB_API pboolean p_rwlock_writer_lock

(

PRWLock *

lock

)

Locks a read-write lock for writing.

Parameters

lock	PRWLock to lock.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).

Forces the calling thread to sleep until the lock becomes available for locking.

p_rwlock_writer_trylock()

P_LIB_API pboolean p_rwlock_writer_trylock

(

PRWLock *

lock

)

Tries to lock a read-write lock immediately.

Parameters

lock	PRWLock to lock.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).

Tries to lock the lock and returns immediately if it is not available for locking.

p_rwlock_writer_unlock()

P_LIB_API pboolean p_rwlock_writer_unlock

(

PRWLock *

lock

)

Releases a locked for writing read-write lock.

Parameters

lock	PRWLock to release.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

Warning

Do not use this function on non-locked read-write locks - behavior may be unpredictable.

Do not use this function to unlock a read-write lock which was locked for reading.

If the lock was previously locked for writing then it becomes unlocked.

It's implementation dependent whether only the same thread can lock and unlock the same read-write lock.