picotm-lib-rwstate.h File Reference

Contains struct picotm_rwstate and helpers. More...

#include "compiler.h"

Data Structures
struct	picotm_rwstate

Macros
#define	PICOTM_RWSTATE_INITIALIZER
	Initializer macro for R/W state variables.

Enumerations
enum	picotm_rwstate_status { PICOTM_RWSTATE_UNLOCKED, PICOTM_RWSTATE_RDLOCKED, PICOTM_RWSTATE_WRLOCKED }

Functions
PICOTM_NOTHROW void	picotm_rwstate_init (struct picotm_rwstate *self)
PICOTM_NOTHROW void	picotm_rwstate_uninit (struct picotm_rwstate *self)
PICOTM_NOTHROW void	picotm_rwstate_set_status (struct picotm_rwstate *self, enum picotm_rwstate_status status)
PICOTM_NOTHROW enum picotm_rwstate_status	picotm_rwstate_get_status (const struct picotm_rwstate *self)
PICOTM_NOTHROW void	picotm_rwstate_try_rdlock (struct picotm_rwstate *self, struct picotm_rwlock *rwlock, struct picotm_error *error)
PICOTM_NOTHROW void	picotm_rwstate_try_wrlock (struct picotm_rwstate *self, struct picotm_rwlock *rwlock, struct picotm_error *error)
PICOTM_NOTHROW void	picotm_rwstate_unlock (struct picotm_rwstate *self, struct picotm_rwlock *rwlock)

Detailed Description

The data structure struct picotm_rwstate represents a transaction's status wrt. shared state.

For example, shared state might be an integer with an associated reader/writer lock.

int i;
struct picotm_rwlock i_lock;

i = 0;
picotm_rwlock_init(&i_lock);

Each transaction accessing the integer i contains a reader/writer state value of type struct picotm_rwstate. The transaction has to initialize the state value with a call to picotm_rwstate_init().

struct picotm_rwstate i_state;

picotm_rwstate_init(&i_state);

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

struct picotm_rwstate i_state = PICOTM_RWSTATE_INITIALIZER;

To safely read the value of resource i, a transaction has to acquire the reader lock i_lock.

struct picotm_error error = PICOTM_ERROR_INITIALIZER;

picotm_rwstate_try_rdlock(&i_state, &i_lock, &error);
if (picotm_error_is_set(&error)) {
    // perform recovery
}

// read i

A call to picotm_rwstate_try_rdlock() acquires a reader lock and sets the transaction's reader/writer state accordingly. If the reader lock could not be acquired, an error is returned. In this case, the transaction should initiate a recovery.

To safely write, a transaction has to acquire the writer lock i_lock.

picotm_rwstate_try_wrlock(&i_state, &i_lock, &error);
if (picotm_error_is_set(&error)) {
    // perform recovery
}

// write i

Depending on the transaction's current reader/writer state, the function picotm_rwstate_try_wrlock() automatically updates a reader lock to a writer lock.

Reader/writer locks can only be acquired once by each transaction, and possibly upgraded once by each transaction. The reader/writer state variable keeps track of the transaction's lock state, so locks can be acquired and upgraded multiple times.

picotm_rwstate_try_wrlock(&i_state, &i_lock, &error);
if (picotm_error_is_set(&error)) {
    // perform recovery
}
picotm_rwstate_try_rdlock(&i_state, &i_lock, &error);
if (picotm_error_is_set(&error)) {
    // perform recovery
}
picotm_rwstate_try_wrlock(&i_state, &i_lock, &error);
if (picotm_error_is_set(&error)) {
    // perform recovery
}

In any case, a reader-writer lock can only be unlocked once, using picotm_rwstate_unlock().

picotm_rwstate_unlock(&i_state, &i_lock);

The current reader/writer state can be queried using picotm_rwstate_get_status(), which returns one of enum picotm_rwstate_status. Using picotm_rwstate_set_status(), the status can also be set explicitly. This might be useful when adopting pre-acquired reader/writer locks, but it's generally preferable to use reader/writer state interfaces for locking and unlocking.

Finally, to uninitialize a reader/writer state the transaction has to call picotm_rwstate_uninit().

picotm_rwstate_uninit(&i_state);

Enumeration Type Documentation

picotm_rwstate_status

enum picotm_rwstate_status

Signals a shared state's status wrt. a transaction

Enumerator
PICOTM_RWSTATE_UNLOCKED	The transaction has not acquired the lock.
PICOTM_RWSTATE_RDLOCKED	The transaction has acquired a reader lock.
PICOTM_RWSTATE_WRLOCKED	The transaction has acquired a writer lock.

Function Documentation

picotm_rwstate_get_status()

PICOTM_NOTHROW enum picotm_rwstate_status picotm_rwstate_get_status

(

const struct picotm_rwstate *

self

)

Returns a reader/writer state's current status.

Parameters

self	The reader/writer state.

Returns

The reader/writer state's status.

picotm_rwstate_init()

PICOTM_NOTHROW void picotm_rwstate_init

(

struct picotm_rwstate *

self

)

Initializes a reader-writer state.

Parameters

self	The reader-writer state to initialize.

picotm_rwstate_set_status()

PICOTM_NOTHROW void picotm_rwstate_set_status	(	struct picotm_rwstate *	self,
		enum picotm_rwstate_status	status
	)

Sets a reader/writer state's status.

Parameters

self	The reader/writer state.
status	The status to set.

Returns

The reader/writer state's status.

picotm_rwstate_try_rdlock()

PICOTM_NOTHROW void picotm_rwstate_try_rdlock	(	struct picotm_rwstate *	self,
		struct picotm_rwlock *	rwlock,
		struct picotm_error *	error
	)

Tries to acquire a reader lock for the state variable. If the lock could not be acquired, the error parameter will return a conflict.

Parameters

	self	The reader/writer state.
	rwlock	The reader lock to acquire.
[out]	error	Returns a error.

picotm_rwstate_try_wrlock()

PICOTM_NOTHROW void picotm_rwstate_try_wrlock	(	struct picotm_rwstate *	self,
		struct picotm_rwlock *	rwlock,
		struct picotm_error *	error
	)

Tries to acquire a writer lock for the state variable or upgrade an acquired reader lock to a writer lock. If the lock could not be acquired, the error parameter will return a conflict.

Parameters

	self	The reader/writer state.
	rwlock	The reader lock to acquire.
[out]	error	Returns a error.

picotm_rwstate_uninit()

PICOTM_NOTHROW void picotm_rwstate_uninit

(

struct picotm_rwstate *

self

)

Uninitializes a reader-writer state.

Parameters

self	The reader-writer state to uninitialize.

picotm_rwstate_unlock()

PICOTM_NOTHROW void picotm_rwstate_unlock	(	struct picotm_rwstate *	self,
		struct picotm_rwlock *	rwlock
	)

Releases a reader-writer lock.

Parameters

self	The reader/writer state.
rwlock	The reader/writer lock to release.