1 /*
2 * Copyright (C) 2016, Google Inc. and others
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Distribution License v. 1.0 which is available at
6 * https://www.eclipse.org/org/documents/edl-v10.php.
7 *
8 * SPDX-License-Identifier: BSD-3-Clause
9 */
10
11 package org.eclipse.jgit.util.time;
12
13 import java.time.Duration;
14
15 /**
16 * A provider of time.
17 * <p>
18 * Clocks should provide wall clock time, obtained from a reasonable clock
19 * source, such as the local system clock.
20 * <p>
21 * MonotonicClocks provide the following behavior, with the assertion always
22 * being true if
23 * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)} is
24 * used:
25 *
26 * <pre>
27 * MonotonicClock clk = ...;
28 * long r1;
29 * try (ProposedTimestamp t1 = clk.propose()) {
30 * r1 = t1.millis();
31 * t1.blockUntil(...);
32 * }
33 *
34 * try (ProposedTimestamp t2 = clk.propose()) {
35 * assert t2.millis() > r1;
36 * }
37 * </pre>
38 *
39 * @since 4.6
40 */
41 public interface MonotonicClock {
42 /**
43 * Obtain a timestamp close to "now".
44 * <p>
45 * Proposed times are close to "now", but may not yet be certainly in the
46 * past. This allows the calling thread to interleave other useful work
47 * while waiting for the clock instance to create an assurance it will never
48 * in the future propose a time earlier than the returned time.
49 * <p>
50 * A hypothetical implementation could read the local system clock (managed
51 * by NTP) and return that proposal, concurrently sending network messages
52 * to closely collaborating peers in the same cluster to also ensure their
53 * system clocks are ahead of this time. In such an implementation the
54 * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)}
55 * method would wait for replies from the peers indicating their own system
56 * clocks have moved past the proposed time.
57 *
58 * @return a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object.
59 */
60 ProposedTimestamp propose();
61 }