rte_seqcount.h(3)

📦
version 25.11.3 · 10 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_seqcount.h(3) 💖

okay bestie, welcome to the Library Functions Manual entry for rte_seqcount.h — yes that's a section 3 page, we're doing C library functions today, and honestly? she's iconic. this is the header that gives you the sequence counter, which is the whole entire foundation of the RTE sequence lock. buckle up 🎀

✨ NAME ✨

rte_seqcount.h — no cap, that's the whole name, that's her 💅

🌸 SYNOPSIS 🌸

first things first, you gotta pull in the vibes:

#include <stdbool.h>
#include <stdint.h>
#include <rte_atomic.h>
#include <rte_branch_prediction.h>
#include <rte_stdatomic.h>

🦋 Data Structures

  • struct rte_seqcount_t — the main character herself

🎀 Macros

#define RTE_SEQCOUNT_INITIALIZER   { .sn = 0 }

👑 Functions

static void rte_seqcount_init (rte_seqcount_t *seqcount)

static uint32_t rte_seqcount_read_begin (const rte_seqcount_t *seqcount)

static bool rte_seqcount_read_retry (const rte_seqcount_t *seqcount,
    uint32_t begin_sn)

static void rte_seqcount_write_begin (rte_seqcount_t *seqcount)

static void rte_seqcount_write_end (rte_seqcount_t *seqcount)

💜 Detailed Description 💜

RTE Seqcount

so like. the sequence counter synchronizes a single writer with multiple, parallel readers. that's the whole plot. and it's used as the basis for the RTE sequence lock — like, rte_seqlock.h is literally built on top of this girlie.

See also

  • rte_seqlock.h

Definition in file rte_seqcount.h.

🌟 Macro Definition Documentation 🌟

#define RTE_SEQCOUNT_INITIALIZER { .sn = 0 }

a static seqcount initializer. that's it, that's the tea 💅

Definition at line 40 of file rte_seqcount.h.

🔥 Function Documentation 🔥

void rte_seqcount_init (rte_seqcount_t * seqcount) [inline], [static]

Initialize the sequence counter. yass, set her up, give her a fresh start ✨

Parameters

  • seqcount — A pointer to the sequence counter.

Definition at line 49 of file rte_seqcount.h.

uint32_t rte_seqcount_read_begin (const rte_seqcount_t * seqcount) [inline], [static]

Begin a read-side critical section.

okay so calling this function marks the beginning of a read-side critical section, for seqcount. it's giving "enter the zone" 🚪✨

rte_seqcount_read_begin() returns a sequence number, which is later used in rte_seqcount_read_retry() to check if the protected data underwent any modifications during the read transaction. so hold onto that number, bestie, it's your receipt 🧾

after (in program order) rte_seqcount_read_begin() has been called, the calling thread reads the protected data, for later use. and listen — the protected data read must be copied (either in pristine form, or in the form of some derivative), since the caller may only read the data from within the read-side critical section (i.e., after rte_seqcount_read_begin() and before rte_seqcount_read_retry()), but must not act upon the retrieved data while in the critical section, since it does not yet know if it is consistent. no acting on unverified data, that's the rule 🙈

the protected data may be read using atomic and/or non-atomic operations. both slay equally here.

after (in program order) all required data loads have been performed, rte_seqcount_read_retry() should be called, marking the end of the read-side critical section.

if rte_seqcount_read_retry() returns true, the just-read data is inconsistent and should be discarded. the caller has the option to either restart the whole procedure right away (i.e., calling rte_seqcount_read_begin() again), or do the same at some later time. your call, main character 🫶

if rte_seqcount_read_retry() returns false, the data was read atomically and the copied data is consistent. periodt. 💅

Parameters

  • seqcount — A pointer to the sequence counter.

Returns

  • The seqcount sequence number for this critical section, to later be passed to rte_seqcount_read_retry().

See also

  • rte_seqcount_read_retry()

Definition at line 97 of file rte_seqcount.h.

bool rte_seqcount_read_retry (const rte_seqcount_t * seqcount, uint32_t begin_sn) [inline], [static]

End a read-side critical section.

a call to this function marks the end of a read-side critical section, for seqcount. the application must supply the sequence number produced by the corresponding rte_seqcount_read_begin() call — that's the begin_sn, the receipt from earlier 🧾✨

after this function has been called, the caller should not access the protected data. like, we're done here, put it down 🙅‍♀️

in case rte_seqcount_read_retry() returns true, the just-read data was modified as it was being read and may be inconsistent, and thus should be discarded. throwing it out, no hesitation 💀

in case this function returns false, the data is consistent and the set of atomic and non-atomic load operations performed between rte_seqcount_read_begin() and rte_seqcount_read_retry() were atomic, as a whole. as a whole bestie, the whole entire vibe check passed 🌈

Parameters

  • seqcount — A pointer to the sequence counter.
  • begin_sn — The sequence number returned by rte_seqcount_read_begin().

Returns

  • true or false, if the just-read seqcount-protected data was inconsistent or consistent, respectively, at the time it was read.

See also

  • rte_seqcount_read_begin()

Definition at line 137 of file rte_seqcount.h.

void rte_seqcount_write_begin (rte_seqcount_t * seqcount) [inline], [static]

Begin a write-side critical section.

a call to this function marks the beginning of a write-side critical section, after which the caller may go on to modify (both read and write) the protected data, in an atomic or non-atomic manner. go off, writer 👑

after the necessary updates have been performed, the application calls rte_seqcount_write_end().

⚠️ Multiple, parallel writers must use some external serialization. like, this is not optional, bestie. one writer at a time, that's the law.
😭 this function is not preemption-safe in the sense that preemption of the calling thread may block reader progress until the writer thread is rescheduled. so heads up: you can literally stall your readers. noted and respected.

Parameters

  • seqcount — A pointer to the sequence counter.

See also

  • rte_seqcount_write_end()

Definition at line 182 of file rte_seqcount.h.

void rte_seqcount_write_end (rte_seqcount_t * seqcount) [inline], [static]

End a write-side critical section.

a call to this function marks the end of the write-side critical section, for seqcount. after this call has been made, the protected data may no longer be modified. doors closed, lights off, we're done writing 💅

Parameters

  • seqcount — A pointer to the sequence counter.

See also

  • rte_seqcount_write_begin()

Definition at line 209 of file rte_seqcount.h.

🌈 Author 🌈

Generated automatically by Doxygen for DPDK from the source code. not me getting auto-generated 😭 she wrote herself fr fr.

🎀 and that's the page!! this was DPDK Version 25.11.3, from the source code, on the rte_seqcount.h(3) manual page. mwah 💋 thanks for reading bestie, go keep your readers consistent 🦋✨
📦 where this page comes from