1 /*
2 * Logback: the reliable, generic, fast and flexible logging framework.
3 * Copyright (C) 1999-2026, QOS.ch. All rights reserved.
4 *
5 * This program and the accompanying materials are dual-licensed under
6 * either the terms of the Eclipse Public License v2.0 as published by
7 * the Eclipse Foundation
8 *
9 * or (per the licensee's choosing)
10 *
11 * under the terms of the GNU Lesser General Public License version 2.1
12 * as published by the Free Software Foundation.
13 */
14
15 package ch.qos.logback.core.util;
16
17 import java.util.concurrent.atomic.AtomicLong;
18
19 /**
20 * A time-based {@link InvocationGate} with fixed-interval logic.
21 * <p>
22 * Callers on a hot path use {@link #isTooSoon(long)} to decide whether to skip
23 * a costly operation. At most one thread per {@linkplain #increment increment}
24 * interval is allowed to proceed (i.e. receives {@code false}); other threads
25 * in the same window receive {@code true} and should skip the work.
26 * </p>
27 * <p>
28 * Compared to {@link DefaultInvocationGate}, this implementation does not adapt
29 * a sampling mask. It only advances an atomic next-allowed timestamp by a fixed
30 * {@link Duration}.
31 * </p>
32 * <p>
33 * Typical use is size checks in rolling policies where file length is expensive
34 * relative to the logging call.
35 * </p>
36 *
37 * @author Ceki Gülcü
38 * @since 1.3.6/1.4.6 (formerly {@link SimpleInvocationGate})
39 * @see InvocationGate
40 * @see DefaultInvocationGate
41 * @see BatchedFixedIntervalInvocationGate
42 * @see ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy
43 */
44 public class FixedIntervalInvocationGate implements InvocationGate {
45
46 /**
47 * Next time (milliseconds since the epoch) at or after which a caller may be
48 * allowed to proceed. Updated with compare-and-set so that only one thread
49 * wins per interval.
50 */
51 AtomicLong atomicNext = new AtomicLong(0);
52
53 /**
54 * Minimum time between allowed invocations.
55 */
56 final Duration increment;
57
58 /**
59 * Default increment: 60 seconds.
60 */
61 final public static Duration DEFAULT_INCREMENT = Duration.buildBySeconds(60);
62
63 /**
64 * Creates a gate with {@link #DEFAULT_INCREMENT}.
65 */
66 public FixedIntervalInvocationGate() {
67 this(DEFAULT_INCREMENT);
68 }
69
70 /**
71 * Creates a gate that allows at most one successful passage per
72 * {@code anIncrement} period.
73 *
74 * @param anIncrement duration between allowed invocations; must not be
75 * {@code null}
76 */
77 public FixedIntervalInvocationGate(Duration anIncrement) {
78 this.increment = anIncrement;
79 }
80
81 /**
82 * Returns {@code true} if the caller should skip further work; {@code false}
83 * if this call is allowed to proceed.
84 * <p>
85 * If {@code currentTime} is {@link InvocationGate#TIME_UNAVAILABLE}
86 * ({@code -1}), this method returns {@code false} so the caller can still
87 * perform the work when the clock is unavailable.
88 * </p>
89 * <p>
90 * Otherwise, when {@code currentTime} is strictly before the next allowed
91 * time, the method returns {@code true} (too soon). When
92 * {@code currentTime} has reached the next allowed time, this thread tries
93 * to advance that time by {@link #increment}. On success it returns
94 * {@code false} (proceed); if another thread already advanced it, this
95 * thread returns {@code true} so that only one passage per interval is
96 * granted.
97 * </p>
98 *
99 * @param currentTime current time in milliseconds, or
100 * {@link InvocationGate#TIME_UNAVAILABLE} if unknown
101 * @return {@code true} if further work should be skipped; {@code false} if
102 * the caller may proceed
103 */
104 @Override
105 public boolean isTooSoon(long currentTime) {
106 if (currentTime == -1)
107 return false;
108
109 long localNext = atomicNext.get();
110 if (currentTime >= localNext) {
111 long next2 = currentTime + increment.getMilliseconds();
112 // if success, we were able to set the variable, otherwise some other thread beat us to it
113 boolean success = atomicNext.compareAndSet(localNext, next2);
114 // while we have crossed 'next', the other thread already returned true. There is
115 // no point in letting more than one thread per duration.
116 return !success;
117 } else {
118 return true;
119 }
120
121 }
122 }