contrib/ofed/management/opensm/include/complib/cl_thread.h

   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_ */