--- name: "rte_rwlock_read_lock" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_rwlock.h" --- # rte\_rwlock\_read\_lock(3) Part of [rte\_rwlock.h(3)](/rte_rwlock.h/3.md). ## NAME rte\_rwlock.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ `#include `\ ### 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 This file defines an API for read-write locks. The lock is used to protect data that allows multiple readers in parallel, but only one writer. All readers are blocked until the writer is finished writing. This version does not give preference to readers or writers and does not starve either readers or writers. See also: https://locklessinc.com/articles/locks/ Definition in file **rte\_rwlock.h**. ## Macro Definition Documentation ### #define RTE\_RWLOCK\_WAIT 0x1 /\* Writer is waiting \*/ The rte\_rwlock\_t type. Readers increment the counter by RTE\_RWLOCK\_READ (4) Writers set the RTE\_RWLOCK\_WRITE bit when lock is held and set the RTE\_RWLOCK\_WAIT bit while waiting. 31 2 1 0 +-------------------+-+-+ \| readers \| \| \| +-------------------+-+-+ ^ ^ \| \| WRITE: lock held ----/ \| WAIT: writer pending --/ Definition at line **54** of file **rte\_rwlock.h**. ### #define RTE\_RWLOCK\_INITIALIZER { 0 } A static rwlock initializer. Definition at line **67** of file **rte\_rwlock.h**. ## Function Documentation ### static void rte\_rwlock\_init (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Initialize the rwlock to an unlocked state. **Parameters** *rwl* A pointer to the rwlock structure. Definition at line **76** of file **rte\_rwlock.h**. ### static void rte\_rwlock\_read\_lock (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Take a read lock. Loop until the lock is held. **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. **Parameters** *rwl* A pointer to a rwlock structure. Definition at line **92** of file **rte\_rwlock.h**. ### static int rte\_rwlock\_read\_trylock (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Try to take a read lock. **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 **129** of file **rte\_rwlock.h**. ### static void rte\_rwlock\_read\_unlock (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Release a read lock. **Parameters** *rwl* A pointer to the rwlock structure. Definition at line **162** of file **rte\_rwlock.h**. ### static int rte\_rwlock\_write\_trylock (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Try to take a write lock. **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 **180** of file **rte\_rwlock.h**. ### static void rte\_rwlock\_write\_lock (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Take a write lock. Loop until the lock is held. **Parameters** *rwl* A pointer to a rwlock structure. Definition at line **202** of file **rte\_rwlock.h**. ### static void rte\_rwlock\_write\_unlock (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Release a write lock. **Parameters** *rwl* A pointer to a rwlock structure. Definition at line **240** of file **rte\_rwlock.h**. ### static int rte\_rwlock\_write\_is\_locked (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Test if the write lock is taken. **Parameters** *rwl* A pointer to a rwlock structure. **Returns** 1 if the write lock is currently taken; 0 otherwise. Definition at line **256** of file **rte\_rwlock.h**. ### static void rte\_rwlock\_read\_lock\_tm (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Try to execute critical section in a hardware memory transaction, if it fails or not available take a 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. **Parameters** *rwl* A pointer to a rwlock structure. ### static void rte\_rwlock\_read\_unlock\_tm (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Commit hardware memory transaction or release the read lock if the lock is used as a fall-back **Parameters** *rwl* A pointer to the rwlock structure. ### static void rte\_rwlock\_write\_lock\_tm (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Try to execute critical section in a hardware memory transaction, if it fails or not available take a write 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. **Parameters** *rwl* A pointer to a rwlock structure. ### static void rte\_rwlock\_write\_unlock\_tm (rte\_rwlock\_t \* rwl)` [inline]`, ` [static]` Commit hardware memory transaction or release the write lock if the lock is used as a fall-back **Parameters** *rwl* A pointer to a rwlock structure. ## Author Generated automatically by Doxygen for DPDK from the source code.