a7f362499825b6bc73be44d74e228c985bb1cad7
[mirror/winof/.git] / inc / complib / cl_timer.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 timer abstraction.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_TIMER_H_\r
44 #define _CL_TIMER_H_\r
45 \r
46 \r
47 #include <complib/cl_types.h>\r
48 \r
49 \r
50 /****h* Component Library/Timer\r
51 * NAME\r
52 *       Timer\r
53 *\r
54 * DESCRIPTION\r
55 *       The Timer provides the ability to schedule a function to be invoked at\r
56 *       a given time in the future.\r
57 *\r
58 *       The timer callback function must not perform any blocking operations.\r
59 *\r
60 *       The timer functions operate on a cl_timer_t structure which should be\r
61 *       treated as opaque and should be manipulated only through the provided\r
62 *       functions.\r
63 *\r
64 * SEE ALSO\r
65 *       Structures:\r
66 *               cl_timer_t\r
67 *\r
68 *       Callbacks:\r
69 *               cl_pfn_timer_callback_t\r
70 *\r
71 *       Initialization:\r
72 *               cl_timer_construct, cl_timer_init, cl_timer_destroy\r
73 *\r
74 *       Manipulation:\r
75 *               cl_timer_start, cl_timer_stop\r
76 *********/\r
77 \r
78 \r
79 /****d* Component Library: Timer/cl_pfn_timer_callback_t\r
80 * NAME\r
81 *       cl_pfn_timer_callback_t\r
82 *\r
83 * DESCRIPTION\r
84 *       The cl_pfn_timer_callback_t function type defines the prototype for\r
85 *       functions used to notify users of a timer expiration.\r
86 *\r
87 * SYNOPSIS\r
88 */\r
89 typedef void\r
90 (CL_API *cl_pfn_timer_callback_t)(\r
91         IN void*        context );\r
92 /*\r
93 * PARAMETERS\r
94 *       context\r
95 *               [in] Value specified in a previous call to cl_timer_init.\r
96 *\r
97 * RETURN VALUE\r
98 *       This function does not return a value.\r
99 *\r
100 * NOTES\r
101 *       This function type is provided as function prototype reference for the\r
102 *       function provided by users as a parameter to the cl_timer_init function.\r
103 *\r
104 * SEE ALSO\r
105 *       Timer, cl_timer_init\r
106 *********/\r
107 \r
108 \r
109 /*\r
110  * This include file defines the timer structure, and depends on the timer\r
111  * callback definition.\r
112  */\r
113 #include <complib/cl_timer_osd.h>\r
114 \r
115 \r
116 #ifdef __cplusplus\r
117 extern "C"\r
118 {\r
119 #endif\r
120 \r
121 \r
122 /****f* Component Library: Timer/cl_timer_construct\r
123 * NAME\r
124 *       cl_timer_construct\r
125 *\r
126 * DESCRIPTION\r
127 *       The cl_timer_construct function initializes the state of a timer.\r
128 *\r
129 * SYNOPSIS\r
130 */\r
131 CL_EXPORT void CL_API\r
132 cl_timer_construct(\r
133         IN      cl_timer_t* const       p_timer );\r
134 /*\r
135 * PARAMETERS\r
136 *       p_timer\r
137 *               [in] Pointer to a cl_timer_t structure whose state to initialize.\r
138 *\r
139 * RETURN VALUE\r
140 *       This function does not return a value.\r
141 *\r
142 * NOTES\r
143 *       Allows calling cl_timer_destroy without first calling cl_timer_init.\r
144 *\r
145 *       Calling cl_timer_construct is a prerequisite to calling any other\r
146 *       timer function except cl_timer_init.\r
147 *\r
148 * SEE ALSO\r
149 *       Timer, cl_timer_init, cl_timer_destroy\r
150 *********/\r
151 \r
152 \r
153 /****f* Component Library: Timer/cl_timer_init\r
154 * NAME\r
155 *       cl_timer_init\r
156 *\r
157 * DESCRIPTION\r
158 *       The cl_timer_init function initializes a timer for use.\r
159 *\r
160 * SYNOPSIS\r
161 */\r
162 CL_EXPORT cl_status_t CL_API\r
163 cl_timer_init(\r
164         IN      cl_timer_t* const               p_timer,\r
165         IN      cl_pfn_timer_callback_t pfn_callback,\r
166         IN      const void* const               context );\r
167 /*\r
168 * PARAMETERS\r
169 *       p_timer\r
170 *               [in] Pointer to a cl_timer_t structure to initialize.\r
171 *\r
172 *       pfn_callback\r
173 *               [in] Address of a callback function to be invoked when a timer expires.\r
174 *               See the cl_pfn_timer_callback_t function type definition for details\r
175 *               about the callback function.\r
176 *\r
177 *       context\r
178 *               [in] Value to pass to the callback function.\r
179 *\r
180 * RETURN VALUES\r
181 *       CL_SUCCESS if the timer was successfully initialized.\r
182 *\r
183 *       CL_ERROR otherwise.\r
184 *\r
185 * NOTES\r
186 *       Allows calling cl_timer_start and cl_timer_stop.\r
187 *\r
188 * SEE ALSO\r
189 *       Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start,\r
190 *       cl_timer_stop, cl_pfn_timer_callback_t\r
191 *********/\r
192 \r
193 \r
194 /****f* Component Library: Timer/cl_timer_destroy\r
195 * NAME\r
196 *       cl_timer_destroy\r
197 *\r
198 * DESCRIPTION\r
199 *       The cl_timer_destroy function performs any necessary cleanup of a timer.\r
200 *\r
201 * SYNOPSIS\r
202 */\r
203 CL_EXPORT void CL_API\r
204 cl_timer_destroy(\r
205         IN      cl_timer_t* const       p_timer );\r
206 /*\r
207 * PARAMETERS\r
208 *       p_timer\r
209 *               [in] Pointer to a cl_timer_t structure to destroy.\r
210 *\r
211 * RETURN VALUE\r
212 *       This function does not return a value.\r
213 *\r
214 * NOTES\r
215 *       cl_timer_destroy cancels any pending callbacks.\r
216 *\r
217 *       This function should only be called after a call to cl_timer_construct\r
218 *       or cl_timer_init.\r
219 *\r
220 * SEE ALSO\r
221 *       Timer, cl_timer_construct, cl_timer_init\r
222 *********/\r
223 \r
224 \r
225 /****f* Component Library: Timer/cl_timer_start\r
226 * NAME\r
227 *       cl_timer_start\r
228 *\r
229 * DESCRIPTION\r
230 *       The cl_timer_start function sets a timer to expire after a given interval.\r
231 *\r
232 * SYNOPSIS\r
233 */\r
234 CL_EXPORT cl_status_t CL_API\r
235 cl_timer_start(\r
236         IN      cl_timer_t* const       p_timer,\r
237         IN      const uint32_t          time_ms );\r
238 /*\r
239 * PARAMETERS\r
240 *       p_timer\r
241 *               [in] Pointer to a cl_timer_t structure to schedule.\r
242 *\r
243 *       time_ms\r
244 *               [in] Time, in milliseconds, before the timer should expire.\r
245 *\r
246 * RETURN VALUES\r
247 *       CL_SUCCESS if the timer was successfully scheduled.\r
248 *\r
249 *       CL_ERROR otherwise.\r
250 *\r
251 * NOTES\r
252 *       cl_timer_start implicitly stops the timer before being scheduled.\r
253 *\r
254 *       The interval specified by the time_ms parameter is a minimum interval.\r
255 *       The timer is guaranteed to expire no sooner than the desired interval, but\r
256 *       may take longer to expire.\r
257 *\r
258 * SEE ALSO\r
259 *       Timer, cl_timer_stop, cl_timer_trim\r
260 *********/\r
261 \r
262 \r
263 /****f* Component Library: Timer/cl_timer_stop\r
264 * NAME\r
265 *       cl_timer_stop\r
266 *\r
267 * DESCRIPTION\r
268 *       The cl_timer_stop function stops a pending timer from expiring.\r
269 *\r
270 * SYNOPSIS\r
271 */\r
272 CL_EXPORT void CL_API\r
273 cl_timer_stop(\r
274         IN      cl_timer_t* const       p_timer );\r
275 /*\r
276 * PARAMETERS\r
277 *       p_timer\r
278 *               [in] Pointer to a cl_timer_t structure.\r
279 *\r
280 * RETURN VALUE\r
281 *       This function does not return a value.\r
282 *\r
283 * SEE ALSO\r
284 *       Timer, cl_timer_start, cl_timer_trim\r
285 *********/\r
286 \r
287 \r
288 /****f* Component Library: Timer/cl_timer_trim\r
289 * NAME\r
290 *       cl_timer_trim\r
291 *\r
292 * DESCRIPTION\r
293 *       The cl_timer_trim function pulls in the absolute expiration\r
294 *       time of a timer if the current expiration time exceeds the specified\r
295 *       interval.\r
296 *\r
297 *       sets a timer to expire after a given\r
298 *       interval if that interval is less than the current timer expiration.\r
299 *\r
300 * SYNOPSIS\r
301 */\r
302 CL_EXPORT cl_status_t CL_API\r
303 cl_timer_trim(\r
304         IN      cl_timer_t* const       p_timer,\r
305         IN      const uint32_t          time_ms );\r
306 /*\r
307 * PARAMETERS\r
308 *       p_timer\r
309 *               [in] Pointer to a cl_timer_t structure to schedule.\r
310 *\r
311 *       time_ms\r
312 *               [in] Maximum time, in milliseconds, before the timer should expire.\r
313 *\r
314 * RETURN VALUES\r
315 *       CL_SUCCESS if the timer was successfully scheduled.\r
316 *\r
317 *       CL_ERROR otherwise.\r
318 *\r
319 * NOTES\r
320 *       cl_timer_trim has no effect if the time interval is greater than the\r
321 *       remaining time when the timer is set.\r
322 *\r
323 *       If the new interval time is less than the remaining time, cl_timer_trim\r
324 *       implicitly stops the timer before reseting it.\r
325 *\r
326 *       If the timer is reset, it is guaranteed to expire no sooner than the\r
327 *       new interval, but may take longer to expire.\r
328 *\r
329 * SEE ALSO\r
330 *       Timer, cl_timer_start, cl_timer_stop\r
331 *********/\r
332 \r
333 \r
334 /****f* Component Library: Time Stamp/cl_get_time_stamp\r
335 * NAME\r
336 *       cl_get_time_stamp\r
337 *\r
338 * DESCRIPTION\r
339 *       The cl_get_time_stamp function returns the current time stamp in\r
340 *       microseconds since the system was booted.\r
341 *\r
342 * SYNOPSIS\r
343 */\r
344 CL_EXPORT uint64_t CL_API\r
345 cl_get_time_stamp( void );\r
346 /*\r
347 * RETURN VALUE\r
348 *       Time elapsed, in microseconds, since the system was booted.\r
349 *\r
350 * SEE ALSO\r
351 *       Timer, cl_get_time_stamp_sec\r
352 *********/\r
353 \r
354 \r
355 /****f* Component Library: Time Stamp/cl_get_time_stamp_sec\r
356 * NAME\r
357 *       cl_get_time_stamp_sec\r
358 *\r
359 * DESCRIPTION\r
360 *       The cl_get_time_stamp_sec function returns the current time stamp in\r
361 *       seconds since the system was booted.\r
362 *\r
363 * SYNOPSIS\r
364 */\r
365 CL_EXPORT uint32_t CL_API\r
366 cl_get_time_stamp_sec( void );\r
367 /*\r
368 * RETURN VALUE\r
369 *       Time elapsed, in seconds, since the system was booted.\r
370 *\r
371 * SEE ALSO\r
372 *       Timer, cl_get_time_stamp\r
373 *********/\r
374 \r
375 \r
376 #ifdef __cplusplus\r
377 }       /* extern "C" */\r
378 #endif\r
379 \r
380 #endif /* _CL_TIMER_H_ */\r