clTimerApi.h

Go to the documentation of this file.

/*
 * Copyright (C) 2002-2012 OpenClovis Solutions Inc.  All Rights Reserved.
 *
 * This file is available  under  a  commercial  license  from  the
 * copyright  holder or the GNU General Public License Version 2.0.
 * 
 * The source code for  this program is not published  or otherwise 
 * divested of  its trade secrets, irrespective  of  what  has been 
 * deposited with the U.S. Copyright office.
 * 
 * This program is distributed in the  hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied  warranty  of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * For more  information, see  the file  COPYING provided with this
 * material.
 */
/*******************************************************************************
 * ModuleName  : timer
 * File        : clTimerApi.h
 *******************************************************************************/

/*******************************************************************************
 * Description :
 *
 * The Timer Service provides timers that allows a user call back
 * function to be invoked when a time out happens. The motivation of the
 * implementation comes from the need to have large number of outstanding
 * timer at any point in time. The timer service library provides a
 * set of API's which are discussed in the following sections.
 *
 *
 *****************************************************************************/

#ifndef _CL_TIMER_API_H_
#define _CL_TIMER_API_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <clCommon.h>
#include <clBufferApi.h>

/******************************************************************************
 *  Data Types
 *****************************************************************************/

typedef ClRcT (*ClTimerCallBackT) (void *);

/*
 *
 * Cluster timer replication callback
 */
typedef ClRcT (*ClTimerReplicationCallbackT) (ClBufferHandleT);

typedef ClPtrT ClTimerHandleT;

typedef struct {
    ClUint32T   tsSec;
    ClUint32T   tsMilliSec;
} ClTimerTimeOutT;


typedef struct {
  ClUint32T   timerResolution;
  ClUint32T   timerTaskPriority;
} ClTimerConfigT;



typedef enum {
    CL_TIMER_ONE_SHOT = 0,
    CL_TIMER_REPETITIVE,
    /* Fire once and deleted automatically*/
    CL_TIMER_VOLATILE,
    CL_TIMER_MAX_TYPE,
} ClTimerTypeT;

typedef enum {
    CL_TIMER_TASK_CONTEXT = 0,
    CL_TIMER_SEPARATE_CONTEXT,
    CL_TIMER_MAX_CONTEXT,
} ClTimerContextT;

#define CL_TIMER_TYPE_STR(type) ( (type) == CL_TIMER_ONE_SHOT ? "one shot" : \
                                  ((type) == CL_TIMER_REPETITIVE) ? "repetitive" : "volatile" )

#define CL_TIMER_CONTEXT_STR(ctxt) ( (ctxt) == CL_TIMER_SEPARATE_CONTEXT ? "thread": "inline" )

typedef struct ClTimerStats
{
    ClTimerTypeT type;
    ClTimerContextT context;
    ClTimeT timeOut;
    ClTimeT expiry;
} ClTimerStatsT;

/*****************************************************************************
 *  Functions
 *****************************************************************************/

ClRcT
clTimerConfigInitialize(void* pConfigData);

ClRcT
clTimerInitialize (ClPtrT pConfig);

ClRcT
clTimerFinalize (void);

ClRcT
clTimerCreate (ClTimerTimeOutT      timeOut, /* the timeout, in clockticks */
        ClTimerTypeT    type, /* one shot or repetitive */
        ClTimerContextT       timerTaskSpawn, /* whether to spawn off the timer function
                                                 * as a separate task or invoke it in the
                                                 * same context as the timer-task
                                                 */
        ClTimerCallBackT     fpAction, /* the function to be called on timeout */
        void*            pActionArgument, /* the argument to the function called on timeout */
        ClTimerHandleT*      pTimerHandle);/* The pointer to the timer handle */

ClRcT
clTimerDelete (ClTimerHandleT* pTimerHandle);

ClRcT
clTimerDeleteAsync(ClTimerHandleT *pTimerHandle);

ClRcT
clTimerStart (ClTimerHandleT  timerHandle);

ClRcT
clTimerStop (ClTimerHandleT  timerHandle);

ClRcT
clTimerCreateAndStart (ClTimerTimeOutT      timeOut, /* the timeout, in clockticks */
        ClTimerTypeT    type, /* one shot or repetitive */
        ClTimerContextT timerTaskSpawn, /* whether to spawn off the timer function
                                                      * as a separate task or invoke it in the
                                                      * same context as the timer-task
                                                      */
        ClTimerCallBackT    fpAction, /* the function to be called on timeout */
                void                *pActionArgument, /* the argument to the function
                                                       * called on timeout */
                ClTimerHandleT      *pTimerHandle);

ClRcT
clTimerRestart (ClTimerHandleT  timerHandle);

ClRcT
clTimerUpdate(ClTimerHandleT timerHandle,
        ClTimerTimeOutT newTimeout);

ClRcT
clTimerTypeGet (ClTimerHandleT timerHandle,
        ClUint32T* pTimerType);

ClRcT clTimerClusterRegister(ClTimerCallBackT clusterCallback,
                             ClTimerReplicationCallbackT replicationCallback);

ClRcT clTimerCreateCluster(ClTimerTimeOutT timeOut, 
                           ClTimerTypeT timerType,
                           ClTimerContextT timerContext,
                           void *timerData,
                           ClUint32T timerDataSize,
                           ClTimerHandleT *pTimerHandle);

ClRcT clTimerCreateAndStartCluster(ClTimerTimeOutT timeOut, 
                                   ClTimerTypeT timerType,
                                   ClTimerContextT timerContext,
                                   void *timerData,
                                   ClUint32T timerDataSize,
                                   ClTimerHandleT *pTimerHandle);

ClRcT clTimerClusterPack(ClTimerHandleT timer, ClBufferHandleT msg);

ClRcT clTimerClusterPackAll(ClBufferHandleT msg);

ClRcT clTimerClusterUnpack(ClBufferHandleT msg, ClTimerHandleT *pTimerHandle);

ClRcT clTimerClusterUnpackAll(ClBufferHandleT msg);

ClRcT clTimerClusterFree(ClTimerHandleT *pTimerHandle);

ClRcT clTimerClusterConfigureAll(void);

ClRcT clTimerClusterConfigure(ClTimerHandleT *pTimerHandle);

ClRcT clTimerClusterSync(void);

ClRcT clTimerClusterRegister(ClTimerCallBackT clusterCallback,
                             ClTimerReplicationCallbackT replicationCallback);

ClRcT clTimerIsRunning(ClTimerHandleT timerHandle, ClBoolT *pState);

ClRcT clTimerIsStopped(ClTimerHandleT timerHandle, ClBoolT *pState);

ClRcT clTimerStatsGet(ClTimerStatsT **ppStats, ClUint32T *pNumTimers);

ClRcT clTimerCheckAndDelete(ClTimerHandleT *pTimerHandle);

#ifdef __cplusplus
}
#endif

#endif  /* _CL_TIMER_API_H_ */