FreeBSD manual

download PDF document: seqc_write_begin.9.pdf

SEQC(9) FreeBSD Kernel Developer's Manual SEQC(9)
NAME seqc_consistent, seqc_read, seqc_write_begin, seqc_write_end - lockless read algorithm
SYNOPSIS #include <sys/seqc.h>
void seqc_write_begin(seqc_t *seqcp);
void seqc_write_end(seqc_t *seqcp);
seqc_t seqc_read(seqc_t *seqcp);
seqc_t seqc_consistent(const seqc_t *seqcp, seqc_t oldseqc);
DESCRIPTION The seqc allows zero or more readers and zero or one writer to concurrently access an object, providing a consistent snapshot of the object for readers. No mutual exclusion between readers and writers is required, but readers may be starved indefinitely by writers.
The functions seqc_write_begin() and seqc_write_end() are used to create a transaction for writer, and notify the readers that the object will be modified.
The seqc_read() function returns the current sequence number. If a writer has started a transaction, this function will spin until the transaction has ended.
The seqc_consistent() function compares the sequence number with a previously fetched value. The oldseqc variable should contain a sequence number from the beginning of read transaction.
The reader at the end of a transaction checks if the sequence number has changed. If the sequence number didn't change the object wasn't modified, and fetched variables are valid. If the sequence number changed the object was modified and the fetch should be repeated. In case when sequence number is odd the object change is in progress and the reader will wait until the write will the sequence number will become even.
EXAMPLES The following example for a writer changees the var1 and var2 variables in the obj structure:
lock_exclusive(&obj->lock); seqc_write_begin(&obj->seqc); obj->var1 = 1; obj->var2 = 2; seqc_write_end(&obj->seqc); unlock_exclusive(&obj->lock);
The following example for a reader reads the var1 and var2 variables from seqc = seqc_read(&obj->seqc); var1 = obj->var1; var2 = obj->var2; if (seqc_consistent(&obj->seqc, seqc)) break; }
AUTHORS The seqc functions was implemented by Mateusz Guzik <mjg@FreeBSD.org>. This manual page was written by Mariusz Zaborski <oshogbo@FreeBSD.org>.
CAVEATS There is no guarantee of progress for readers. In case when there are a lot of writers the reader can be starved. This concern may be solved by returning error after a few attempts.
Theoretically if reading takes a very long time, and when there are many writers the counter may overflow and wrap around to the same value. In that case the reader will not notice that the object was changed. Given that this needs 4 billion transactional writes across a single contended reader, it is unlikely to ever happen. This could be avoided by extending the interface to allow 64-bit counters.
FreeBSD 14.0-RELEASE-p11 July 29, 2019 FreeBSD 14.0-RELEASE-p11