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  * TLS key type, an opaque pointer.
  35  */
  36 typedef struct eal_tls_key *rte_thread_key;
  37
  38 /**
  39  * @warning
  40  * @b EXPERIMENTAL: this API may change without prior notice.
  41  *
  42  * Get the id of the calling thread.
  43  *
  44  * @return
  45  *   Return the thread id of the calling thread.
  46  */
  47 __rte_experimental
  48 rte_thread_t rte_thread_self(void);
  49
  50 #ifdef RTE_HAS_CPUSET
  51
  52 /**
  53  * @warning
  54  * @b EXPERIMENTAL: this API may change without prior notice.
  55  *
  56  * Set the affinity of thread 'thread_id' to the cpu set
  57  * specified by 'cpuset'.
  58  *
  59  * @param thread_id
  60  *    Id of the thread for which to set the affinity.
  61  *
  62  * @param cpuset
  63  *   Pointer to CPU affinity to set.
  64  *
  65  * @return
  66  *   On success, return 0.
  67  *   On failure, return a positive errno-style error number.
  68  */
  69 __rte_experimental
  70 int rte_thread_set_affinity_by_id(rte_thread_t thread_id,
  71                 const rte_cpuset_t *cpuset);
  72
  73 /**
  74  * @warning
  75  * @b EXPERIMENTAL: this API may change without prior notice.
  76  *
  77  * Get the affinity of thread 'thread_id' and store it
  78  * in 'cpuset'.
  79  *
  80  * @param thread_id
  81  *    Id of the thread for which to get the affinity.
  82  *
  83  * @param cpuset
  84  *   Pointer for storing the affinity value.
  85  *
  86  * @return
  87  *   On success, return 0.
  88  *   On failure, return a positive errno-style error number.
  89  */
  90 __rte_experimental
  91 int rte_thread_get_affinity_by_id(rte_thread_t thread_id,
  92                 rte_cpuset_t *cpuset);
  93
  94 /**
  95  * Set core affinity of the current thread.
  96  * Support both EAL and non-EAL thread and update TLS.
  97  *
  98  * @param cpusetp
  99  *   Pointer to CPU affinity to set.
 100  * @return
 101  *   On success, return 0; otherwise return -1;
 102  */
 103 int rte_thread_set_affinity(rte_cpuset_t *cpusetp);
 104
 105 /**
 106  * Get core affinity of the current thread.
 107  *
 108  * @param cpusetp
 109  *   Pointer to CPU affinity of current thread.
 110  *   It presumes input is not NULL, otherwise it causes panic.
 111  *
 112  */
 113 void rte_thread_get_affinity(rte_cpuset_t *cpusetp);
 114
 115 #endif /* RTE_HAS_CPUSET */
 116
 117 /**
 118  * Create a TLS data key visible to all threads in the process.
 119  * the created key is later used to get/set a value.
 120  * and optional destructor can be set to be called when a thread exits.
 121  *
 122  * @param key
 123  *   Pointer to store the allocated key.
 124  * @param destructor
 125  *   The function to be called when the thread exits.
 126  *   Ignored on Windows OS.
 127  *
 128  * @return
 129  *   On success, zero.
 130  *   On failure, a negative number and an error number is set in rte_errno.
 131  *   rte_errno can be: ENOMEM  - Memory allocation error.
 132  *                     ENOEXEC - Specific OS error.
 133  */
 134
 135 __rte_experimental
 136 int rte_thread_key_create(rte_thread_key *key,
 137                         void (*destructor)(void *));
 138
 139 /**
 140  * Delete a TLS data key visible to all threads in the process.
 141  *
 142  * @param key
 143  *   The key allocated by rte_thread_key_create().
 144  *
 145  * @return
 146  *   On success, zero.
 147  *   On failure, a negative number and an error number is set in rte_errno.
 148  *   rte_errno can be: EINVAL  - Invalid parameter passed.
 149  *                     ENOEXEC - Specific OS error.
 150  */
 151 __rte_experimental
 152 int rte_thread_key_delete(rte_thread_key key);
 153
 154 /**
 155  * Set value bound to the TLS key on behalf of the calling thread.
 156  *
 157  * @param key
 158  *   The key allocated by rte_thread_key_create().
 159  * @param value
 160  *   The value bound to the rte_thread_key key for the calling thread.
 161  *
 162  * @return
 163  *   On success, zero.
 164  *   On failure, a negative number and an error number is set in rte_errno.
 165  *   rte_errno can be: EINVAL  - Invalid parameter passed.
 166  *                     ENOEXEC - Specific OS error.
 167  */
 168 __rte_experimental
 169 int rte_thread_value_set(rte_thread_key key, const void *value);
 170
 171 /**
 172  * Get value bound to the TLS key on behalf of the calling thread.
 173  *
 174  * @param key
 175  *   The key allocated by rte_thread_key_create().
 176  *
 177  * @return
 178  *   On success, value data pointer (can also be NULL).
 179  *   On failure, NULL and an error number is set in rte_errno.
 180  *   rte_errno can be: EINVAL  - Invalid parameter passed.
 181  *                     ENOEXEC - Specific OS error.
 182  */
 183 __rte_experimental
 184 void *rte_thread_value_get(rte_thread_key key);
 185
 186 #ifdef __cplusplus
 187 }
 188 #endif
 189
 190 #endif /* _RTE_THREAD_H_ */