org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java

/*
 * Copyright (C) 2016, Google Inc. and others
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0 which is available at
 * https://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package org.eclipse.jgit.util.time;

import static java.util.concurrent.TimeUnit.MICROSECONDS;
import static java.util.concurrent.TimeUnit.MILLISECONDS;

import java.sql.Timestamp;
import java.time.Duration;
import java.time.Instant;
import java.util.Date;
import java.util.Iterator;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

/**
 * A timestamp generated by
 * {@link org.eclipse.jgit.util.time.MonotonicClock#propose()}.
 * <p>
 * ProposedTimestamp implements AutoCloseable so that implementations can
 * release resources associated with obtaining certainty about time elapsing.
 * For example the constructing MonotonicClock may start network IO with peers
 * when creating the ProposedTimestamp, and {@link #close()} can ensure those
 * network resources are released in a timely fashion.
 *
 * @since 4.6
 */
public abstract class ProposedTimestamp implements AutoCloseable {
	/**
	 * Wait for several timestamps.
	 *
	 * @param times
	 *            timestamps to wait on.
	 * @param maxWait
	 *            how long to wait for the timestamps.
	 * @throws java.lang.InterruptedException
	 *             current thread was interrupted before the waiting process
	 *             completed normally.
	 * @throws java.util.concurrent.TimeoutException
	 *             the timeout was reached without the proposed timestamp become
	 *             certainly in the past.
	 */
	public static void blockUntil(Iterable<ProposedTimestamp> times,
			Duration maxWait) throws TimeoutException, InterruptedException {
		Iterator<ProposedTimestamp> itr = times.iterator();
		if (!itr.hasNext()) {
			return;
		}

		long now = System.currentTimeMillis();
		long deadline = now + maxWait.toMillis();
		for (;;) {
			long w = deadline - now;
			if (w < 0) {
				throw new TimeoutException();
			}
			itr.next().blockUntil(Duration.ofMillis(w));
			if (itr.hasNext()) {
				now = System.currentTimeMillis();
			} else {
				break;
			}
		}
	}

	/**
	 * Read the timestamp as {@code unit} since the epoch.
	 * <p>
	 * The timestamp value for a specific {@code ProposedTimestamp} object never
	 * changes, and can be read before {@link #blockUntil(Duration)}.
	 *
	 * @param unit
	 *            what unit to return the timestamp in. The timestamp will be
	 *            rounded if the unit is bigger than the clock's granularity.
	 * @return {@code unit} since the epoch.
	 */
	public abstract long read(TimeUnit unit);

	/**
	 * Wait for this proposed timestamp to be certainly in the recent past.
	 * <p>
	 * This method forces the caller to wait up to {@code timeout} for
	 * {@code this} to pass sufficiently into the past such that the creating
	 * {@link org.eclipse.jgit.util.time.MonotonicClock} instance will not
	 * create an earlier timestamp.
	 *
	 * @param maxWait
	 *            how long the implementation may block the caller.
	 * @throws java.lang.InterruptedException
	 *             current thread was interrupted before the waiting process
	 *             completed normally.
	 * @throws java.util.concurrent.TimeoutException
	 *             the timeout was reached without the proposed timestamp
	 *             becoming certainly in the past.
	 */
	public abstract void blockUntil(Duration maxWait)
			throws InterruptedException, TimeoutException;

	/**
	 * Get milliseconds since epoch; {@code read(MILLISECONDS}).
	 *
	 * @return milliseconds since epoch; {@code read(MILLISECONDS}).
	 */
	public long millis() {
		return read(MILLISECONDS);
	}

	/**
	 * Get microseconds since epoch; {@code read(MICROSECONDS}).
	 *
	 * @return microseconds since epoch; {@code read(MICROSECONDS}).
	 */
	public long micros() {
		return read(MICROSECONDS);
	}

	/**
	 * Get time since epoch, with up to microsecond resolution.
	 *
	 * @return time since epoch, with up to microsecond resolution.
	 */
	public Instant instant() {
		long usec = micros();
		long secs = usec / 1000000L;
		long nanos = (usec % 1000000L) * 1000L;
		return Instant.ofEpochSecond(secs, nanos);
	}

	/**
	 * Get time since epoch, with up to microsecond resolution.
	 *
	 * @return time since epoch, with up to microsecond resolution.
	 */
	public Timestamp timestamp() {
		return Timestamp.from(instant());
	}

	/**
	 * Get time since epoch, with up to millisecond resolution.
	 *
	 * @return time since epoch, with up to millisecond resolution.
	 */
	public Date date() {
		return new Date(millis());
	}

	/**
	 * {@inheritDoc}
	 * <p>
	 * Release resources allocated by this timestamp.
	 */
	@Override
	public void close() {
		// Do nothing by default.
	}

	/** {@inheritDoc} */
	@Override
	public String toString() {
		return instant().toString();
	}
}