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.39 by jsr166, Thu Jun 9 07:48:43 2011 UTC vs.
Revision 1.40 by jsr166, Wed Jan 16 01:59:48 2013 UTC

#	Line 7 | Line 7
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:
#	Line 34 | Line 34 | package java.util.concurrent;
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
#	Line 148 | Line 148 | public enum TimeUnit {
148		* Convert the given time duration in the given unit to this
149		* unit.  Conversions from finer to coarser granularities
150		* truncate, so lose precision. For example converting
151	<	* <tt>999</tt> milliseconds to seconds results in
152	<	* <tt>0</tt>. Conversions from coarser to finer granularities
151	>	* {@code 999} milliseconds to seconds results in
152	>	* {@code 0}. Conversions from coarser to finer granularities
153		* with arguments that would numerically overflow saturate to
154	<	* <tt>Long.MIN_VALUE</tt> if negative or <tt>Long.MAX_VALUE</tt>
154	>	* {@code Long.MIN_VALUE} if negative or {@code Long.MAX_VALUE}
155		* if positive.
156		*
157		* <p>For example, to convert 10 minutes to milliseconds, use:
158	<	* <tt>TimeUnit.MILLISECONDS.convert(10L, TimeUnit.MINUTES)</tt>
158	>	* {@code TimeUnit.MILLISECONDS.convert(10L, TimeUnit.MINUTES)}
159		*
160	<	* @param sourceDuration the time duration in the given <tt>sourceUnit</tt>
161	<	* @param sourceUnit the unit of the <tt>sourceDuration</tt> argument
160	>	* @param sourceDuration the time duration in the given {@code sourceUnit}
161	>	* @param sourceUnit the unit of the {@code sourceDuration} argument
162		* @return the converted duration in this unit,
163	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
164	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
163	>	* or {@code Long.MIN_VALUE} if conversion would negatively
164	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
165		*/
166		public long convert(long sourceDuration, TimeUnit sourceUnit) {
167		throw new AbstractMethodError();
168		}
169
170		/**
171	<	* Equivalent to <tt>NANOSECONDS.convert(duration, this)</tt>.
171	>	* Equivalent to {@code NANOSECONDS.convert(duration, this)}.
172		* @param duration the duration
173		* @return the converted duration,
174	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
175	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
174	>	* or {@code Long.MIN_VALUE} if conversion would negatively
175	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
176		* @see #convert
177		*/
178		public long toNanos(long duration) {
#	Line 180 | Line 180 | public enum TimeUnit {
180		}
181
182		/**
183	<	* Equivalent to <tt>MICROSECONDS.convert(duration, this)</tt>.
183	>	* Equivalent to {@code MICROSECONDS.convert(duration, this)}.
184		* @param duration the duration
185		* @return the converted duration,
186	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
187	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
186	>	* or {@code Long.MIN_VALUE} if conversion would negatively
187	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
188		* @see #convert
189		*/
190		public long toMicros(long duration) {
#	Line 192 | Line 192 | public enum TimeUnit {
192		}
193
194		/**
195	<	* Equivalent to <tt>MILLISECONDS.convert(duration, this)</tt>.
195	>	* Equivalent to {@code MILLISECONDS.convert(duration, this)}.
196		* @param duration the duration
197		* @return the converted duration,
198	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
199	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
198	>	* or {@code Long.MIN_VALUE} if conversion would negatively
199	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
200		* @see #convert
201		*/
202		public long toMillis(long duration) {
#	Line 204 | Line 204 | public enum TimeUnit {
204		}
205
206		/**
207	<	* Equivalent to <tt>SECONDS.convert(duration, this)</tt>.
207	>	* Equivalent to {@code SECONDS.convert(duration, this)}.
208		* @param duration the duration
209		* @return the converted duration,
210	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
211	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
210	>	* or {@code Long.MIN_VALUE} if conversion would negatively
211	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
212		* @see #convert
213		*/
214		public long toSeconds(long duration) {
#	Line 216 | Line 216 | public enum TimeUnit {
216		}
217
218		/**
219	<	* Equivalent to <tt>MINUTES.convert(duration, this)</tt>.
219	>	* Equivalent to {@code MINUTES.convert(duration, this)}.
220		* @param duration the duration
221		* @return the converted duration,
222	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
223	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
222	>	* or {@code Long.MIN_VALUE} if conversion would negatively
223	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
224		* @see #convert
225		* @since 1.6
226		*/
#	Line 229 | Line 229 | public enum TimeUnit {
229		}
230
231		/**
232	<	* Equivalent to <tt>HOURS.convert(duration, this)</tt>.
232	>	* Equivalent to {@code HOURS.convert(duration, this)}.
233		* @param duration the duration
234		* @return the converted duration,
235	<	* or <tt>Long.MIN_VALUE</tt> if conversion would negatively
236	<	* overflow, or <tt>Long.MAX_VALUE</tt> if it would positively overflow.
235	>	* or {@code Long.MIN_VALUE} if conversion would negatively
236	>	* overflow, or {@code Long.MAX_VALUE} if it would positively overflow.
237		* @see #convert
238		* @since 1.6
239		*/
#	Line 242 | Line 242 | public enum TimeUnit {
242		}
243
244		/**
245	<	* Equivalent to <tt>DAYS.convert(duration, this)</tt>.
245	>	* Equivalent to {@code DAYS.convert(duration, this)}.
246		* @param duration the duration
247		* @return the converted duration
248		* @see #convert
#	Line 265 | Line 265 | public enum TimeUnit {
265		* Performs a timed {@link Object#wait(long, int) Object.wait}
266		* using this time unit.
267		* This is a convenience method that converts timeout arguments
268	<	* into the form required by the <tt>Object.wait</tt> method.
268	>	* into the form required by the {@code Object.wait} method.
269		*
270	<	* <p>For example, you could implement a blocking <tt>poll</tt>
270	>	* <p>For example, you could implement a blocking {@code poll}
271		* method (see {@link BlockingQueue#poll BlockingQueue.poll})
272		* using:
273		*
#	Line 298 | Line 298 | public enum TimeUnit {
298		* Performs a timed {@link Thread#join(long, int) Thread.join}
299		* using this time unit.
300		* This is a convenience method that converts time arguments into the
301	<	* form required by the <tt>Thread.join</tt> method.
301	>	* form required by the {@code Thread.join} method.
302		*
303		* @param thread the thread to wait for
304		* @param timeout the maximum time to wait. If less than
#	Line 318 | Line 318 | public enum TimeUnit {
318		* Performs a {@link Thread#sleep(long, int) Thread.sleep} using
319		* this time unit.
320		* This is a convenience method that converts time arguments into the
321	<	* form required by the <tt>Thread.sleep</tt> method.
321	>	* form required by the {@code Thread.sleep} method.
322		*
323		* @param timeout the minimum time to sleep. If less than
324		* or equal to zero, do not sleep at all.

Diff Legend

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