1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 package org.apache.hc.client5.http.impl.classic; 28 29 import org.apache.hc.client5.http.HttpRoute; 30 import org.apache.hc.client5.http.classic.BackoffManager; 31 import org.apache.hc.core5.pool.ConnPoolControl; 32 import org.apache.hc.core5.util.Args; 33 import org.apache.hc.core5.util.TimeValue; 34 import org.slf4j.Logger; 35 import org.slf4j.LoggerFactory; 36 37 import java.time.Instant; 38 import java.time.temporal.ChronoUnit; 39 import java.util.Map; 40 import java.util.concurrent.ConcurrentHashMap; 41 import java.util.concurrent.atomic.AtomicInteger; 42 import java.util.concurrent.atomic.AtomicReference; 43 44 /** 45 * AbstractBackoff is an abstract class that provides a common implementation for managing 46 * backoff behavior in HttpClient connection pool. Subclasses should implement the specific 47 * backoff algorithms by overriding the abstract methods. 48 * <p> 49 * This class provides common functionality for maintaining the route-wise backoff and probe 50 * timestamps, as well as the cool-down period for each backoff attempt. 51 * <p> 52 * It also contains the basic structure of the backOff and probe methods, which use the route-wise 53 * timestamps to determine if the backoff or probe should be applied, and then call the specific 54 * algorithm implementation for calculating the new pool size. 55 * 56 * @since 5.3 57 */ 58 public abstract class AbstractBackoff implements BackoffManager { 59 60 61 private static final Logger LOG = LoggerFactory.getLogger(AbstractBackoff.class); 62 63 /** 64 * Connection pool control responsible for managing the maximum number of connections per HTTP route. 65 */ 66 private final ConnPoolControl<HttpRoute> connPerRoute; 67 68 /** 69 * A map that stores the last probe timestamp for each HTTP route. 70 */ 71 private final Map<HttpRoute, Instant> lastRouteProbes; 72 73 /** 74 * A map that stores the last backoff timestamp for each HTTP route. 75 */ 76 private final Map<HttpRoute, Instant> lastRouteBackoffs; 77 78 /** 79 * The cool-down period after which the backoff or probe process can be performed again. 80 */ 81 private final AtomicReference<TimeValue> coolDown = new AtomicReference<>(TimeValue.ofSeconds(5L)); 82 83 /** 84 * The growth rate used in the exponential backoff algorithm. 85 */ 86 private final AtomicReference<Double> backoffFactor = new AtomicReference<>(0.5); 87 88 /** 89 * The per-host connection cap, as defined in RFC 2616 sec 8.1.4. 90 */ 91 private final AtomicInteger cap = new AtomicInteger(2); 92 93 /** 94 * The number of time intervals used in the exponential backoff algorithm. 95 */ 96 private final AtomicInteger timeInterval = new AtomicInteger(0); 97 98 /** 99 * Constructs a new ExponentialBackoffManager with the specified connection pool control. 100 * 101 * @param connPerRoute the connection pool control to be used for managing connections 102 * @throws IllegalArgumentException if connPerRoute is null 103 */ 104 public AbstractBackoff(final ConnPoolControl<HttpRoute> connPerRoute) { 105 this.connPerRoute = Args.notNull(connPerRoute, "Connection pool control"); 106 this.lastRouteProbes = new ConcurrentHashMap<>(); 107 this.lastRouteBackoffs = new ConcurrentHashMap<>(); 108 } 109 110 /** 111 * Reduces the number of maximum allowed connections for the specified route based on the exponential backoff algorithm. 112 * 113 * @param route the HttpRoute for which the backoff needs to be applied 114 */ 115 @Override 116 public void backOff(final HttpRoute route) { 117 final int curr = connPerRoute.getMaxPerRoute(route); 118 final Instant now = Instant.now(); 119 120 lastRouteBackoffs.compute(route, (r, lastUpdate) -> { 121 if (lastUpdate == null || now.isAfter(lastUpdate.plus(coolDown.get().toMilliseconds(), ChronoUnit.MILLIS))) { 122 final int backedOffPoolSize = getBackedOffPoolSize(curr); // Exponential backoff 123 connPerRoute.setMaxPerRoute(route, backedOffPoolSize); 124 if (LOG.isDebugEnabled()) { 125 LOG.debug("Backoff applied for route: {}, new max connections: {}", route, connPerRoute.getMaxPerRoute(route)); 126 } 127 return now; 128 } 129 return lastUpdate; 130 }); 131 } 132 133 134 /** 135 * Calculates the new pool size after applying the exponential backoff algorithm. 136 * The new pool size is calculated using the formula: floor(curr / (1 + growthRate) ^ t), 137 * where curr is the current pool size, growthRate is the exponential growth rate, and t is the time interval. 138 * 139 * @param curr the current pool size 140 * @return the new pool size after applying the backoff 141 */ 142 protected abstract int getBackedOffPoolSize(int curr); 143 144 145 /** 146 * Increases the number of maximum allowed connections for the specified route after a successful connection has been established. 147 * 148 * @param route the HttpRoute for which the probe needs to be applied 149 */ 150 @Override 151 public void probe(final HttpRoute route) { 152 final int curr = connPerRoute.getMaxPerRoute(route); 153 final int max = (curr >= cap.get()) ? cap.get() : curr + 1; 154 final Instant now = Instant.now(); 155 156 lastRouteProbes.compute(route, (r, lastProbe) -> { 157 if (lastProbe == null || now.isAfter(lastProbe.plus(coolDown.get().toMilliseconds(), ChronoUnit.MILLIS))) { 158 final Instant lastBackoff = lastRouteBackoffs.get(r); 159 if (lastBackoff == null || now.isAfter(lastBackoff.plus(coolDown.get().toMilliseconds(), ChronoUnit.MILLIS))) { 160 connPerRoute.setMaxPerRoute(route, max); 161 if (LOG.isDebugEnabled()) { 162 LOG.info("Probe applied for route: {}, new max connections: {}", route, connPerRoute.getMaxPerRoute(route)); 163 } 164 timeInterval.set(0); // Reset the time interval 165 return now; 166 } 167 } 168 return lastProbe; 169 }); 170 } 171 172 /** 173 * Retrieves the last update timestamp for the specified route from the provided updates map. 174 * 175 * @param updates the map containing update timestamps for HttpRoutes 176 * @param route the HttpRoute for which the last update timestamp is needed 177 * @return the last update timestamp for the specified route or 0L if not present in the map 178 */ 179 public long getLastUpdate(final Map<HttpRoute, Long> updates, final HttpRoute route) { 180 return updates.getOrDefault(route, 0L); 181 } 182 183 /** 184 * Sets the per-host connection cap. 185 * 186 * @param cap the per-host connection cap to be set 187 * @throws IllegalArgumentException if the cap is not positive 188 */ 189 public void setPerHostConnectionCap(final int cap) { 190 Args.positive(cap, "Per host connection cap"); 191 this.cap.set(cap); 192 } 193 194 /** 195 * Sets the backoff factor for the backoff algorithm. 196 * The backoff factor should be a value between 0.0 and 1.0. 197 * The specific implementation of how the backoff factor is used should be provided by subclasses. 198 * 199 * @param d the backoff factor to be set 200 */ 201 abstract void setBackoffFactor(final double d); 202 203 204 /** 205 * Sets the cool-down time value for adjustments in pool sizes for a given host. This time value 206 * allows enough time for the adjustments to take effect before further adjustments are made. 207 * The cool-down time value must be positive and not null. 208 * 209 * @param coolDown the TimeValue representing the cool-down period between adjustments 210 * @throws IllegalArgumentException if the provided cool-down time value is null or non-positive 211 */ 212 213 public void setCoolDown(final TimeValue coolDown) { 214 Args.notNull(coolDown, "Cool down time value cannot be null"); 215 Args.positive(coolDown.getDuration(), "coolDown"); 216 this.coolDown.set(coolDown); 217 } 218 219 /** 220 * Returns the connection pool control for managing the maximum number of connections per route. 221 * 222 * @return the connection pool control instance 223 */ 224 protected ConnPoolControl<HttpRoute> getConnPerRoute() { 225 return connPerRoute; 226 } 227 228 /** 229 * Returns the map containing the last probe times for each HttpRoute. 230 * 231 * @return the map of HttpRoute to Instant representing the last probe times 232 */ 233 protected Map<HttpRoute, Instant> getLastRouteProbes() { 234 return lastRouteProbes; 235 } 236 237 /** 238 * Returns the map containing the last backoff times for each HttpRoute. 239 * 240 * @return the map of HttpRoute to Instant representing the last backoff times 241 */ 242 protected Map<HttpRoute, Instant> getLastRouteBackoffs() { 243 return lastRouteBackoffs; 244 } 245 246 /** 247 * Returns the cool down period between backoff and probe operations as an AtomicReference of TimeValue. 248 * 249 * @return the AtomicReference containing the cool down period 250 */ 251 protected AtomicReference<TimeValue> getCoolDown() { 252 return coolDown; 253 } 254 255 /** 256 * Returns the backoff factor as an AtomicReference of Double. 257 * 258 * @return the AtomicReference containing the backoff factor 259 */ 260 protected AtomicReference<Double> getBackoffFactor() { 261 return backoffFactor; 262 } 263 264 /** 265 * Returns the cap on the maximum number of connections per route as an AtomicInteger. 266 * 267 * @return the AtomicInteger containing the cap value 268 */ 269 protected AtomicInteger getCap() { 270 return cap; 271 } 272 273 /** 274 * Returns the time interval between backoff and probe operations as an AtomicInteger. 275 * 276 * @return the AtomicInteger containing the time interval 277 */ 278 protected AtomicInteger getTimeInterval() { 279 return timeInterval; 280 } 281 }