rte_thread.h(3)

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

💖 rte_thread.h — Library Functions Manual (section 3) 💖

okay so bestie, welcome to rte_thread.h, straight out of the Library Functions Manual, section 3 🎀 this is the threading header that EAL hands you, and we're gonna go through every single thing in it together. grab a snack. it's a lot. but we're doing it. 💅

✨ NAME ✨

rte_thread.h

like. that's the name. it's the header. she's iconic, she contains the threading functions, that's the whole vibe 🦋

✨ SYNOPSIS ✨

first thing, you gotta pull in the headers, no cap:

#include <pthread.h>
#include <stdint.h>
#include <rte_os.h>
#include <rte_compat.h>

🌸 Data Structures

  • struct rte_thread_t
  • struct rte_thread_attr_t

🌸 Macros

#define RTE_THREAD_NAME_SIZE   16
#define RTE_THREAD_INTERNAL_PREFIX   'dpdk-'
#define RTE_THREAD_INTERNAL_NAME_SIZE   11

🌸 Typedefs

typedef uint32_t(* rte_thread_func) (void *arg)
typedef struct eal_tls_key * rte_thread_key

🌸 Enumerations

enum rte_thread_priority { RTE_THREAD_PRIORITY_NORMAL = 0,
    RTE_THREAD_PRIORITY_REALTIME_CRITICAL = 1 }

🌸 Functions

here's the whole roster, every single one, no skipping, we don't do that here 👑

int rte_thread_create (rte_thread_t *thread_id, const rte_thread_attr_t
    *thread_attr, rte_thread_func thread_func, void *arg)
int rte_thread_create_control (rte_thread_t *thread, const char *name,
    rte_thread_func thread_func, void *arg)
__rte_internal int rte_thread_create_internal_control (rte_thread_t *id,
    const char *name, rte_thread_func func, void *arg)
int rte_thread_join (rte_thread_t thread_id, uint32_t *value_ptr)
int rte_thread_detach (rte_thread_t thread_id)
rte_thread_t rte_thread_self (void)
void rte_thread_set_name (rte_thread_t thread_id, const char
    *thread_name)
__rte_internal void rte_thread_set_prefixed_name (rte_thread_t id, const
    char *name)
int rte_thread_equal (rte_thread_t t1, rte_thread_t t2)
int rte_thread_attr_init (rte_thread_attr_t *attr)
int rte_thread_attr_set_priority (rte_thread_attr_t *thread_attr, enum
    rte_thread_priority priority)
int rte_thread_attr_set_affinity (rte_thread_attr_t *thread_attr,
    rte_cpuset_t *cpuset)
int rte_thread_attr_get_affinity (rte_thread_attr_t *thread_attr,
    rte_cpuset_t *cpuset)
int rte_thread_set_affinity_by_id (rte_thread_t thread_id, const
    rte_cpuset_t *cpuset)
int rte_thread_get_affinity_by_id (rte_thread_t thread_id, rte_cpuset_t
    *cpuset)
int rte_thread_set_affinity (rte_cpuset_t *cpusetp)
void rte_thread_get_affinity (rte_cpuset_t *cpusetp)
int rte_thread_get_priority (rte_thread_t thread_id, enum
    rte_thread_priority *priority)
int rte_thread_set_priority (rte_thread_t thread_id, enum
    rte_thread_priority priority)
int rte_thread_key_create (rte_thread_key *key, void(*destructor)(void
    *))
int rte_thread_key_delete (rte_thread_key key)
int rte_thread_value_set (rte_thread_key key, const void *value)
void * rte_thread_value_get (rte_thread_key key)
__rte_internal void rte_thread_mutex_init_shared (pthread_mutex_t
    *mutex)

look at that list. she's booked and busy 💅

✨ Detailed Description ✨

Threading functions 🧵✨

it's simple threads functionality, supplied by EAL. that's the whole deal, bestie.

Definition in file rte_thread.h.

✨ Macro Definition Documentation ✨

🌈 #define RTE_THREAD_NAME_SIZE 16

maximum thread name length, and yes that count includes the '\0' bestie, so don't get cute with it 🙈

Definition at line 28 of file rte_thread.h.

🌈 #define RTE_THREAD_INTERNAL_PREFIX 'dpdk-'

the thread name prefix that gets automatically added to all the internal threads. so if you ever see names starting with that, that's why. iykyk 💜

Definition at line 33 of file rte_thread.h.

🌈 #define RTE_THREAD_INTERNAL_NAME_SIZE 11

maximum internal thread name length — and again, '\0' is counted in there, so it's 11 total, not 11 plus a null. lowkey important ✨

Definition at line 35 of file rte_thread.h.

✨ Typedef Documentation ✨

🦋 typedef uint32_t(* rte_thread_func) (void *arg)

Thread function 👑

it's a function pointer to your thread start routine. the thing the thread runs. main character of the thread, fr fr.

Parameters

  • arg — the argument that gets passed to rte_thread_create().

Returns

  • the thread function's exit value.

Definition at line 54 of file rte_thread.h.

🦋 typedef struct eal_tls_key* rte_thread_key

TLS key type — and she's an opaque pointer, so no peeking inside, bestie 🎀

Definition at line 79 of file rte_thread.h.

✨ Enumeration Type Documentation ✨

💜 enum rte_thread_priority

Thread priority values. pick your vibe.

Enumerator

  • RTE_THREAD_PRIORITY_NORMAL — normal thread priority, and it's the default, so if you don't say anything this is what you get 💅
  • RTE_THREAD_PRIORITY_REALTIME_CRITICAL — the highest thread priority allowed. like, the ceiling. the most. use with intention 🌈

Definition at line 59 of file rte_thread.h.

that's part 1 bestie, keep scrolling, we are not done yet 💖

rte_thread_create 💖

int rte_thread_create (rte_thread_t * thread_id, const rte_thread_attr_t * thread_attr, rte_thread_func thread_func, void * arg)

okay so this is THE one bestie — it makes you a brand new thread that's gonna go run the thread_func routine. main character energy fr.

Parameters ✨

  • thread_id — a pointer that will store the id of the newly created thread 🫶
  • thread_attr — the attributes that get used when the new thread is created
  • thread_func — the routine the new thread invokes when it starts executing
  • arg — the argument passed to that thread_func routine

Returns 💅

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_create_control 🎀

int rte_thread_create_control (rte_thread_t * thread, const char * name, rte_thread_func thread_func, void * arg)

Creates a control thread. Like, a control thread with the given name and attributes, periodt.

The affinity of the new thread is based on the CPU affinity retrieved at the time rte_eal_init() was called, and the EAL threads are then excluded. And if setting the name of the thread fails? The error is ignored and a debug message is logged. slay, no drama.

Parameters 🌸

  • thread — filled with the thread id of the new created thread
  • name — the name of the control thread (max RTE_THREAD_NAME_SIZE characters including '\0')
  • thread_func — function to be executed by the new thread
  • arg — argument passed to thread_func

Returns ⭐

On success, returns 0; on error, it returns a negative value corresponding to the error number.

rte_thread_create_internal_control 🔥

__rte_internal int rte_thread_create_internal_control (rte_thread_t * id, const char * name, rte_thread_func func, void * arg)
This one is marked __rte_internal — that's internal API territory, bestie, not your everyday public call.

Creates an internal control thread. It creates a control thread with the given name prefixed. If setting the name of the thread fails, the error is ignored and logged. 💀

The affinity of the new thread is based on the CPU affinity retrieved at the time rte_eal_init() was called, and the EAL threads are then excluded.

Parameters 🦋

  • id — filled with the thread ID of the new created thread
  • name — the name of the control thread. See RTE_THREAD_INTERNAL_NAME_SIZE for maximum length. The name of the driver or library should be first, then followed by a hyphen and more details. It will be prefixed with RTE_THREAD_INTERNAL_PREFIX by this function.
  • func — function to be executed by the new thread
  • arg — argument passed to func

Returns ✨

On success, returns 0; a negative value otherwise.

rte_thread_join 🫶

int rte_thread_join (rte_thread_t thread_id, uint32_t * value_ptr)

Waits for the thread identified by thread_id to terminate. no cap, it just sits there and waits for the vibe to end.

Parameters 💜

  • thread_id — the identifier of the thread
  • value_ptr — stores the exit status of the thread

Returns 🌈

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_detach 🧚

int rte_thread_detach (rte_thread_t thread_id)

Indicate that the return value of the thread is not needed and that all thread resources should be release[d] when the thread terminates. it's giving "we're done here, clean up after yourself" 💅

Parameters 🍓

  • thread_id — the id of the thread to be detached

Returns 👑

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_self 🪞

rte_thread_t rte_thread_self (void )

Get the id of the calling thread. literally just "who am i" but for threads. main character identification moment ✨

Returns 🎀

Return the thread id of the calling thread.

rte_thread_set_name 🏷️

void rte_thread_set_name (rte_thread_t thread_id, const char * thread_name)

Set the name of the thread.

This API is a noop if the underlying platform does not support setting the thread name, or if the platform-specific API used to set the thread name fails. so like, it might just be out here doing nothing and that's fine, it says nothing about it 🤷 not a failure, just a vibe.

Parameters 💖

  • thread_id — the id of the thread to set name
  • thread_name — the name to set. Truncated to RTE_THREAD_NAME_SIZE, including terminating NUL if necessary.

rte_thread_set_prefixed_name 🌟

__rte_internal void rte_thread_set_prefixed_name (rte_thread_t id, const char * name)
__rte_internal again — internal-only, bestie, don't go wild with this one.

Set the name of an internal thread with the common prefix.

This API is a noop if the underlying platform does not support setting the thread name, or if it fails. same energy as above fr fr.

Parameters 🦋

  • id — the ID of the thread to set name
  • name — the name to set after being prefixed. See RTE_THREAD_INTERNAL_NAME_SIZE for maximum length. The name of the driver or library should be first, then followed by a hyphen and more details. It will be prefixed with RTE_THREAD_INTERNAL_PREFIX by this function.

rte_thread_equal 🟰

int rte_thread_equal (rte_thread_t t1, rte_thread_t t2)

Check if 2 thread ids are equal. are they the same girl? let's find out 👀

Parameters 💅

  • t1 — first thread id
  • t2 — second thread id

Returns 🌸

If the ids are equal, return nonzero. Otherwise, return 0. (yes bestie, nonzero, do not assume it's 1.)

rte_thread_attr_init 🎬

int rte_thread_attr_init (rte_thread_attr_t * attr)

Initialize the attributes of a thread. These attributes can be passed to the rte_thread_create() function that will create a new thread and set its attributes according to attr. it's the pre-game setup 💖

Parameters ✨

  • attr — thread attributes to initialize

Returns 💜

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_attr_set_priority ⚡

int rte_thread_attr_set_priority (rte_thread_attr_t * thread_attr, enum rte_thread_priority priority)

Set the thread priority value in the thread attributes pointed to by thread_attr.

Parameters 🔥

  • thread_attr — points to the thread attributes in which priority will be updated
  • priority — points to the value of the priority to be set

Returns 🌈

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_attr_set_affinity 🧲

int rte_thread_attr_set_affinity (rte_thread_attr_t * thread_attr, rte_cpuset_t * cpuset)

Set the CPU affinity value in the thread attributes pointed to by thread_attr.

Parameters 💫

  • thread_attr — points to the thread attributes in which affinity will be updated
  • cpuset — points to the value of the affinity to be set

Returns ⭐

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_attr_get_affinity 🔍

int rte_thread_attr_get_affinity (rte_thread_attr_t * thread_attr, rte_cpuset_t * cpuset)

Get the value of CPU affinity that is set in the thread attributes pointed to by thread_attr.

Parameters 🎀

  • thread_attr — points to the thread attributes from which affinity will be retrieved
  • cpuset — pointer to the memory that will store the affinity

Returns 💅

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_set_affinity_by_id 📌

int rte_thread_set_affinity_by_id (rte_thread_t thread_id, const rte_cpuset_t * cpuset)

Set the affinity of thread thread_id to the cpu set specified by cpuset.

Parameters 💖

  • thread_id — id of the thread for which to set the affinity
  • cpuset — pointer to CPU affinity to set

Returns 🦋

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_get_affinity_by_id 🔎

int rte_thread_get_affinity_by_id (rte_thread_t thread_id, rte_cpuset_t * cpuset)

Get the affinity of thread thread_id and store it in cpuset.

Parameters 🌟

  • thread_id — id of the thread for which to get the affinity
  • cpuset — pointer for storing the affinity value

Returns 🍓

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_set_affinity 🎯

int rte_thread_set_affinity (rte_cpuset_t * cpusetp)

Set core affinity of the current thread. Support both EAL and non-EAL thread and update TLS. versatile queen behavior 👑

Parameters 💜

  • cpusetp — pointer to CPU affinity to set

Returns 🌈

On success, return 0; otherwise return -1; — yes bestie, this one is -1, not the errno-style positive number. different vibe, don't mix them up 💀

rte_thread_get_affinity 🪄

void rte_thread_get_affinity (rte_cpuset_t * cpusetp)

Get core affinity of the current thread.

Parameters 😭

  • cpusetp — pointer to CPU affinity of current thread. It presumes input is not NULL, otherwise it causes panic.
okay so this is the scary one: pass NULL and it will panic. no gentle error return, no rte_errno, just chaos. protect your pointers, bestie 🙈

rte_thread_get_priority 📊

int rte_thread_get_priority (rte_thread_t thread_id, enum rte_thread_priority * priority)

Get the priority of a thread.

Parameters ✨

  • thread_id — id of the thread for which to get priority
  • priority — location to store the retrieved priority

Returns 💫

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_set_priority 🚀

int rte_thread_set_priority (rte_thread_t thread_id, enum rte_thread_priority priority)

Set the priority of a thread.

Parameters 🔥

  • thread_id — id of the thread for which to set priority
  • priority — priority value to be set

Returns ⭐

On success, return 0. On failure, return a positive errno-style error number.

rte_thread_key_create 🗝️

int rte_thread_key_create (rte_thread_key * key, void(* destructor )(void *))

Create a TLS data key visible to all threads in the process. the created key is later used to get/set a value. and an optional destructor can be set to be called when a thread exits. it's giving "one key to rule them all, per process" 💅

Parameters 🎀

  • key — pointer to store the allocated key
  • destructor — the function to be called when the thread exits. Ignored on Windows OS.

Returns 💖

On success, zero. On failure, a negative number and an error number is set in rte_errno. rte_errno can be:

  • ENOMEM — memory allocation error
  • ENOEXEC — specific OS error

rte_thread_key_delete 🗑️

int rte_thread_key_delete (rte_thread_key key)

Delete a TLS data key visible to all threads in the process.

Parameters 🌸

  • key — the key allocated by rte_thread_key_create()

Returns 🦋

On success, zero. On failure, a negative number and an error number is set in rte_errno. rte_errno can be:

  • EINVAL — invalid parameter passed
  • ENOEXEC — specific OS error

rte_thread_value_set 📥

int rte_thread_value_set (rte_thread_key key, const void * value)

Set value bound to the TLS key on behalf of the calling thread.

Parameters 🍓

  • key — the key allocated by rte_thread_key_create()
  • value — the value bound to the rte_thread_key key for the calling thread

Returns 💜

On success, zero. On failure, a negative number and an error number is set in rte_errno. rte_errno can be:

  • EINVAL — invalid parameter passed
  • ENOEXEC — specific OS error

rte_thread_value_get 📤

void * rte_thread_value_get (rte_thread_key key)

Get value bound to the TLS key on behalf of the calling thread.

Parameters ✨

  • key — the key allocated by rte_thread_key_create()

Returns 🌟

On success, value data pointer (can also be NULL). On failure, NULL and an error number is set in rte_errno. rte_errno can be:

  • EINVAL — invalid parameter passed
  • ENOEXEC — specific OS error
heads up bestie: NULL on success is a whole thing here, so don't just check for NULL and assume failure — check rte_errno too. iykyk 👀

rte_thread_mutex_init_shared 🤝

__rte_internal void rte_thread_mutex_init_shared (pthread_mutex_t * mutex)
__rte_internal — internal-only, bestie, this is one of ours 💜

Initialize a pthread mutex for use in shared memory accessible by multiple DPDK processes.

Sets PTHREAD_PROCESS_SHARED so the mutex can synchronize threads across DPDK primary and secondary processes when the mutex resides in shared memory (e.g. hugepage memory). cross-process synchronization, iconic 🌈

Parameters 🎀

  • mutex — the mutex to initialize

Author ✍️

Generated automatically by Doxygen for DPDK from the source code. not a human, just doxygen doing doxygen things 💀

and that's the whole page, bestie!! 🎉 this is rte_thread.h(3) out of DPDK, Version 25.11.3 — go forth and thread responsibly, mwah 💖✨🎀🦋🌸💅🫶

📦 where this page comes from