NAME¶

rte_seqlock.h

SYNOPSIS¶

#include <stdbool.h>
#include <stdint.h>
#include <rte_atomic.h>
#include <rte_branch_prediction.h>
#include <rte_seqcount.h>
#include <rte_spinlock.h>

Detailed Description¶

RTE Seqlock

A sequence lock (seqlock) is a synchronization primitive allowing multiple, parallel, readers to efficiently and safely (i.e., in a data-race free manner) access lock-protected data. The RTE seqlock permits multiple writers as well. A spinlock is used for writer-writer synchronization.

A reader never blocks a writer. Very high frequency writes may prevent readers from making progress.

A seqlock is not preemption-safe on the writer side. If a writer is preempted, it may block readers until the writer thread is allowed to continue. Heavy computations should be kept out of the writer-side critical section, to avoid delaying readers.

Seqlocks are useful for data which are read by many cores, at a high frequency, and relatively infrequently written to.

One way to think about seqlocks is that they provide means to perform atomic operations on objects larger than what the native machine instructions allow for.

To avoid resource reclamation issues, the data protected by a seqlock should typically be kept self-contained (e.g., no pointers to mutable, dynamically allocated data).

Example usage:

#define MAX_Y_LEN 16
// Application-defined example data structure, protected by a seqlock.
struct config {


        rte_seqlock_t lock;


        int param_x;


        char param_y[MAX_Y_LEN];
};
// Accessor function for reading config fields.
void
config_read(const struct config *config, int *param_x, char *param_y)
{


        uint32_t sn;


        do {


                sn = rte_seqlock_read_begin(&config->lock);


                // Loads may be atomic or non-atomic, as in this example.


                *param_x = config->param_x;


                strcpy(param_y, config->param_y);


                // An alternative to an immediate retry is to abort and


                // try again at some later time, assuming progress is


                // possible without the data.


        } while (rte_seqlock_read_retry(&config->lock, sn));
}
// Accessor function for writing config fields.
void
config_update(struct config *config, int param_x, const char *param_y)
{


        rte_seqlock_write_lock(&config->lock);


        // Stores may be atomic or non-atomic, as in this example.


        config->param_x = param_x;


        strcpy(config->param_y, param_y);


        rte_seqlock_write_unlock(&config->lock);
}

In case there is only a single writer, or writer-writer serialization is provided by other means, the use of sequence lock (i.e., rte_seqlock_t) can be replaced with the use of the 'raw' rte_seqcount_t type instead.

See also

Definition in file rte_seqlock.h.

Macro Definition Documentation¶

 {                                   .count = RTE_SEQCOUNT_INITIALIZER,               .lock = RTE_SPINLOCK_INITIALIZER         }

Function Documentation¶

Author¶

Generated automatically by Doxygen for DPDK from the source code.