1ck_sequence(3)           BSD Library Functions Manual           ck_sequence(3)
2

NAME

4     ck_sequence_init, ck_sequence_read_begin, ck_sequence_read_retry,
5     ck_sequence_write_begin, ck_sequence_write_end — sequence locks
6

LIBRARY

8     Concurrency Kit (libck, -lck)
9

SYNOPSIS

11     #include <ck_sequence.h>
12
13     ck_sequence_t seqlock = CK_SEQUENCE_INITIALIZER;
14
15     void
16     ck_sequence_init(ck_sequence_t *sq);
17
18     unsigned int
19     ck_sequence_read_begin(const ck_sequence_t *sq);
20
21     bool
22     ck_sequence_read_retry(const ck_sequence_t *sq, unsigned int version);
23
24     void
25     ck_sequence_write_begin(ck_sequence_t *sq);
26
27     void
28     ck_sequence_write_end(ck_sequence_t *sq);
29

DESCRIPTION

31     It is recommended to use ck_sequence when a small amount of data that
32     cannot be accessed atomically has to be synchronized with readers in a
33     fashion that does not block any writer. Readers are able to execute their
34     read-side critical sections without any atomic operations. A
35     ck_sequence_t must be initialized before use. It may be initialized using
36     either a static initializer (CK_SEQUENCE_INITIALIZER) or using
37     ck_sequence_init().  Before readers attempt to read data that may be con‐
38     currently modified they must first save the return value of
39     ck_sequence_read_begin().  While or after a reader has completed copying
40     the data associated with a ck_sequence_t it must pass the earlier return
41     value of ck_sequence_read_begin() to ck_sequence_read_retry(). If
42     ck_sequence_read_retry() returns true then the copy of data may be incon‐
43     sistent and the read process must be retried. Writers must rely on their
44     own synchronization primitives.  Once a writer has entered its respective
45     critical section, it must call ck_sequence_write_begin() to signal intent
46     to update the data protected by the ck_sequence_t. Before the writer
47     leaves its critical section it must execute ck_sequence_write_end() to
48     indicate that the updates have left respective objects in a consistent
49     state.
50

EXAMPLE

52           #include <ck_sequence.h>
53           #include <stdlib.h>
54
55           static struct example {
56                   int a;
57                   int b;
58                   int c;
59           } global;
60
61           static ck_sequence_t seqlock = CK_SEQUENCE_INITIALIZER;
62
63           void
64           reader(void)
65           {
66                   struct example copy;
67                   unsigned int version;
68
69                   /*
70                    * Attempt a read of the data structure. If the structure
71                    * has been modified between ck_sequence_read_begin and
72                    * ck_sequence_read_retry then attempt another read since
73                    * the data may be in an inconsistent state.
74                    */
75                   do {
76                           version = ck_sequence_read_begin(&seqlock);
77                           copy = global;
78                   } while (ck_sequence_read_retry(&seqlock, version));
79
80                   /*
81                    * The previous may also be expressed using CK_SEQUENCE_READ.
82                    * Generally recommend to only use ck_sequence_read_retry
83                    * if you would like to detect a conflicting write at some
84                    * higher granularity.
85                    */
86                   CK_SEQUENCE_READ(&seqlock, &version) {
87                           copy = global;
88                   }
89
90                   return;
91           }
92
93           void
94           writer(void)
95           {
96
97                   for (;;) {
98                           ck_sequence_write_begin(&seqlock);
99                           global.a = rand();
100                           global.b = global.a + global.b;
101                           global.c = global.b + global.c;
102                           ck_sequence_write_end(&seqlock);
103                   }
104
105                   return;
106           }
107

SEE ALSO

109     ck_brlock(3), ck_bytelock(3), ck_rwlock(3)
110
111     Additional information available at http://concurrencykit.org/
112
113                                July 26, 2013.