home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / nspr30-e.zip / nspr30-e / include / obsolete / pralarm.h next >
C/C++ Source or Header  |  1998-11-02  |  8KB  |  176 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.  
  50. PR_BEGIN_EXTERN_C
  51.  
  52. /**********************************************************************/
  53. /************************* TYPES AND CONSTANTS ************************/
  54. /**********************************************************************/
  55.  
  56. typedef struct PRAlarm PRAlarm;
  57. typedef struct PRAlarmID PRAlarmID;
  58.  
  59. typedef PRBool (PR_CALLBACK *PRPeriodicAlarmFn)(
  60.     PRAlarmID *id, void *clientData, PRUint32 late);
  61.  
  62. /**********************************************************************/
  63. /****************************** FUNCTIONS *****************************/
  64. /**********************************************************************/
  65.  
  66. /***********************************************************************
  67. ** FUNCTION:    PR_CreateAlarm
  68. ** DESCRIPTION:
  69. **  Create an alarm context.
  70. ** INPUTS:      void
  71. ** OUTPUTS:     None
  72. ** RETURN:      PRAlarm*
  73. **  
  74. ** SIDE EFFECTS:
  75. **  This creates an alarm context, which is an object used for subsequent
  76. **  notification creations. It also creates a thread that will be used to
  77. ** deliver the notifications that are expected to be defined. The client
  78. ** is resposible for destroying the context when appropriate.
  79. ** RESTRICTIONS:
  80. **  None. 
  81. ** MEMORY:      The object (PRAlarm) and a thread to support notifications.
  82. ** ALGORITHM:   N/A
  83. ***********************************************************************/
  84. PR_EXTERN(PRAlarm*) PR_CreateAlarm(void);
  85.  
  86. /***********************************************************************
  87. ** FUNCTION:    PR_DestroyAlarm
  88. ** DESCRIPTION:
  89. **  Destroys the context created by PR_CreateAlarm().
  90. ** INPUTS:      PRAlarm*
  91. ** OUTPUTS:     None
  92. ** RETURN:      PRStatus
  93. **  
  94. ** SIDE EFFECTS:
  95. **  This destroys the context that was created by PR_CreateAlarm().
  96. **  If there are any active alarms (PRAlarmID), they will be cancelled.
  97. **  Once that is done, the thread that was used to deliver the alarms
  98. **  will be joined. 
  99. ** RESTRICTIONS:
  100. **  None. 
  101. ** MEMORY:      N/A
  102. ** ALGORITHM:   N/A
  103. ***********************************************************************/
  104. PR_EXTERN(PRStatus) PR_DestroyAlarm(PRAlarm *alarm);
  105.  
  106. /***********************************************************************
  107. ** FUNCTION:    PR_SetAlarm
  108. ** DESCRIPTION:
  109. **  Creates a periodic notifier that is to be delivered to a specified
  110. **  function at some fixed interval.
  111. ** INPUTS:      PRAlarm *alarm              Parent alarm context
  112. **              PRIntervalTime period       Interval over which the notifies
  113. **                                          are delivered.
  114. **              PRUint32 rate               The rate within the interval that
  115. **                                          the notifies will be delivered.
  116. **              PRPeriodicAlarmFn function  Entry point where the notifies
  117. **                                          will be delivered.
  118. ** OUTPUTS:     None
  119. ** RETURN:      PRAlarmID*                  Handle to the notifier just created
  120. **                                          or NULL if the request failed.
  121. **  
  122. ** SIDE EFFECTS:
  123. **  A periodic notifier is created. The notifications will be delivered
  124. **  by the alarm's internal thread at a fixed interval whose rate is the
  125. **  number of interrupts per interval specified. The first notification
  126. **  will be delivered as soon as possible, and they will continue until
  127. **  the notifier routine indicates that they should cease of the alarm
  128. **  context is destroyed (PR_DestroyAlarm).
  129. ** RESTRICTIONS:
  130. **  None. 
  131. ** MEMORY:      Memory for the notifier object.
  132. ** ALGORITHM:   The rate at which notifications are delivered are stated
  133. **              to be "'rate' notifies per 'interval'". The exact time of
  134. **              the notification is computed based on a epoch established
  135. **              when the notifier was set. Each notification is delivered
  136. **              not ealier than the epoch plus the fixed rate times the
  137. **              notification sequence number. Such notifications have the
  138. **              potential to be late by not more than 'interval'/'rate'.
  139. **              The amount of lateness of one notification is taken into
  140. **              account on the next in an attempt to avoid long term slew.  
  141. ***********************************************************************/
  142. PR_EXTERN(PRAlarmID*) PR_SetAlarm(
  143.     PRAlarm *alarm, PRIntervalTime period, PRUint32 rate,
  144.     PRPeriodicAlarmFn function, void *clientData);
  145.  
  146. /***********************************************************************
  147. ** FUNCTION:    PR_ResetAlarm
  148. ** DESCRIPTION:
  149. **  Resets an existing alarm.
  150. ** INPUTS:      PRAlarmID *id               Identify of the notifier.
  151. **              PRIntervalTime period       Interval over which the notifies
  152. **                                          are delivered.
  153. **              PRUint32 rate               The rate within the interval that
  154. **                                          the notifies will be delivered.
  155. ** OUTPUTS:     None
  156. ** RETURN:      PRStatus                    Indication of completion.
  157. **  
  158. ** SIDE EFFECTS:
  159. **  An existing alarm may have its period and rate redefined. The
  160. **  additional side effect is that the notifier's epoch is recomputed.
  161. **  The first notification delivered by the newly refreshed alarm is
  162. **  defined to be 'interval'/'rate' from the time of the reset.
  163. ** RESTRICTIONS:
  164. **  This function may only be called in the notifier for that alarm.
  165. ** MEMORY:      N/A.
  166. ** ALGORITHM:   See PR_SetAlarm().  
  167. ***********************************************************************/
  168. PR_EXTERN(PRStatus) PR_ResetAlarm(
  169.     PRAlarmID *id, PRIntervalTime period, PRUint32 rate);
  170.  
  171. PR_END_EXTERN_C
  172.  
  173. #endif /* !defined(pralarm_h) */
  174.  
  175. /* prinrval.h */
  176.