• file
• revisions
• annotate
• diff
• comparison
• raw

nsprpub/pr/include/obsolete/pralarm.h@44a2da4a2ab2 (annotated)

nsprpub/pr/include/obsolete/pralarm.h

Fri, 16 Jan 2015 04:50:19 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Fri, 16 Jan 2015 04:50:19 +0100

branch

TOR_BUG_9701

changeset 13

44a2da4a2ab2

permissions

-rw-r--r--

Replace accessor implementation with direct member state manipulation, by
request https://trac.torproject.org/projects/tor/ticket/9701#comment:32

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