1 /* 2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5 * 6 * This software is available to you under a choice of one of two 7 * licenses. You may choose to be licensed under the terms of the GNU 8 * General Public License (GPL) Version 2, available from the file 9 * COPYING in the main directory of this source tree, or the 10 * OpenIB.org BSD license below: 11 * 12 * Redistribution and use in source and binary forms, with or 13 * without modification, are permitted provided that the following 14 * conditions are met: 15 * 16 * - Redistributions of source code must retain the above 17 * copyright notice, this list of conditions and the following 18 * disclaimer. 19 * 20 * - Redistributions in binary form must reproduce the above 21 * copyright notice, this list of conditions and the following 22 * disclaimer in the documentation and/or other materials 23 * provided with the distribution. 24 * 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32 * SOFTWARE. 33 * 34 */ 35 36 /* 37 * Abstract: 38 * Declaration of thread abstraction and thread related operations. 39 */ 40 41 #ifndef _CL_THREAD_H_ 42 #define _CL_THREAD_H_ 43 44 #include <complib/cl_thread_osd.h> 45 46 #ifdef __cplusplus 47 # define BEGIN_C_DECLS extern "C" { 48 # define END_C_DECLS } 49 #else /* !__cplusplus */ 50 # define BEGIN_C_DECLS 51 # define END_C_DECLS 52 #endif /* __cplusplus */ 53 54 BEGIN_C_DECLS 55 /****i* Component Library/Thread 56 * NAME 57 * Thread 58 * 59 * DESCRIPTION 60 * The Thread provides a separate thread of execution. 61 * 62 * The cl_thread_t structure should be treated as opaque and should be 63 * manipulated only through the provided functions. 64 *********/ 65 /****d* Component Library: Thread/cl_pfn_thread_callback_t 66 * NAME 67 * cl_pfn_thread_callback_t 68 * 69 * DESCRIPTION 70 * The cl_pfn_thread_callback_t function type defines the prototype 71 * for functions invoked by thread objects 72 * 73 * SYNOPSIS 74 */ 75 typedef void (*cl_pfn_thread_callback_t) (IN void *context); 76 /* 77 * PARAMETERS 78 * context 79 * [in] Value specified in a call to cl_thread_init. 80 * 81 * RETURN VALUE 82 * This function does not return a value. 83 * 84 * NOTES 85 * This function type is provided as function prototype reference for 86 * the function provided by users as a parameter to cl_thread_init. 87 * 88 * SEE ALSO 89 * Thread Pool 90 *********/ 91 92 /****i* Component Library: Thread/cl_thread_t 93 * NAME 94 * cl_thread_t 95 * 96 * DESCRIPTION 97 * Thread structure. 98 * 99 * The cl_thread_t structure should be treated as opaque and should be 100 * manipulated only through the provided functions. 101 * 102 * SYNOPSIS 103 */ 104 typedef struct _cl_thread { 105 cl_thread_osd_t osd; 106 cl_pfn_thread_callback_t pfn_callback; 107 const void *context; 108 char name[16]; 109 } cl_thread_t; 110 /* 111 * FIELDS 112 * osd 113 * Implementation specific structure for managing thread information. 114 * 115 * pfn_callback 116 * Callback function for the thread to invoke. 117 * 118 * context 119 * Context to pass to the thread callback function. 120 * 121 * name 122 * Name to assign to the thread. 123 * 124 * SEE ALSO 125 * Thread 126 *********/ 127 128 /****i* Component Library: Thread/cl_thread_construct 129 * NAME 130 * cl_thread_construct 131 * 132 * DESCRIPTION 133 * The cl_thread_construct function initializes the state of a thread. 134 * 135 * SYNOPSIS 136 */ 137 void cl_thread_construct(IN cl_thread_t * const p_thread); 138 /* 139 * PARAMETERS 140 * p_thread 141 * [in] Pointer to a cl_thread_t structure whose state to initialize. 142 * 143 * RETURN VALUE 144 * This function does not return a value. 145 * 146 * NOTES 147 * Allows calling cl_thread_destroy without first calling cl_thread_init. 148 * 149 * Calling cl_thread_construct is a prerequisite to calling any other 150 * thread function except cl_thread_init. 151 * 152 * SEE ALSO 153 * Thread, cl_thread_init, cl_thread_destroy 154 *********/ 155 156 /****i* Component Library: Thread/cl_thread_init 157 * NAME 158 * cl_thread_init 159 * 160 * DESCRIPTION 161 * The cl_thread_init function creates a new thread of execution. 162 * 163 * SYNOPSIS 164 */ 165 cl_status_t 166 cl_thread_init(IN cl_thread_t * const p_thread, 167 IN cl_pfn_thread_callback_t pfn_callback, 168 IN const void *const context, IN const char *const name); 169 /* 170 * PARAMETERS 171 * p_thread 172 * [in] Pointer to a cl_thread_t structure to initialize. 173 * 174 * pfn_callback 175 * [in] Address of a function to be invoked by a thread. 176 * See the cl_pfn_thread_callback_t function type definition for 177 * details about the callback function. 178 * 179 * context 180 * [in] Value to pass to the callback function. 181 * 182 * name 183 * [in] Name to associate with the thread. The name may be up to 16 184 * characters, including a terminating null character. 185 * 186 * RETURN VALUES 187 * CL_SUCCESS if thread creation succeeded. 188 * 189 * CL_ERROR if thread creation failed. 190 * 191 * NOTES 192 * The thread created with cl_thread_init will invoke the callback 193 * specified by the callback parameter with context as single parameter. 194 * 195 * The callback function is invoked once, and the thread exits when the 196 * callback returns. 197 * 198 * It is invalid to call cl_thread_destroy from the callback function, 199 * as doing so will result in a deadlock. 200 * 201 * SEE ALSO 202 * Thread, cl_thread_construct, cl_thread_destroy, cl_thread_suspend, 203 * cl_thread_stall, cl_pfn_thread_callback_t 204 *********/ 205 206 /****i* Component Library: Thread/cl_thread_destroy 207 * NAME 208 * cl_thread_destroy 209 * 210 * DESCRIPTION 211 * The cl_thread_destroy function performs any necessary cleanup to free 212 * resources associated with the specified thread. 213 * 214 * SYNOPSIS 215 */ 216 void cl_thread_destroy(IN cl_thread_t * const p_thread); 217 /* 218 * PARAMETERS 219 * p_thread 220 * [in] Pointer to a cl_thread_t structure to destroy. 221 * 222 * RETURN VALUE 223 * This function does not return a value. 224 * 225 * NOTES 226 * This function blocks until the thread exits and must not be called by the 227 * thread itself. Callers must therefore ensure that such a blocking call is 228 * possible from the context of the call. 229 * 230 * This function must only be called after a call to cl_thread_construct or 231 * cl_thread_init. 232 * 233 * SEE ALSO 234 * Thread, cl_thread_construct, cl_thread_init 235 *********/ 236 237 /****f* Component Library: Thread/cl_thread_suspend 238 * NAME 239 * cl_thread_suspend 240 * 241 * DESCRIPTION 242 * The cl_thread_suspend function suspends the calling thread for a minimum 243 * of the specified number of milliseconds. 244 * 245 * SYNOPSIS 246 */ 247 void cl_thread_suspend(IN const uint32_t pause_ms); 248 /* 249 * PARAMETERS 250 * pause_ms 251 * [in] Number of milliseconds to suspend the calling thread. 252 * 253 * RETURN VALUE 254 * This function does not return a value. 255 * 256 * NOTES 257 * This function should only be called if it is valid for the caller's thread 258 * to enter a wait state. For stalling a thread that cannot enter a wait 259 * state, callers should use cl_thread_stall. 260 * 261 * SEE ALSO 262 * Thread, cl_thread_stall 263 *********/ 264 265 /****f* Component Library: Thread/cl_thread_stall 266 * NAME 267 * cl_thread_stall 268 * 269 * DESCRIPTION 270 * The cl_thread_stall function stalls the calling thread for a minimum of 271 * the specified number of microseconds. 272 * 273 * SYNOPSIS 274 */ 275 void cl_thread_stall(IN const uint32_t pause_us); 276 /* 277 * PARAMETERS 278 * pause_us 279 * [in] Number of microseconds to stall the calling thread. 280 * 281 * RETURN VALUE 282 * This function does not return a value. 283 * 284 * NOTES 285 * The cl_thread_stall function performs a busy wait for the specified 286 * number of microseconds. Care should be taken when using this function as 287 * it does not relinquish its quantum of operation. For longer wait 288 * operations, users should call cl_thread_suspend if possible. 289 * 290 * SEE ALSO 291 * Thread, cl_thread_suspend 292 *********/ 293 294 /****f* Component Library: Thread/cl_proc_count 295 * NAME 296 * cl_proc_count 297 * 298 * DESCRIPTION 299 * The cl_proc_count function returns the number of processors in the system. 300 * 301 * SYNOPSIS 302 */ 303 int cl_proc_count(void); 304 /* 305 * RETURN VALUE 306 * Returns the number of processors in the system. 307 *********/ 308 309 /****i* Component Library: Thread/cl_is_current_thread 310 * NAME 311 * cl_is_current_thread 312 * 313 * DESCRIPTION 314 * The cl_is_current_thread function compares the calling thread to the 315 * specified thread and returns whether they are the same. 316 * 317 * SYNOPSIS 318 */ 319 boolean_t cl_is_current_thread(IN const cl_thread_t * const p_thread); 320 /* 321 * PARAMETERS 322 * p_thread 323 * [in] Pointer to a cl_thread_t structure to compare to the 324 * caller's thead. 325 * 326 * RETURN VALUES 327 * TRUE if the thread specified by the p_thread parameter is the 328 * calling thread. 329 * 330 * FALSE otherwise. 331 * 332 * SEE ALSO 333 * Thread, cl_threadinit_t 334 *********/ 335 336 /****f* Component Library: Thread/cl_is_blockable 337 * NAME 338 * cl_is_blockable 339 * 340 * DESCRIPTION 341 * The cl_is_blockable indicates if the current caller context is 342 * blockable. 343 * 344 * SYNOPSIS 345 */ 346 boolean_t cl_is_blockable(void); 347 /* 348 * RETURN VALUE 349 * TRUE 350 * Current caller context can be blocked, i.e it is safe to perform 351 * a sleep, or call a down operation on a semaphore. 352 * 353 *********/ 354 355 END_C_DECLS 356 #endif /* _CL_THREAD_H_ */ 357