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 package ch.qos.logback.core.util;
15
16 import java.util.concurrent.atomic.AtomicInteger;
17 import java.util.concurrent.atomic.AtomicLong;
18
19 /**
20 * An {@link InvocationGate} that allows a fixed number of successive callers to
21 * proceed, then enforces a lull of a fixed {@link Duration}.
22 * <p>
23 * Callers on a hot path use {@link #isTooSoon(long)} to decide whether to skip a
24 * costly operation. Up to {@linkplain #batchSize N} invocations may receive
25 * {@code false} (proceed) in succession. After the N-th success, the gate enters
26 * a lull of {@linkplain #increment increment} milliseconds during which all
27 * callers receive {@code true} (skip). When the lull ends, another batch of N
28 * is available.
29 * </p>
30 * <p>
31 * This extends the idea of {@link FixedIntervalInvocationGate} (at most one
32 * success per interval) to batches of size N. Token accounting and the lull
33 * deadline use atomics so concurrent callers share one batch.
34 * </p>
35 *
36 * @author Ceki Gülcü
37 * @since 1.6.3
38 * @see InvocationGate
39 * @see FixedIntervalInvocationGate
40 */
41 public class BatchedFixedIntervalInvocationGate implements InvocationGate {
42
43 /**
44 * Default batch size: number of successive allowed passages before a lull.
45 */
46 public static final int DEFAULT_BATCH_SIZE = 4;
47
48 /**
49 * Default lull duration after a batch is exhausted (same as
50 * {@link FixedIntervalInvocationGate#DEFAULT_INCREMENT}).
51 */
52 public static final Duration DEFAULT_INCREMENT = FixedIntervalInvocationGate.DEFAULT_INCREMENT;
53
54 /**
55 * Number of successive allowed invocations per open batch.
56 */
57 final int batchSize;
58
59 /**
60 * Duration of the lull after a batch is exhausted.
61 */
62 final Duration increment;
63
64 /**
65 * Remaining tokens in the current batch. Re-armed to {@link #batchSize}
66 * when the last token of a batch is taken (the lull deadline is set first).
67 */
68 final AtomicInteger remaining;
69
70 /**
71 * Earliest time (milliseconds since the epoch) at which a new batch may be
72 * used. While {@code currentTime} is strictly less than this value, the
73 * gate is in lull and all callers are too soon.
74 */
75 final AtomicLong atomicNext = new AtomicLong(0);
76
77 /**
78 * Creates a gate with {@link #DEFAULT_BATCH_SIZE} and
79 * {@link #DEFAULT_INCREMENT}.
80 */
81 public BatchedFixedIntervalInvocationGate() {
82 this(DEFAULT_BATCH_SIZE, DEFAULT_INCREMENT);
83 }
84
85 /**
86 * Creates a gate with the given batch size and {@link #DEFAULT_INCREMENT}.
87 *
88 * @param batchSize number of successive allowed invocations per batch; must
89 * be at least 1
90 */
91 public BatchedFixedIntervalInvocationGate(int batchSize) {
92 this(batchSize, DEFAULT_INCREMENT);
93 }
94
95 /**
96 * Creates a gate that allows {@code batchSize} successive passages, then
97 * lulls for {@code anIncrement}.
98 *
99 * @param batchSize number of successive allowed invocations per batch;
100 * must be at least 1
101 * @param anIncrement lull duration after a batch is exhausted; must not be
102 * {@code null}
103 */
104 public BatchedFixedIntervalInvocationGate(int batchSize, Duration anIncrement) {
105 if (batchSize < 1) {
106 throw new IllegalArgumentException("batchSize must be at least 1, was " + batchSize);
107 }
108 if (anIncrement == null) {
109 throw new IllegalArgumentException("increment must not be null");
110 }
111 this.batchSize = batchSize;
112 this.increment = anIncrement;
113 this.remaining = new AtomicInteger(batchSize);
114 }
115
116 /**
117 * Returns {@code true} if the caller should skip further work; {@code false}
118 * if this call is allowed to proceed.
119 * <p>
120 * If {@code currentTime} is {@link InvocationGate#TIME_UNAVAILABLE}
121 * ({@code -1}), returns {@code false} so work can still run when the clock
122 * is unavailable.
123 * </p>
124 * <p>
125 * During a lull ({@code currentTime} before the next open time), returns
126 * {@code true}. Otherwise tries to consume one batch token. The first
127 * {@code batchSize} successful consumptions return {@code false}. The
128 * caller that takes the last token starts a lull of {@link #increment} and
129 * re-arms the batch for after the lull.
130 * </p>
131 *
132 * @param currentTime current time in milliseconds, or
133 * {@link InvocationGate#TIME_UNAVAILABLE} if unknown
134 * @return {@code true} if further work should be skipped; {@code false} if
135 * the caller may proceed
136 */
137 @Override
138 public boolean isTooSoon(long currentTime) {
139 if (currentTime == -1) {
140 return false;
141 }
142
143 if (currentTime < atomicNext.get()) {
144 return true;
145 }
146
147 while (true) {
148 int left = remaining.get();
149 if (left <= 0) {
150 // Last token already taken; lull is being established or in force.
151 return true;
152 }
153 if (remaining.compareAndSet(left, left - 1)) {
154 if (left == 1) {
155 // Order matters: set lull deadline before re-arming tokens so
156 // concurrent callers see the lull and do not drain the new batch.
157 atomicNext.set(currentTime + increment.getMilliseconds());
158 remaining.set(batchSize);
159 }
160 return false;
161 }
162 }
163 }
164 }