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