DragonFly On-Line Manual Pages

ck_sequence(3)        DragonFly 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_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.