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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
38 * Declaration of thread abstraction and thread related operations.
44 #include <complib/cl_thread_osd.h>
47 # define BEGIN_C_DECLS extern "C" {
48 # define END_C_DECLS }
49 #else /* !__cplusplus */
50 # define BEGIN_C_DECLS
52 #endif /* __cplusplus */
55 /****i* Component Library/Thread
60 * The Thread provides a separate thread of execution.
62 * The cl_thread_t structure should be treated as opaque and should be
63 * manipulated only through the provided functions.
65 /****d* Component Library: Thread/cl_pfn_thread_callback_t
67 * cl_pfn_thread_callback_t
70 * The cl_pfn_thread_callback_t function type defines the prototype
71 * for functions invoked by thread objects
75 typedef void (*cl_pfn_thread_callback_t) (IN void *context);
79 * [in] Value specified in a call to cl_thread_init.
82 * This function does not return a value.
85 * This function type is provided as function prototype reference for
86 * the function provided by users as a parameter to cl_thread_init.
92 /****i* Component Library: Thread/cl_thread_t
99 * The cl_thread_t structure should be treated as opaque and should be
100 * manipulated only through the provided functions.
104 typedef struct _cl_thread {
106 cl_pfn_thread_callback_t pfn_callback;
113 * Implementation specific structure for managing thread information.
116 * Callback function for the thread to invoke.
119 * Context to pass to the thread callback function.
122 * Name to assign to the thread.
128 /****i* Component Library: Thread/cl_thread_construct
130 * cl_thread_construct
133 * The cl_thread_construct function initializes the state of a thread.
137 void cl_thread_construct(IN cl_thread_t * const p_thread);
141 * [in] Pointer to a cl_thread_t structure whose state to initialize.
144 * This function does not return a value.
147 * Allows calling cl_thread_destroy without first calling cl_thread_init.
149 * Calling cl_thread_construct is a prerequisite to calling any other
150 * thread function except cl_thread_init.
153 * Thread, cl_thread_init, cl_thread_destroy
156 /****i* Component Library: Thread/cl_thread_init
161 * The cl_thread_init function creates a new thread of execution.
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);
172 * [in] Pointer to a cl_thread_t structure to initialize.
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.
180 * [in] Value to pass to the callback function.
183 * [in] Name to associate with the thread. The name may be up to 16
184 * characters, including a terminating null character.
187 * CL_SUCCESS if thread creation succeeded.
189 * CL_ERROR if thread creation failed.
192 * The thread created with cl_thread_init will invoke the callback
193 * specified by the callback parameter with context as single parameter.
195 * The callback function is invoked once, and the thread exits when the
198 * It is invalid to call cl_thread_destroy from the callback function,
199 * as doing so will result in a deadlock.
202 * Thread, cl_thread_construct, cl_thread_destroy, cl_thread_suspend,
203 * cl_thread_stall, cl_pfn_thread_callback_t
206 /****i* Component Library: Thread/cl_thread_destroy
211 * The cl_thread_destroy function performs any necessary cleanup to free
212 * resources associated with the specified thread.
216 void cl_thread_destroy(IN cl_thread_t * const p_thread);
220 * [in] Pointer to a cl_thread_t structure to destroy.
223 * This function does not return a value.
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.
230 * This function must only be called after a call to cl_thread_construct or
234 * Thread, cl_thread_construct, cl_thread_init
237 /****f* Component Library: Thread/cl_thread_suspend
242 * The cl_thread_suspend function suspends the calling thread for a minimum
243 * of the specified number of milliseconds.
247 void cl_thread_suspend(IN const uint32_t pause_ms);
251 * [in] Number of milliseconds to suspend the calling thread.
254 * This function does not return a value.
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.
262 * Thread, cl_thread_stall
265 /****f* Component Library: Thread/cl_thread_stall
270 * The cl_thread_stall function stalls the calling thread for a minimum of
271 * the specified number of microseconds.
275 void cl_thread_stall(IN const uint32_t pause_us);
279 * [in] Number of microseconds to stall the calling thread.
282 * This function does not return a value.
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.
291 * Thread, cl_thread_suspend
294 /****f* Component Library: Thread/cl_proc_count
299 * The cl_proc_count function returns the number of processors in the system.
303 int cl_proc_count(void);
306 * Returns the number of processors in the system.
309 /****i* Component Library: Thread/cl_is_current_thread
311 * cl_is_current_thread
314 * The cl_is_current_thread function compares the calling thread to the
315 * specified thread and returns whether they are the same.
319 boolean_t cl_is_current_thread(IN const cl_thread_t * const p_thread);
323 * [in] Pointer to a cl_thread_t structure to compare to the
327 * TRUE if the thread specified by the p_thread parameter is the
333 * Thread, cl_threadinit_t
336 /****f* Component Library: Thread/cl_is_blockable
341 * The cl_is_blockable indicates if the current caller context is
346 boolean_t cl_is_blockable(void);
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.
356 #endif /* _CL_THREAD_H_ */