lib/eal/include/rte_thread.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2021 Mellanox Technologies, Ltd
   3  * Copyright (C) 2022 Microsoft Corporation
   4  */
   5
   6 #include <stdint.h>
   7
   8 #include <rte_os.h>
   9 #include <rte_compat.h>
  10
  11 #ifndef _RTE_THREAD_H_
  12 #define _RTE_THREAD_H_
  13
  14 /**
  15  * @file
  16  *
  17  * Threading functions
  18  *
  19  * Simple threads functionality supplied by EAL.
  20  */
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * Thread id descriptor.
  28  */
  29 typedef struct {
  30         uintptr_t opaque_id; /**< thread identifier */
  31 } rte_thread_t;
  32
  33 /**
  34  * Thread priority values.
  35  */
  36 enum rte_thread_priority {
  37         RTE_THREAD_PRIORITY_NORMAL            = 0,
  38         /**< normal thread priority, the default */
  39         RTE_THREAD_PRIORITY_REALTIME_CRITICAL = 1,
  40         /**< highest thread priority allowed */
  41 };
  42
  43 /**
  44  * TLS key type, an opaque pointer.
  45  */
  46 typedef struct eal_tls_key *rte_thread_key;
  47
  48 /**
  49  * @warning
  50  * @b EXPERIMENTAL: this API may change without prior notice.
  51  *
  52  * Get the id of the calling thread.
  53  *
  54  * @return
  55  *   Return the thread id of the calling thread.
  56  */
  57 __rte_experimental
  58 rte_thread_t rte_thread_self(void);
  59
  60 #ifdef RTE_HAS_CPUSET
  61
  62 /**
  63  * @warning
  64  * @b EXPERIMENTAL: this API may change without prior notice.
  65  *
  66  * Set the affinity of thread 'thread_id' to the cpu set
  67  * specified by 'cpuset'.
  68  *
  69  * @param thread_id
  70  *    Id of the thread for which to set the affinity.
  71  *
  72  * @param cpuset
  73  *   Pointer to CPU affinity to set.
  74  *
  75  * @return
  76  *   On success, return 0.
  77  *   On failure, return a positive errno-style error number.
  78  */
  79 __rte_experimental
  80 int rte_thread_set_affinity_by_id(rte_thread_t thread_id,
  81                 const rte_cpuset_t *cpuset);
  82
  83 /**
  84  * @warning
  85  * @b EXPERIMENTAL: this API may change without prior notice.
  86  *
  87  * Get the affinity of thread 'thread_id' and store it
  88  * in 'cpuset'.
  89  *
  90  * @param thread_id
  91  *    Id of the thread for which to get the affinity.
  92  *
  93  * @param cpuset
  94  *   Pointer for storing the affinity value.
  95  *
  96  * @return
  97  *   On success, return 0.
  98  *   On failure, return a positive errno-style error number.
  99  */
 100 __rte_experimental
 101 int rte_thread_get_affinity_by_id(rte_thread_t thread_id,
 102                 rte_cpuset_t *cpuset);
 103
 104 /**
 105  * Set core affinity of the current thread.
 106  * Support both EAL and non-EAL thread and update TLS.
 107  *
 108  * @param cpusetp
 109  *   Pointer to CPU affinity to set.
 110  * @return
 111  *   On success, return 0; otherwise return -1;
 112  */
 113 int rte_thread_set_affinity(rte_cpuset_t *cpusetp);
 114
 115 /**
 116  * Get core affinity of the current thread.
 117  *
 118  * @param cpusetp
 119  *   Pointer to CPU affinity of current thread.
 120  *   It presumes input is not NULL, otherwise it causes panic.
 121  *
 122  */
 123 void rte_thread_get_affinity(rte_cpuset_t *cpusetp);
 124
 125 #endif /* RTE_HAS_CPUSET */
 126
 127 /**
 128  * @warning
 129  * @b EXPERIMENTAL: this API may change without prior notice.
 130  *
 131  * Get the priority of a thread.
 132  *
 133  * @param thread_id
 134  *   Id of the thread for which to get priority.
 135  *
 136  * @param priority
 137  *   Location to store the retrieved priority.
 138  *
 139  * @return
 140  *   On success, return 0.
 141  *   On failure, return a positive errno-style error number.
 142  */
 143 __rte_experimental
 144 int rte_thread_get_priority(rte_thread_t thread_id,
 145                 enum rte_thread_priority *priority);
 146
 147 /**
 148  * @warning
 149  * @b EXPERIMENTAL: this API may change without prior notice.
 150  *
 151  * Set the priority of a thread.
 152  *
 153  * @param thread_id
 154  *   Id of the thread for which to set priority.
 155  *
 156  * @param priority
 157  *   Priority value to be set.
 158  *
 159  * @return
 160  *   On success, return 0.
 161  *   On failure, return a positive errno-style error number.
 162  */
 163 __rte_experimental
 164 int rte_thread_set_priority(rte_thread_t thread_id,
 165                 enum rte_thread_priority priority);
 166
 167 /**
 168  * Create a TLS data key visible to all threads in the process.
 169  * the created key is later used to get/set a value.
 170  * and optional destructor can be set to be called when a thread exits.
 171  *
 172  * @param key
 173  *   Pointer to store the allocated key.
 174  * @param destructor
 175  *   The function to be called when the thread exits.
 176  *   Ignored on Windows OS.
 177  *
 178  * @return
 179  *   On success, zero.
 180  *   On failure, a negative number and an error number is set in rte_errno.
 181  *   rte_errno can be: ENOMEM  - Memory allocation error.
 182  *                     ENOEXEC - Specific OS error.
 183  */
 184
 185 __rte_experimental
 186 int rte_thread_key_create(rte_thread_key *key,
 187                         void (*destructor)(void *));
 188
 189 /**
 190  * Delete a TLS data key visible to all threads in the process.
 191  *
 192  * @param key
 193  *   The key allocated by rte_thread_key_create().
 194  *
 195  * @return
 196  *   On success, zero.
 197  *   On failure, a negative number and an error number is set in rte_errno.
 198  *   rte_errno can be: EINVAL  - Invalid parameter passed.
 199  *                     ENOEXEC - Specific OS error.
 200  */
 201 __rte_experimental
 202 int rte_thread_key_delete(rte_thread_key key);
 203
 204 /**
 205  * Set value bound to the TLS key on behalf of the calling thread.
 206  *
 207  * @param key
 208  *   The key allocated by rte_thread_key_create().
 209  * @param value
 210  *   The value bound to the rte_thread_key key for the calling thread.
 211  *
 212  * @return
 213  *   On success, zero.
 214  *   On failure, a negative number and an error number is set in rte_errno.
 215  *   rte_errno can be: EINVAL  - Invalid parameter passed.
 216  *                     ENOEXEC - Specific OS error.
 217  */
 218 __rte_experimental
 219 int rte_thread_value_set(rte_thread_key key, const void *value);
 220
 221 /**
 222  * Get value bound to the TLS key on behalf of the calling thread.
 223  *
 224  * @param key
 225  *   The key allocated by rte_thread_key_create().
 226  *
 227  * @return
 228  *   On success, value data pointer (can also be NULL).
 229  *   On failure, NULL and an error number is set in rte_errno.
 230  *   rte_errno can be: EINVAL  - Invalid parameter passed.
 231  *                     ENOEXEC - Specific OS error.
 232  */
 233 __rte_experimental
 234 void *rte_thread_value_get(rte_thread_key key);
 235
 236 #ifdef __cplusplus
 237 }
 238 #endif
 239
 240 #endif /* _RTE_THREAD_H_ */