PageRenderTime 916ms CodeModel.GetById 590ms app.highlight 5ms RepoModel.GetById 250ms app.codeStats 0ms

/gecko_api/include/obsolete/pralarm.h

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