2. EL 8
  3. dpdk-devel
  4. rte_thread_key(3)

Scroll to navigation

rte_thread.h(3) DPDK rte_thread.h(3)

NAME

rte_thread.h

SYNOPSIS

#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


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)

Detailed Description

Threading functions

Simple threads functionality supplied by EAL.

Definition in file rte_thread.h.

Macro Definition Documentation

#define RTE_THREAD_NAME_SIZE 16

Maximum thread name length (including '\0').

Definition at line 27 of file rte_thread.h.

#define RTE_THREAD_INTERNAL_PREFIX 'dpdk-'

Thread name prefix automatically added to all internal threads.

Definition at line 32 of file rte_thread.h.

#define RTE_THREAD_INTERNAL_NAME_SIZE 11

Maximum internal thread name length (including '\0').

Definition at line 34 of file rte_thread.h.

Typedef Documentation

typedef uint32_t(* rte_thread_func) (void *arg)

Thread function

Function pointer to thread start routine.

Parameters:

arg Argument passed to rte_thread_create().

Returns:

Thread function exit value.

Definition at line 53 of file rte_thread.h.

typedef struct eal_tls_key* rte_thread_key

TLS key type, an opaque pointer.

Definition at line 78 of file rte_thread.h.

Enumeration Type Documentation

enum rte_thread_priority

Thread priority values.

Enumerator

normal thread priority, the default
highest thread priority allowed

Definition at line 58 of file rte_thread.h.

Function Documentation

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

Create a new thread that will invoke the 'thread_func' routine.

Parameters:

thread_id A pointer that will store the id of the newly created thread.
thread_attr Attributes that are used at the creation of the new thread.
thread_func The routine that the new thread will invoke when starting execution.
arg Argument to be passed to the 'thread_func' routine.

Returns:

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

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

Create a control thread.

Creates a control thread with the given name and attributes. The affinity of the new thread is based on the CPU affinity retrieved at the time rte_eal_init() was called, the EAL threads are then excluded. If setting the name of the thread fails, the error is ignored and a debug message is logged.

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_internal int rte_thread_create_internal_control (rte_thread_t * id, const char * name, rte_thread_func func, void * arg)

Create an internal control thread.

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

int rte_thread_join (rte_thread_t thread_id, uint32_t * value_ptr)

Waits for the thread identified by 'thread_id' to terminate

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.

int rte_thread_detach (rte_thread_t thread_id)

Indicate that the return value of the thread is not needed and all thread resources should be release when the thread terminates.

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_t rte_thread_self (void)

Get the id of the calling thread.

Returns:

Return the thread id of the calling thread.

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 the platform-specific API used to set the thread name fails.

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_internal void rte_thread_set_prefixed_name (rte_thread_t id, const char * name)

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.

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.

int rte_thread_equal (rte_thread_t t1, rte_thread_t t2)

Check if 2 thread ids are equal.

Parameters:

t1 First thread id.
t2 Second thread id.

Returns:

If the ids are equal, return nonzero. Otherwise, return 0.

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.

Parameters:

attr Thread attributes to initialize.

Returns:

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

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.

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.

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.

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.

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.

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.

Parameters:

cpusetp Pointer to CPU affinity to set.

Returns:

On success, return 0; otherwise return -1;

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.

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.

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.

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

Create a TLS data key visible to all threads in the process. the created key is later used to get/set a value. and optional destructor can be set to be called when a thread exits.

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.

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.

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.

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.

Author

Generated automatically by Doxygen for DPDK from the source code.

Thu May 23 2024 Version 23.11.0