ck_sequence man page

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 concurrently 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 inconsistent 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 Also

ck_brlock(3), ck_bytelock(3), ck_rwlock(3)

Additional information available at http://concurrencykit.org/

Info

July 26, 2013.