prinrval.h (5339B)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 /* 7 ** File: prinrval.h 8 ** Description: API to interval timing functions of NSPR. 9 ** 10 ** 11 ** NSPR provides interval times that are independent of network time 12 ** of day values. Interval times are (in theory) accurate regardless 13 ** of host processing requirements and also very cheap to acquire. It 14 ** is expected that getting an interval time while in a synchronized 15 ** function (holding one's lock). 16 **/ 17 18 #if !defined(prinrval_h) 19 #define prinrval_h 20 21 #include "prtypes.h" 22 23 PR_BEGIN_EXTERN_C 24 25 /**********************************************************************/ 26 /************************* TYPES AND CONSTANTS ************************/ 27 /**********************************************************************/ 28 29 typedef PRUint32 PRIntervalTime; 30 31 /*********************************************************************** 32 ** DEFINES: PR_INTERVAL_MIN 33 ** PR_INTERVAL_MAX 34 ** DESCRIPTION: 35 ** These two constants define the range (in ticks / second) of the 36 ** platform dependent type, PRIntervalTime. These constants bound both 37 ** the period and the resolution of a PRIntervalTime. 38 ***********************************************************************/ 39 #define PR_INTERVAL_MIN 1000UL 40 #define PR_INTERVAL_MAX 100000UL 41 42 /*********************************************************************** 43 ** DEFINES: PR_INTERVAL_NO_WAIT 44 ** PR_INTERVAL_NO_TIMEOUT 45 ** DESCRIPTION: 46 ** Two reserved constants are defined in the PRIntervalTime namespace. 47 ** They are used to indicate that the process should wait no time (return 48 ** immediately) or wait forever (never time out), respectively. 49 ** Note: PR_INTERVAL_NO_TIMEOUT passed as input to PR_Connect is 50 ** interpreted as use the OS's connect timeout. 51 ** 52 ***********************************************************************/ 53 #define PR_INTERVAL_NO_WAIT 0UL 54 #define PR_INTERVAL_NO_TIMEOUT 0xffffffffUL 55 56 /**********************************************************************/ 57 /****************************** FUNCTIONS *****************************/ 58 /**********************************************************************/ 59 60 /*********************************************************************** 61 ** FUNCTION: PR_IntervalNow 62 ** DESCRIPTION: 63 ** Return the value of NSPR's free running interval timer. That timer 64 ** can be used to establish epochs and determine intervals (be computing 65 ** the difference between two times). 66 ** INPUTS: void 67 ** OUTPUTS: void 68 ** RETURN: PRIntervalTime 69 ** 70 ** SIDE EFFECTS: 71 ** None 72 ** RESTRICTIONS: 73 ** The units of PRIntervalTime are platform dependent. They are chosen 74 ** such that they are appropriate for the host OS, yet provide sufficient 75 ** resolution and period to be useful to clients. 76 ** MEMORY: N/A 77 ** ALGORITHM: Platform dependent 78 ***********************************************************************/ 79 NSPR_API(PRIntervalTime) PR_IntervalNow(void); 80 81 /*********************************************************************** 82 ** FUNCTION: PR_TicksPerSecond 83 ** DESCRIPTION: 84 ** Return the number of ticks per second for PR_IntervalNow's clock. 85 ** The value will be in the range [PR_INTERVAL_MIN..PR_INTERVAL_MAX]. 86 ** INPUTS: void 87 ** OUTPUTS: void 88 ** RETURN: PRUint32 89 ** 90 ** SIDE EFFECTS: 91 ** None 92 ** RESTRICTIONS: 93 ** None 94 ** MEMORY: N/A 95 ** ALGORITHM: N/A 96 ***********************************************************************/ 97 NSPR_API(PRUint32) PR_TicksPerSecond(void); 98 99 /*********************************************************************** 100 ** FUNCTION: PR_SecondsToInterval 101 ** PR_MillisecondsToInterval 102 ** PR_MicrosecondsToInterval 103 ** DESCRIPTION: 104 ** Convert standard clock units to platform dependent intervals. 105 ** INPUTS: PRUint32 106 ** OUTPUTS: void 107 ** RETURN: PRIntervalTime 108 ** 109 ** SIDE EFFECTS: 110 ** None 111 ** RESTRICTIONS: 112 ** Conversion may cause overflow, which is not reported. 113 ** MEMORY: N/A 114 ** ALGORITHM: N/A 115 ***********************************************************************/ 116 NSPR_API(PRIntervalTime) PR_SecondsToInterval(PRUint32 seconds); 117 NSPR_API(PRIntervalTime) PR_MillisecondsToInterval(PRUint32 milli); 118 NSPR_API(PRIntervalTime) PR_MicrosecondsToInterval(PRUint32 micro); 119 120 /*********************************************************************** 121 ** FUNCTION: PR_IntervalToSeconds 122 ** PR_IntervalToMilliseconds 123 ** PR_IntervalToMicroseconds 124 ** DESCRIPTION: 125 ** Convert platform dependent intervals to standard clock units. 126 ** INPUTS: PRIntervalTime 127 ** OUTPUTS: void 128 ** RETURN: PRUint32 129 ** 130 ** SIDE EFFECTS: 131 ** None 132 ** RESTRICTIONS: 133 ** Conversion may cause overflow, which is not reported. 134 ** MEMORY: N/A 135 ** ALGORITHM: N/A 136 ***********************************************************************/ 137 NSPR_API(PRUint32) PR_IntervalToSeconds(PRIntervalTime ticks); 138 NSPR_API(PRUint32) PR_IntervalToMilliseconds(PRIntervalTime ticks); 139 NSPR_API(PRUint32) PR_IntervalToMicroseconds(PRIntervalTime ticks); 140 141 PR_END_EXTERN_C 142 143 144 #endif /* !defined(prinrval_h) */ 145 146 /* prinrval.h */