Java : TimeUnit - API使用例

TimeUnit (Java SE 18 & JDK 18) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様のおともにどうぞ。

概要

TimeUnitは、指定された粒度単位で時間を表し、単位を変換したり、それらの単位でタイミングおよび遅延操作を実行したりするユーティリティ・メソッドを提供します。

クラス構成

TimeUnit は、時間の単位を表す列挙型です。
列挙子には

日 (DAYS)
時 (HOURS)
分 (MINUTES)
秒 (SECONDS)
ミリ秒 (MILLISECONDS)
マイクロ秒 (MICROSECONDS)
ナノ秒 (NANOSECONDS)

があります。

主に、スレッド関連のAPIで、待機時間などを指定するときに、その時間単位として使われます。

final var executorService = Executors.newSingleThreadExecutor();
try {
    final var future = executorService.submit(() -> "abcd");

    final var ret = future.get();
    System.out.println(ret); // abcd

} finally {
    executorService.shutdown();
}

final var ret = executorService.awaitTermination(1, TimeUnit.MINUTES);
System.out.println(ret); // true

TimeUnit は列挙型ですが、いくつかのユーティリティ・メソッドが提供されています。
おすすめは sleep メソッドです。Thread.sleep の代わりに TimeUnit の sleep を使うと、時間の単位が明確になりソースコードの可読性が(少し)よくなります。

final var start = System.nanoTime();

// Thread.sleep(5000) と同じ意味です。
TimeUnit.SECONDS.sleep(5);

final var end = System.nanoTime();

// 5.001643 sec.
System.out.printf("%f sec.%n", (end - start) / 1000000000.0);

列挙型定数

DAYS

24時間を表す時間単位

System.out.println(TimeUnit.DAYS); // DAYS
System.out.println(TimeUnit.DAYS.toHours(1)); // 24

HOURS

60分を表す時間単位

System.out.println(TimeUnit.HOURS); // HOURS
System.out.println(TimeUnit.HOURS.toMinutes(1)); // 60

MICROSECONDS

ミリ秒の1000分の1を表す時間単位

System.out.println(TimeUnit.MICROSECONDS); // MICROSECONDS
System.out.println(TimeUnit.MICROSECONDS.toNanos(1)); // 1000

MILLISECONDS

秒の1000分の1を表す時間単位

System.out.println(TimeUnit.MILLISECONDS); // MILLISECONDS
System.out.println(TimeUnit.MILLISECONDS.toMicros(1)); // 1000

MINUTES

60秒を表す時間単位

System.out.println(TimeUnit.MINUTES); // MINUTES
System.out.println(TimeUnit.MINUTES.toSeconds(1)); // 60

NANOSECONDS

マイクロ秒の1000分の1を表す時間単位

System.out.println(TimeUnit.NANOSECONDS); // NANOSECONDS
System.out.println(TimeUnit.NANOSECONDS.toSeconds(1000000000)); // 1

SECONDS

1秒を表す時間単位

System.out.println(TimeUnit.SECONDS); // SECONDS
System.out.println(TimeUnit.SECONDS.toMillis(1)); // 1000

メソッド

long convert (long sourceDuration, TimeUnit sourceUnit)

指定された単位による指定されたデュレーションを、この単位に変換します。

final var ret1 = TimeUnit.HOURS.convert(1, TimeUnit.DAYS);
System.out.println(ret1); // 24

final var ret2 = TimeUnit.MINUTES.convert(2, TimeUnit.HOURS);
System.out.println(ret2); // 120

final var ret3 = TimeUnit.MILLISECONDS.convert(3, TimeUnit.SECONDS);
System.out.println(ret3); // 3000

final var ret1 = TimeUnit.SECONDS.convert(1000, TimeUnit.MILLISECONDS);
System.out.println(ret1); // 1

final var ret2 = TimeUnit.SECONDS.convert(999, TimeUnit.MILLISECONDS);
System.out.println(ret2); // 0

// オーバーフローの例です。
final var ret1 = TimeUnit.NANOSECONDS.convert(100000000, TimeUnit.DAYS);
System.out.println(ret1 == Long.MAX_VALUE); // true

final var ret2 = TimeUnit.NANOSECONDS.convert(-100000000, TimeUnit.DAYS);
System.out.println(ret2 == Long.MIN_VALUE); // true

long convert (Duration duration)

指定された期間をこの単位に変換します。

final var ret1 = TimeUnit.HOURS.convert(Duration.ofDays(1));
System.out.println(ret1); // 24

final var ret2 = TimeUnit.MINUTES.convert(Duration.ofHours(2));
System.out.println(ret2); // 120

final var ret3 = TimeUnit.MILLISECONDS.convert(Duration.ofSeconds(3));
System.out.println(ret3); // 3000

static TimeUnit of (ChronoUnit chronoUnit)

ChronoUnitを同等のTimeUnitに変換します。

final var ret1 = TimeUnit.of(ChronoUnit.DAYS);
System.out.println(ret1); // DAYS

final var ret2 = TimeUnit.of(ChronoUnit.SECONDS);
System.out.println(ret2); // SECONDS

void sleep (long timeout)

この時間単位を使用して、Thread.sleepを実行します。

final var start = System.nanoTime();

// Thread.sleep(5000) と同じ意味です。
TimeUnit.SECONDS.sleep(5);

final var end = System.nanoTime();

// 5.001643 sec.
System.out.printf("%f sec.%n", (end - start) / 1000000000.0);

final var start = System.nanoTime();

TimeUnit.MINUTES.sleep(1);

final var end = System.nanoTime();

// 60.000510 sec.
System.out.printf("%f sec.%n", (end - start) / 1000000000.0);

void timedJoin (Thread thread, long timeout)

この時間単位を使用して、時間指定されたThread.joinを実行します。

final var thread = new Thread(() -> {
    try {
        System.out.println("task : start");
        TimeUnit.SECONDS.sleep(2);
    } catch (InterruptedException e) {
        System.out.println("Interrupted!");
    } finally {
        System.out.println("task : end");
    }
});

System.out.println("-- start --");
thread.start();

System.out.println("-- join start --");
TimeUnit.SECONDS.timedJoin(thread, 3);

System.out.println("-- join end --");

// 結果
// ↓
//-- start --
//-- join start --
//task : start
//task : end
//-- join end --

void timedWait (Object obj, long timeout)

この時間単位を使用して、時間指定されたObject.waitを実行します。

// 基準となる時刻
final long current = System.nanoTime();

// 基準となる時刻からの差分を秒として取得
final DoubleSupplier elapsedSec = () -> (System.nanoTime() - current) / 1000000000.0;

final var executorService = Executors.newSingleThreadExecutor();
try {
    final var obj = new Object();
    final Callable<Void> task = () -> {
        try {
            System.out.printf("task start : %f sec.%n", elapsedSec.getAsDouble());
            synchronized (obj) {
                TimeUnit.SECONDS.timedWait(obj, 2);
            }
        } finally {
            System.out.printf("task end : %f sec.%n", elapsedSec.getAsDouble());
        }
        return null;
    };

    executorService.submit(task);

    TimeUnit.SECONDS.sleep(5);

    synchronized (obj) {
        obj.notify();
    }

} finally {
    executorService.shutdown();
    System.out.printf("--- shutdown --- : %f sec.%n", elapsedSec.getAsDouble());
}

final var ret = executorService.awaitTermination(10, TimeUnit.SECONDS);
System.out.printf("termination %b : %f sec.%n", ret, elapsedSec.getAsDouble());

// 結果
// ↓
//task start : 0.002766 sec.
//task end : 2.016894 sec.
//--- shutdown --- : 5.031749 sec.
//termination true : 5.033790 sec.

ChronoUnit toChronoUnit ()

このTimeUnitを同等のChronoUnitに変換します。

final var ret1 = TimeUnit.HOURS.toChronoUnit();
System.out.println(ret1); // Hours

final var ret2 = TimeUnit.MINUTES.toChronoUnit();
System.out.println(ret2); // Minutes

final var ret3 = TimeUnit.SECONDS.toChronoUnit();
System.out.println(ret3); // Seconds

long toDays (long duration)

DAYS.convert(duration, this)と同等です。

final var ret1 = TimeUnit.HOURS.toDays(48);
System.out.println(ret1); // 2

final var ret2 = TimeUnit.MINUTES.toDays(24 * 60 * 10);
System.out.println(ret2); // 10

long toHours (long duration)

HOURS.convert(duration, this)と同等です。

final var ret1 = TimeUnit.DAYS.toHours(1);
System.out.println(ret1); // 24

final var ret2 = TimeUnit.MINUTES.toHours(60 * 10);
System.out.println(ret2); // 10

long toMicros (long duration)

MICROSECONDS.convert(duration, this)と同等です。

final var ret1 = TimeUnit.MILLISECONDS.toMicros(1);
System.out.println(ret1); // 1000

final var ret2 = TimeUnit.NANOSECONDS.toMicros(1000 * 50);
System.out.println(ret2); // 50

long toMillis (long duration)

MILLISECONDS.convert(duration, this)と同等です。

final var ret1 = TimeUnit.SECONDS.toMillis(1);
System.out.println(ret1); // 1000

final var ret2 = TimeUnit.MICROSECONDS.toMillis(1000 * 50);
System.out.println(ret2); // 50

long toMinutes (long duration)

MINUTES.convert(duration, this)と同等です。

final var ret1 = TimeUnit.HOURS.toMinutes(1);
System.out.println(ret1); // 60

final var ret2 = TimeUnit.SECONDS.toMinutes(60 * 150);
System.out.println(ret2); // 150

long toNanos (long duration)

NANOSECONDS.convert(duration, this)と同等です。

final var ret1 = TimeUnit.MICROSECONDS.toNanos(1);
System.out.println(ret1); // 1000

final var ret2 = TimeUnit.MILLISECONDS.toNanos(5);
System.out.println(ret2); // 5000000

long toSeconds (long duration)

SECONDS.convert(duration, this)と同等です。

final var ret1 = TimeUnit.MINUTES.toSeconds(1);
System.out.println(ret1); // 60

final var ret2 = TimeUnit.MILLISECONDS.toSeconds(1000 * 150);
System.out.println(ret2); // 150

static TimeUnit valueOf (String name)

指定された名前を持つこのクラスのenum定数を返します。

final var ret1 = TimeUnit.valueOf("DAYS");
System.out.println(ret1); // DAYS

final var ret2 = TimeUnit.valueOf("SECONDS");
System.out.println(ret2); // SECONDS

static TimeUnit[] values ()

この列挙クラスの定数を含む配列を宣言されている順序で返します。

for (final var value : TimeUnit.values()) {
    System.out.println(value);
}

// 結果
// ↓
//NANOSECONDS
//MICROSECONDS
//MILLISECONDS
//SECONDS
//MINUTES
//HOURS
//DAYS

Enumで宣言されたメソッド

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

「Java API 使用例 : Enum」をご参照ください。

API 使用例