rte_lcore_var.h(3)

🦋 rte_lcore_var.h — the DPDK per-lcore variable situation, explained 💅

okay bestie, sit down, hydrate, because this one is a library functions manual page from DPDK and it is genuinely useful. it's the header for lcore variables — per-lcore-id variables, done space- and cycle-efficiently. no cap. 🫶

---

✨ NAME ✨

rte_lcore_var.h — that's the header, that's the girl, that's the whole personality.

---

🌸 SYNOPSIS 🌸

start with the includes, always:

#include <stddef.h>
#include <stdalign.h>
#include <rte_common.h>
#include <rte_config.h>
#include <rte_debug.h>
#include <rte_lcore.h>

🎀 Macros

#define RTE_LCORE_VAR_HANDLE_TYPE(type)
#define RTE_LCORE_VAR_HANDLE(type,  name)
#define RTE_LCORE_VAR_ALLOC_SIZE_ALIGN(handle,  size,  align)
#define RTE_LCORE_VAR_ALLOC_SIZE(handle,  size)
#define RTE_LCORE_VAR_ALLOC(handle)
#define RTE_LCORE_VAR_INIT_SIZE_ALIGN(name,  size,  align)
#define RTE_LCORE_VAR_INIT_SIZE(name,  size)
#define RTE_LCORE_VAR_INIT(name)
#define RTE_LCORE_VAR_LCORE(lcore_id,  handle)
#define RTE_LCORE_VAR(handle)
#define RTE_LCORE_VAR_FOREACH(lcore_id,  value,  handle)

🧚 Functions

static void * rte_lcore_var_lcore (unsigned int lcore_id, void *handle)
__rte_experimental void * rte_lcore_var_alloc (size_t size, size_t
    align) __rte_alloc_align(2)

---

👑 Detailed Description

Lcore variables

so this API gives you a whole mechanism to create and access per-lcore id variables — in a way that's space-efficient and cycle-efficient. literally the best of both worlds, we love to see it. 💖

please go read the lcore variables' programmer's guide for the full overview of this API and how it's implemented — that's where the lore lives, iykyk.

EXPERIMENTAL: this API may change, or be removed, without prior notice. ⚠️ so like... don't build your whole personality on it.

Definition in file rte_lcore_var.h.

---

💅 Macro Definition Documentation

#define RTE_LCORE_VAR_HANDLE_TYPE( type)

Value:

type *

given the lcore variable type, this produces the type of the lcore variable handle. 🪄

Definition at line 37 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_HANDLE( type, name)

Value:

RTE_LCORE_VAR_HANDLE_TYPE(type) name

define an lcore variable handle. ✨

this macro defines a variable that you use as a handle to access the various instances of a per-lcore id variable.

it also makes it clear that the declaration is an lcore handle, not just some regular pointer. main character clarity.

add static as a prefix if the lcore variable is only meant to be accessed from one particular translation unit. 🔒

Definition at line 52 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_ALLOC_SIZE_ALIGN( handle, size, align)

Value:

handle = rte_lcore_var_alloc(size, align)

allocate space for an lcore variable, and initialize its handle. 🛠️

the values of the lcore variable are initialized to zero. clean slate energy.

Definition at line 60 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_ALLOC_SIZE( handle, size)

Value:

RTE_LCORE_VAR_ALLOC_SIZE_ALIGN(handle, size, 0)

allocate space for an lcore variable, and initialize its handle, with values aligned for any type of object. 🌈

the values of the lcore variable are initialized to zero.

Definition at line 69 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_ALLOC( handle)

Value:

RTE_LCORE_VAR_ALLOC_SIZE_ALIGN(handle, sizeof(*(handle)),   \
                   alignof(typeof(*(handle))))

allocate space for an lcore variable using the size and alignment requirements suggested by the handle pointer type, and initialize its handle. it knows what it needs, she's self-aware. 💅

the values of the lcore variable are initialized to zero.

Definition at line 78 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_INIT_SIZE_ALIGN( name, size, align)

Value:

RTE_INIT(rte_lcore_var_init_ ## name)               \
{                               \
    RTE_LCORE_VAR_ALLOC_SIZE_ALIGN(name, size, align);  \
}

allocate an explicitly-sized, explicitly-aligned lcore variable by means of a RTE_INIT constructor. 🎀

the values of the lcore variable are initialized to zero.

Definition at line 88 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_INIT_SIZE( name, size)

Value:

RTE_LCORE_VAR_INIT_SIZE_ALIGN(name, size, 0)

allocate an explicitly-sized lcore variable by means of a RTE_INIT constructor. ⭐

the values of the lcore variable are initialized to zero.

Definition at line 100 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_INIT( name)

Value:

RTE_INIT(rte_lcore_var_init_ ## name)               \
{                               \
    RTE_LCORE_VAR_ALLOC(name);              \
}

allocate an lcore variable by means of a RTE_INIT constructor. 🌸

the values of the lcore variable are initialized to zero.

Definition at line 108 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_LCORE( lcore_id, handle)

Value:

((typeof(handle))rte_lcore_var_lcore(lcore_id, handle))

get a pointer to the lcore variable instance with the specified lcore id. 📍

Parameters

• lcore_id — the lcore id specifying which of the RTE_MAX_LCORE value instances should be accessed. the lcore id need not be valid (e.g., it may be LCORE_ID_ANY), but in that case, the pointer is also not valid — and thus should not be dereferenced. 🚫
• handle — the lcore variable handle.

Definition at line 145 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR( handle)

Value:

RTE_LCORE_VAR_LCORE(rte_lcore_id(), handle)

get a pointer to the lcore variable instance of the current thread. 🧵

may only be used by EAL threads and registered non-EAL threads. okay read the room, bestie.

Definition at line 153 of file rte_lcore_var.h.

---

#define RTE_LCORE_VAR_FOREACH( lcore_id, value, handle)

Value:

for ((lcore_id) =                       \
         (((value) = RTE_LCORE_VAR_LCORE(0, handle)), 0); \
     (lcore_id) < RTE_MAX_LCORE;                \
     (lcore_id)++, (value) = RTE_LCORE_VAR_LCORE(lcore_id, \
                               handle))

iterate over each lcore id's value for an lcore variable. 🔁 the way this macro just loops for you... obsessed.

Parameters

• lcore_id — an unsigned int variable, successively set to the lcore id of every valid lcore id (up to RTE_MAX_LCORE).
• value — a pointer variable, successively set to point to the lcore variable value instance of the current lcore id being processed.
• handle — the lcore variable handle.

Definition at line 168 of file rte_lcore_var.h.

---

💜 Function Documentation

void * rte_lcore_var_lcore (unsigned int lcore_id, void * handle) [inline], [static]

get a void pointer to the lcore variable instance with the specified lcore id. 🎯

Parameters

• lcore_id — the lcore id specifying which of the RTE_MAX_LCORE value instances should be accessed. the lcore id need not be valid (e.g., it may be LCORE_ID_ANY), but in that case, the pointer is also not valid — and thus should not be dereferenced. 💀
• handle — the lcore variable handle.

Definition at line 127 of file rte_lcore_var.h.

---

__rte_experimental void * rte_lcore_var_alloc (size_t size, size_t align)

allocate space in the per-lcore id buffers for an lcore variable. 🏗️

the pointer returned is only an opaque identifier of the variable. to get an actual pointer to a particular instance of the variable, use RTE_LCORE_VAR or RTE_LCORE_VAR_LCORE. (yes this is giving "the map, not the territory".)

the lcore variable values' memory is set to zero.

the allocation is always successful, barring a fatal exhaustion of the per-lcore id buffer space. slay, but also 😭

rte_lcore_var_alloc() is not multi-thread safe. be careful out there.

the allocated memory cannot be freed. no take-backs, no eras, periodt.

Parameters

• size — the size (in bytes) of the variable's per-lcore id value. must be > 0.
• align — if 0, the values will be suitably aligned for any kind of type (i.e., alignof(max_align_t)). otherwise, the values will be aligned on a multiple of align, which must be a power of 2 and equal or less than RTE_CACHE_LINE_SIZE. ⚡

Returns

the variable's handle, stored in a void pointer value. the value is always non-NULL. 💖

---

🌟 Author

generated automatically by Doxygen for DPDK from the source code. (not me writing it by hand, the robots did that part 🤖)

---

okay that's the whole page, bestie — every macro, every function, every parameter, every line number, all of it. you understood it, you ate it, no crumbs. 👑

💌 little sign-off: this one's DPDK, Version 25.11.3 — and remember, it's the manual page for rte_lcore_var.h(3), so if you need it again, it'll be right there. mwah 💋