OpenClovis Logo

clTimerApi.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2002-2012 OpenClovis Solutions Inc. All Rights Reserved.
3  *
4  * This file is available under a commercial license from the
5  * copyright holder or the GNU General Public License Version 2.0.
6  *
7  * The source code for this program is not published or otherwise
8  * divested of its trade secrets, irrespective of what has been
9  * deposited with the U.S. Copyright office.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * General Public License for more details.
15  *
16  * For more information, see the file COPYING provided with this
17  * material.
18  */
19 /*******************************************************************************
20  * ModuleName : timer
21  * File : clTimerApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  *
27  * The Timer Service provides timers that allows a user call back
28  * function to be invoked when a time out happens. The motivation of the
29  * implementation comes from the need to have large number of outstanding
30  * timer at any point in time. The timer service library provides a
31  * set of API's which are discussed in the following sections.
32  *
33  *
34  *****************************************************************************/
35 
49 #ifndef _CL_TIMER_API_H_
50 #define _CL_TIMER_API_H_
51 
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55 
56 #include <clCommon.h>
57 #include <clBufferApi.h>
58 
59 /******************************************************************************
60  * Data Types
61  *****************************************************************************/
62 
68 typedef ClRcT (*ClTimerCallBackT) (void *);
69 
70 /*
71  *
72  * Cluster timer replication callback
73  */
74 typedef ClRcT (*ClTimerReplicationCallbackT) (ClBufferHandleT);
75 
82 typedef ClPtrT ClTimerHandleT;
83 
87 typedef struct {
89  ClUint32T tsSec;
91  ClUint32T tsMilliSec;
93 
94 
99 typedef struct {
104  ClUint32T timerResolution;
109  ClUint32T timerTaskPriority;
111 
112 
113 
117 typedef enum {
122  /* Fire once and deleted automatically*/
123  CL_TIMER_VOLATILE,
124  CL_TIMER_MAX_TYPE,
125 } ClTimerTypeT;
126 
137 typedef enum {
142  CL_TIMER_MAX_CONTEXT,
144 
145 #define CL_TIMER_TYPE_STR(type) ( (type) == CL_TIMER_ONE_SHOT ? "one shot" : \
146  ((type) == CL_TIMER_REPETITIVE) ? "repetitive" : "volatile" )
147 
148 #define CL_TIMER_CONTEXT_STR(ctxt) ( (ctxt) == CL_TIMER_SEPARATE_CONTEXT ? "thread": "inline" )
149 
150 typedef struct ClTimerStats
151 {
152  ClTimerTypeT type;
153  ClTimerContextT context;
154  ClTimeT timeOut;
155  ClTimeT expiry;
156 } ClTimerStatsT;
157 
158 /*****************************************************************************
159  * Functions
160  *****************************************************************************/
161 
182 ClRcT
183 clTimerConfigInitialize(void* pConfigData);
184 
201 ClRcT
202 clTimerInitialize (ClPtrT pConfig);
203 
217 ClRcT
219 
256 ClRcT
257 clTimerCreate (ClTimerTimeOutT timeOut, /* the timeout, in clockticks */
258  ClTimerTypeT type, /* one shot or repetitive */
259  ClTimerContextT timerTaskSpawn, /* whether to spawn off the timer function
260  * as a separate task or invoke it in the
261  * same context as the timer-task
262  */
263  ClTimerCallBackT fpAction, /* the function to be called on timeout */
264  void* pActionArgument, /* the argument to the function called on timeout */
265  ClTimerHandleT* pTimerHandle);/* The pointer to the timer handle */
266 
289 ClRcT
291 
292 ClRcT
293 clTimerDeleteAsync(ClTimerHandleT *pTimerHandle);
294 
313 ClRcT
315 
334 ClRcT
336 
364 ClRcT
365 clTimerCreateAndStart (ClTimerTimeOutT timeOut, /* the timeout, in clockticks */
366  ClTimerTypeT type, /* one shot or repetitive */
367  ClTimerContextT timerTaskSpawn, /* whether to spawn off the timer function
368  * as a separate task or invoke it in the
369  * same context as the timer-task
370  */
371  ClTimerCallBackT fpAction, /* the function to be called on timeout */
372  void *pActionArgument, /* the argument to the function
373  * called on timeout */
374  ClTimerHandleT *pTimerHandle);
375 
392 ClRcT
394 
411 ClRcT
413  ClTimerTimeOutT newTimeout);
414 
437 ClRcT
439  ClUint32T* pTimerType);
440 
441 ClRcT clTimerClusterRegister(ClTimerCallBackT clusterCallback,
442  ClTimerReplicationCallbackT replicationCallback);
443 
444 ClRcT clTimerCreateCluster(ClTimerTimeOutT timeOut,
445  ClTimerTypeT timerType,
446  ClTimerContextT timerContext,
447  void *timerData,
448  ClUint32T timerDataSize,
449  ClTimerHandleT *pTimerHandle);
450 
451 ClRcT clTimerCreateAndStartCluster(ClTimerTimeOutT timeOut,
452  ClTimerTypeT timerType,
453  ClTimerContextT timerContext,
454  void *timerData,
455  ClUint32T timerDataSize,
456  ClTimerHandleT *pTimerHandle);
457 
458 ClRcT clTimerClusterPack(ClTimerHandleT timer, ClBufferHandleT msg);
459 
460 ClRcT clTimerClusterPackAll(ClBufferHandleT msg);
461 
462 ClRcT clTimerClusterUnpack(ClBufferHandleT msg, ClTimerHandleT *pTimerHandle);
463 
464 ClRcT clTimerClusterUnpackAll(ClBufferHandleT msg);
465 
466 ClRcT clTimerClusterFree(ClTimerHandleT *pTimerHandle);
467 
468 ClRcT clTimerClusterConfigureAll(void);
469 
470 ClRcT clTimerClusterConfigure(ClTimerHandleT *pTimerHandle);
471 
472 ClRcT clTimerClusterSync(void);
473 
474 ClRcT clTimerClusterRegister(ClTimerCallBackT clusterCallback,
475  ClTimerReplicationCallbackT replicationCallback);
476 
477 ClRcT clTimerIsRunning(ClTimerHandleT timerHandle, ClBoolT *pState);
478 
479 ClRcT clTimerIsStopped(ClTimerHandleT timerHandle, ClBoolT *pState);
480 
481 ClRcT clTimerStatsGet(ClTimerStatsT **ppStats, ClUint32T *pNumTimers);
482 
483 ClRcT clTimerCheckAndDelete(ClTimerHandleT *pTimerHandle);
484 
485 #ifdef __cplusplus
486 }
487 #endif
488 
493 #endif /* _CL_TIMER_API_H_ */
494 
495 
Typical defines found in any software project.
Header file of Buffer Management related APIs.
ClPtrT ClBufferHandleT
The type of the handle for the buffer messages.
Definition: clBufferApi.h:82
ClUint32T ClRcT
Clovis return code type.
Definition: clCommon.h:168
ClInt64T ClTimeT
Time duration specified in nanoseconds.
Definition: clCommon.h:154
ClRcT clTimerInitialize(ClPtrT pConfig)
Initializes the Timer library.
ClRcT clTimerTypeGet(ClTimerHandleT timerHandle, ClUint32T *pTimerType)
Returns the timer type.
ClPtrT ClTimerHandleT
The type of the handle identifying the timer.
Definition: clTimerApi.h:82
ClRcT clTimerConfigInitialize(void *pConfigData)
Configures the Timer library.
ClRcT clTimerRestart(ClTimerHandleT timerHandle)
Restarts a timer.
ClRcT clTimerCreateAndStart(ClTimerTimeOutT timeOut, ClTimerTypeT type, ClTimerContextT timerTaskSpawn, ClTimerCallBackT fpAction, void *pActionArgument, ClTimerHandleT *pTimerHandle)
Creates a new timer and activates it.
ClRcT clTimerDelete(ClTimerHandleT *pTimerHandle)
Deletes a timer.
ClTimerTypeT
type of action on timer expiry.
Definition: clTimerApi.h:117
ClRcT clTimerCreate(ClTimerTimeOutT timeOut, ClTimerTypeT type, ClTimerContextT timerTaskSpawn, ClTimerCallBackT fpAction, void *pActionArgument, ClTimerHandleT *pTimerHandle)
Creates a timer.
ClTimerContextT
When the timer expires, decides the method of invocation of the timer callback function.
Definition: clTimerApi.h:137
ClRcT clTimerStart(ClTimerHandleT timerHandle)
Starts a timer.
ClRcT clTimerUpdate(ClTimerHandleT timerHandle, ClTimerTimeOutT newTimeout)
Updates a timer.
ClRcT clTimerStop(ClTimerHandleT timerHandle)
\breif Stops a timer.
ClRcT(* ClTimerCallBackT)(void *)
The type fo the callback fucntion that will be called on timer expiry.
Definition: clTimerApi.h:68
ClRcT clTimerFinalize(void)
Cleans up the Timer library.
@ CL_TIMER_ONE_SHOT
Fire just once.
Definition: clTimerApi.h:119
@ CL_TIMER_REPETITIVE
Fire periodically.
Definition: clTimerApi.h:121
@ CL_TIMER_TASK_CONTEXT
Use the timer thread.
Definition: clTimerApi.h:139
@ CL_TIMER_SEPARATE_CONTEXT
A new thread will be created to invoke the callback.
Definition: clTimerApi.h:141
The timeout value in seconds and milliseconds.
Definition: clTimerApi.h:87
ClUint32T tsSec
Number of seconds of the timeout.
Definition: clTimerApi.h:89
ClUint32T tsMilliSec
Number of Milliseconds.
Definition: clTimerApi.h:91
It contains the timer library configuration information.
Definition: clTimerApi.h:99
ClUint32T timerResolution
Timer resolution in milliseconds.
Definition: clTimerApi.h:104
ClUint32T timerTaskPriority
Timer task priority.
Definition: clTimerApi.h:109

Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen