Seqlock

Sequence Lock. More...

Collaboration diagram for Seqlock:

Detailed Description

Sequence Lock.

A sequence lock is similar to a read-write lock, but optimized for scenarios where there are many more readers than writers, or where reads are frequent and writes are rare.

Readers can read the data without acquiring a lock, instead they check a "sequence number" before and after their read to verify that no write occured during their read, if one did, they must retry their read.

Writers acquire the lock exclusively and increment the "sequence number" before and after their write, this means that readers can detect if a write has occured, and if a write is currently in progress by checking if the sequence number is odd.

Data Structures
struct	seqlock_t
	Sequence lock structure. More...

Macros
#define	SEQLOCK_CREATE()   {.sequence = ATOMIC_VAR_INIT(0), .writeLock = LOCK_CREATE()}
	Create a sequence lock initializer.
#define	SEQLOCK_READ_SCOPE(seqlock)
	Read scope for a sequence lock.

Functions
static void	seqlock_init (seqlock_t *seqlock)
	Initializes a sequence lock.
static void	seqlock_write_acquire (seqlock_t *seqlock)
	Acquires the write lock of a sequence lock.
static void	seqlock_write_release (seqlock_t *seqlock)
	Releases the write lock of a sequence lock.
static uint64_t	seqlock_read_begin (seqlock_t *seqlock)
	Begins a read operation on a sequence lock.
static bool	seqlock_read_retry (seqlock_t *seqlock, uint64_t seq)
	Checks if a read operation on a sequence lock needs to be retried.

Macro Definition Documentation

SEQLOCK_CREATE

#define SEQLOCK_CREATE

(

)

{.sequence = ATOMIC_VAR_INIT(0), .writeLock = LOCK_CREATE()}

Create a sequence lock initializer.

Returns

A seqlock_t initializer.

Definition at line 40 of file seqlock.h.

SEQLOCK_READ_SCOPE

#define SEQLOCK_READ_SCOPE

(

seqlock

)

Value:

    for (uint64_t __seq = seqlock_read_begin(seqlock); \
        seqlock_read_retry(seqlock, __seq) ? (__seq = seqlock_read_begin(seqlock), true) : false;)

Read scope for a sequence lock.

Example usage:

SEQLOCK_READ_SCOPE(&seqlock)
{
    // read data here
}

Parameters

seqlock

Pointer to the sequence lock.

Definition at line 125 of file seqlock.h.

Function Documentation

seqlock_init()

static void seqlock_init ( seqlock_t *  seqlock )

inlinestatic

Initializes a sequence lock.

Parameters

seqlock

Pointer to the sequence lock to initialize.

Definition at line 47 of file seqlock.h.

Here is the call graph for this function:

seqlock_write_acquire()

static void seqlock_write_acquire ( seqlock_t *  seqlock )

inlinestatic

Acquires the write lock of a sequence lock.

This function busy-waits until the write lock is acquired.

Parameters

seqlock

Pointer to the sequence lock.

Definition at line 60 of file seqlock.h.

Here is the call graph for this function:

Here is the caller graph for this function:

seqlock_write_release()

static void seqlock_write_release ( seqlock_t *  seqlock )

inlinestatic

Releases the write lock of a sequence lock.

Parameters

seqlock

Pointer to the sequence lock.

Definition at line 71 of file seqlock.h.

Here is the call graph for this function:

Here is the caller graph for this function:

seqlock_read_begin()

static uint64_t seqlock_read_begin ( seqlock_t *  seqlock )

inlinestatic

Begins a read operation on a sequence lock.

Should be called in a loop, for example:

uint64_t seq;
do {
   seq = seqlock_read_begin(&seqlock);
  // read data here
} while (seqlock_read_retry(&seqlock, seq));

Or use the SEQLOCK_READ_SCOPE() macro.

Parameters

seqlock

Pointer to the sequence lock.

Returns

The current sequence number.

Definition at line 94 of file seqlock.h.

Here is the caller graph for this function:

seqlock_read_retry()

static bool seqlock_read_retry ( seqlock_t *  seqlock, uint64_t  seq  )

inlinestatic

Checks if a read operation on a sequence lock needs to be retried.

Parameters

seqlock	Pointer to the sequence lock.
seq	The sequence number returned by seqlock_read_begin().

Returns

true if the read operation needs to be retried, false otherwise.

Definition at line 106 of file seqlock.h.

Here is the caller graph for this function: