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

FreeBSD Manual Pages

  
 
  

home | help
ck_sequence(3)	       FreeBSD 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_se-
     quence_t must be initialized before use. It may be	initialized using ei-
     ther 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 ALSO
     ck_brlock(3), ck_bytelock(3), ck_rwlock(3)

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

				July 26, 2013.

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO

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

home | help