java.lang.Object
net.i2p.router.message.OutboundCache
public class OutboundCacheextends Object
Helper cache manager for outbound message optimization in OCMOSJ.

This class maintains several caches to optimize outbound message routing and delivery:

  • LeaseSet cache - minimizes overhead by reusing our own LeaseSet.
  • Lease cache - persists sending to the same lease to reduce out-of-order delivery.
  • Tunnel caches - caches outbound tunnels per destination to stabilize delivery paths.
  • Last reply request cache - ensures periodic replies to detect failed tunnels.
  • Multihomed cache - tracks LeaseSets for multihomed routers.

All caches use ConcurrentHashMap with tuned initial capacity, load factor, and concurrency level to allow safe concurrent access and high throughput with low contention. Tunnel caches have been converted from HashMaps with explicit synchronization to ConcurrentHashMaps for consistent concurrency management without external locking.

Cache cleaning occurs periodically with a configurable interval, removing expired entries to balance memory use and cache freshness.

  • Field Details

    • tunnelCache

      final ConcurrentHashMap<OutboundCache.HashPair, TunnelInfo> tunnelCache
      Cache for outbound tunnels per source-destination pair. Maintains consistent outbound tunnel usage to optimize streaming performance. Uses ConcurrentHashMap for thread safety and high concurrency.

    • backloggedTunnelCache

      final ConcurrentHashMap<OutboundCache.HashPair, TunnelInfo> backloggedTunnelCache
      Cache for backlogged tunnels per source-destination pair. Also uses ConcurrentHashMap for consistency and concurrency.

    • stalledTunnelCache

      final ConcurrentHashMap<OutboundCache.HashPair, TunnelInfo> stalledTunnelCache
      Cache for tunnels set aside because the stream to that destination stalled. Held apart from tunnelCache so the pair reselects, and drained with the backlogged cache so an entry cannot pin a dead tunnel. Purely advisory: the caller still returns a tunnel when every candidate is here.

    • tunnelStartTime

      final ConcurrentHashMap<OutboundCache.HashPair, Long> tunnelStartTime
      Tracks when each tunnel was first selected for a source-destination pair, to prevent rapid tunnel switching that causes out-of-order delivery and unnecessary NACKs in the streaming layer.

    • leaseSetCache

      final ConcurrentHashMap<OutboundCache.HashPair, LeaseSet> leaseSetCache
      LeaseSet cache keyed by source-destination pairs. Controls when to bundle our own LeaseSet to reduce overhead on repeated communications.

    • leaseCache

      final ConcurrentHashMap<OutboundCache.HashPair, Lease> leaseCache
      Lease cache keyed by source-destination pairs. Ensures persistent use of the same inbound lease to minimize out-of-order delivery.

    • lastReplyRequestCache

      final ConcurrentHashMap<OutboundCache.HashPair, Long> lastReplyRequestCache
      Cache to track the last reply request time per source-destination pair. Used to detect and recover from failed tunnels.

    • multihomedCache

      public final ConcurrentHashMap<Hash,LeaseSet> multihomedCache
      Cache for LeaseSets associated with multihomed routers or hosted destinations.

    • lsFailCooldown

      final ConcurrentHashMap<Hash,Long> lsFailCooldown
      Per-destination cooldown timestamps (epoch ms) after a failed LeaseSet lookup. Gates rapid-fire sends to destinations whose LS is missing or negatively cached. Entries are cleaned by OCMOSJCacheCleaner.

    • LS_FAIL_COOLDOWN_MS

      static final long LS_FAIL_COOLDOWN_MS
      Cooldown period (ms) after a failed LS lookup before another send is attempted to the same destination. Prevents message floods to unreachable destinations.
      See Also:

    • TRANSIENT_GAP_GRACE_MS

      static final long TRANSIENT_GAP_GRACE_MS
      A destination whose LeaseSet was valid within this window is treated as "transiently unreachable", not confirmed dead, so a missing local copy must not hard-fail sends for long: lookups keep being re-probed (see shouldSkipLeaseSetSend(Long, long, Long, Long, long, long)).
      See Also:

    • LS_PROBE_INTERVAL_MS

      static final long LS_PROBE_INTERVAL_MS
      Minimum gap between real (negative-cache-clearing) LeaseSet lookups for a destination whose LeaseSet was valid recently. Deduplicates concurrent sends while still allowing one recovery probe per window.
      See Also:

    • lsLastValid

      final ConcurrentHashMap<Hash,Long> lsLastValid
      Timestamp (epoch ms) when a valid LeaseSet for the destination was last observed locally (set on local find and on successful send). Pruned by OCMOSJCacheCleaner.

    • lsLastLookup

      final ConcurrentHashMap<Hash,Long> lsLastLookup
      Timestamp (epoch ms) when the most recent real LeaseSet lookup for the destination started. Used to deduplicate concurrent sends to a recently-valid destination that is undergoing a transient gap. Pruned by OCMOSJCacheCleaner.

    • _context

      private final RouterContext _context
      The router sending the messages.

    • CLEAN_INTERVAL

      private static final int CLEAN_INTERVAL
      How often expired tags are dropped - every 2 minutes.
      See Also:

  • Constructor Details

    • OutboundCache

      public OutboundCache(RouterContext ctx)
      Creates an OutboundCache instance and schedules periodic cache cleanup.
      Parameters:
      ctx - the router context providing environment and utilities.

  • Method Details

    • clearCaches

      void clearCaches(OutboundCache.HashPair hashPair, Lease lease, TunnelInfo inTunnel, TunnelInfo outTunnel)
      Clears cache entries related to the provided key and elements upon failure, allowing retries with fresh associations.
      Parameters:
      hashPair - the source-destination key for caches.
      lease - lease to clear from leaseCache, may be null.
      inTunnel - inbound tunnel to check for leaseSetCache invalidation, may be null.
      outTunnel - outbound tunnel to clear from tunnel caches, may be null.

    • clearAllCaches

      public void clearAllCaches()
      Clears all caches managed by this instance. Use cautiously as this impacts performance temporarily.

    • cleanLeaseSetCache

      private static void cleanLeaseSetCache(RouterContext ctx, Map<OutboundCache.HashPair, LeaseSet> tc)
      Removes expired LeaseSets from the provided cache.
      Parameters:
      ctx - the router context for current time.
      tc - the LeaseSet cache to clean.

    • cleanLeaseCache

      private static void cleanLeaseCache(Map<OutboundCache.HashPair, Lease> tc)
      Removes expired Leases from the provided cache.
      Parameters:
      tc - the Lease cache to clean.

    • cleanTunnelCache

      private static void cleanTunnelCache(RouterContext ctx, Map<OutboundCache.HashPair, TunnelInfo> tc)
      Removes invalid or expired TunnelInfo entries from the provided tunnel cache.
      Parameters:
      ctx - the router context for tunnel validation.
      tc - the TunnelInfo cache to clean.

    • cleanReplyCache

      private static void cleanReplyCache(RouterContext ctx, Map<OutboundCache.HashPair, Long> tc)
      Removes stale entries from the last reply request cache. Entries older than CLEAN_INTERVAL are purged.
      Parameters:
      ctx - the router context for current time.
      tc - the last reply request cache to clean.

    • cleanMultihomedCache

      private static void cleanMultihomedCache(RouterContext ctx, Map<Hash,LeaseSet> mc)
      Removes expired LeaseSets from the multihomed cache.
      Parameters:
      ctx - the router context for current time.
      mc - the multihomed cache to clean.

    • cleanLsFailCooldown

      private static void cleanLsFailCooldown(RouterContext ctx, Map<Hash,Long> cc)
      Removes expired LS fail cooldown entries.
      Parameters:
      ctx - the router context for current time.
      cc - the cooldown cache to clean.

    • pickDistinctTunnel

      static TunnelInfo pickDistinctTunnel(TunnelInfo old, List<TunnelInfo> candidates, Random rnd)
      Choose the outbound tunnel for a fresh connection, preferring a candidate different from the one used by the previous connection to the same destination. Called by OutboundClientMessageOneShotJob on the first message of a new stream (streaming SYN carrying the fresh-connection marker), so an HTTP/protocol retry does not ride the same tunnel that stalled the prior connection.

      This is pure decision logic - identity comparison only, no router context - extracted so the rotation behaviour is unit-testable.

      Parameters:
      old - the outbound tunnel used by the previous connection, or null
      candidates - pool picks gathered for this rotation, never null; may be empty when no tunnels are currently available
      rnd - randomness source for choosing among several distinct tunnels
      Returns:
      a candidate distinct from old when one exists, otherwise old unchanged, so rotation is best-effort and never blocks or drops a connection

    • shouldSkipLeaseSetSend

      static boolean shouldSkipLeaseSetSend(Long cooldownEnd, long now, Long lastValid, Long lastLookup, long transientGraceMs, long probeIntervalMs)
      Decide whether a send to a destination whose LeaseSet was not found locally should be skipped without performing a lookup.

      Failure can be confirmed or transient. A destination whose LeaseSet was valid within transientGraceMs is a transient gap: skipping must only deduplicate concurrent sends (one real probe every probeIntervalMs), never suppress the recovery search itself. A destination with no recent validity is treated as confirmed-dead and the full cooldown fast-fail applies.

      Parameters:
      cooldownEnd - end time of the fail cooldown, or null if none (epoch ms)
      now - current time in ms
      lastValid - last time a valid LeaseSet was observed, or null (epoch ms)
      lastLookup - last time a real lookup started, or null (epoch ms)
      transientGraceMs - treat as transient gap if now - lastValid <= this
      probeIntervalMs - minimum gap between real lookups for a transient gap
      Returns:
      true if the send should be skipped (dieFatal), false to probe

    • cleanLsLastValid

      private static void cleanLsLastValid(RouterContext ctx, Map<Hash,Long> mc)
      Prunes last-valid timestamps older than the transient-gap grace window plus one cleanup interval (so a two-minute slack is kept).
      Parameters:
      ctx - the router context for current time.
      mc - the last-valid cache to clean.

    • cleanLsLastLookup

      private static void cleanLsLastLookup(RouterContext ctx, Map<Hash,Long> mc)
      Prunes last-lookup timestamps older than two probe intervals.
      Parameters:
      ctx - the router context for current time.
      mc - the last-lookup cache to clean.