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)

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.
`(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) 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 auto-computed default.
`(package private) static long`	`getLeaseSetBuildMinInterval(RouterContext ctx)` LeaseSet build minimum interval from config or default (2 minutes).
`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.
`(package private) int`	`getTunnelCount()` duplicate of size(), let's pick one
`(package private) static int`	`getTunnelLifetime(RouterContext ctx)` Tunnel lifetime from config or default (10 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()` Return a list of tunnels in the pool
`protected LeaseSet`	`locked_buildNewLeaseSet()` Build a leaseSet with the required tunnels that aren't about to expire.
`(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) 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()` noop for outbound and exploratory
`(package private) void`	`refreshLeaseSet(boolean force)` Refresh the LeaseSet, throttled to prevent flooding but not on initial creation.
`(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.
`(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) void`	`shutdown()` Shut down the pool and clean up resources.
`int`	`size()` duplicate of getTunnelCount(), let's pick one
`(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()` toString.
`(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
- 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.
    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)
  - 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
  - getInboundTunnelsAsLeaseSet
```
LeaseSet getInboundTunnelsAsLeaseSet()
```
    Build and return current LeaseSet from our tunnels. Used by TunnelPoolManager to validate NetDB has current data.
    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 auto-computed default. Lease end dates in published LeaseSets are capped to this value from now, so peers re-fetch our LeaseSet sooner when this is set shorter than the tunnel lifetime. The tunnel itself continues to process messages; only the cached LeaseSet on the requesting side expires earlier, triggering a re-fetch. The default is auto-computed as (i2p.netdb.republishInterval + 60s) to ensure the lease outlives the RepublishLeaseSetJob backup cycle, preventing a gap where peers have no valid LS. With the default republish interval of 5 min this gives a 6-minute lease — plenty of margin over the pool’s 2-minute refresh cycle. 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
  - 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
  - getTunnelCount
```
int getTunnelCount()
```
    duplicate of size(), let's pick one
    Returns:
    the number of tunnels in the pool
  - getTunnelLifetime
```
static int getTunnelLifetime(RouterContext ctx)
```
    Tunnel lifetime from config or default (10 minutes). Tunable via i2p.tunnel.lifetime (default: 600000).
    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 adaptive quantity throttling in getAdjustedTotalQuantity() can respond.
  - 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()
```
    Return a list of tunnels 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
  - 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.
  - 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()
```
    noop for outbound and exploratory
  - 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)
  - 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
  - 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
  - shutdown
```
void shutdown()
```
    Shut down the pool and clean up resources.
  - size
```
public int size()
```
    duplicate of getTunnelCount(), let's pick one
    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()
```
    toString.
    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

Constructor Detail

TunnelPool

Method Detail

addTunnel

buildComplete

buildFallback

cancelExcessInProgress

configureNewTunnel

ensureSufficientTunnels

formatPoolIdentity

getActiveTunnelCount

getAvgBWPerTunnel

getBuildTriesQuantityOverride

getConsecutiveBuildTimeouts

getInboundTunnelsAsLeaseSet

getInProgressCount

getLeaseMaxDuration

getLeaseSetBuildMinInterval

getLifetimeProcessed

getMaxConcurrentBuildsPerDirection

getPairedPool

getPruneEarlyExpiry

getRateName

getRefreshThrottle

getSettings

getStartupTime

getTestingTunnelCount

getTunnel

getTunnelAvgLatency

getTunnelCount

getTunnelLifetime

getTunnelPoolManager

getUsableTunnelCount

getValidTunnelCount

incrementBuildTimeout

isAlive

isExpiringSoon

isStruggling

listPending

listTunnels

locked_buildNewLeaseSet

needFallback

notifyServerPoolTestFailed

proactiveRepublishIfHealthy

pruneExcessTunnels

refreshLeaseSet

refreshLeaseSet

removeTunnel

removeTunnelSynchronous

selectTunnel

selectTunnel

setPairedPool

setSettings

shutdown

size

startup

toString

tunnelFailed

tunnelFailed