Converts the specified reader-writer lock from read mode to write mode.
#include <nks/synch.h>
int NXRwLockUpgrade (
NXRwLock_t *lock);
(IN) Points to the reader-writer lock to upgrade.
If successful, returns 0; otherwise returns a nonzero error code:
The specified lock must be a lock already acquired in read mode and the lock must be owned by the calling thread.
The first thread, which should have acquired the read lock previously, that requests this upgrade is guaranteed to acquire it before any waiting writers. Hence, when this call returns successfully, the calling thread no longer holds a read lock, but owns the write lock which obviously no other writer is granted.
The advantage of an upgrade operation when compared to releasing a read lock to then acquire the write lock is that, if successful, the acquiring thread can be assured that the data protected by the lock has not been modified in the intervening moments of the upgrade. Consequently, it need not re-examine the data protected by the lock to see if it has changed.