ovs_mutex_unlock(&seq_mutex);
}
-/* Returns 'seq''s current sequence number (which could change immediately). */
+/* Returns 'seq''s current sequence number (which could change immediately).
+ *
+ * seq_read() and seq_wait() can be used together to yield a race-free wakeup
+ * when an object changes, even without an ability to lock the object. See
+ * Usage in seq.h for details. */
uint64_t
seq_read(const struct seq *seq)
OVS_EXCLUDED(seq_mutex)
/* Causes the following poll_block() to wake up when 'seq''s sequence number
* changes from 'value'. (If 'seq''s sequence number isn't 'value', then
- * poll_block() won't block at all.) */
+ * poll_block() won't block at all.)
+ *
+ * seq_read() and seq_wait() can be used together to yield a race-free wakeup
+ * when an object changes, even without an ability to lock the object. See
+ * Usage in seq.h for details. */
void
seq_wait(const struct seq *seq_, uint64_t value)
OVS_EXCLUDED(seq_mutex)
/* Thread-safe, pollable sequence number.
*
*
- * Background
+ * Motivation
* ==========
*
* It is sometimes desirable to take an action whenever an object changes.
* poll_block();
*
*
+ * Alternate Usage
+ * ===============
+ *
+ * struct seq can also be used as a sort of pollable condition variable.
+ * Suppose that we want a thread to process items in a queue, and thus to be
+ * able to wake up whenever the queue is nonempty. This requires a lock to
+ * protect the queue and a seq to signal that the queue has become nonempty,
+ * e.g.:
+ *
+ * struct ovs_mutex mutex;
+ * struct list queue OVS_GUARDED_BY(mutex);
+ * struct seq nonempty_seq;
+ *
+ * To add an element to the queue:
+ *
+ * ovs_mutex_lock(&mutex);
+ * list_push_back(&queue, ...element...);
+ * if (list_is_singleton(&queue)) { // The 'if' test here is optional.
+ * seq_change(&nonempty_seq);
+ * }
+ * ovs_mutex_unlock(&mutex);
+ *
+ * To wait for the queue to become nonempty:
+ *
+ * ovs_mutex_lock(&mutex);
+ * if (list_is_empty(&queue)) {
+ * seq_wait(&nonempty_seq, seq_read(&nonempty_seq));
+ * } else {
+ * poll_immediate_wake();
+ * }
+ * ovs_mutex_unlock(&mutex);
+ *
+ * (In the above code 'mutex' prevents the queue from changing between
+ * seq_read() and seq_wait(). Otherwise, it would be necessary to seq_read(),
+ * check for a nonempty queue, and then seq_wait() on the previously read
+ * sequence number, as under Usage above.)
+ *
+ *
* Thread-safety
* =============
*