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 */ |
147 | |