ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/concurrent/TimeUnit.java

Comparing jsr166/src/main/java/util/concurrent/TimeUnit.java (file contents):
Revision 1.29 by jsr166, Tue Apr 26 01:17:18 2005 UTC vs.
Revision 1.43 by jsr166, Wed Jul 17 21:17:43 2013 UTC

#	Line 1 | Line 1
1		/*
2	<	* Written by Doug Lea with assistance from members of JCP JSR-166
3	<	* Expert Group and released to the public domain, as explained at
4	<	* http://creativecommons.org/licenses/publicdomain
5	<	*/
2	>	* Written by Doug Lea with assistance from members of JCP JSR-166
3	>	* Expert Group and released to the public domain, as explained at
4	>	* http://creativecommons.org/publicdomain/zero/1.0/
5	>	*/
6
7		package java.util.concurrent;
8
9		/**
10	<	* A <tt>TimeUnit</tt> represents time durations at a given unit of
10	>	* A {@code TimeUnit} represents time durations at a given unit of
11		* granularity and provides utility methods to convert across units,
12		* and to perform timing and delay operations in these units.  A
13	<	* <tt>TimeUnit</tt> does not maintain time information, but only
13	>	* {@code TimeUnit} does not maintain time information, but only
14		* helps organize and use time representations that may be maintained
15		* separately across various contexts.  A nanosecond is defined as one
16		* thousandth of a microsecond, a microsecond as one thousandth of a
#	Line 18 | Line 18 | package java.util.concurrent;
18		* as sixty seconds, an hour as sixty minutes, and a day as twenty four
19		* hours.
20		*
21	<	* <p>A <tt>TimeUnit</tt> is mainly used to inform time-based methods
21	>	* <p>A {@code TimeUnit} is mainly used to inform time-based methods
22		* how a given timing parameter should be interpreted. For example,
23		* the following code will timeout in 50 milliseconds if the {@link
24		* java.util.concurrent.locks.Lock lock} is not available:
25		*
26	<	* <pre>  Lock lock = ...;
27	<	*  if ( lock.tryLock(50L, TimeUnit.MILLISECONDS) ) ...
28	<	* </pre>
26	>	*  <pre> {@code
27	>	* Lock lock = ...;
28	>	* if (lock.tryLock(50L, TimeUnit.MILLISECONDS)) ...}</pre>
29	>	*
30		* while this code will timeout in 50 seconds:
31	<	* <pre>
32	<	*  Lock lock = ...;
33	<	*  if ( lock.tryLock(50L, TimeUnit.SECONDS) ) ...
33	<	* </pre>
31	>	*  <pre> {@code
32	>	* Lock lock = ...;
33	>	* if (lock.tryLock(50L, TimeUnit.SECONDS)) ...}</pre>
34		*
35		* Note however, that there is no guarantee that a particular timeout
36		* implementation will be able to notice the passage of time at the
37	<	* same granularity as the given <tt>TimeUnit</tt>.
37	>	* same granularity as the given {@code TimeUnit}.
38		*
39		* @since 1.5
40		* @author Doug Lea
41		*/
42		public enum TimeUnit {
43	<	NANOSECONDS (0) {
43	>	/**
44	>	* Time unit representing one thousandth of a microsecond
45	>	*/
46	>	NANOSECONDS {
47		public long toNanos(long d)   { return d; }
48		public long toMicros(long d)  { return d/(C1/C0); }
49		public long toMillis(long d)  { return d/(C2/C0); }
#	Line 51 | Line 54 | public enum TimeUnit {
54		public long convert(long d, TimeUnit u) { return u.toNanos(d); }
55		int excessNanos(long d, long m) { return (int)(d - (m*C2)); }
56		},
57	<	MICROSECONDS (1) {
57	>
58	>	/**
59	>	* Time unit representing one thousandth of a millisecond
60	>	*/
61	>	MICROSECONDS {
62		public long toNanos(long d)   { return x(d, C1/C0, MAX/(C1/C0)); }
63		public long toMicros(long d)  { return d; }
64		public long toMillis(long d)  { return d/(C2/C1); }
#	Line 62 | Line 69 | public enum TimeUnit {
69		public long convert(long d, TimeUnit u) { return u.toMicros(d); }
70		int excessNanos(long d, long m) { return (int)((d*C1) - (m*C2)); }
71		},
72	<	MILLISECONDS (2) {
72	>
73	>	/**
74	>	* Time unit representing one thousandth of a second
75	>	*/
76	>	MILLISECONDS {
77		public long toNanos(long d)   { return x(d, C2/C0, MAX/(C2/C0)); }
78		public long toMicros(long d)  { return x(d, C2/C1, MAX/(C2/C1)); }
79		public long toMillis(long d)  { return d; }
#	Line 73 | Line 84 | public enum TimeUnit {
84		public long convert(long d, TimeUnit u) { return u.toMillis(d); }
85		int excessNanos(long d, long m) { return 0; }
86		},
87	<	SECONDS (3) {
87	>
88	>	/**
89	>	* Time unit representing one second
90	>	*/
91	>	SECONDS {
92		public long toNanos(long d)   { return x(d, C3/C0, MAX/(C3/C0)); }
93		public long toMicros(long d)  { return x(d, C3/C1, MAX/(C3/C1)); }
94		public long toMillis(long d)  { return x(d, C3/C2, MAX/(C3/C2)); }
#	Line 84 | Line 99 | public enum TimeUnit {
99		public long convert(long d, TimeUnit u) { return u.toSeconds(d); }
100		int excessNanos(long d, long m) { return 0; }
101		},
102	<	MINUTES (4) {
102	>
103	>	/**
104	>	* Time unit representing sixty seconds
105	>	*/
106	>	MINUTES {
107		public long toNanos(long d)   { return x(d, C4/C0, MAX/(C4/C0)); }
108		public long toMicros(long d)  { return x(d, C4/C1, MAX/(C4/C1)); }
109		public long toMillis(long d)  { return x(d, C4/C2, MAX/(C4/C2)); }
#	Line 95 | Line 114 | public enum TimeUnit {
114		public long convert(long d, TimeUnit u) { return u.toMinutes(d); }
115		int excessNanos(long d, long m) { return 0; }
116		},
117	<	HOURS (5) {
117	>
118	>	/**
119	>	* Time unit representing sixty minutes
120	>	*/
121	>	HOURS {
122		public long toNanos(long d)   { return x(d, C5/C0, MAX/(C5/C0)); }
123		public long toMicros(long d)  { return x(d, C5/C1, MAX/(C5/C1)); }
124		public long toMillis(long d)  { return x(d, C5/C2, MAX/(C5/C2)); }
#	Line 106 | Line 129 | public enum TimeUnit {
129		public long convert(long d, TimeUnit u) { return u.toHours(d); }
130		int excessNanos(long d, long m) { return 0; }
131		},
132	<	DAYS (6) {
132	>
133	>	/**
134	>	* Time unit representing twenty four hours
135	>	*/
136	>	DAYS {
137		public long toNanos(long d)   { return x(d, C6/C0, MAX/(C6/C0)); }
138		public long toMicros(long d)  { return x(d, C6/C1, MAX/(C6/C1)); }
139		public long toMillis(long d)  { return x(d, C6/C2, MAX/(C6/C2)); }
#	Line 118 | Line 145 | public enum TimeUnit {
145		int excessNanos(long d, long m) { return 0; }
146		};
147
121	–	/**
122	–	* The index of this unit. This value is no longer used in this
123	–	* version of this class, but is retained for serialization
124	–	* compatibility with previous version.
125	–	*/
126	–	private final int index;
127	–
128	–	/** Internal constructor */
129	–	TimeUnit(int index) {
130	–	this.index = index;
131	–	}
132	–
148		// Handy constants for conversion methods
149		static final long C0 = 1L;
150		static final long C1 = C0 * 1000L;
#	Line 151 | Line 166 | public enum TimeUnit {
166		return d * m;
167		}
168
169	+	// To maintain full signature compatibility with 1.5, and to improve the
170	+	// clarity of the generated javadoc (see 6287639: Abstract methods in
171	+	// enum classes should not be listed as abstract), method convert
172	+	// etc. are not declared abstract but otherwise act as abstract methods.
173	+
174		/**
175	<	* Convert the given time duration in the given unit to this
176	<	* unit.  Conversions from finer to coarser granularities
177	<	* truncate, so lose precision. For example converting
178	<	* <tt>999</tt> milliseconds to seconds results in
179	<	* <tt>0</tt>. Conversions from coarser to finer granularities
180	<	* with arguments that would numerically overflow saturate to
181	<	* <tt>Long.MIN_VALUE</tt> if negative or <tt>Long.MAX_VALUE</tt>
162	<	* if positive.
175	>	* Converts the given time duration in the given unit to this unit.
176	>	* Conversions from finer to coarser granularities truncate, so
177	>	* lose precision. For example, converting {@code 999} milliseconds
178	>	* to seconds results in {@code 0}. Conversions from coarser to
179	>	* finer granularities with arguments that would numerically
180	>	* overflow saturate to {@code Long.MIN_VALUE} if negative or
181	>	* {@code Long.MAX_VALUE} if positive.
182		*
183	<	* @param duration the time duration in the given <tt>unit</tt>
184	<	* @param unit the unit of the <tt>duration</tt> argument
183	>	* <p>For example, to convert 10 minutes to milliseconds, use:
184	>	* {@code TimeUnit.MILLISECONDS.convert(10L, TimeUnit.MINUTES)}
185	>	*
186	>	* @param sourceDuration the time duration in the given {@code sourceUnit}
187	>	* @param sourceUnit the unit of the {@code sourceDuration} argument
188		* @return the converted duration in this unit,
189	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
190	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
189	>	* or {@code Long.MIN_VALUE} if conversion would negatively
190	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
191		*/
192	<	public abstract long convert(long duration, TimeUnit unit);
192	>	public long convert(long sourceDuration, TimeUnit sourceUnit) {
193	>	throw new AbstractMethodError();
194	>	}
195
196		/**
197	<	* Equivalent to <tt>NANOSECONDS.convert(duration, this)</tt>.
197	>	* Equivalent to
198	>	* {@link #convert(long, TimeUnit) NANOSECONDS.convert(duration, this)}.
199		* @param duration the duration
200		* @return the converted duration,
201	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
202	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
178	<	* @see #convert
201	>	* or {@code Long.MIN_VALUE} if conversion would negatively
202	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
203		*/
204	<	public abstract long toNanos(long duration);
204	>	public long toNanos(long duration) {
205	>	throw new AbstractMethodError();
206	>	}
207
208		/**
209	<	* Equivalent to <tt>MICROSECONDS.convert(duration, this)</tt>.
209	>	* Equivalent to
210	>	* {@link #convert(long, TimeUnit) MICROSECONDS.convert(duration, this)}.
211		* @param duration the duration
212		* @return the converted duration,
213	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
214	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
188	<	* @see #convert
213	>	* or {@code Long.MIN_VALUE} if conversion would negatively
214	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
215		*/
216	<	public abstract long toMicros(long duration);
216	>	public long toMicros(long duration) {
217	>	throw new AbstractMethodError();
218	>	}
219
220		/**
221	<	* Equivalent to <tt>MILLISECONDS.convert(duration, this)</tt>.
221	>	* Equivalent to
222	>	* {@link #convert(long, TimeUnit) MILLISECONDS.convert(duration, this)}.
223		* @param duration the duration
224		* @return the converted duration,
225	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
226	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
198	<	* @see #convert
225	>	* or {@code Long.MIN_VALUE} if conversion would negatively
226	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
227		*/
228	<	public abstract long toMillis(long duration);
228	>	public long toMillis(long duration) {
229	>	throw new AbstractMethodError();
230	>	}
231
232		/**
233	<	* Equivalent to <tt>SECONDS.convert(duration, this)</tt>.
233	>	* Equivalent to
234	>	* {@link #convert(long, TimeUnit) SECONDS.convert(duration, this)}.
235		* @param duration the duration
236		* @return the converted duration,
237	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
238	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
208	<	* @see #convert
237	>	* or {@code Long.MIN_VALUE} if conversion would negatively
238	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
239		*/
240	<	public abstract long toSeconds(long duration);
240	>	public long toSeconds(long duration) {
241	>	throw new AbstractMethodError();
242	>	}
243
244		/**
245	<	* Equivalent to <tt>MINUTES.convert(duration, this)</tt>.
245	>	* Equivalent to
246	>	* {@link #convert(long, TimeUnit) MINUTES.convert(duration, this)}.
247		* @param duration the duration
248		* @return the converted duration,
249	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
250	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
251	<	* @see #convert
249	>	* or {@code Long.MIN_VALUE} if conversion would negatively
250	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
251	>	* @since 1.6
252		*/
253	<	public abstract long toMinutes(long duration);
253	>	public long toMinutes(long duration) {
254	>	throw new AbstractMethodError();
255	>	}
256
257		/**
258	<	* Equivalent to <tt>HOURS.convert(duration, this)</tt>.
258	>	* Equivalent to
259	>	* {@link #convert(long, TimeUnit) HOURS.convert(duration, this)}.
260		* @param duration the duration
261		* @return the converted duration,
262	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
263	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
264	<	* @see #convert
262	>	* or {@code Long.MIN_VALUE} if conversion would negatively
263	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
264	>	* @since 1.6
265		*/
266	<	public abstract long toHours(long duration);
266	>	public long toHours(long duration) {
267	>	throw new AbstractMethodError();
268	>	}
269
270		/**
271	<	* Equivalent to <tt>DAYS.convert(duration, this)</tt>.
271	>	* Equivalent to
272	>	* {@link #convert(long, TimeUnit) DAYS.convert(duration, this)}.
273		* @param duration the duration
274		* @return the converted duration
275	<	* @see #convert
275	>	* @since 1.6
276		*/
277	<	public abstract long toDays(long duration);
277	>	public long toDays(long duration) {
278	>	throw new AbstractMethodError();
279	>	}
280
281		/**
282		* Utility to compute the excess-nanosecond argument to wait,
#	Line 247 | Line 288 | public enum TimeUnit {
288		abstract int excessNanos(long d, long m);
289
290		/**
291	<	* Performs a timed <tt>Object.wait</tt> using this time unit.
291	>	* Performs a timed {@link Object#wait(long, int) Object.wait}
292	>	* using this time unit.
293		* This is a convenience method that converts timeout arguments
294	<	* into the form required by the <tt>Object.wait</tt> method.
294	>	* into the form required by the {@code Object.wait} method.
295		*
296	<	* <p>For example, you could implement a blocking <tt>poll</tt>
296	>	* <p>For example, you could implement a blocking {@code poll}
297		* method (see {@link BlockingQueue#poll BlockingQueue.poll})
298		* using:
299		*
300	<	* <pre>  public synchronized  Object poll(long timeout, TimeUnit unit) throws InterruptedException {
301	<	*    while (empty) {
302	<	*      unit.timedWait(this, timeout);
303	<	*      ...
304	<	*    }
305	<	*  }</pre>
300	>	*  <pre> {@code
301	>	* public synchronized Object poll(long timeout, TimeUnit unit)
302	>	*     throws InterruptedException {
303	>	*   while (empty) {
304	>	*     unit.timedWait(this, timeout);
305	>	*     ...
306	>	*   }
307	>	* }}</pre>
308		*
309		* @param obj the object to wait on
310		* @param timeout the maximum time to wait. If less than
311		* or equal to zero, do not wait at all.
312	<	* @throws InterruptedException if interrupted while waiting.
269	<	* @see Object#wait(long, int)
312	>	* @throws InterruptedException if interrupted while waiting
313		*/
314		public void timedWait(Object obj, long timeout)
315	<	throws InterruptedException {
315	>	throws InterruptedException {
316		if (timeout > 0) {
317		long ms = toMillis(timeout);
318		int ns = excessNanos(timeout, ms);
#	Line 278 | Line 321 | public enum TimeUnit {
321		}
322
323		/**
324	<	* Performs a timed <tt>Thread.join</tt> using this time unit.
324	>	* Performs a timed {@link Thread#join(long, int) Thread.join}
325	>	* using this time unit.
326		* This is a convenience method that converts time arguments into the
327	<	* form required by the <tt>Thread.join</tt> method.
327	>	* form required by the {@code Thread.join} method.
328	>	*
329		* @param thread the thread to wait for
330		* @param timeout the maximum time to wait. If less than
331		* or equal to zero, do not wait at all.
332	<	* @throws InterruptedException if interrupted while waiting.
288	<	* @see Thread#join(long, int)
332	>	* @throws InterruptedException if interrupted while waiting
333		*/
334		public void timedJoin(Thread thread, long timeout)
335	<	throws InterruptedException {
335	>	throws InterruptedException {
336		if (timeout > 0) {
337		long ms = toMillis(timeout);
338		int ns = excessNanos(timeout, ms);
#	Line 297 | Line 341 | public enum TimeUnit {
341		}
342
343		/**
344	<	* Performs a <tt>Thread.sleep</tt> using this unit.
344	>	* Performs a {@link Thread#sleep(long, int) Thread.sleep} using
345	>	* this time unit.
346		* This is a convenience method that converts time arguments into the
347	<	* form required by the <tt>Thread.sleep</tt> method.
347	>	* form required by the {@code Thread.sleep} method.
348	>	*
349		* @param timeout the minimum time to sleep. If less than
350		* or equal to zero, do not sleep at all.
351	<	* @throws InterruptedException if interrupted while sleeping.
306	<	* @see Thread#sleep
351	>	* @throws InterruptedException if interrupted while sleeping
352		*/
353		public void sleep(long timeout) throws InterruptedException {
354		if (timeout > 0) {

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines