ck_sequence(3) BSD Library Functions Manual ck_sequence(3)NAME
ck_sequence_init, ck_sequence_read_begin, ck_sequence_read_retry,
ck_sequence_write_begin, ck_sequence_write_end — sequence locks
LIBRARY
Concurrency Kit (libck, -lck)
SYNOPSIS
#include <ck_sequence.h>
ck_sequence_t seqlock = CK_SEQUENCE_INITIALIZER;
void
ck_sequence_init(ck_sequence_t *sq);
unsigned int
ck_sequence_read_begin(const ck_sequence_t *sq);
bool
ck_sequence_read_retry(const ck_sequence_t *sq, unsigned int version);
void
ck_sequence_write_begin(ck_sequence_t *sq);
void
ck_sequence_write_end(ck_sequence_t *sq);
DESCRIPTION
It is recommended to use ck_sequence when a small amount of data that
cannot be accessed atomically has to be synchronized with readers in a
fashion that does not block any writer. Readers are able to execute their
read-side critical sections without any atomic operations. A
ck_sequence_t must be initialized before use. It may be initialized using
either a static initializer (CK_SEQUENCE_INITIALIZER) or using
ck_sequence_init(). Before readers attempt to read data that may be con‐
currently modified they must first save the return value of
ck_sequence_read_begin(). While or after a reader has completed copying
the data associated with a ck_sequence_t it must pass the earlier return
value of ck_sequence_read_begin() to ck_sequence_read_retry(). If
ck_sequence_read_retry() returns true then the copy of data may be incon‐
sistent and the read process must be retried. Writers must rely on their
own synchronization primitives. Once a writer has entered its respective
critical section, it must call ck_sequence_write_begin() to signal intent
to update the data protected by the ck_sequence_t. Before the writer
leaves its critical section it must execute ck_sequence_write_end() to
indicate that the updates have left respective objects in a consistent
state.
EXAMPLE
#include <ck_sequence.h>
#include <stdlib.h>
static struct example {
int a;
int b;
int c;
} global;
static ck_sequence_t seqlock = CK_SEQUENCE_INITIALIZER;
void
reader(void)
{
struct example copy;
unsigned int version;
/*
* Attempt a read of the data structure. If the structure
* has been modified between ck_sequence_read_begin and
* ck_sequence_read_retry then attempt another read since
* the data may be in an inconsistent state.
*/
do {
version = ck_sequence_read_begin(&seqlock);
copy = global;
} while (ck_sequence_read_retry(&seqlock, version));
/*
* The previous may also be expressed using CK_SEQUENCE_READ.
* Generally recommend to only use ck_sequence_read_retry
* if you would like to detect a conflicting write at some
* higher granularity.
*/
CK_SEQUENCE_READ(&seqlock, &version) {
copy = global;
}
return;
}
void
writer(void)
{
for (;;) {
ck_sequence_write_begin(&seqlock);
global.a = rand();
global.b = global.a + global.b;
global.c = global.b + global.c;
ck_sequence_write_end(&seqlock);
}
return;
}
SEE ALSOck_brlock(3), ck_bytelock(3), ck_rwlock(3)
Additional information available at http://concurrencykit.org/
July 26, 2013.
