BuildExecutor (Javadocs [I2P+ 2.13.0+]

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

All Implemented Interfaces:
Runnable
```
public class BuildExecutor
extends Object
implements Runnable
```
Single threaded controller of the tunnel creation process, spanning all tunnel pools. Essentially, this loops across the pools, sees which want to build tunnels, and fires off the necessary activities if the load allows. If nothing wants to build any tunnels, it waits for a short period before looping again (or until it is told that something changed, such as a tunnel failed, new client started up, or tunnel creation was aborted). Note that the default 11 minute tunnel expiration is assumed in here. As of 0.8.11, inbound request handling is done in a separate thread.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`(package private) static class`	`BuildExecutor.ExpiryBuckets` Immutable result of `countExpiryBuckets(List, long, boolean)`.
`(package private) static class`	`BuildExecutor.Result` Build result enumeration.

Constructor Summary
Constructors
Constructor and Description
BuildExecutor(RouterContext ctx, TunnelPoolManager mgr, GhostPeerManager ghostMgr)
Create a new BuildExecutor.

Constructors
Constructor and Description
`BuildExecutor(RouterContext ctx, TunnelPoolManager mgr, GhostPeerManager ghostMgr)` Create a new BuildExecutor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`buildComplete(PooledTunnelCreatorConfig cfg, BuildExecutor.Result result)` Handle a completed tunnel build.
`void`	`buildComplete(PooledTunnelCreatorConfig cfg, BuildExecutor.Result result, String detail)` Handle a completed tunnel build with additional detail.
`(package private) void`	`buildTunnel(PooledTunnelCreatorConfig cfg)` Build a tunnel with the given configuration.
`(package private) static Map<Hash,int[]>`	`collectPairTargets(List<TunnelPool> pools)` Collect per-direction build quantity targets for paired destinations, used by the proportional per-direction cap in calculatePairedBuilds().
`(package private) static int`	`computeUrgencyScore(int usableCount, int target)` Urgency score used to sort pools before build allocation, so a collapsed or near-collapse pool earlier in the list cannot consume build slots (or trigger the proportional cap) before an urgent pool later in the list gets any.
`(package private) void`	`cooldownFailedPeers(PooledTunnelCreatorConfig cfg)` Cool down every non-self hop of a failed build so the immediate retry selects different peers.
`(package private) static BuildExecutor.ExpiryBuckets`	`countExpiryBuckets(List<TunnelInfo> tunnels, long now, boolean allowZeroHop)` Count a pool's tunnels into cumulative expiry-window buckets.
`(package private) static boolean`	`countsAsPoolFailure(BuildExecutor.Result result)` Pool-backoff counting excludes results that are not peer failures: SUCCESS, DUP_ID (already handled), REJECT (peer said no), NO_TUNNELS (local resource condition), NO_NETDB (local netdb miss), and SKIPPED (local policy, no build dispatched).
`boolean`	`fullStats()` Check if full statistics are enabled.
`static long`	`getGoodDeficitThrottle(RouterContext ctx)` The GOOD deficit throttle interval from config or default (30s).
`static int`	`getMaxConcurrentBuilds()` The maximum number of concurrent builds allowed.
`static long`	`getPoolBackoffMs()` The pool backoff time in milliseconds.
`static int`	`getPoolFailureThreshold()` The pool failure threshold.
`(package private) static int`	`getTunnelLifetime(RouterContext ctx)` The tunnel lifetime from config, delegated to TunnelPool.
`(package private) static int`	`getTunnelTargetBuffer(RouterContext ctx)` The target build buffer from config or default (0).
`(package private) boolean`	`isPoolInBackoff(TunnelPool pool)` Check if a pool is in backoff due to consecutive build failures.
`boolean`	`isRunning()` Check if the executor is currently running.
`(package private) void`	`penalizeTimeout(PooledTunnelCreatorConfig cfg)` Penalize the peers of an expired build.
`(package private) PooledTunnelCreatorConfig`	`removeFromBuilding(long id)` This returns the PTCC up to a minute after it 'expired', thus allowing us to still use a tunnel if it was accepted, and to update peer stats.
`(package private) void`	`removePoolState(TunnelPool pool)` Remove failure state for a pool that is being removed.
`void`	`repoll()` Signal the executor to repoll for tunnel building opportunities.
`void`	`restart()` Restart the build executor, clearing recent build state.
`void`	`run()` Starts the tunnel building process in a loop and takes care of error handling.
`static void`	`setMaxConcurrentBuilds(int val)` The maximum number of concurrent builds allowed.
`static void`	`setPoolBackoffMs(long val)` The pool backoff time in milliseconds.
`static void`	`setPoolFailureThreshold(int val)` The pool failure threshold.
`void`	`shutdown()` Cannot be restarted.
`(package private) static long`	`spacingDelay(long lastPassTime, long now)` Remaining build-pass spacing in ms: 0 when the spacing floor since the last pass is satisfied, otherwise the time still left to wait.
`(package private) static void`	`trimFifo(Set<Long> ids, int max)` Trim a FIFO id set to at most `max` entries, dropping the oldest (head) entries first.
`boolean`	`wasRecentlyBuilding(long replyId)` Check if a tunnel build was recently attempted.

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

- Constructor Detail
  - BuildExecutor
```
public BuildExecutor(RouterContext ctx,
                     TunnelPoolManager mgr,
                     GhostPeerManager ghostMgr)
```
    Create a new BuildExecutor.
    Parameters:
    ctx - the router context
    mgr - the tunnel pool manager
    ghostMgr - the ghost peer manager for tracking timeouts
- Method Detail
  - buildComplete
```
public void buildComplete(PooledTunnelCreatorConfig cfg,
                          BuildExecutor.Result result)
```
    Handle a completed tunnel build.
    Parameters:
    cfg - the tunnel configuration that completed
    result - the build result (success, failure, etc.)
  - buildComplete
```
public void buildComplete(PooledTunnelCreatorConfig cfg,
                          BuildExecutor.Result result,
                          String detail)
```
    Handle a completed tunnel build with additional detail.
    Parameters:
    cfg - the tunnel configuration that completed
    result - the build result (success, failure, etc.)
    detail - additional detail on the result
  - buildTunnel
```
void buildTunnel(PooledTunnelCreatorConfig cfg)
```
    Build a tunnel with the given configuration. Burst builds to different peers freely, but never start a second build request to a first-hop peer that already has a build in flight — stacking requests on one peer floods it and makes the first build answer slower. Zero-hop tunnels build inline, unguarded.
    Parameters:
    cfg - the tunnel configuration to build
  - collectPairTargets
```
static Map<Hash,int[]> collectPairTargets(List<TunnelPool> pools)
```
    Collect per-direction build quantity targets for paired destinations, used by the proportional per-direction cap in calculatePairedBuilds(). For each destination the inbound and outbound quantities are the maxima of the quantities configured on the pools for that direction, so a pair with asymmetric quantities (e.g. 4 inbound / 2 outbound) splits the build budget proportionally instead of 50/50.
    Parameters:
    pools - pools to scan; dead pools and pools without a destination are skipped
    Returns:
    destination -> int[2] {inboundQty, outboundQty}, never null
  - computeUrgencyScore
```
static int computeUrgencyScore(int usableCount,
                               int target)
```
    Urgency score used to sort pools before build allocation, so a collapsed or near-collapse pool earlier in the list cannot consume build slots (or trigger the proportional cap) before an urgent pool later in the list gets any. Scores are tiered far apart on purpose: 0 usable tunnels (1 << 20) outrank 1-2 usable (1 << 16) which outrank any numerical deficit, so the sort order is stable regardless of configured quantities.
    Parameters:
    usableCount - current usable tunnel count of the pool
    target - minimum desired tunnel count (already clamped to >= 2)
    Returns:
    urgency score; larger sorts earlier
  - cooldownFailedPeers
```
void cooldownFailedPeers(PooledTunnelCreatorConfig cfg)
```
    Cool down every non-self hop of a failed build so the immediate retry selects different peers. Selection-scope only — entries live for TunnelPeerSelector.PEER_SELECTION_COOLDOWN_MS and both peer selectors consult this map; profile penalties are separate and, for timeouts, go to the contacted hop only via penalizeTimeout(PooledTunnelCreatorConfig).
    Parameters:
    cfg - the failed build config
  - countExpiryBuckets
```
static BuildExecutor.ExpiryBuckets countExpiryBuckets(List<TunnelInfo> tunnels,
                                                      long now,
                                                      boolean allowZeroHop)
```
    Count a pool's tunnels into cumulative expiry-window buckets. Tunnels at or below one window boundary fall into that window (and no later one), so expire30s is "expires within 30s", expire90s is "within 90s but not 30s", and so on; expireLater covers everything beyond 330s. Each bucket has a GOOD-only twin (good status and at most 1 consecutive failure) used for proactive replacement, plus aggregates: zero-hop fallback count, GOOD count and their total latency.
    Parameters:
    tunnels - tunnels of one pool, never null
    now - current time, used to compute time-to-expiry
    allowZeroHop - if false, length-1 tunnels are counted as fallbackCount and skipped; if true they are counted normally
    Returns:
    bucket counts, never null
  - countsAsPoolFailure
```
static boolean countsAsPoolFailure(BuildExecutor.Result result)
```
    Pool-backoff counting excludes results that are not peer failures: SUCCESS, DUP_ID (already handled), REJECT (peer said no), NO_TUNNELS (local resource condition), NO_NETDB (local netdb miss), and SKIPPED (local policy, no build dispatched).
    Parameters:
    result - the build result
    Returns:
    true if the result increments the pool consecutive-failure counter
  - fullStats
```
public boolean fullStats()
```
    Check if full statistics are enabled.
    Returns:
    true if full statistics are enabled
  - getGoodDeficitThrottle
```
public static long getGoodDeficitThrottle(RouterContext ctx)
```
    The GOOD deficit throttle interval from config or default (30s). Minimum time between GOOD-tunnel deficit rebuilds for non-critical pools. Tunable via i2p.tunnel.goodDeficitThrottle (default: 30000).
    Parameters:
    ctx - the router context
    Returns:
    the throttle interval in milliseconds
  - getMaxConcurrentBuilds
```
public static int getMaxConcurrentBuilds()
```
    The maximum number of concurrent builds allowed.
    Returns:
    maximum concurrent builds
  - getPoolBackoffMs
```
public static long getPoolBackoffMs()
```
    The pool backoff time in milliseconds.
    Returns:
    the backoff in ms
  - getPoolFailureThreshold
```
public static int getPoolFailureThreshold()
```
    The pool failure threshold.
    Returns:
    the threshold
  - getTunnelLifetime
```
static int getTunnelLifetime(RouterContext ctx)
```
    The tunnel lifetime from config, delegated to TunnelPool.
    Parameters:
    ctx - the router context
    Returns:
    the tunnel lifetime in milliseconds
  - getTunnelTargetBuffer
```
static int getTunnelTargetBuffer(RouterContext ctx)
```
    The target build buffer from config or default (0). Extra tunnels to maintain beyond the configured quantity. Tunable via i2p.tunnel.targetBuffer (default: 0).
    Parameters:
    ctx - the router context
    Returns:
    the target buffer count
  - isPoolInBackoff
```
boolean isPoolInBackoff(TunnelPool pool)
```
    Check if a pool is in backoff due to consecutive build failures. Uses a 12s backoff to prevent build storms while allowing recovery before expiring tunnels deplete the pool. On backoff expiry, resets the failure counter so the pool gets a fresh window of attempts. During collapse (0 usable tunnels), backoff is shortened to 4s to allow faster recovery while still preventing build storms.
    Parameters:
    pool - the tunnel pool to check
    Returns:
    true if the pool is in backoff
  - isRunning
```
public boolean isRunning()
```
    Check if the executor is currently running.
    Returns:
    true if running, false otherwise
  - penalizeTimeout
```
void penalizeTimeout(PooledTunnelCreatorConfig cfg)
```
    Penalize the peers of an expired build. Only the hop the build request was dispatched to — the gateway (peer 0) for inbound, the next hop (peer 1) for outbound, per BuildRequestor.getBuildRequestPeer(PooledTunnelCreatorConfig) — failed to deliver a reply; the other hops may never have received the request, or may be waiting downstream of a silent peer. Blaming them all shrinks the pool on innocent peers during network-wide no-reply events, so the profile penalty and ghost mark go to the contacted hop only. The per-tier expire stat and the didNotReply debug log stay per-hop for accounting and triage. Every non-self hop is additionally cooled down out of the immediate retry selection (cooldownFailedPeers(PooledTunnelCreatorConfig)), since any of them may have been the silent one.
    Parameters:
    cfg - the expired build config, non-null
  - removeFromBuilding
```
PooledTunnelCreatorConfig removeFromBuilding(long id)
```
    This returns the PTCC up to a minute after it 'expired', thus allowing us to still use a tunnel if it was accepted, and to update peer stats. This means that manager.buildComplete() could be called more than once, and a build can be failed or successful after it was timed out, which will affect the stats and profiles. But that's ok. A peer that rejects slowly gets penalized twice, for example.
    Parameters:
    id - the build message ID
    Returns:
    ptcc or null
  - removePoolState
```
void removePoolState(TunnelPool pool)
```
    Remove failure state for a pool that is being removed. Prevents unbounded growth of _poolFailureState and _lastRebuildTime across pool lifecycles.
    Parameters:
    pool - the pool to remove state for
  - repoll
```
public void repoll()
```
    Signal the executor to repoll for tunnel building opportunities.
  - restart
```
public void restart()
```
    Restart the build executor, clearing recent build state.
  - run
```
public void run()
```
    Starts the tunnel building process in a loop and takes care of error handling. Catches a specific fatal error related to Java versioning and ensures the running state is properly reset on exit.
    Specified by:
    run in interface Runnable
  - setMaxConcurrentBuilds
```
public static void setMaxConcurrentBuilds(int val)
```
    The maximum number of concurrent builds allowed.
    Parameters:
    val - the maximum concurrent builds
  - setPoolBackoffMs
```
public static void setPoolBackoffMs(long val)
```
    The pool backoff time in milliseconds.
    Parameters:
    val - the backoff in ms (1000-60000)
  - setPoolFailureThreshold
```
public static void setPoolFailureThreshold(int val)
```
    The pool failure threshold.
    Parameters:
    val - the threshold value (1-20)
  - shutdown
```
public void shutdown()
```
    Cannot be restarted.
  - spacingDelay
```
static long spacingDelay(long lastPassTime,
                         long now)
```
    Remaining build-pass spacing in ms: 0 when the spacing floor since the last pass is satisfied, otherwise the time still left to wait.
    Parameters:
    lastPassTime - the end of the last build pass in ms
    now - the current time in ms
    Returns:
    ms still to wait, 0 if the floor is met
  - trimFifo
```
static void trimFifo(Set<Long> ids,
                     int max)
```
    Trim a FIFO id set to at most max entries, dropping the oldest (head) entries first. Insertion order is preserved by the caller.
    Parameters:
    ids - the id set, held by the caller's monitor
    max - the maximum size to keep
  - wasRecentlyBuilding
```
public boolean wasRecentlyBuilding(long replyId)
```
    Check if a tunnel build was recently attempted.
    Parameters:
    replyId - the reply message ID to check
    Returns:
    true if the build was recently attempted, false otherwise

Class BuildExecutor

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BuildExecutor

Method Detail

buildComplete

buildComplete

buildTunnel

collectPairTargets

computeUrgencyScore

cooldownFailedPeers

countExpiryBuckets

countsAsPoolFailure

fullStats

getGoodDeficitThrottle

getMaxConcurrentBuilds

getPoolBackoffMs

getPoolFailureThreshold

getTunnelLifetime

getTunnelTargetBuffer

isPoolInBackoff

isRunning

penalizeTimeout

removeFromBuilding

removePoolState

repoll

restart

run

setMaxConcurrentBuilds

setPoolBackoffMs

setPoolFailureThreshold

shutdown

spacingDelay

trimFifo

wasRecentlyBuilding