Skip to content
Tutorials Center
My learning

Topics

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.

Java
long millis = TimeUnit.SECONDS.toMillis(3);                       // 3000
long minutes = TimeUnit.MINUTES.convert(7200, TimeUnit.SECONDS);  // 120

Try it

Java Converting between units

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.

Java Timeouts and sleeping

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

Java
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 the toX methods for readability.
  • Truncation: conversion to a coarser unit rounds toward zero (90 min is 1 hour); conversion to a finer unit multiplies.
  • Saturation: overflow returns Long.MIN_VALUE or Long.MAX_VALUE rather 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 like poll()).
  • 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.