read_seqbegin_or_lock(9)

💅 read_seqbegin_or_lock(9) — Kernel API Manual, bestie edition 🎀

okay so this one's from the Linux Kernel API Manual and honestly? it's giving "smart girl optimist energy" the whole way through. let's get into it ✨

---

🌸 NAME 🌸

read_seqbegin_or_lock — it kicks off a seqlock_t reader that's either lockless OR locking, and the fun part is it decides which one on the fly 💫

---

✨ SYNOPSIS ✨

void read_seqbegin_or_lock (seqlock_t *lock , int *seq );

---

🦋 ARGUMENTS 🦋

• lock — a pointer to your seqlock_t. that's it, that's the whole vibe.
• seq — bestie this one's both a marker AND a return parameter, it's literally doing two jobs (main character energy, work ethic, we love her 👑). here's the tea:
  • if the value you pass in is even, the reader becomes a *lockless* seqlock_t reader, exactly like in read_seqbegin.
  • if the value you pass in is odd, the reader becomes a *locking* reader, exactly like in read_seqlock_excl.
  • and on the first call to this function, the caller *must* initialize and pass an even value to seq. this is so a lockless read can be optimistically tried first — shoot your shot, y'know? 🙈

---

💖 DESCRIPTION 💖

read_seqbegin_or_lock is an API designed to optimistically try a normal lockless seqlock_t read section first. like, manifest the fast path, believe in it 💫

if an odd counter is found, that means the lockless read trial has failed, and the next read iteration transforms itself into a full seqlock_t locking reader. character development honestly 😭

this is typically used to avoid seqlock_t lockless readers starvation (too much retry loops) in the case of a sharp spike in write side activity.

ngl please check Documentation/locking/seqlock.rst for template example code — there's a whole example waiting for you there 🫶

---

🔥 CONTEXT 🔥

if the seqlock_t write section, *or other read sections*, can be invoked from hardirq or softirq contexts — then use the _irqsave or _bh variant of this function instead. no exceptions, this is a vibe check you do NOT wanna skip 💀

---

⭐ RETURN ⭐

the encountered sequence counter value, through the seq parameter, which is overloaded as a return parameter (like we said — double duty queen 💅).

this returned value must be checked with need_seqretry. and if the read section needs to be retried, this returned value must also be passed as the seq parameter of the next read_seqbegin_or_lock iteration. yes bestie it's a loop, it comes back around, that's the whole bit 🔁

---

🌈 SEE ALSO 🌈

Kernel file ./include/linux/seqlock.h seqcount_init(9), SEQCNT_ZERO(9), __read_seqcount_begin(9), raw_read_seqcount_begin(9), read_seqcount_begin(9), raw_read_seqcount(9), raw_seqcount_try_begin(9), raw_seqcount_begin(9), __read_seqcount_retry(9), read_seqcount_retry(9), raw_write_seqcount_begin(9), raw_write_seqcount_end(9), write_seqcount_begin_nested(9), write_seqcount_begin(9), write_seqcount_end(9), raw_write_seqcount_barrier(9), write_seqcount_invalidate(9), SEQCNT_LATCH_ZERO(9), seqcount_latch_init(9), raw_read_seqcount_latch(9), read_seqcount_latch(9), raw_read_seqcount_latch_retry(9), read_seqcount_latch_retry(9), raw_write_seqcount_latch(9), write_seqcount_latch_begin(9), write_seqcount_latch(9), write_seqcount_latch_end(9), seqlock_init(9), DEFINE_SEQLOCK(9), read_seqbegin(9), read_seqretry(9), write_seqlock(9), write_sequnlock(9), write_seqlock_bh(9), write_sequnlock_bh(9), write_seqlock_irq(9), write_sequnlock_irq(9), write_seqlock_irqsave(9), write_sequnlock_irqrestore(9), read_seqlock_excl(9), read_sequnlock_excl(9), read_seqlock_excl_bh(9), read_sequnlock_excl_bh(9), read_seqlock_excl_irq(9), read_sequnlock_excl_irq(9), read_seqlock_excl_irqsave(9), read_seqlock_excl_irqrestore(9), need_seqretry(9), done_seqretry(9), read_seqbegin_or_lock_irqsave(9), done_seqretry_irqrestore(9), scoped_seqlock_read(9)

like, that's the whole friend group right there, they all show up to the function 💜

---

that's it bestie!! go be optimistic, try the lockless path first, and remember to retry 💅 🦋

mwah 💋 — this lil page lives in ./include/linux, dated October 2026. iykyk 🎀