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)