rvtimer.h

基于h323协议的软phone

/***********************************************************************
Filename   : rvtimer.h
Description: rvtimer header file
************************************************************************
      Copyright (c) 2001,2002 RADVISION Inc. and RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Inc. and RADVISION Ltd.. No part of this document may be
reproduced in any form whatsoever without written prior approval by
RADVISION Inc. or RADVISION Ltd..

RADVISION Inc. and RADVISION Ltd. reserve the right to revise this
publication and make changes without obligation to notify any person of
such revisions or changes.
***********************************************************************/
/*$
{package:
	{name: Timer}
	{superpackage: CBase}
	{include: rvtimer.h}
	{description:	
		{p: This module provides functions for creating timer events and timer
			queues for those events.}
	}
}
$*/
#ifndef RV_TIMER_H
#define RV_TIMER_H

#include "rvcbase.h"
#include "rvlock.h"
#include "rvsemaphore.h"
#include "rvobjpool.h"
#include "rvpqueue.h"
#include "rvmemory.h"

/* Error checks to make sure configuration has been done properly */
#if !defined(RV_TIMER_TYPE) || ((RV_TIMER_TYPE != RV_TIMER_STANDARD))
#error RV_TIMER_TYPE not set properly
#endif
/* End of configuration error checks */

/* Module specific error codes (-512..-1023). See rverror.h for more details */
#define RV_TIMER_ERROR_POOL -512         /* Timer event pool error */
#define RV_TIMER_ERROR_PQUEUE -513       /* Timer Priority Queue error */
#define RV_TIMER_ERROR_QUEUEFULL -514    /* Timer queue is full. */
#define RV_TIMER_ERROR_QUEUESTOPPED -515 /* Timer queue has been stopped. */

/* Module specific Warning codes (512..1023). See rverror.h for more details */
#define RV_TIMER_WARNING_BUSY 512       /* Timer callback in progress. */
#define RV_TIMER_WARNING_QUEUEEMPTY 513 /* Timer queue is empty. */

/*$
{callback:
	{name:	  RvTimerFunc}	
	{superpackage: Timer}
	{include: rvTimer.h}
	{description:
		{p: This is the function that should be called when a timer is triggered.}
	}
	{proto: RvBool RvTimerFunc(void *data);}
	{params:
		{param: {n: data} {d: User parameter that was passed to RvTimerStart.}}
	}
	{returns:	Return value only affects PERIODIC timers. A return value of RV_TRUE
				indicates that the timer should be resheduled. A value of RV_FALSE
				indicates that the timer should not be rescheduled (and is, in effect,
				canceled).}
}
$*/
typedef RvBool (*RvTimerFunc)(void *);

/* Forward declaration for internal structure. */
typedef struct RvTimerEvent_s RvTimerEvent;

/*$
{type:
	{name: RvTimerQueue}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:	
		{p: A timer queue object.}
	}
}
$*/
typedef struct {
	RvPQueue pqueue;    /* Priority queue for timer events */
	RvObjPool pool;     /* Pool of free timer events. */
	RvLock lock;        /* lock for access to timer queue */
	RvUint idcounter;   /* counter for generating id numbers for events. */
	RvSize_t callcount; /* Number of callbacks currently in progress. */
	RvSemaphore wait;   /* Used to block task waiting for all callbacks to complete (QueueStop). */
	RvBool stopped;     /* Is set to RV_TRUE when queue has been stopped. */
} RvTimerQueue;

/*$
{type:
	{name: RvTimer}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:	
		{p: A timer identifier. This object is returned when a timer is started
			and is used only to cancel that timer. It's existance is not requred
			in order for the timer to trigger. Thus deleting this object has no
			effect on the timer other then the fact that the timer can no longer
			be canceled.}
	}
}
$*/
typedef struct {
	RvTimerEvent *event;  /* Points to internal timer event. */
	RvTimerQueue *tqueue; /* Timer queue that event was placed on. */
	RvInt64 starttime;    /* timestamp at start time, used for sanity check. */
	RvUint id;            /* id number of event, used for sanity check. */
} RvTimer;

/* Timer event types. */
/* ONESHOT: standard timer which will go off in the time specificed. */
/* PERIODIC: timer will go off periodically with the time specified being the interval. */
#define RV_TIMER_TYPE_ONESHOT RvIntConst(0)
#define RV_TIMER_TYPE_PERIODIC RvIntConst(1)

/* Timer Event Queue types*/
/*   FIXED: pool and priority queue is fixed size and preallocated. */
/*   EXPANDING: pool increased as needed and heap size is increased by */
/*              a factor of 2 and reallocated when heap is full. */
/*   DYNAMIC: EXPANDING plus pool reduced as needed and heap size is reduced */
/*            by a factor of 2 (min of startsize) when heap only 25% full. */
/*            The freelevel parameter should be set to items free per 100 */
/*            which should be maintained (frelevel = 0 indicates to always */
/*            remove free pages). */
#define RV_TIMER_QTYPE_FIXED RvIntConst(0)
#define RV_TIMER_QTYPE_EXPANDING RvIntConst(1)
#define RV_TIMER_QTYPE_DYNAMIC RvIntConst(2)

/* Flags to indicate direction of value deltas for */
/* RvTimerQueueChangeMaxtimers and RvTimerQueueChangeMintimers */
/* functions. */
#define RV_TIMER_VALUE_INCREASE RV_TRUE
#define RV_TIMER_VALUE_DECREASE RV_FALSE

/* Flags to indicate if RvTimerCancel should be blocking or non-blocking. */
#define RV_TIMER_CANCEL_BLOCKING RV_TRUE
#define RV_TIMER_CANCEL_NONBLOCKING RV_FALSE

#if defined(__cplusplus)
extern "C" {
#endif 

/* Prototypes: See documentation blocks below for details. */
RvStatus RvTimerInit(void);
RvStatus RvTimerEnd(void);
RVCOREAPI RvStatus RVCALLCONV RvTimerQueueConstruct(RvTimerQueue *tqueue, RvInt tqtype, RvSize_t starttimers, RvSize_t maxtimers, RvSize_t mintimers, RvSize_t freelevel, RvSize_t pagetimers, RvMemory *memregion);
RvStatus RvTimerQueueStop(RvTimerQueue *tqueue);
RvSize_t RvTimerQueueNumEvents(RvTimerQueue *tqueue);
RVCOREAPI RvSize_t RVCALLCONV RvTimerQueueGetSize(RvTimerQueue *tqueue);
RvSize_t RvTimerQueueSetSize(RvTimerQueue *tqueue, RvSize_t newsize);
RVCOREAPI RvSize_t RVCALLCONV RvTimerQueueAddSize(RvTimerQueue *tqueue, RvSize_t addsize);
RvSize_t RvTimerQueueGetMaxtimers(RvTimerQueue *tqueue);
RvBool RvTimerQueueSetMaxtimers(RvTimerQueue *tqueue, RvSize_t maxtimers);
RvBool RvTimerQueueChangeMaxtimers(RvTimerQueue *tqueue, RvSize_t delta, RvBool direction);
RvSize_t RvTimerQueueGetMintimers(RvTimerQueue *tqueue);
RvBool RvTimerQueueSetMintimers(RvTimerQueue *tqueue, RvSize_t mintimers);
RvBool RvTimerQueueChangeMintimers(RvTimerQueue *tqueue, RvSize_t delta, RvBool direction);
RvSize_t RvTimerQueueGetFreelevel(RvTimerQueue *tqueue);
RvBool RvTimerQueueSetFreelevel(RvTimerQueue *tqueue, RvSize_t freelevel);
RVCOREAPI RvStatus RVCALLCONV RvTimerQueueNextEvent(RvTimerQueue *tqueue, RvInt64 *nextevent);
RVCOREAPI RvStatus RVCALLCONV RvTimerQueueDestruct(RvTimerQueue *tqueue);
RVCOREAPI RvStatus RVCALLCONV RvTimerStart(RvTimer *timer, RvTimerQueue *tqueue, RvInt timertype, RvInt64 delay, RvTimerFunc callback, void *userdata);
RVCOREAPI RvStatus RVCALLCONV RvTimerCancel(RvTimer *timer, RvBool blocking);
RvInt64 RvTimerResolution(void);
RVCOREAPI RvStatus RVCALLCONV RvTimerQueueService(RvTimerQueue *tqueue, RvSize_t maxevents, RvSize_t *numevents);

#if defined(RV_TEST_CODE)
void RvTimerTest(void);
#endif /* RV_TEST_CODE */

#if defined(__cplusplus)
}
#endif 

/* Function Documentation */
/*$
{function scope="protected":
	{name: RvTimerInit}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Initializes the Timer module. Must be called once (and
			only once) before any other functions in the module are called.}
	}
	{proto: RvStatus RvTimerInit(void); }
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function scope="protected":
	{name: RvTimerEnd}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Shuts down the Timer module. Must be called once (and
			only once) when no further calls to this module will be made.}
	}
	{proto: RvStatus RvTimerEnd(void); }
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvTimerQueueConstruct}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Constructs a timer queue object based on the parameters passed in. There are
			two parts to each timer queue, the timer pool and the priority queue, both
			of which require memory.}
		{p: There are three types of pools:}
		{bulletlist:
			{item:  FIXED: This creates a fixed size timer queue (which contains
					a fixed size timer pool and a fixed size priority queue) with
					all memory pre-allocated based on the number of starttimers
					requested. The number of blocks can be increased with the
					RvTimerQueueSetSize and RvTimerQueueAddSize calls.}
			{item:  EXPANDING: This creates a timer queue pool which expands (by adding
					pages and doubling the priority queue size) as needed. The additional
					memory is not released until the timer queue is destructed.}
			{item:  DYNAMIC: This creates a timer queue which expands exactly like
					and EXPANDING timer queue but also has the ability to remove
					unused pages and reduce the size of the priority queue.
					The freelevel value determines when a page should be released.
					The priority queue is reduced by 50% when 25% or less of it is
					in use.}
		}
	}
	{proto: RvStatus RvTimerQueueConstruct(RvTimerQueue *tqueue, RvInt tqtype, RvSize_t starttimers, RvSize_t maxtimers, RvSize_t mintimers, RvSize_t freelevel, RvSize_t pagetimers, RvMemory *memregion);}
	{params:
		{param: {n: tqueue}      {d: Pointer to timer queue object to be constructed.}}
		{param: {n: tqtype}      {d: Type of timer queue: RV_TIMER_QTYPE_FIXED, RV_TIMER_QTYPE_EXPANDING, or RV_TIMER_QTYPE_DYNAMIC.}}
		{param: {n: starttimers} {d: Number of timers to start with.}}
		{param: {n: maxtimers}   {d: Never exceed this number of timers.}}
		{param: {n: mintimers}   {d: Never go below this number of timers.}}
		{param: {n: freelevel}   {d: The minimum number of free timers per 100 to maintain
									 in the pool when shrinking a DYNAMIC timer pool (0 to 100).
									 A value of 0 always releases empty pages and a value of 100
									 never releases empty pages (which is the same as an EXPANDING
									 pool).}}
		{param: {n: pagetimers}  {d: Number of timers per memory allocation page in th pool.}}
		{param: {n: memregion}   {d: Memory region to allocate memory from (NULL = default region).}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvTimerQueueStop}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Permanently stops a timer queue. No more timers will be allowed to be started and
			no more timer will be serviced. This function will suspend the caller until all
			callbacks currently being serviced have completed.}
	}
	{proto: RvStatus RvTimerQueueStop(RvTimerQueue *tqueue);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be stopped.}}
	}
	{returns:   RV_OK if successful otherwise an error code.}
	{notes:
		{note:  When a timer queue is stopped it is permanent, there is no way to undo it.}
		{note:  This function may not be called simultaneously from multiple threads
				for the same timer queue.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueNumEvents}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Find out how many events are in the timer queue.}
	}
	{proto: RvSize_t RvTimerQueueNumEvents(RvTimerQueue *tqueue);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be checked.}}
	}
	{returns: Number of events currently in the timer queue.}
}
$*/
/*$
{function:
	{name: RvTimerQueueGetSize}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Find the current total size of the timer queue.}
	}
	{proto: RvSize_t RvTimerQueueGetSize(RvTimerQueue *tqueue);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be checked.}}
	}
	{returns: Number of timers in the timer queue pool.}
}
$*/
/*$
{function:
	{name: RvTimerQueueSetSize}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description:
		{p: Set the total size of the timer queue.}
	}
	{proto: RvSize_t RvTimerQueueSetSize(RvTimerQueue *tqueue, RvSize_t newsize);}
	{params:
		{param: {n: tqueue} {d: Pointer to timer queue object to be set.}}
		{param: {n: newsize} {d: New size that the timer queue should be set to.}}
	}
	{returns: New size of the timer queue pool.}
	{notes:
		{note:  The size may only be increased over its current value.}
		{note:  The actual number of timers may be larger than that requested since
				the amount added will be a multiple of the number of timers per
				page that was set when the timer queue was constructed. The value
				returned will be the actual new number of timers available.}
		{note:  Changes are subject to the limits of the maxtimers and mintimers settings.}
	}
}
$*/
/*$
{function:
	{name: RvTimerQueueAddSize}
	{superpackage: Timer}
	{include: rvtimer.h}
	{description: