Man page - ck_sequence(3)

Packages contains this manual

Package: libck-dev
apt-get install libck-dev

Manuals in package:

Documentations in package:

libck-dev

Manual

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 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/ July 26, 2013. ck_sequence (3)