---
name: "rte_thread.h"
section: "3"
platform: "linux"
package: "dpdk-doc"
version: "24.11.4-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rte_thread.h"
---

# 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**

- *RTE\_THREAD\_PRIORITY\_NORMAL*

  *normal thread priority, the default*

- *RTE\_THREAD\_PRIORITY\_REALTIME\_CRITICAL*

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