[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_event.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of event abstraction.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_EVENT_H_\r
44 #define _CL_EVENT_H_\r
45 \r
46 \r
47 /* Indicates that waiting on an event should never timeout */\r
48 #define EVENT_NO_TIMEOUT        0xFFFFFFFF\r
49 \r
50 \r
51 #include <complib/cl_event_osd.h>\r
52 \r
53 \r
54 /****h* Component Library/Event\r
55 * NAME\r
56 *       Event\r
57 *\r
58 * DESCRIPTION\r
59 *       The Event provides the ability to suspend and wakeup a thread.\r
60 *\r
61 *       The event functions operates on a cl_event_t structure which should be\r
62 *       treated as opaque and should be manipulated only through the provided\r
63 *       functions.\r
64 *\r
65 * SEE ALSO\r
66 *       Structures:\r
67 *               cl_event_t\r
68 *\r
69 *       Initialization/Destruction:\r
70 *               cl_event_construct, cl_event_init, cl_event_destroy\r
71 *\r
72 *       Manipulation:\r
73 *               cl_event_signal, cl_event_reset, cl_event_wait_on\r
74 *********/\r
75 \r
76 \r
77 #ifdef __cplusplus\r
78 extern "C"\r
79 {\r
80 #endif\r
81 \r
82 \r
83 /****f* Component Library: Event/cl_event_construct\r
84 * NAME\r
85 *       cl_event_construct\r
86 *\r
87 * DESCRIPTION\r
88 *       The cl_event_construct function constructs an event.\r
89 *\r
90 * SYNOPSIS\r
91 */\r
92 CL_EXPORT void CL_API\r
93 cl_event_construct(\r
94         IN      cl_event_t* const       p_event );\r
95 /*\r
96 * PARAMETERS\r
97 *       p_event\r
98 *               [in] Pointer to an cl_event_t structure to construct.\r
99 *\r
100 * RETURN VALUE\r
101 *       This function does not return a value.\r
102 *\r
103 * NOTES\r
104 *       Allows calling cl_event_destroy without first calling cl_event_init.\r
105 *\r
106 *       Calling cl_event_construct is a prerequisite to calling any other event\r
107 *       function except cl_event_init.\r
108 *\r
109 * SEE ALSO\r
110 *       Event, cl_event_init, cl_event_destroy\r
111 *********/\r
112 \r
113 \r
114 /****f* Component Library: Event/cl_event_init\r
115 * NAME\r
116 *       cl_event_init\r
117 *\r
118 * DESCRIPTION\r
119 *       The cl_event_init function initializes an event for use.\r
120 *\r
121 * SYNOPSIS\r
122 */\r
123 CL_EXPORT cl_status_t CL_API\r
124 cl_event_init(\r
125         IN      cl_event_t* const       p_event,\r
126         IN      const boolean_t         manual_reset );\r
127 /*\r
128 * PARAMETERS\r
129 *       p_event\r
130 *               [in] Pointer to an cl_event_t structure to initialize.\r
131 *\r
132 *       manual_reset\r
133 *               [in] If FALSE, indicates that the event resets itself after releasing\r
134 *               a single waiter.  If TRUE, the event remains in the signalled state\r
135 *               until explicitly reset by a call to cl_event_reset.\r
136 *\r
137 * RETURN VALUES\r
138 *       CL_SUCCESS if event initialization succeeded.\r
139 *\r
140 *       CL_ERROR otherwise.\r
141 *\r
142 * NOTES\r
143 *       Allows calling event manipulation functions, such as cl_event_signal,\r
144 *       cl_event_reset, and cl_event_wait_on.\r
145 *\r
146 *       The event is initially in a reset state.\r
147 *\r
148 * SEE ALSO\r
149 *       Event, cl_event_construct, cl_event_destroy, cl_event_signal,\r
150 *       cl_event_reset, cl_event_wait_on\r
151 *********/\r
152 \r
153 \r
154 /****f* Component Library: Event/cl_event_destroy\r
155 * NAME\r
156 *       cl_event_destroy\r
157 *\r
158 * DESCRIPTION\r
159 *       The cl_event_destroy function performs any necessary cleanup of an event.\r
160 *\r
161 * SYNOPSIS\r
162 */\r
163 CL_EXPORT void CL_API\r
164 cl_event_destroy(\r
165         IN      cl_event_t* const       p_event );\r
166 \r
167 /*\r
168 * PARAMETERS\r
169 *       p_event\r
170 *               [in] Pointer to an cl_event_t structure to destroy.\r
171 *\r
172 * RETURN VALUE\r
173 *       This function does not return a value.\r
174 *\r
175 * NOTES\r
176 *       This function should only be called after a call to cl_event_construct\r
177 *       or cl_event_init.\r
178 *\r
179 * SEE ALSO\r
180 *       Event, cl_event_construct, cl_event_init\r
181 *********/\r
182 \r
183 \r
184 /****f* Component Library: Event/cl_event_signal\r
185 * NAME\r
186 *       cl_event_signal\r
187 *\r
188 * DESCRIPTION\r
189 *       The cl_event_signal function sets an event to the signalled state and\r
190 *       releases one or more waiting threads.\r
191 *\r
192 * SYNOPSIS\r
193 */\r
194 CL_EXPORT cl_status_t CL_API\r
195 cl_event_signal(\r
196         IN      cl_event_t* const       p_event );\r
197 /*\r
198 * PARAMETERS\r
199 *       p_event\r
200 *               [in] Pointer to an cl_event_t structure to set.\r
201 *\r
202 * RETURN VALUES\r
203 *       CL_SUCCESS if the event was successfully signalled.\r
204 *\r
205 *       CL_ERROR otherwise.\r
206 *\r
207 * NOTES\r
208 *       For auto-reset events, the event is reset automatically once a wait\r
209 *       operation is satisfied.\r
210 *\r
211 *       Triggering the event multiple times does not guarantee that the same\r
212 *       number of wait operations are satisfied. This is because events are\r
213 *       either in a signalled on non-signalled state, and triggering an event\r
214 *       that is already in the signalled state has no effect.\r
215 *\r
216 * SEE ALSO\r
217 *       Event, cl_event_reset, cl_event_wait_on\r
218 *********/\r
219 \r
220 \r
221 /****f* Component Library: Event/cl_event_reset\r
222 * NAME\r
223 *       cl_event_reset\r
224 *\r
225 * DESCRIPTION\r
226 *       The cl_event_reset function sets an event to the non-signalled state.\r
227 *\r
228 * SYNOPSIS\r
229 */\r
230 CL_EXPORT cl_status_t CL_API\r
231 cl_event_reset(\r
232         IN      cl_event_t* const       p_event );\r
233 /*\r
234 * PARAMETERS\r
235 *       p_event\r
236 *               [in] Pointer to an cl_event_t structure to reset.\r
237 *\r
238 * RETURN VALUES\r
239 *       CL_SUCCESS if the event was successfully reset.\r
240 *\r
241 *       CL_ERROR otherwise.\r
242 *\r
243 * SEE ALSO\r
244 *       Event, cl_event_signal, cl_event_wait_on\r
245 *********/\r
246 \r
247 \r
248 /****f* Component Library: Event/cl_event_wait_on\r
249 * NAME\r
250 *       cl_event_wait_on\r
251 *\r
252 * DESCRIPTION\r
253 *       The cl_event_wait_on function waits for the specified event to be\r
254 *       triggered for a minimum amount of time.\r
255 *\r
256 * SYNOPSIS\r
257 */\r
258 CL_EXPORT cl_status_t CL_API\r
259 cl_event_wait_on(\r
260         IN      cl_event_t* const       p_event,\r
261         IN      const uint32_t          wait_us,\r
262         IN      const boolean_t         interruptible );\r
263 /*\r
264 * PARAMETERS\r
265 *       p_event\r
266 *               [in] Pointer to an cl_event_t structure on which to wait.\r
267 *\r
268 *       wait_us\r
269 *               [in] Number of microseconds to wait.\r
270 *\r
271 *       interruptible\r
272 *               [in] Indicates whether the wait operation can be interrupted\r
273 *               by external signals.\r
274 *\r
275 * RETURN VALUES\r
276 *       CL_SUCCESS if the wait operation succeeded in response to the event\r
277 *       being set.\r
278 *\r
279 *       CL_TIMEOUT if the specified time period elapses.\r
280 *\r
281 *       CL_NOT_DONE if the wait was interrupted by an external signal.\r
282 *\r
283 *       CL_ERROR if the wait operation failed.\r
284 *\r
285 * NOTES\r
286 *       If wait_us is set to EVENT_NO_TIMEOUT, the function will wait until the\r
287 *       event is triggered and never timeout.\r
288 *\r
289 *       If the timeout value is zero, this function simply tests the state of\r
290 *       the event.\r
291 *\r
292 *       If the event is already in the signalled state at the time of the call\r
293 *       to cl_event_wait_on, the call completes immediately with CL_SUCCESS.\r
294 *\r
295 * SEE ALSO\r
296 *       Event, cl_event_signal, cl_event_reset\r
297 *********/\r
298 \r
299 \r
300 #ifdef __cplusplus\r
301 }       /* extern "C" */\r
302 #endif\r
303 \r
304 #endif /* _CL_EVENT_H_ */\r