home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / nsprpub / pr / include / obsolete / pralarm.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  7.4 KB  |  175 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /*
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  * 
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  * 
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. /*
  20. ** File:        pralarm.h
  21. ** Description:    API to periodic alarms.
  22. **
  23. **
  24. ** Alarms are defined to invoke some client specified function at 
  25. ** a time in the future. The notification may be a one time event
  26. ** or repeated at a fixed interval. The interval at which the next
  27. ** notification takes place may be modified by the client code only
  28. ** during the respective notification.
  29. **
  30. ** The notification is delivered on a thread that is part of the
  31. ** alarm context (PRAlarm). The thread will inherit the priority
  32. ** of the Alarm creator.
  33. **
  34. ** Any number of periodic alarms (PRAlarmID) may be created within
  35. ** the context of a single alarm (PRAlarm). The notifications will be
  36. ** scheduled as close to the desired time as possible.
  37. **
  38. ** Repeating periodic notifies are expected to run at a fixed rate.
  39. ** That rate is expressed as some number of notifies per period where
  40. ** the period is much larger than a PRIntervalTime (see prinrval.h).
  41. */
  42.  
  43. #if !defined(pralarm_h)
  44. #define pralarm_h
  45.  
  46. #include "prtypes.h"
  47. #include "prinrval.h"
  48.  
  49. PR_BEGIN_EXTERN_C
  50.  
  51. /**********************************************************************/
  52. /************************* TYPES AND CONSTANTS ************************/
  53. /**********************************************************************/
  54.  
  55. typedef struct PRAlarm PRAlarm;
  56. typedef struct PRAlarmID PRAlarmID;
  57.  
  58. typedef PRBool (PR_CALLBACK *PRPeriodicAlarmFn)(
  59.     PRAlarmID *id, void *clientData, PRUint32 late);
  60.  
  61. /**********************************************************************/
  62. /****************************** FUNCTIONS *****************************/
  63. /**********************************************************************/
  64.  
  65. /***********************************************************************
  66. ** FUNCTION:    PR_CreateAlarm
  67. ** DESCRIPTION:
  68. **  Create an alarm context.
  69. ** INPUTS:      void
  70. ** OUTPUTS:     None
  71. ** RETURN:      PRAlarm*
  72. **  
  73. ** SIDE EFFECTS:
  74. **  This creates an alarm context, which is an object used for subsequent
  75. **  notification creations. It also creates a thread that will be used to
  76. ** deliver the notifications that are expected to be defined. The client
  77. ** is resposible for destroying the context when appropriate.
  78. ** RESTRICTIONS:
  79. **  None. 
  80. ** MEMORY:      The object (PRAlarm) and a thread to support notifications.
  81. ** ALGORITHM:   N/A
  82. ***********************************************************************/
  83. PR_EXTERN(PRAlarm*) PR_CreateAlarm(void);
  84.  
  85. /***********************************************************************
  86. ** FUNCTION:    PR_DestroyAlarm
  87. ** DESCRIPTION:
  88. **  Destroys the context created by PR_CreateAlarm().
  89. ** INPUTS:      PRAlarm*
  90. ** OUTPUTS:     None
  91. ** RETURN:      PRStatus
  92. **  
  93. ** SIDE EFFECTS:
  94. **  This destroys the context that was created by PR_CreateAlarm().
  95. **  If there are any active alarms (PRAlarmID), they will be cancelled.
  96. **  Once that is done, the thread that was used to deliver the alarms
  97. **  will be joined. 
  98. ** RESTRICTIONS:
  99. **  None. 
  100. ** MEMORY:      N/A
  101. ** ALGORITHM:   N/A
  102. ***********************************************************************/
  103. PR_EXTERN(PRStatus) PR_DestroyAlarm(PRAlarm *alarm);
  104.  
  105. /***********************************************************************
  106. ** FUNCTION:    PR_SetAlarm
  107. ** DESCRIPTION:
  108. **  Creates a periodic notifier that is to be delivered to a specified
  109. **  function at some fixed interval.
  110. ** INPUTS:      PRAlarm *alarm              Parent alarm context
  111. **              PRIntervalTime period       Interval over which the notifies
  112. **                                          are delivered.
  113. **              PRUint32 rate               The rate within the interval that
  114. **                                          the notifies will be delivered.
  115. **              PRPeriodicAlarmFn function  Entry point where the notifies
  116. **                                          will be delivered.
  117. ** OUTPUTS:     None
  118. ** RETURN:      PRAlarmID*                  Handle to the notifier just created
  119. **                                          or NULL if the request failed.
  120. **  
  121. ** SIDE EFFECTS:
  122. **  A periodic notifier is created. The notifications will be delivered
  123. **  by the alarm's internal thread at a fixed interval whose rate is the
  124. **  number of interrupts per interval specified. The first notification
  125. **  will be delivered as soon as possible, and they will continue until
  126. **  the notifier routine indicates that they should cease of the alarm
  127. **  context is destroyed (PR_DestroyAlarm).
  128. ** RESTRICTIONS:
  129. **  None. 
  130. ** MEMORY:      Memory for the notifier object.
  131. ** ALGORITHM:   The rate at which notifications are delivered are stated
  132. **              to be "'rate' notifies per 'interval'". The exact time of
  133. **              the notification is computed based on a epoch established
  134. **              when the notifier was set. Each notification is delivered
  135. **              not ealier than the epoch plus the fixed rate times the
  136. **              notification sequence number. Such notifications have the
  137. **              potential to be late by not more than 'interval'/'rate'.
  138. **              The amount of lateness of one notification is taken into
  139. **              account on the next in an attempt to avoid long term slew.  
  140. ***********************************************************************/
  141. PR_EXTERN(PRAlarmID*) PR_SetAlarm(
  142.     PRAlarm *alarm, PRIntervalTime period, PRUint32 rate,
  143.     PRPeriodicAlarmFn function, void *clientData);
  144.  
  145. /***********************************************************************
  146. ** FUNCTION:    PR_ResetAlarm
  147. ** DESCRIPTION:
  148. **  Resets an existing alarm.
  149. ** INPUTS:      PRAlarmID *id               Identify of the notifier.
  150. **              PRIntervalTime period       Interval over which the notifies
  151. **                                          are delivered.
  152. **              PRUint32 rate               The rate within the interval that
  153. **                                          the notifies will be delivered.
  154. ** OUTPUTS:     None
  155. ** RETURN:      PRStatus                    Indication of completion.
  156. **  
  157. ** SIDE EFFECTS:
  158. **  An existing alarm may have its period and rate redefined. The
  159. **  additional side effect is that the notifier's epoch is recomputed.
  160. **  The first notification delivered by the newly refreshed alarm is
  161. **  defined to be 'interval'/'rate' from the time of the reset.
  162. ** RESTRICTIONS:
  163. **  This function may only be called in the notifier for that alarm.
  164. ** MEMORY:      N/A.
  165. ** ALGORITHM:   See PR_SetAlarm().  
  166. ***********************************************************************/
  167. PR_EXTERN(PRStatus) PR_ResetAlarm(
  168.     PRAlarmID *id, PRIntervalTime period, PRUint32 rate);
  169.  
  170. PR_END_EXTERN_C
  171.  
  172. #endif /* !defined(pralarm_h) */
  173.  
  174. /* prinrval.h */
  175.