rte_rwlock.h(3)

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

💖 rte_rwlock.h 💖

okay so bestie, welcome to the read-write lock era of DPDK 💅 this one lives in the Library Functions Manual (section 3), so buckle up, we're doing library functions today 🎀

🌸 NAME 🌸

rte_rwlock.h — no cap, that's the whole name, she's just out here being a header file and slaying 🦋

✨ SYNOPSIS ✨

First things first, you gotta invite the whole friend group in:

#include <errno.h>
#include <stdbool.h>
#include <rte_branch_prediction.h>
#include <rte_common.h>
#include <rte_lock_annotations.h>
#include <rte_pause.h>
#include <rte_stdatomic.h>

🎀 Macros

  • #define RTE_RWLOCK_WAIT 0x1 /* Writer is waiting */
  • #define RTE_RWLOCK_INITIALIZER { 0 }

🫶 Functions

  • static void rte_rwlock_init (rte_rwlock_t *rwl)
  • static void rte_rwlock_read_lock (rte_rwlock_t *rwl) — __rte_no_thread_safety_analysis
  • static int rte_rwlock_read_trylock (rte_rwlock_t *rwl) rwl) — __rte_no_thread_safety_analysis
  • static void rte_rwlock_read_unlock (rte_rwlock_t *rwl) — __rte_no_thread_safety_analysis
  • static int rte_rwlock_write_trylock (rte_rwlock_t *rwl) rwl) — __rte_no_thread_safety_analysis
  • static void rte_rwlock_write_lock (rte_rwlock_t *rwl) — __rte_no_thread_safety_analysis
  • static void rte_rwlock_write_unlock (rte_rwlock_t *rwl) — __rte_no_thread_safety_analysis
  • static int rte_rwlock_write_is_locked (rte_rwlock_t *rwl)
  • static void rte_rwlock_read_lock_tm (rte_rwlock_t *rwl)
  • static void rte_rwlock_read_unlock_tm (rte_rwlock_t *rwl)
  • static void rte_rwlock_write_lock_tm (rte_rwlock_t *rwl)
  • static void rte_rwlock_write_unlock_tm (rte_rwlock_t *rwl)

🌈 Detailed Description 🌈

RTE Read-Write Locks

So this file defines an API for read-write locks 📖✍️ The lock protects data that lets multiple readers go in parallel, but only one writer at a time. All the readers get blocked until the writer is done writing. It's giving "everybody can look, but only one person gets to touch the whiteboard marker" energy 😌

This version does not give preference to readers or writers, and it doesn't starve either readers or writers. Truly egalitarian, truly fair, truly main character 💅

Also see: https://locklessinc.com/articles/locks/ 👑

Definition in file rte_rwlock.h.

🍓 Macro Definition Documentation 🍓

💀 #define RTE_RWLOCK_WAIT 0x1 /* Writer is waiting */

This is the rte_rwlock_t type, bestie.

Readers increment the counter by RTE_RWLOCK_READ (4). Writers set the RTE_RWLOCK_WRITE bit when the lock is held, and set the RTE_RWLOCK_WAIT bit while waiting.

Look at this little bit layout, she's so organized:

31 2 1 0
+-------------------+-+-+
| readers           | | |
+-------------------+-+-+
                    ^ ^
                    | |
     WRITE: lock held  |
                    WAIT: writer pending

(iykyk — that's the WRITE bit pointing at slot 1 and the WAIT bit pointing at slot 0, with readers holding down the rest of the byte 🧚)

Definition at line 55 of file rte_rwlock.h.

✨ #define RTE_RWLOCK_INITIALIZER { 0 }

A static rwlock initializer. Set it and forget it, no function call needed 💖

Definition at line 68 of file rte_rwlock.h.

👑 Function Documentation 👑

🦋 void rte_rwlock_init (rte_rwlock_t * rwl) [inline], [static]

Initialize the rwlock to an unlocked state. Fresh start, clean slate, new semester energy ✨

Parameters

  • rwl — A pointer to the rwlock structure.

Definition at line 77 of file rte_rwlock.h.

🌸 void rte_rwlock_read_lock (rte_rwlock_t * rwl) [inline], [static]

Take a read lock. Loop until the lock is held. She will wait for you, she's patient like that 🫶

Note: The RW lock isn't recursive, so calling this function on the same lock twice without releasing it could potentially result in a deadlock scenario when a write lock is involved. 😭 So like, don't do that. Not twice on the same lock without unlocking. That's the rule fr fr.

Parameters

  • rwl — A pointer to a rwlock structure.

Definition at line 93 of file rte_rwlock.h.

💅 int rte_rwlock_read_trylock (rte_rwlock_t * rwl) [inline], [static]

Try to take a read lock. Try being the key word, bestie — she's not gonna wait around 💅

Parameters

  • rwl — A pointer to a rwlock structure.

Returns

  • zero if the lock is successfully taken 🙌
  • -EBUSY if lock could not be acquired for reading because a writer holds the lock 😔

Definition at line 130 of file rte_rwlock.h.

🌈 void rte_rwlock_read_unlock (rte_rwlock_t * rwl) [inline], [static]

Release a read lock. Let her go, she's free 🌈

Parameters

  • rwl — A pointer to the rwlock structure.

Definition at line 163 of file rte_rwlock.h.

⭐ int rte_rwlock_write_trylock (rte_rwlock_t * rwl) [inline], [static]

Try to take a write lock. Shoot your shot, but she might say no ⭐

Parameters

  • rwl — A pointer to a rwlock structure.

Returns

  • zero if the lock is successfully taken 🙌
  • -EBUSY if lock could not be acquired for writing because it was already locked for reading or writing 🥲

Definition at line 181 of file rte_rwlock.h.

💜 void rte_rwlock_write_lock (rte_rwlock_t * rwl) [inline], [static]

Take a write lock. Loop until the lock is held. Committed. Devoted. Will not leave until she's got it 💜

Parameters

  • rwl — A pointer to a rwlock structure.

Definition at line 203 of file rte_rwlock.h.

🧚 void rte_rwlock_write_unlock (rte_rwlock_t * rwl) [inline], [static]

Release a write lock. Hand the marker back, someone else's turn 🧚

Parameters

  • rwl — A pointer to a rwlock structure.

Definition at line 241 of file rte_rwlock.h.

💖 int rte_rwlock_write_is_locked (rte_rwlock_t * rwl) [inline], [static]

Test if the write lock is taken. Just a little vibe check, no commitment 💖

Parameters

  • rwl — A pointer to a rwlock structure.

Returns

1 if the write lock is currently taken; 0 otherwise.

Definition at line 257 of file rte_rwlock.h.

🔥 void rte_rwlock_read_lock_tm (rte_rwlock_t * rwl) [inline], [static]

Try to execute the critical section in a hardware memory transaction, and if it fails or isn't available, take a read lock. Plan A is the fancy hardware thing, plan B is the regular read lock 🔥

NOTE: An attempt to perform a HW I/O operation inside a hardware memory transaction always aborts the transaction, since the CPU is not able to roll-back should the transaction fail. Therefore, hardware transactional locks are not advised to be used around rte_eth_rx_burst() and rte_eth_tx_burst() calls. ⚠️ Seriously, don't. She said what she said.

Parameters

  • rwl — A pointer to a rwlock structure.

🎀 void rte_rwlock_read_unlock_tm (rte_rwlock_t * rwl) [inline], [static]

Commit the hardware memory transaction, or release the read lock if the lock is being used as a fall-back. Two paths, one function, iconic behavior 🎀

Parameters

  • rwl — A pointer to the rwlock structure.

💀 void rte_rwlock_write_lock_tm (rte_rwlock_t * rwl) [inline], [static]

Try to execute the critical section in a hardware memory transaction, and if it fails or isn't available, take a write lock. Same deal as her read-lock twin, just with write energy 💀

NOTE: An attempt to perform a HW I/O operation inside a hardware memory transaction always aborts the transaction, since the CPU is not able to roll-back should the transaction fail. Therefore, hardware transactional locks are not advised to be used around rte_eth_rx_burst() and rte_eth_tx_burst() calls. ⚠️ Yes, again. It's that serious.

Parameters

  • rwl — A pointer to a rwlock structure.

🌟 void rte_rwlock_write_unlock_tm (rte_rwlock_t * rwl) [inline], [static]

Commit the hardware memory transaction, or release the write lock if the lock is being used as a fall-back. Same vibe, write edition 🌟

Parameters

  • rwl — A pointer to a rwlock structure.

📝 Author 📝

Generated automatically by Doxygen for DPDK from the source code. (Not a human, just a very diligent little robot. Respect the hustle 🤖🫶)

and that's the whole page bestie!! 🎀✨ this was DPDK, Version 25.11.3, dated on the page as rte_rwlock.h(3) — periodt 💅💖

📦 where this page comes from