View Javadoc
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&uuml;lc&uuml;
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 }