Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 concur-
     rently access an object, providing	a consistent snapshot of the object
     for readers.  No mutual exclusion between readers and writers is re-
     quired, 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	previ-
     ously fetched value.  The oldseqc variable	should contain a sequence num-
     ber 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 modi-
     fied, 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
     the obj structure.	 In the	case where the sequence	number was changed it
     restarts the whole	process.

     int var1, var2;
     seqc_t seqc;

     for (;;) {
	     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 extend-
     ing the interface to allow	64-bit counters.

FreeBSD	13.0			 July 29, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=seqc_consistent&sektion=9&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help