.TH "rte_thread.h" 3 "Version 25.11.0" "DPDK" \" -*- nroff -*-
.ad l
.nh
.SH NAME
rte_thread.h
.SH SYNOPSIS
.br
.PP
\fR#include <stdint\&.h>\fP
.br
\fR#include <rte_os\&.h>\fP
.br
\fR#include <rte_compat\&.h>\fP
.br

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBrte_thread_t\fP"
.br
.ti -1c
.RI "struct \fBrte_thread_attr_t\fP"
.br
.in -1c
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBRTE_THREAD_NAME_SIZE\fP   16"
.br
.ti -1c
.RI "#define \fBRTE_THREAD_INTERNAL_PREFIX\fP   'dpdk\-'"
.br
.ti -1c
.RI "#define \fBRTE_THREAD_INTERNAL_NAME_SIZE\fP   11"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "\fBtypedef\fP uint32_t(* \fBrte_thread_func\fP) (void *arg)"
.br
.ti -1c
.RI "\fBtypedef\fP struct eal_tls_key * \fBrte_thread_key\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBrte_thread_priority\fP { \fBRTE_THREAD_PRIORITY_NORMAL\fP = 0, \fBRTE_THREAD_PRIORITY_REALTIME_CRITICAL\fP = 1 }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBrte_thread_create\fP (\fBrte_thread_t\fP *thread_id, const \fBrte_thread_attr_t\fP *thread_attr, \fBrte_thread_func\fP thread_func, void *arg)"
.br
.ti -1c
.RI "int \fBrte_thread_create_control\fP (\fBrte_thread_t\fP *thread, const char *name, \fBrte_thread_func\fP thread_func, void *arg)"
.br
.ti -1c
.RI "__rte_internal int \fBrte_thread_create_internal_control\fP (\fBrte_thread_t\fP *id, const char *name, \fBrte_thread_func\fP func, void *arg)"
.br
.ti -1c
.RI "int \fBrte_thread_join\fP (\fBrte_thread_t\fP thread_id, uint32_t *value_ptr)"
.br
.ti -1c
.RI "int \fBrte_thread_detach\fP (\fBrte_thread_t\fP thread_id)"
.br
.ti -1c
.RI "\fBrte_thread_t\fP \fBrte_thread_self\fP (void)"
.br
.ti -1c
.RI "void \fBrte_thread_set_name\fP (\fBrte_thread_t\fP thread_id, const char *thread_name)"
.br
.ti -1c
.RI "__rte_internal void \fBrte_thread_set_prefixed_name\fP (\fBrte_thread_t\fP id, const char *name)"
.br
.ti -1c
.RI "int \fBrte_thread_equal\fP (\fBrte_thread_t\fP t1, \fBrte_thread_t\fP t2)"
.br
.ti -1c
.RI "int \fBrte_thread_attr_init\fP (\fBrte_thread_attr_t\fP *attr)"
.br
.ti -1c
.RI "int \fBrte_thread_attr_set_priority\fP (\fBrte_thread_attr_t\fP *thread_attr, enum \fBrte_thread_priority\fP priority)"
.br
.ti -1c
.RI "int \fBrte_thread_attr_set_affinity\fP (\fBrte_thread_attr_t\fP *thread_attr, rte_cpuset_t *cpuset)"
.br
.ti -1c
.RI "int \fBrte_thread_attr_get_affinity\fP (\fBrte_thread_attr_t\fP *thread_attr, rte_cpuset_t *cpuset)"
.br
.ti -1c
.RI "int \fBrte_thread_set_affinity_by_id\fP (\fBrte_thread_t\fP thread_id, const rte_cpuset_t *cpuset)"
.br
.ti -1c
.RI "int \fBrte_thread_get_affinity_by_id\fP (\fBrte_thread_t\fP thread_id, rte_cpuset_t *cpuset)"
.br
.ti -1c
.RI "int \fBrte_thread_set_affinity\fP (rte_cpuset_t *cpusetp)"
.br
.ti -1c
.RI "void \fBrte_thread_get_affinity\fP (rte_cpuset_t *cpusetp)"
.br
.ti -1c
.RI "int \fBrte_thread_get_priority\fP (\fBrte_thread_t\fP thread_id, enum \fBrte_thread_priority\fP *priority)"
.br
.ti -1c
.RI "int \fBrte_thread_set_priority\fP (\fBrte_thread_t\fP thread_id, enum \fBrte_thread_priority\fP priority)"
.br
.ti -1c
.RI "int \fBrte_thread_key_create\fP (\fBrte_thread_key\fP *key, void(*destructor)(void *))"
.br
.ti -1c
.RI "int \fBrte_thread_key_delete\fP (\fBrte_thread_key\fP key)"
.br
.ti -1c
.RI "int \fBrte_thread_value_set\fP (\fBrte_thread_key\fP key, const void *value)"
.br
.ti -1c
.RI "void * \fBrte_thread_value_get\fP (\fBrte_thread_key\fP key)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Threading functions

.PP
Simple threads functionality supplied by EAL\&. 
.PP
Definition in file \fBrte_thread\&.h\fP\&.
.SH "Macro Definition Documentation"
.PP 
.SS "#define RTE_THREAD_NAME_SIZE   16"
Maximum thread name length (including '\\0')\&. 
.PP
Definition at line \fB27\fP of file \fBrte_thread\&.h\fP\&.
.SS "#define RTE_THREAD_INTERNAL_PREFIX   'dpdk\-'"
Thread name prefix automatically added to all internal threads\&. 
.PP
Definition at line \fB32\fP of file \fBrte_thread\&.h\fP\&.
.SS "#define RTE_THREAD_INTERNAL_NAME_SIZE   11"
Maximum internal thread name length (including '\\0')\&. 
.PP
Definition at line \fB34\fP of file \fBrte_thread\&.h\fP\&.
.SH "Typedef Documentation"
.PP 
.SS "\fBtypedef\fP uint32_t(* rte_thread_func) (void *arg)"
Thread function

.PP
Function pointer to thread start routine\&.

.PP
\fBParameters\fP
.RS 4
\fIarg\fP Argument passed to \fBrte_thread_create()\fP\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Thread function exit value\&. 
.RE
.PP

.PP
Definition at line \fB53\fP of file \fBrte_thread\&.h\fP\&.
.SS "\fBtypedef\fP struct eal_tls_key* \fBrte_thread_key\fP"
TLS key type, an opaque pointer\&. 
.PP
Definition at line \fB78\fP of file \fBrte_thread\&.h\fP\&.
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBrte_thread_priority\fP"
Thread priority values\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIRTE_THREAD_PRIORITY_NORMAL \fP
normal thread priority, the default 
.TP
\f(BIRTE_THREAD_PRIORITY_REALTIME_CRITICAL \fP
highest thread priority allowed 
.PP
Definition at line \fB58\fP of file \fBrte_thread\&.h\fP\&.
.SH "Function Documentation"
.PP 
.SS "int rte_thread_create (\fBrte_thread_t\fP * thread_id, const \fBrte_thread_attr_t\fP * thread_attr, \fBrte_thread_func\fP thread_func, void * arg)"
Create a new thread that will invoke the 'thread_func' routine\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP A pointer that will store the id of the newly created thread\&.
.br
\fIthread_attr\fP Attributes that are used at the creation of the new thread\&.
.br
\fIthread_func\fP The routine that the new thread will invoke when starting execution\&.
.br
\fIarg\fP Argument to be passed to the 'thread_func' routine\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_create_control (\fBrte_thread_t\fP * thread, const char * name, \fBrte_thread_func\fP thread_func, void * arg)"
Create a control thread\&.

.PP
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 \fBrte_eal_init()\fP 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\&.

.PP
\fBParameters\fP
.RS 4
\fIthread\fP Filled with the thread id of the new created thread\&. 
.br
\fIname\fP The name of the control thread (max RTE_THREAD_NAME_SIZE characters including '\\0')\&. 
.br
\fIthread_func\fP Function to be executed by the new thread\&. 
.br
\fIarg\fP Argument passed to thread_func\&. 
.RE
.PP
\fBReturns\fP
.RS 4
On success, returns 0; on error, it returns a negative value corresponding to the error number\&. 
.RE
.PP

.SS "__rte_internal int rte_thread_create_internal_control (\fBrte_thread_t\fP * id, const char * name, \fBrte_thread_func\fP func, void * arg)"
Create an internal control thread\&.

.PP
Creates a control thread with the given name prefixed\&. If setting the name of the thread fails, the error is ignored and logged\&.

.PP
The affinity of the new thread is based on the CPU affinity retrieved at the time \fBrte_eal_init()\fP was called, the EAL threads are then excluded\&.

.PP
\fBParameters\fP
.RS 4
\fIid\fP Filled with the thread ID of the new created thread\&. 
.br
\fIname\fP 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\&. 
.br
\fIfunc\fP Function to be executed by the new thread\&. 
.br
\fIarg\fP Argument passed to func\&. 
.RE
.PP
\fBReturns\fP
.RS 4
On success, returns 0; a negative value otherwise\&. 
.RE
.PP

.SS "int rte_thread_join (\fBrte_thread_t\fP thread_id, uint32_t * value_ptr)"
Waits for the thread identified by 'thread_id' to terminate

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP The identifier of the thread\&.
.br
\fIvalue_ptr\fP Stores the exit status of the thread\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_detach (\fBrte_thread_t\fP thread_id)"
Indicate that the return value of the thread is not needed and all thread resources should be release when the thread terminates\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP The id of the thread to be detached\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "\fBrte_thread_t\fP rte_thread_self (void )"
Get the id of the calling thread\&.

.PP
\fBReturns\fP
.RS 4
Return the thread id of the calling thread\&. 
.RE
.PP

.SS "void rte_thread_set_name (\fBrte_thread_t\fP thread_id, const char * thread_name)"
Set the name of the thread\&.

.PP
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\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP The id of the thread to set name\&.
.br
\fIthread_name\fP The name to set\&. Truncated to RTE_THREAD_NAME_SIZE, including terminating NUL if necessary\&. 
.RE
.PP

.SS "__rte_internal void rte_thread_set_prefixed_name (\fBrte_thread_t\fP id, const char * name)"
Set the name of an internal thread with the common prefix\&.

.PP
This API is a noop if the underlying platform does not support setting the thread name, or if it fails\&.

.PP
\fBParameters\fP
.RS 4
\fIid\fP The ID of the thread to set name\&.
.br
\fIname\fP 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\&. 
.RE
.PP

.SS "int rte_thread_equal (\fBrte_thread_t\fP t1, \fBrte_thread_t\fP t2)"
Check if 2 thread ids are equal\&.

.PP
\fBParameters\fP
.RS 4
\fIt1\fP First thread id\&.
.br
\fIt2\fP Second thread id\&.
.RE
.PP
\fBReturns\fP
.RS 4
If the ids are equal, return nonzero\&. Otherwise, return 0\&. 
.RE
.PP

.SS "int rte_thread_attr_init (\fBrte_thread_attr_t\fP * attr)"
Initialize the attributes of a thread\&. These attributes can be passed to the \fBrte_thread_create()\fP function that will create a new thread and set its attributes according to attr\&.

.PP
\fBParameters\fP
.RS 4
\fIattr\fP Thread attributes to initialize\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_attr_set_priority (\fBrte_thread_attr_t\fP * thread_attr, enum \fBrte_thread_priority\fP priority)"
Set the thread priority value in the thread attributes pointed to by 'thread_attr'\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_attr\fP Points to the thread attributes in which priority will be updated\&.
.br
\fIpriority\fP Points to the value of the priority to be set\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_attr_set_affinity (\fBrte_thread_attr_t\fP * thread_attr, rte_cpuset_t * cpuset)"
Set the CPU affinity value in the thread attributes pointed to by 'thread_attr'\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_attr\fP Points to the thread attributes in which affinity will be updated\&.
.br
\fIcpuset\fP Points to the value of the affinity to be set\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_attr_get_affinity (\fBrte_thread_attr_t\fP * thread_attr, rte_cpuset_t * cpuset)"
Get the value of CPU affinity that is set in the thread attributes pointed to by 'thread_attr'\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_attr\fP Points to the thread attributes from which affinity will be retrieved\&.
.br
\fIcpuset\fP Pointer to the memory that will store the affinity\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_set_affinity_by_id (\fBrte_thread_t\fP thread_id, const rte_cpuset_t * cpuset)"
Set the affinity of thread 'thread_id' to the cpu set specified by 'cpuset'\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP Id of the thread for which to set the affinity\&.
.br
\fIcpuset\fP Pointer to CPU affinity to set\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_get_affinity_by_id (\fBrte_thread_t\fP thread_id, rte_cpuset_t * cpuset)"
Get the affinity of thread 'thread_id' and store it in 'cpuset'\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP Id of the thread for which to get the affinity\&.
.br
\fIcpuset\fP Pointer for storing the affinity value\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "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\&.

.PP
\fBParameters\fP
.RS 4
\fIcpusetp\fP Pointer to CPU affinity to set\&. 
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0; otherwise return -1; 
.RE
.PP

.SS "void rte_thread_get_affinity (rte_cpuset_t * cpusetp)"
Get core affinity of the current thread\&.

.PP
\fBParameters\fP
.RS 4
\fIcpusetp\fP Pointer to CPU affinity of current thread\&. It presumes input is not NULL, otherwise it causes panic\&. 
.RE
.PP

.SS "int rte_thread_get_priority (\fBrte_thread_t\fP thread_id, enum \fBrte_thread_priority\fP * priority)"
Get the priority of a thread\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP Id of the thread for which to get priority\&.
.br
\fIpriority\fP Location to store the retrieved priority\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_set_priority (\fBrte_thread_t\fP thread_id, enum \fBrte_thread_priority\fP priority)"
Set the priority of a thread\&.

.PP
\fBParameters\fP
.RS 4
\fIthread_id\fP Id of the thread for which to set priority\&.
.br
\fIpriority\fP Priority value to be set\&.
.RE
.PP
\fBReturns\fP
.RS 4
On success, return 0\&. On failure, return a positive errno-style error number\&. 
.RE
.PP

.SS "int rte_thread_key_create (\fBrte_thread_key\fP * 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 optional destructor can be set to be called when a thread exits\&.

.PP
\fBParameters\fP
.RS 4
\fIkey\fP Pointer to store the allocated key\&. 
.br
\fIdestructor\fP The function to be called when the thread exits\&. Ignored on Windows OS\&.
.RE
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SS "int rte_thread_key_delete (\fBrte_thread_key\fP key)"
Delete a TLS data key visible to all threads in the process\&.

.PP
\fBParameters\fP
.RS 4
\fIkey\fP The key allocated by \fBrte_thread_key_create()\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SS "int rte_thread_value_set (\fBrte_thread_key\fP key, const void * value)"
Set value bound to the TLS key on behalf of the calling thread\&.

.PP
\fBParameters\fP
.RS 4
\fIkey\fP The key allocated by \fBrte_thread_key_create()\fP\&. 
.br
\fIvalue\fP The value bound to the \fBrte_thread_key\fP key for the calling thread\&.
.RE
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SS "void * rte_thread_value_get (\fBrte_thread_key\fP key)"
Get value bound to the TLS key on behalf of the calling thread\&.

.PP
\fBParameters\fP
.RS 4
\fIkey\fP The key allocated by \fBrte_thread_key_create()\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for DPDK from the source code\&.
