cl_thread.h revision 219820
1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Declaration of thread abstraction and thread related operations. 39219820Sjeff */ 40219820Sjeff 41219820Sjeff#ifndef _CL_THREAD_H_ 42219820Sjeff#define _CL_THREAD_H_ 43219820Sjeff 44219820Sjeff#include <complib/cl_thread_osd.h> 45219820Sjeff 46219820Sjeff#ifdef __cplusplus 47219820Sjeff# define BEGIN_C_DECLS extern "C" { 48219820Sjeff# define END_C_DECLS } 49219820Sjeff#else /* !__cplusplus */ 50219820Sjeff# define BEGIN_C_DECLS 51219820Sjeff# define END_C_DECLS 52219820Sjeff#endif /* __cplusplus */ 53219820Sjeff 54219820SjeffBEGIN_C_DECLS 55219820Sjeff/****i* Component Library/Thread 56219820Sjeff* NAME 57219820Sjeff* Thread 58219820Sjeff* 59219820Sjeff* DESCRIPTION 60219820Sjeff* The Thread provides a separate thread of execution. 61219820Sjeff* 62219820Sjeff* The cl_thread_t structure should be treated as opaque and should be 63219820Sjeff* manipulated only through the provided functions. 64219820Sjeff*********/ 65219820Sjeff/****d* Component Library: Thread/cl_pfn_thread_callback_t 66219820Sjeff* NAME 67219820Sjeff* cl_pfn_thread_callback_t 68219820Sjeff* 69219820Sjeff* DESCRIPTION 70219820Sjeff* The cl_pfn_thread_callback_t function type defines the prototype 71219820Sjeff* for functions invoked by thread objects 72219820Sjeff* 73219820Sjeff* SYNOPSIS 74219820Sjeff*/ 75219820Sjefftypedef void (*cl_pfn_thread_callback_t) (IN void *context); 76219820Sjeff/* 77219820Sjeff* PARAMETERS 78219820Sjeff* context 79219820Sjeff* [in] Value specified in a call to cl_thread_init. 80219820Sjeff* 81219820Sjeff* RETURN VALUE 82219820Sjeff* This function does not return a value. 83219820Sjeff* 84219820Sjeff* NOTES 85219820Sjeff* This function type is provided as function prototype reference for 86219820Sjeff* the function provided by users as a parameter to cl_thread_init. 87219820Sjeff* 88219820Sjeff* SEE ALSO 89219820Sjeff* Thread Pool 90219820Sjeff*********/ 91219820Sjeff 92219820Sjeff/****i* Component Library: Thread/cl_thread_t 93219820Sjeff* NAME 94219820Sjeff* cl_thread_t 95219820Sjeff* 96219820Sjeff* DESCRIPTION 97219820Sjeff* Thread structure. 98219820Sjeff* 99219820Sjeff* The cl_thread_t structure should be treated as opaque and should be 100219820Sjeff* manipulated only through the provided functions. 101219820Sjeff* 102219820Sjeff* SYNOPSIS 103219820Sjeff*/ 104219820Sjefftypedef struct _cl_thread { 105219820Sjeff cl_thread_osd_t osd; 106219820Sjeff cl_pfn_thread_callback_t pfn_callback; 107219820Sjeff const void *context; 108219820Sjeff char name[16]; 109219820Sjeff} cl_thread_t; 110219820Sjeff/* 111219820Sjeff* FIELDS 112219820Sjeff* osd 113219820Sjeff* Implementation specific structure for managing thread information. 114219820Sjeff* 115219820Sjeff* pfn_callback 116219820Sjeff* Callback function for the thread to invoke. 117219820Sjeff* 118219820Sjeff* context 119219820Sjeff* Context to pass to the thread callback function. 120219820Sjeff* 121219820Sjeff* name 122219820Sjeff* Name to assign to the thread. 123219820Sjeff* 124219820Sjeff* SEE ALSO 125219820Sjeff* Thread 126219820Sjeff*********/ 127219820Sjeff 128219820Sjeff/****i* Component Library: Thread/cl_thread_construct 129219820Sjeff* NAME 130219820Sjeff* cl_thread_construct 131219820Sjeff* 132219820Sjeff* DESCRIPTION 133219820Sjeff* The cl_thread_construct function initializes the state of a thread. 134219820Sjeff* 135219820Sjeff* SYNOPSIS 136219820Sjeff*/ 137219820Sjeffvoid cl_thread_construct(IN cl_thread_t * const p_thread); 138219820Sjeff/* 139219820Sjeff* PARAMETERS 140219820Sjeff* p_thread 141219820Sjeff* [in] Pointer to a cl_thread_t structure whose state to initialize. 142219820Sjeff* 143219820Sjeff* RETURN VALUE 144219820Sjeff* This function does not return a value. 145219820Sjeff* 146219820Sjeff* NOTES 147219820Sjeff* Allows calling cl_thread_destroy without first calling cl_thread_init. 148219820Sjeff* 149219820Sjeff* Calling cl_thread_construct is a prerequisite to calling any other 150219820Sjeff* thread function except cl_thread_init. 151219820Sjeff* 152219820Sjeff* SEE ALSO 153219820Sjeff* Thread, cl_thread_init, cl_thread_destroy 154219820Sjeff*********/ 155219820Sjeff 156219820Sjeff/****i* Component Library: Thread/cl_thread_init 157219820Sjeff* NAME 158219820Sjeff* cl_thread_init 159219820Sjeff* 160219820Sjeff* DESCRIPTION 161219820Sjeff* The cl_thread_init function creates a new thread of execution. 162219820Sjeff* 163219820Sjeff* SYNOPSIS 164219820Sjeff*/ 165219820Sjeffcl_status_t 166219820Sjeffcl_thread_init(IN cl_thread_t * const p_thread, 167219820Sjeff IN cl_pfn_thread_callback_t pfn_callback, 168219820Sjeff IN const void *const context, IN const char *const name); 169219820Sjeff/* 170219820Sjeff* PARAMETERS 171219820Sjeff* p_thread 172219820Sjeff* [in] Pointer to a cl_thread_t structure to initialize. 173219820Sjeff* 174219820Sjeff* pfn_callback 175219820Sjeff* [in] Address of a function to be invoked by a thread. 176219820Sjeff* See the cl_pfn_thread_callback_t function type definition for 177219820Sjeff* details about the callback function. 178219820Sjeff* 179219820Sjeff* context 180219820Sjeff* [in] Value to pass to the callback function. 181219820Sjeff* 182219820Sjeff* name 183219820Sjeff* [in] Name to associate with the thread. The name may be up to 16 184219820Sjeff* characters, including a terminating null character. 185219820Sjeff* 186219820Sjeff* RETURN VALUES 187219820Sjeff* CL_SUCCESS if thread creation succeeded. 188219820Sjeff* 189219820Sjeff* CL_ERROR if thread creation failed. 190219820Sjeff* 191219820Sjeff* NOTES 192219820Sjeff* The thread created with cl_thread_init will invoke the callback 193219820Sjeff* specified by the callback parameter with context as single parameter. 194219820Sjeff* 195219820Sjeff* The callback function is invoked once, and the thread exits when the 196219820Sjeff* callback returns. 197219820Sjeff* 198219820Sjeff* It is invalid to call cl_thread_destroy from the callback function, 199219820Sjeff* as doing so will result in a deadlock. 200219820Sjeff* 201219820Sjeff* SEE ALSO 202219820Sjeff* Thread, cl_thread_construct, cl_thread_destroy, cl_thread_suspend, 203219820Sjeff* cl_thread_stall, cl_pfn_thread_callback_t 204219820Sjeff*********/ 205219820Sjeff 206219820Sjeff/****i* Component Library: Thread/cl_thread_destroy 207219820Sjeff* NAME 208219820Sjeff* cl_thread_destroy 209219820Sjeff* 210219820Sjeff* DESCRIPTION 211219820Sjeff* The cl_thread_destroy function performs any necessary cleanup to free 212219820Sjeff* resources associated with the specified thread. 213219820Sjeff* 214219820Sjeff* SYNOPSIS 215219820Sjeff*/ 216219820Sjeffvoid cl_thread_destroy(IN cl_thread_t * const p_thread); 217219820Sjeff/* 218219820Sjeff* PARAMETERS 219219820Sjeff* p_thread 220219820Sjeff* [in] Pointer to a cl_thread_t structure to destroy. 221219820Sjeff* 222219820Sjeff* RETURN VALUE 223219820Sjeff* This function does not return a value. 224219820Sjeff* 225219820Sjeff* NOTES 226219820Sjeff* This function blocks until the thread exits and must not be called by the 227219820Sjeff* thread itself. Callers must therefore ensure that such a blocking call is 228219820Sjeff* possible from the context of the call. 229219820Sjeff* 230219820Sjeff* This function must only be called after a call to cl_thread_construct or 231219820Sjeff* cl_thread_init. 232219820Sjeff* 233219820Sjeff* SEE ALSO 234219820Sjeff* Thread, cl_thread_construct, cl_thread_init 235219820Sjeff*********/ 236219820Sjeff 237219820Sjeff/****f* Component Library: Thread/cl_thread_suspend 238219820Sjeff* NAME 239219820Sjeff* cl_thread_suspend 240219820Sjeff* 241219820Sjeff* DESCRIPTION 242219820Sjeff* The cl_thread_suspend function suspends the calling thread for a minimum 243219820Sjeff* of the specified number of milliseconds. 244219820Sjeff* 245219820Sjeff* SYNOPSIS 246219820Sjeff*/ 247219820Sjeffvoid cl_thread_suspend(IN const uint32_t pause_ms); 248219820Sjeff/* 249219820Sjeff* PARAMETERS 250219820Sjeff* pause_ms 251219820Sjeff* [in] Number of milliseconds to suspend the calling thread. 252219820Sjeff* 253219820Sjeff* RETURN VALUE 254219820Sjeff* This function does not return a value. 255219820Sjeff* 256219820Sjeff* NOTES 257219820Sjeff* This function should only be called if it is valid for the caller's thread 258219820Sjeff* to enter a wait state. For stalling a thread that cannot enter a wait 259219820Sjeff* state, callers should use cl_thread_stall. 260219820Sjeff* 261219820Sjeff* SEE ALSO 262219820Sjeff* Thread, cl_thread_stall 263219820Sjeff*********/ 264219820Sjeff 265219820Sjeff/****f* Component Library: Thread/cl_thread_stall 266219820Sjeff* NAME 267219820Sjeff* cl_thread_stall 268219820Sjeff* 269219820Sjeff* DESCRIPTION 270219820Sjeff* The cl_thread_stall function stalls the calling thread for a minimum of 271219820Sjeff* the specified number of microseconds. 272219820Sjeff* 273219820Sjeff* SYNOPSIS 274219820Sjeff*/ 275219820Sjeffvoid cl_thread_stall(IN const uint32_t pause_us); 276219820Sjeff/* 277219820Sjeff* PARAMETERS 278219820Sjeff* pause_us 279219820Sjeff* [in] Number of microseconds to stall the calling thread. 280219820Sjeff* 281219820Sjeff* RETURN VALUE 282219820Sjeff* This function does not return a value. 283219820Sjeff* 284219820Sjeff* NOTES 285219820Sjeff* The cl_thread_stall function performs a busy wait for the specified 286219820Sjeff* number of microseconds. Care should be taken when using this function as 287219820Sjeff* it does not relinquish its quantum of operation. For longer wait 288219820Sjeff* operations, users should call cl_thread_suspend if possible. 289219820Sjeff* 290219820Sjeff* SEE ALSO 291219820Sjeff* Thread, cl_thread_suspend 292219820Sjeff*********/ 293219820Sjeff 294219820Sjeff/****f* Component Library: Thread/cl_proc_count 295219820Sjeff* NAME 296219820Sjeff* cl_proc_count 297219820Sjeff* 298219820Sjeff* DESCRIPTION 299219820Sjeff* The cl_proc_count function returns the number of processors in the system. 300219820Sjeff* 301219820Sjeff* SYNOPSIS 302219820Sjeff*/ 303219820Sjeffint cl_proc_count(void); 304219820Sjeff/* 305219820Sjeff* RETURN VALUE 306219820Sjeff* Returns the number of processors in the system. 307219820Sjeff*********/ 308219820Sjeff 309219820Sjeff/****i* Component Library: Thread/cl_is_current_thread 310219820Sjeff* NAME 311219820Sjeff* cl_is_current_thread 312219820Sjeff* 313219820Sjeff* DESCRIPTION 314219820Sjeff* The cl_is_current_thread function compares the calling thread to the 315219820Sjeff* specified thread and returns whether they are the same. 316219820Sjeff* 317219820Sjeff* SYNOPSIS 318219820Sjeff*/ 319219820Sjeffboolean_t cl_is_current_thread(IN const cl_thread_t * const p_thread); 320219820Sjeff/* 321219820Sjeff* PARAMETERS 322219820Sjeff* p_thread 323219820Sjeff* [in] Pointer to a cl_thread_t structure to compare to the 324219820Sjeff* caller's thead. 325219820Sjeff* 326219820Sjeff* RETURN VALUES 327219820Sjeff* TRUE if the thread specified by the p_thread parameter is the 328219820Sjeff* calling thread. 329219820Sjeff* 330219820Sjeff* FALSE otherwise. 331219820Sjeff* 332219820Sjeff* SEE ALSO 333219820Sjeff* Thread, cl_threadinit_t 334219820Sjeff*********/ 335219820Sjeff 336219820Sjeff/****f* Component Library: Thread/cl_is_blockable 337219820Sjeff* NAME 338219820Sjeff* cl_is_blockable 339219820Sjeff* 340219820Sjeff* DESCRIPTION 341219820Sjeff* The cl_is_blockable indicates if the current caller context is 342219820Sjeff* blockable. 343219820Sjeff* 344219820Sjeff* SYNOPSIS 345219820Sjeff*/ 346219820Sjeffboolean_t cl_is_blockable(void); 347219820Sjeff/* 348219820Sjeff* RETURN VALUE 349219820Sjeff* TRUE 350219820Sjeff* Current caller context can be blocked, i.e it is safe to perform 351219820Sjeff* a sleep, or call a down operation on a semaphore. 352219820Sjeff* 353219820Sjeff*********/ 354219820Sjeff 355219820SjeffEND_C_DECLS 356219820Sjeff#endif /* _CL_THREAD_H_ */ 357