lib: Adding GR capabilites encode and decode.

[mirror_frr.git] / lib / seqlock.h

diff --git a/lib/seqlock.h b/lib/seqlock.h
index eef05a4307ec5168703e3a5df44ad6c8586ab3bc..b551e3ffc4dad1c78fbd9612fe5465128a127498 100644 (file)
--- a/lib/seqlock.h
+++ b/lib/seqlock.h
@@ -54,12 +54,28 @@
  */
 
 /* use sequentially increasing "ticket numbers".  lowest bit will always
- * be 1 to have a 'cleared' indication (i.e., counts 1,3,5,7,etc. )
+ * be 1 to have a 'cleared' indication (i.e., counts 1,5,9,13,etc. )
+ * 2nd lowest bit is used to indicate we have waiters.
  */
 typedef _Atomic uint32_t       seqlock_ctr_t;
 typedef uint32_t               seqlock_val_t;
-#define seqlock_assert_valid(val) assert(val & 1)
+#define seqlock_assert_valid(val) assert((val) & SEQLOCK_HELD)
 
+/* NB: SEQLOCK_WAITERS is only allowed if SEQLOCK_HELD is also set; can't
+ * have waiters on an unheld seqlock
+ */
+#define SEQLOCK_HELD           (1U << 0)
+#define SEQLOCK_WAITERS                (1U << 1)
+#define SEQLOCK_VAL(n)         ((n) & ~SEQLOCK_WAITERS)
+#define SEQLOCK_STARTVAL       1U
+#define SEQLOCK_INCR           4U
+
+/* TODO: originally, this was using "atomic_fetch_add", which is the reason
+ * bit 0 is used to indicate held state.  With SEQLOCK_WAITERS added, there's
+ * no fetch_add anymore (cmpxchg loop instead), so we don't need to use bit 0
+ * for this anymore & can just special-case the value 0 for it and skip it in
+ * counting.
+ */
 
 struct seqlock {
 /* always used */
@@ -74,8 +90,16 @@ struct seqlock {
 extern void seqlock_init(struct seqlock *sqlo);
 
 
-/* while (sqlo <= val) - wait until seqlock->pos > val, or seqlock unheld */
+/* basically: "while (sqlo <= val) wait();"
+ * returns when sqlo > val || !seqlock_held(sqlo)
+ */
 extern void seqlock_wait(struct seqlock *sqlo, seqlock_val_t val);
+
+/* same, but time-limited (limit is an absolute CLOCK_MONOTONIC value) */
+extern bool seqlock_timedwait(struct seqlock *sqlo, seqlock_val_t val,
+                             const struct timespec *abs_monotime_limit);
+
+/* one-shot test, returns true if seqlock_wait would return immediately */
 extern bool seqlock_check(struct seqlock *sqlo, seqlock_val_t val);
 
 static inline bool seqlock_held(struct seqlock *sqlo)
@@ -85,12 +109,20 @@ static inline bool seqlock_held(struct seqlock *sqlo)
 
 /* sqlo - get seqlock position -- for the "counter" seqlock */
 extern seqlock_val_t seqlock_cur(struct seqlock *sqlo);
-/* sqlo++ - note: like x++, returns previous value, before bumping */
+
+/* ++sqlo (but atomic & wakes waiters) - returns value that we bumped to.
+ *
+ * guarantees:
+ *  - each seqlock_bump call bumps the position by exactly one SEQLOCK_INCR.
+ *    There are no skipped/missed or multiple increments.
+ *  - each return value is only returned from one seqlock_bump() call
+ */
 extern seqlock_val_t seqlock_bump(struct seqlock *sqlo);
 
 
 /* sqlo = val - can be used on held seqlock. */
 extern void seqlock_acquire_val(struct seqlock *sqlo, seqlock_val_t val);
+
 /* sqlo = ref - standard pattern: acquire relative to other seqlock */
 static inline void seqlock_acquire(struct seqlock *sqlo, struct seqlock *ref)
 {