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 54BEGIN_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*/ 75typedef 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*/ 104typedef 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*/ 137void 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*/ 165cl_status_t 166cl_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*/ 216void 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*/ 247void 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*/ 275void 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*/ 303int 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*/ 319boolean_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*/ 346boolean_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 355END_C_DECLS 356#endif /* _CL_THREAD_H_ */ 357