Java Reference ยท Concurrency
The TimeUnit enum
Reference for java.util.concurrent.TimeUnit: the seven time units, converting durations with convert and toX methods, saturation, and timed waits.
TimeUnit is an enum that represents a granularity of time, from NANOSECONDS up to DAYS. It appears in the signatures of almost every timed concurrency method, for example future.get(2, TimeUnit.SECONDS) or queue.poll(100, TimeUnit.MILLISECONDS), so that a bare long is never ambiguous. It also converts durations between units.
Since Java 9 TimeUnit can also convert to and from java.time.temporal.ChronoUnit and Duration. For new code that models a length of time as a value prefer Duration; TimeUnit remains the standard way to pass a timeout to concurrency APIs.
long millis = TimeUnit.SECONDS.toMillis(3); // 3000 long minutes = TimeUnit.MINUTES.convert(7200, TimeUnit.SECONDS); // 120
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public enum TimeUnit { NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS; public long convert(long sourceDuration, TimeUnit sourceUnit) public long convert(Duration duration) // since 11 public long toNanos(long d) /* toMicros, toMillis, toSeconds, toMinutes, toHours, toDays */ public void sleep(long timeout) throws InterruptedException public void timedJoin(Thread thread, long timeout) throws InterruptedException public ChronoUnit toChronoUnit() // since 9 public static TimeUnit of(ChronoUnit chronoUnit) // since 9 }
| Member | Description |
|---|---|
convert(d, unit) |
Converts d expressed in unit into this unit. Read it as "this unit, converted from that one". |
toMillis(d) etc. |
Converts d in this unit into the named unit. |
convert(Duration) |
Converts a Duration into this unit (truncating). |
sleep(n) |
Same as Thread.sleep in this unit; returns at once for zero or negative values. |
timedJoin(t, n) / timedWait(o, n) |
Timed Thread.join and Object.wait. |
toChronoUnit(), of(ChronoUnit) |
Mapping to java.time units. |
Usage notes
- Direction confusion:
TimeUnit.MINUTES.convert(60, SECONDS)is 1;TimeUnit.SECONDS.toMinutes(60)is also 1. Prefer thetoXmethods for readability. - Truncation: conversion to a coarser unit rounds toward zero (
90 minis1 hour); conversion to a finer unit multiplies. - Saturation: overflow returns
Long.MIN_VALUEorLong.MAX_VALUErather than a wrapped number, so a huge timeout becomes "effectively forever". - Zero and negative timeouts mean "do not wait" in most APIs (
poll(0, unit)behaves likepoll()). - No months or years: they have variable length. Use
java.time(Period,ChronoUnit) for calendar math. - Precision of waits depends on the OS; nanosecond and microsecond arguments are rounded to what the platform can do.
- Do not use it for measuring elapsed time: use
System.nanoTime()and convert the difference.