TunnelPool (Javadocs [I2P+ 2.13.0+]

java.lang.Object
- net.i2p.router.tunnel.pool.TunnelPool

Direct Known Subclasses:
AliasedTunnelPool
```
public class TunnelPool
extends Object
```
A group of tunnels for the router or a particular client, in a single direction. Public only for TunnelRenderer in router console.

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`_alive` Whether this pool is running
`protected RouterContext`	`_context` The router context
`protected Log`	`_log` The log
`(package private) static long`	`DEFAULT_PRUNE_EARLY_EXPIRY` Default early expiration time for pruned tunnels (30 seconds)
`(package private) static Comparator<TunnelInfo>`	`QUALITY_COMPARATOR` Best tunnels first for LeaseSet publication: freshest (longest remaining life) so the lease survives floodfill propagation, then lowest average latency, then fewest consecutive failures.

Constructor Summary
Constructors
Constructor and Description
TunnelPool(RouterContext ctx, TunnelPoolManager mgr, TunnelPoolSettings settings, TunnelPeerSelector sel)
Tunnel pool

Constructors
Constructor and Description
`TunnelPool(RouterContext ctx, TunnelPoolManager mgr, TunnelPoolSettings settings, TunnelPeerSelector sel)` Tunnel pool

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`addTunnel(TunnelInfo info)` Add a tunnel to the pool.
`(package private) void`	`buildComplete(PooledTunnelCreatorConfig cfg, BuildExecutor.Result result)` Remove from the _inprogress list and call addTunnel() if result is SUCCESS.
`(package private) boolean`	`buildFallback()` This will build a fallback (zero-hop) tunnel ONLY if this pool is exploratory, or the settings allow it.
`List<PooledTunnelCreatorConfig>`	`cancelExcessInProgress(int maxAllowed)` Cancel excess in-progress tunnel builds to stay within budget.
`void`	`clearFailingOnTraffic()` Clear the FAILING flag on inbound tunnels that have provably carried real traffic recently.
`(package private) PooledTunnelCreatorConfig`	`configureNewTunnel()` This only sets the peers and creation/expiration times in the configuration.
`(package private) void`	`ensureSufficientTunnels()` Ensure the pool has at least target valid tunnels, building replacements proactively when the count drops below target.
`static String`	`formatPoolIdentity(TunnelPoolSettings settings)` Format a pool identity for log messages, combining nickname and truncated hash.
`int`	`getActiveTunnelCount()` Count GOOD and TESTING (non-failed, not expired) tunnels in the pool.
`int`	`getAvgBWPerTunnel()` Average bandwidth per tunnel in the pool.
`(package private) static int`	`getBuildTriesQuantityOverride(RouterContext ctx)` Quantity override threshold from config or default (12).
`(package private) int`	`getConsecutiveBuildTimeouts()` Count of consecutive tunnel build timeouts.
`(package private) int`	`getEffectiveTarget()` The tunnel count the pool maintains, never less than 2 per direction regardless of the configured quantity, unless the pool is a ping pool or expressly zero-hop.
`LeaseSet`	`getInboundTunnelsAsLeaseSet()` Build and return current LeaseSet from our tunnels.
`int`	`getInProgressCount()` Count tunnels currently being built.
`(package private) static long`	`getLeaseMaxDuration(RouterContext ctx)` Maximum lease set lease duration from config or default (10 minutes).
`(package private) static long`	`getLeaseSetBuildMinInterval(RouterContext ctx)` LeaseSet build minimum interval from config or default (2 minutes).
`static long`	`getLeaseViabilityWindow(RouterContext ctx)` A lease counts toward a re-mint while it has at least this much remaining: three minutes covers the re-sign request, floodfill propagation, and initial connection establishment, and a tunnel closer to expiry than this is already inside the pool's proactive replacement window (BuildExecutor starts replacing GOOD tunnels 330s out), so counting it would overstate the pool's health.
`long`	`getLifetimeProcessed()` Total lifetime processed bytes for this pool.
`(package private) static int`	`getMaxConcurrentBuildsPerDirection(RouterContext ctx)` Max concurrent builds per direction from config or default (6).
`(package private) TunnelPool`	`getPairedPool()` Paired pool (inbound <-> outbound for same destination).
`(package private) long`	`getPruneEarlyExpiry()` Early expiry time for pruned tunnels.
`String`	`getRateName()` RateStat name for the bandwidth graph
`(package private) static long`	`getRefreshThrottle(RouterContext ctx)` Refresh throttle interval from config or default (2 minutes).
`TunnelPoolSettings`	`getSettings()` Pool settings.
`(package private) static long`	`getStartupTime(RouterContext ctx)` Startup suppression period from config or default (5 minutes).
`int`	`getTestingTunnelCount()` Count tunnels that have been built but not yet passed their first test.
`TunnelInfo`	`getTunnel(TunnelId gatewayId)` Tunnel by its gateway tunnel ID.
`(package private) static int`	`getTunnelAvgLatency(TunnelInfo t)` Average test latency for a tunnel.
`static int`	`getTunnelLifetime(RouterContext ctx)` Tunnel lifetime from config or default (11 minutes).
`TunnelPoolManager`	`getTunnelPoolManager()` TunnelPoolManager that owns this pool.
`(package private) int`	`getUsableTunnelCount()` Count tunnels that are usable for routing — not failed, not expired, not expiring within 5 minutes.
`int`	`getValidTunnelCount()` Count valid (non-failed, not expired) tunnels in the pool.
`(package private) void`	`incrementBuildTimeout()` Increment consecutive build timeout counter.
`boolean`	`isAlive()` Is this pool running AND either exploratory, or tracked by the client manager? A pool will be alive but not tracked after the client manager removes it but before all the tunnels have expired.
`(package private) boolean`	`isExpiringSoon(long now)` Check if the LeaseSet is expiring soon (within 1 minute).
`boolean`	`isStruggling()` Whether this pool is struggling to meet its tunnel targets.
`List<PooledTunnelCreatorConfig>`	`listPending()` List of tunnelInfo instances of tunnels currently being built.
`List<TunnelInfo>`	`listTunnels()` List of tunnels currently in the pool.
`protected LeaseSet`	`locked_buildNewLeaseSet()` Build a leaseSet with the required tunnels that aren't about to expire.
`(package private) static long`	`maxExpirationStagger(long lifetimeMs)` Upper bound for the expiration stagger: keeps lifetime plus stagger under the NetDb's 15-minute future-lease rejection boundary with a 15-second margin, and never exceeds 4 minutes.
`(package private) boolean`	`needFallback()` Do we really need more fallbacks? Used to prevent a zillion of them.
`(package private) void`	`notifyServerPoolTestFailed()` Called by TestJob when a server pool tunnel fails a test but is retained.
`(package private) static boolean`	`passesScanGates(TunnelInfo info, long now, boolean longTunnelsOnly)` Whether a pooled tunnel passes the scan eligibility gates: not failed, not over the consecutive-test-failure cap (test failures are often reply-path problems, not tunnel quality), non-expired, and — on the first pass — longer than a single hop.
`(package private) void`	`proactiveRepublishIfHealthy()` Proactively republish the LeaseSet when all tunnels are healthy (all > 5 min expiry).
`int`	`pruneExcessTunnels()` Prune excess tunnels from the pool to stay within budget.
`(package private) void`	`refreshLeaseSet()` No-op for outbound and exploratory pools.
`(package private) void`	`refreshLeaseSet(boolean force)` Refresh the LeaseSet, throttled to prevent flooding but not on initial creation.
`(package private) void`	`removeInProgress(PooledTunnelCreatorConfig cfg)` Remove a config that was never actually sent to the network (e.g.
`(package private) void`	`removeTunnel(TunnelInfo info)` Remove a tunnel from the pool.
`(package private) boolean`	`removeTunnelSynchronous(TunnelInfo info)` Synchronous tunnel removal for use during recovery or critical situations.
`void`	`requestFreshTunnelBuild()` Request new inbound tunnels so the pool holds the target count with at least `getLeaseViabilityWindow(RouterContext)` remaining.
`(package private) TunnelInfo`	`selectTunnel()` Pull a random tunnel out of the pool.
`(package private) TunnelInfo`	`selectTunnel(Hash closestTo)` Return the tunnel from the pool that is XOR-closest to the target.
`(package private) void`	`setPairedPool(TunnelPool pool)` Paired pool (inbound <-> outbound for same destination).
`(package private) void`	`setSettings(TunnelPoolSettings settings)` Update the settings for this pool
`(package private) static boolean`	`shouldWarnSelectPeersFailure(long uptime, long now, long lastWarnTime)` The selectPeers-failure WARN is rate-limited: never before `SELECT_PEERS_FAILURE_SILENCE_MS` of uptime, then at most once per `SELECT_PEERS_FAILURE_WARN_INTERVAL_MS` per pool.
`(package private) void`	`shutdown()` Shut down the pool and clean up resources.
`int`	`size()`
`(package private) void`	`startup()` Warning, this may be called more than once (without an intervening shutdown()) if the tunnel is stopped and then restarted by the client manager with the same Destination (i.e.
`String`	`toString()` Description of the pool and its settings.
`(package private) void`	`tunnelFailed(TunnelInfo cfg)` Remove tunnel and blame all peers (not necessarily equally).
`(package private) void`	`tunnelFailed(TunnelInfo cfg, Hash blamePeer)` Remove the tunnel and blame only one peer.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - _alive
```
protected volatile boolean _alive
```
    Whether this pool is running
  - _context
```
protected final RouterContext _context
```
    The router context
  - _log
```
protected final Log _log
```
    The log
  - DEFAULT_PRUNE_EARLY_EXPIRY
```
static final long DEFAULT_PRUNE_EARLY_EXPIRY
```
    Default early expiration time for pruned tunnels (30 seconds)
    See Also:
    Constant Field Values
  - QUALITY_COMPARATOR
```
static final Comparator<TunnelInfo> QUALITY_COMPARATOR
```
    Best tunnels first for LeaseSet publication: freshest (longest remaining life) so the lease survives floodfill propagation, then lowest average latency, then fewest consecutive failures.
- Constructor Detail
  - TunnelPool
```
TunnelPool(RouterContext ctx,
           TunnelPoolManager mgr,
           TunnelPoolSettings settings,
           TunnelPeerSelector sel)
```
    Tunnel pool
- Method Detail
  - addTunnel
```
protected void addTunnel(TunnelInfo info)
```
    Add a tunnel to the pool.
    Parameters:
    info - the tunnel to add
  - buildComplete
```
void buildComplete(PooledTunnelCreatorConfig cfg,
                   BuildExecutor.Result result)
```
    Remove from the _inprogress list and call addTunnel() if result is SUCCESS. Updates consecutive build timeout count.
    Parameters:
    cfg - the completed tunnel configuration
    result - the build result
  - buildFallback
```
boolean buildFallback()
```
    This will build a fallback (zero-hop) tunnel ONLY if this pool is exploratory, or the settings allow it. Matches upstream: client pools with zero-hop disabled must never fall back to 0-hop, since such a tunnel would be selected for data and would fail every connection through it.
    Returns:
    true if a fallback tunnel is built, false otherwise
  - cancelExcessInProgress
```
public List<PooledTunnelCreatorConfig> cancelExcessInProgress(int maxAllowed)
```
    Cancel excess in-progress tunnel builds to stay within budget. Cancels the newest builds first (less time invested).
    Parameters:
    maxAllowed - the maximum number of in-progress builds allowed
    Returns:
    list of cancelled tunnel configs (BuildExecutor should remove from _currentlyBuildingMap)
  - clearFailingOnTraffic
```
public void clearFailingOnTraffic()
```
    Clear the FAILING flag on inbound tunnels that have provably carried real traffic recently. Data that actually arrived through the tunnel (InboundEndpointProcessor) is end-to-end proof it works — the tunnel has not failed, so it must stay selectable and in the pool. A test failure on such a tunnel is a reply-path false negative. Inbound-only: for an outbound tunnel, dispatched bytes prove only that the gateway accepted the message, not that the tunnel delivered it — clearing on dispatch would keep a dead-tailed tunnel alive while messages vanish into it. Outbound tunnels are resolved by the test itself (deferred while active, arbiter when quiet). Only FAILING (1-2 consecutive failures) tunnels are cleared; FAILED (3+) tunnels stay removal-bound so a genuinely dead tunnel is still replaced. Combined with the test deferral while traffic is fresh, failures can only accumulate during quiet periods, so no tunnel becomes immortal. Called from the periodic pool maintenance sweep (~15s).
  - configureNewTunnel
```
PooledTunnelCreatorConfig configureNewTunnel()
```
    This only sets the peers and creation/expiration times in the configuration. For the crypto, see BuildRequestor and BuildMessageGenerator.
    Returns:
    null on failure
  - ensureSufficientTunnels
```
void ensureSufficientTunnels()
```
    Ensure the pool has at least target valid tunnels, building replacements proactively when the count drops below target. This prevents the pool from silently draining to zero, avoiding tunnel collapse cascades.
  - formatPoolIdentity
```
public static String formatPoolIdentity(TunnelPoolSettings settings)
```
    Format a pool identity for log messages, combining nickname and truncated hash. Format: "nickname/hash" if nickname set, or just "hash" if not. Globally available helper for consistent log formatting across all tunnel pool code.
    Parameters:
    settings - the pool settings
    Returns:
    formatted identity string
  - getActiveTunnelCount
```
public int getActiveTunnelCount()
```
    Count GOOD and TESTING (non-failed, not expired) tunnels in the pool. Excludes untested, failing, and failed tunnels. Includes TESTING tunnels so the pool doesn't build unnecessarily while tunnels await test results. Suitable for LeaseSet publication and UI "ready" indicators.
    Returns:
    the number of active tunnels
  - getAvgBWPerTunnel
```
public int getAvgBWPerTunnel()
```
    Average bandwidth per tunnel in the pool.
    Returns:
    average bandwidth per configured tunnel in Bps
  - getBuildTriesQuantityOverride
```
static int getBuildTriesQuantityOverride(RouterContext ctx)
```
    Quantity override threshold from config or default (12). If less than one success in this many, reduce quantity. Tunable via i2p.tunnel.buildTriesQuantityOverride (default: 12).
    Parameters:
    ctx - the router context
    Returns:
    the quantity override threshold
  - getConsecutiveBuildTimeouts
```
int getConsecutiveBuildTimeouts()
```
    Count of consecutive tunnel build timeouts.
    Returns:
    the number of consecutive build timeouts
  - getEffectiveTarget
```
int getEffectiveTarget()
```
    The tunnel count the pool maintains, never less than 2 per direction regardless of the configured quantity, unless the pool is a ping pool or expressly zero-hop.
    Returns:
    the number of tunnels to build and keep
  - getInboundTunnelsAsLeaseSet
```
public LeaseSet getInboundTunnelsAsLeaseSet()
```
    Build and return current LeaseSet from our tunnels. Used by TunnelPoolManager to validate NetDB has current data and by RepublishLeaseSetJob to re-mint local-only (unpublished) LeaseSets.
    Returns:
    current LeaseSet or null
  - getInProgressCount
```
public int getInProgressCount()
```
    Count tunnels currently being built.
    Returns:
    the number of in-progress builds
  - getLeaseMaxDuration
```
static long getLeaseMaxDuration(RouterContext ctx)
```
    Maximum lease set lease duration from config or default (10 minutes). Lease end dates in published LeaseSets are capped to this value from now, so peers re-fetch our LeaseSet sooner than the 11-minute tunnel lifetime. The tunnel itself continues to process messages; only the cached LeaseSet on the requesting side expires earlier, triggering a re-fetch. The 5-minute republish cycle re-floods (or re-mints) well before a lease dies: the re-mint floor re-signs any stored copy under 10 minutes, and the reschedule anchors each check inside the 5-minute expiry window. Set "i2p.tunnel.leaseMaxDuration" explicitly to override.
    Parameters:
    ctx - the router context
    Returns:
    the maximum lease duration in milliseconds
  - getLeaseSetBuildMinInterval
```
static long getLeaseSetBuildMinInterval(RouterContext ctx)
```
    LeaseSet build minimum interval from config or default (2 minutes). Minimum interval between LeaseSet object rebuilds, kept at or below the refresh throttle so a republish always reflects the current tunnel set (including newly built tunnels and excluding failed ones). Tunable via i2p.tunnel.leasesetBuildMinInterval (default: 120000).
    Parameters:
    ctx - the router context
    Returns:
    the LeaseSet build minimum interval in milliseconds
  - getLeaseViabilityWindow
```
public static long getLeaseViabilityWindow(RouterContext ctx)
```
    A lease counts toward a re-mint while it has at least this much remaining: three minutes covers the re-sign request, floodfill propagation, and initial connection establishment, and a tunnel closer to expiry than this is already inside the pool's proactive replacement window (BuildExecutor starts replacing GOOD tunnels 330s out), so counting it would overstate the pool's health. Shrinks toward two minutes for very short lifetimes so short-lifetime configs aren't stuck deferring forever.
    Parameters:
    ctx - the router context
    Returns:
    the lease viability window in ms
  - getLifetimeProcessed
```
public long getLifetimeProcessed()
```
    Total lifetime processed bytes for this pool.
    Returns:
    the total number of bytes processed through this pool
  - getMaxConcurrentBuildsPerDirection
```
static int getMaxConcurrentBuildsPerDirection(RouterContext ctx)
```
    Max concurrent builds per direction from config or default (6). Tunable via i2p.tunnel.maxConcurrentBuildsPerDirection (default: 6).
    Parameters:
    ctx - the router context
    Returns:
    the max concurrent builds per direction
  - getPairedPool
```
TunnelPool getPairedPool()
```
    Paired pool (inbound <-> outbound for same destination).
    Returns:
    the paired pool, or null
  - getPruneEarlyExpiry
```
long getPruneEarlyExpiry()
```
    Early expiry time for pruned tunnels. Reads from property router.tunnel.pruneEarlyExpiry, or uses default (30s).
    Returns:
    early expiry time in milliseconds
  - getRateName
```
public String getRateName()
```
    RateStat name for the bandwidth graph
    Returns:
    non-null
  - getRefreshThrottle
```
static long getRefreshThrottle(RouterContext ctx)
```
    Refresh throttle interval from config or default (2 minutes). Minimum interval between LeaseSet publishes, so a failed inbound tunnel is dropped from the published LeaseSet promptly while staying under the floodfill republish budget (~6 per destination per 10 min). Tunable via i2p.tunnel.refreshThrottle (default: 120000).
    Parameters:
    ctx - the router context
    Returns:
    the refresh throttle interval in milliseconds
  - getSettings
```
public TunnelPoolSettings getSettings()
```
    Pool settings.
    Returns:
    the settings for this pool
  - getStartupTime
```
static long getStartupTime(RouterContext ctx)
```
    Startup suppression period from config or default (5 minutes). Tunable via i2p.tunnel.startupTime (default: 300000).
    Parameters:
    ctx - the router context
    Returns:
    the startup time in milliseconds
  - getTestingTunnelCount
```
public int getTestingTunnelCount()
```
    Count tunnels that have been built but not yet passed their first test. Excludes previously-GOOD (FAILING), FAILED, and definitely-failed tunnels. These are treated as "in progress" for replacement accounting and UI display.
    Returns:
    the number of testing tunnels
  - getTunnel
```
public TunnelInfo getTunnel(TunnelId gatewayId)
```
    Tunnel by its gateway tunnel ID.
    Parameters:
    gatewayId - for inbound, the GW rcv tunnel ID; for outbound, the GW send tunnel ID.
    Returns:
    the tunnel with the matching gateway ID, or null if not found
  - getTunnelAvgLatency
```
static int getTunnelAvgLatency(TunnelInfo t)
```
    Average test latency for a tunnel.
    Parameters:
    t - the tunnel to query
    Returns:
    average test latency in ms for the tunnel, or -1 if unknown
  - getTunnelLifetime
```
public static int getTunnelLifetime(RouterContext ctx)
```
    Tunnel lifetime from config or default (11 minutes). Longer than stock so a pool holds overlapping tunnel generations, giving the LeaseSet re-mint more leases to choose from at any moment. Tunable via i2p.tunnel.lifetime (default: 660000).
    Parameters:
    ctx - the router context
    Returns:
    the tunnel lifetime in milliseconds
  - getTunnelPoolManager
```
public TunnelPoolManager getTunnelPoolManager()
```
    TunnelPoolManager that owns this pool.
    Returns:
    non-null
  - getUsableTunnelCount
```
int getUsableTunnelCount()
```
    Count tunnels that are usable for routing — not failed, not expired, not expiring within 5 minutes. Used by the EMERGENCY balance check so zombie tunnels don't skew the comparison.
    Returns:
    the number of usable tunnels
  - getValidTunnelCount
```
public int getValidTunnelCount()
```
    Count valid (non-failed, not expired) tunnels in the pool. Includes untested and testing tunnels — suitable for exploratory pools and build management.
    Returns:
    the number of valid tunnels
  - incrementBuildTimeout
```
void incrementBuildTimeout()
```
    Increment consecutive build timeout counter. Called by BuildExecutor for first-hop failures (OTHER_FAILURE with buildTime >= 1000ms) so the pool's build-health checks can respond to sustained first-hop failures.
  - isAlive
```
public boolean isAlive()
```
    Is this pool running AND either exploratory, or tracked by the client manager? A pool will be alive but not tracked after the client manager removes it but before all the tunnels have expired.
    Returns:
    true if the pool is alive and should be tracked
  - isExpiringSoon
```
boolean isExpiringSoon(long now)
```
    Check if the LeaseSet is expiring soon (within 1 minute).
    Parameters:
    now - current time
    Returns:
    true if refresh should be forced
  - isStruggling
```
public boolean isStruggling()
```
    Whether this pool is struggling to meet its tunnel targets. Returns true if this pool can't meet its published LeaseSet target or has fewer active tunnels than the configured quantity. Used by ClientPeerSelector to relax the cross-tunnel peer diversity constraint when the pool is starved for build candidates.
    Returns:
    true if the pool is struggling
  - listPending
```
public List<PooledTunnelCreatorConfig> listPending()
```
    List of tunnelInfo instances of tunnels currently being built.
    Returns:
    the list of tunnels currently being built
  - listTunnels
```
public List<TunnelInfo> listTunnels()
```
    List of tunnels currently in the pool.
    Returns:
    a copy of the list of TunnelInfo objects
  - locked_buildNewLeaseSet
```
protected LeaseSet locked_buildNewLeaseSet()
```
    Build a leaseSet with the required tunnels that aren't about to expire. Caller must hold _tunnelsLock. The returned LeaseSet will be incomplete; it will not have the destination set and will not be signed. Only the leases will be included.
    Returns:
    null on failure
  - maxExpirationStagger
```
static long maxExpirationStagger(long lifetimeMs)
```
    Upper bound for the expiration stagger: keeps lifetime plus stagger under the NetDb's 15-minute future-lease rejection boundary with a 15-second margin, and never exceeds 4 minutes.
    Parameters:
    lifetimeMs - the configured tunnel lifetime in ms
    Returns:
    the maximum stagger in ms, 0 when the lifetime alone reaches the boundary
  - needFallback
```
boolean needFallback()
```
    Do we really need more fallbacks? Used to prevent a zillion of them. Does not check config, only call if config allows zero hop.
    Returns:
    true if more fallback tunnels are needed
  - notifyServerPoolTestFailed
```
void notifyServerPoolTestFailed()
```
    Called by TestJob when a server pool tunnel fails a test but is retained. Schedules a deferred republish to batch any additional failures within the 10s debounce window rather than publishing an emergency LeaseSet on every single failure.
  - passesScanGates
```
static boolean passesScanGates(TunnelInfo info,
                               long now,
                               boolean longTunnelsOnly)
```
    Whether a pooled tunnel passes the scan eligibility gates: not failed, not over the consecutive-test-failure cap (test failures are often reply-path problems, not tunnel quality), non-expired, and — on the first pass — longer than a single hop. Pure decision — no side effects.
    Parameters:
    info - the candidate tunnel
    now - current time in ms
    longTunnelsOnly - first-pass mode (zero-hop-avoiding pools): long tunnels only
    Returns:
    whether the tunnel is a scan candidate
  - proactiveRepublishIfHealthy
```
void proactiveRepublishIfHealthy()
```
    Proactively republish the LeaseSet when all tunnels are healthy (all > 5 min expiry). This ensures the LeaseSet always has fresh lifetime and prevents orphaned LeaseSets where the LeaseSet is technically valid but all leases have expired. Unlike refreshLeaseSet() which republishes when tunnels are EXPIRING SOON, this republishes when tunnels are ALL HEALTHY to reset the LeaseSet lifetime.
  - pruneExcessTunnels
```
public int pruneExcessTunnels()
```
    Prune excess tunnels from the pool to stay within budget. Uses ExpireJob.scheduleExpiration() for budget-based pruning instead of direct removal.
    Returns:
    number of tunnels marked for removal
  - refreshLeaseSet
```
void refreshLeaseSet()
```
    No-op for outbound and exploratory pools.
  - refreshLeaseSet
```
void refreshLeaseSet(boolean force)
```
    Refresh the LeaseSet, throttled to prevent flooding but not on initial creation.
    Parameters:
    force - if true, bypass throttle (for critical refresh when below minimum or near expiry)
  - removeInProgress
```
void removeInProgress(PooledTunnelCreatorConfig cfg)
```
    Remove a config that was never actually sent to the network (e.g. a build skipped because the first-hop peer already had a build in flight). Unlike buildComplete(), no result accounting, peer cooldowns, or profile updates occur; the pool's deficit logic will simply request the tunnel again later.
    Parameters:
    cfg - the config to remove from the in-progress list
  - removeTunnel
```
void removeTunnel(TunnelInfo info)
```
    Remove a tunnel from the pool.
    Parameters:
    info - the tunnel to remove
  - removeTunnelSynchronous
```
boolean removeTunnelSynchronous(TunnelInfo info)
```
    Synchronous tunnel removal for use during recovery or critical situations. This removes the tunnel and ensures a new LeaseSet is published BEFORE returning, preventing client connection failures during recovery.
    Parameters:
    info - tunnel to remove
    Returns:
    true if removed and LeaseSet republished, false otherwise
  - requestFreshTunnelBuild
```
public void requestFreshTunnelBuild()
```
    Request new inbound tunnels so the pool holds the target count with at least getLeaseViabilityWindow(RouterContext) remaining. Called by the LeaseSet republisher before a re-mint: the normal build logic replaces tunnels only when below target or inside its proactive replacement window (BuildExecutor starts 330s out), so a pool at target with aging leases never rebuilds on its own, and a re-mint would re-sign the same near-expired leases. Respects the in-progress cap, the per-period dedup guard and pool backoff to avoid build storms.
  - selectTunnel
```
TunnelInfo selectTunnel()
```
    Pull a random tunnel out of the pool. If there are none available but the pool is configured to allow 0hop tunnels, this builds a fake one and returns it.
    Returns:
    null on failure, but it should always build and return a fallback
  - selectTunnel
```
TunnelInfo selectTunnel(Hash closestTo)
```
    Return the tunnel from the pool that is XOR-closest to the target. By using this instead of the random selectTunnel(), we force some locality in OBEP-IBGW connections to minimize those connections network-wide. Does not check for backlogged next peer. Does not return an expired tunnel.
    Parameters:
    closestTo - the hash to find the closest tunnel to
    Returns:
    the tunnel closest to the target, or null on failure
  - setPairedPool
```
void setPairedPool(TunnelPool pool)
```
    Paired pool (inbound <-> outbound for same destination).
    Parameters:
    pool - the paired pool
  - setSettings
```
void setSettings(TunnelPoolSettings settings)
```
    Update the settings for this pool
    Parameters:
    settings - the new settings, may be null
  - shouldWarnSelectPeersFailure
```
static boolean shouldWarnSelectPeersFailure(long uptime,
                                            long now,
                                            long lastWarnTime)
```
    The selectPeers-failure WARN is rate-limited: never before SELECT_PEERS_FAILURE_SILENCE_MS of uptime, then at most once per SELECT_PEERS_FAILURE_WARN_INTERVAL_MS per pool.
    Parameters:
    uptime - the router uptime in ms
    now - the current time in ms
    lastWarnTime - the last WARN time in ms
    Returns:
    true if the WARN should fire
  - shutdown
```
void shutdown()
```
    Shut down the pool and clean up resources.
  - size
```
public int size()
```
    Returns:
    the number of tunnels in the pool
  - startup
```
void startup()
```
    Warning, this may be called more than once (without an intervening shutdown()) if the tunnel is stopped and then restarted by the client manager with the same Destination (i.e. for servers or clients w/ persistent key, or restarting close-on-idle clients)
  - toString
```
public String toString()
```
    Description of the pool and its settings.
    Overrides:
    toString in class Object
  - tunnelFailed
```
void tunnelFailed(TunnelInfo cfg)
```
    Remove tunnel and blame all peers (not necessarily equally). This may be called multiple times from TestJob. Enhanced with intelligent failure analysis and recovery.
    Parameters:
    cfg - the tunnel that failed
  - tunnelFailed
```
void tunnelFailed(TunnelInfo cfg,
                  Hash blamePeer)
```
    Remove the tunnel and blame only one peer. This may be called multiple times.
    Parameters:
    cfg - the tunnel that failed
    blamePeer - the peer to blame

Class TunnelPool

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

_alive

_context

_log

DEFAULT_PRUNE_EARLY_EXPIRY

QUALITY_COMPARATOR

Constructor Detail

TunnelPool

Method Detail

addTunnel

buildComplete

buildFallback

cancelExcessInProgress

clearFailingOnTraffic

configureNewTunnel

ensureSufficientTunnels

formatPoolIdentity

getActiveTunnelCount

getAvgBWPerTunnel

getBuildTriesQuantityOverride

getConsecutiveBuildTimeouts

getEffectiveTarget

getInboundTunnelsAsLeaseSet

getInProgressCount

getLeaseMaxDuration

getLeaseSetBuildMinInterval

getLeaseViabilityWindow

getLifetimeProcessed

getMaxConcurrentBuildsPerDirection

getPairedPool

getPruneEarlyExpiry

getRateName

getRefreshThrottle

getSettings

getStartupTime

getTestingTunnelCount

getTunnel

getTunnelAvgLatency

getTunnelLifetime

getTunnelPoolManager

getUsableTunnelCount

getValidTunnelCount

incrementBuildTimeout

isAlive

isExpiringSoon

isStruggling

listPending

listTunnels

locked_buildNewLeaseSet

maxExpirationStagger

needFallback

notifyServerPoolTestFailed

passesScanGates

proactiveRepublishIfHealthy

pruneExcessTunnels

refreshLeaseSet

refreshLeaseSet

removeInProgress

removeTunnel

removeTunnelSynchronous

requestFreshTunnelBuild

selectTunnel

selectTunnel

setPairedPool

setSettings

shouldWarnSelectPeersFailure

shutdown

size

startup

toString

tunnelFailed

tunnelFailed