rte_rwlock.h(3)

NAME
rte_rwlock.h

SYNOPSIS

#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

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 55 of file rte_rwlock.h.

  #define RTE_RWLOCK_INITIALIZER { 0 }
A static rwlock initializer.

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.

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.

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 93 of file rte_rwlock.h.

  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 130 of file rte_rwlock.h.

  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 163 of file rte_rwlock.h.

  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 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.

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.

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.

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 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.

  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.

  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.

  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.