| /* |
| * 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 java.time.Duration; |
| |
| /** |
| * A provider of time. |
| * <p> |
| * Clocks should provide wall clock time, obtained from a reasonable clock |
| * source, such as the local system clock. |
| * <p> |
| * MonotonicClocks provide the following behavior, with the assertion always |
| * being true if |
| * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)} is |
| * used: |
| * |
| * <pre> |
| * MonotonicClock clk = ...; |
| * long r1; |
| * try (ProposedTimestamp t1 = clk.propose()) { |
| * r1 = t1.millis(); |
| * t1.blockUntil(...); |
| * } |
| * |
| * try (ProposedTimestamp t2 = clk.propose()) { |
| * assert t2.millis() > r1; |
| * } |
| * </pre> |
| * |
| * @since 4.6 |
| */ |
| public interface MonotonicClock { |
| /** |
| * Obtain a timestamp close to "now". |
| * <p> |
| * Proposed times are close to "now", but may not yet be certainly in the |
| * past. This allows the calling thread to interleave other useful work |
| * while waiting for the clock instance to create an assurance it will never |
| * in the future propose a time earlier than the returned time. |
| * <p> |
| * A hypothetical implementation could read the local system clock (managed |
| * by NTP) and return that proposal, concurrently sending network messages |
| * to closely collaborating peers in the same cluster to also ensure their |
| * system clocks are ahead of this time. In such an implementation the |
| * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)} |
| * method would wait for replies from the peers indicating their own system |
| * clocks have moved past the proposed time. |
| * |
| * @return a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. |
| */ |
| ProposedTimestamp propose(); |
| } |