picotm_rwlock Struct Reference

A reader-writer lock. More...

#include <picotm/picotm-lib-rwlock.h>

Data Fields
atomic_uint_least8_t	n

Detailed Description

The struct picotm_rwlock data structure implements a reader-writer lock. Each instance can only be acquired at most once by each transaction. The implementation does not track which transactions acquired the lock, so transactions have to ensure that they acquire each lock at most once.

Before using an instance of struct picotm_rwlock, initialize as show below.

struct picotm_rwlock rwlock;

picotm_rwlock_init(&rwlock);

The function picotm_rwlock_init() cannot fail. All fields of the structure are private.

Alternatively, the macro PICOTM_RWLOCK_INITIALIZER initializes a static or stack-allocated R/W-lock variable. If both, function and macro initialization, is possible, the macro form is prefered.

struct picotm_rwlock rwlock = PICOTM_RWLOCK_INITIALIZER;

Likewise, uninitialize with picotm_rwlock_uninit() as shown below.

picotm_rwlock_uninit(&rwlock);

The function picotm_rwlock_try_rdlock() acquires a reader lock. With too many readers, the function fails with a conflict. You should always check the error parameter and perform recovery if necessary.

struct picotm_error error;

picotm_rwlock_try_rdlock(&rwlock, &error);
if (picotm_error_is_set(&error)) {
    // probably busy; start recovery
}

The function picotm_rwlock_try_wrlock() acquires a writer lock, or upgrades a transaction's reader lock to a writer lock. With concurrent users, the function fails with a conflict. A reader lock can be updated to a writer lock at most once.

As with picotm_rwlock_try_rdlock(), you should always check the error parameter and perform recovery if necessary.

// Upgrade to writer lock
picotm_rwlock_try_wrlock(&rwlock, true, &error);
if (picotm_error_is_set(&error)) {
    // concurrent users; start recovery
}

Field Documentation

n

atomic_uint_least8_t picotm_rwlock::n

counter variable