TunnelDispatcher (Javadocs [I2P+ 2.13.0+]

java.lang.Object
- net.i2p.router.tunnel.TunnelDispatcher

All Implemented Interfaces:: Service

public class TunnelDispatcher
extends Object
implements Service

Handle the actual processing and forwarding of messages through the various tunnels.

  For each type of tunnel, it creates a chain of handlers, as follows:

  Following tunnels are created by us:

    Outbound Gateway > 0 hops:
       PumpedTunnelGateway
         BatchedRouterPreprocessor -> OutboundSender -> OutboundReceiver -> OutNetMessagePool

    Outbound zero-hop Gateway+Endpoint:
       TunnelGatewayZeroHop
         OutboundMessageDistributor -> OutNetMessagePool

    Inbound Endpoint > 0 hops:
       TunnelParticipant
        RouterFragmentHandler ->  InboundEndpointProcessor -> InboundMessageDistributor -> InNetMessagePool

    Inbound zero-hop Gateway+Endpoint:
       TunnelGatewayZeroHop
         InboundMessageDistributor -> InNetMessagePool


  Following tunnels are NOT created by us:

    Participant (not gateway or endpoint)
       TunnelParticipant
         HopProcessor -> OutNetMessagePool

    Outbound Endpoint > 0 hops:
       OutboundTunnelEndpoint
         RouterFragmentHandler -> HopProcessor -> OutboundMessageDistributor -> OutNetMessagePool

    Inbound Gateway > 0 hops:
       ThrottledPumpedTunnelGateway
         BatchedRouterPreprocessor -> InboundSender -> InboundGatewayReceiver -> OutNetMessagePool

Nested Class Summary
Nested Classes
Modifier and Type Class and Description
static class TunnelDispatcher.Location
Location in the tunnel for RED (Random Early Discard) logic.

Nested Classes
Modifier and Type	Class and Description
`static class`	`TunnelDispatcher.Location` Location in the tunnel for RED (Random Early Discard) logic.

Constructor Summary
Constructors
Constructor and Description
TunnelDispatcher(RouterContext ctx)
Creates a new instance of TunnelDispatcher

Constructors
Constructor and Description
`TunnelDispatcher(RouterContext ctx)` Creates a new instance of TunnelDispatcher

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`adjustPumperThreads(int value)`
`void`	`dispatch(TunnelDataMessage msg, Hash recvFrom)` Dispatch a TunnelDataMessage to the appropriate participant or endpoint
`void`	`dispatch(TunnelGatewayMessage msg)` Dispatch a TunnelGatewayMessage to the appropriate gateway
`boolean`	`dispatchOutbound(I2NPMessage msg, TunnelId outboundTunnel, Hash targetPeer)` Dispatch an outbound message through a tunnel.
`boolean`	`dispatchOutbound(I2NPMessage msg, TunnelId outboundTunnel, TunnelId targetTunnel, Hash targetPeer)` Dispatch an outbound message through a tunnel.
`void`	`freeBandwidth(int bw)` Free allocated bandwidth for a tunnel.
`int`	`getAllocatedBW()` Get the total bandwidth allocated for participating tunnels
`long`	`getLastParticipatingExpiration()` Returns the timestamp of the last participating tunnel expiration.
`static int`	`getMaxIbMsgsPerPump()`
`static int`	`getMaxObMsgsPerPump()`
`(package private) int`	`getMaxPerTunnelBandwidth(TunnelDispatcher.Location loc)` Get the max bandwidth per transit tunnel.
`TunnelId`	`getNewIBEPID()` Get a new random receive tunnel ID that isn't a duplicate
`TunnelId`	`getNewIBZeroHopID()` Get a new random receive tunnel ID that isn't a duplicate (zero hop)
`TunnelId`	`getNewOBGWID()` Get a new random send tunnel ID that isn't a duplicate
`int`	`getParticipatingCount()` Get the number of participating tunnels
`static int`	`getPumperMaxThreads()`
`static int`	`getPumperQueueCapacity()`
`static double`	`getPumperUtilization()` Get pumper pool utilization as a ratio (0.0-1.0).
`static long`	`getRequeueTime()`
`static int`	`getShareBandwidth(RouterContext ctx)` Get the current bandwidth share in KBps
`boolean`	`hasOutboundGateway(TunnelId tid)`
`boolean`	`joinInbound(TunnelCreatorConfig cfg)` We are the inbound endpoint - we created this tunnel
`boolean`	`joinInboundGateway(HopConfig cfg)` We are the inbound gateway in this tunnel, and did not create it
`boolean`	`joinOutbound(PooledTunnelCreatorConfig cfg)` We are the outbound gateway - we created this tunnel
`boolean`	`joinOutboundEndpoint(HopConfig cfg)` We are the outbound endpoint in this tunnel, and did not create it
`boolean`	`joinParticipant(HopConfig cfg)` We are a participant in this tunnel, but not as the endpoint or gateway
`List<HopConfig>`	`listParticipatingTunnels()` Get a list of participating tunnels (for console display).
`void`	`remove(HopConfig cfg)` Remove a tunnel we're participating in
`void`	`remove(TunnelCreatorConfig cfg)` Remove a tunnel we created
`void`	`removeFromExpirationQueue(HopConfig cfg)` Remove a tunnel from the expiration queue.
`static void`	`resizePumperQueue(int value)`
`void`	`restart()` Restart the TunnelDispatcher
`static void`	`setMaxIbMsgsPerPump(int val)`
`static void`	`setMaxObMsgsPerPump(int val)`
`static void`	`setPumperMaxThreads(int value)`
`static void`	`setPumperQueueCapacity(int value)`
`static void`	`setRequeueTime(long ms)`
`(package private) boolean`	`shouldDropParticipatingInboundMessage(TunnelDispatcher.Location loc, int type, int length, SyntheticREDQueue bwe)` Check if we should drop an inbound participating tunnel message.
`(package private) boolean`	`shouldDropParticipatingMessage(TunnelDispatcher.Location loc, int type, int length, SyntheticREDQueue bwe)` Implement RED (Random Early Discard) to enforce bandwidth limits.
`void`	`shutdown()` Shut down TunnelDispatcher
`void`	`startup()` Start up the TunnelDispatcher
`void`	`updateParticipatingStats(int ms)` Update stats for participating tunnels
`(package private) void`	`updateThrottleFactors()` Update cached transit throttle factors from router properties.

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

Methods inherited from interface net.i2p.router.Service
renderStatusHTML

- Constructor Detail
  - TunnelDispatcher
```
public TunnelDispatcher(RouterContext ctx)
```
    Creates a new instance of TunnelDispatcher
    Parameters:
    ctx - the router context
- Method Detail
  - adjustPumperThreads
```
public static void adjustPumperThreads(int value)
```
  - dispatch
```
public void dispatch(TunnelDataMessage msg,
                     Hash recvFrom)
```
    Dispatch a TunnelDataMessage to the appropriate participant or endpoint
  - dispatch
```
public void dispatch(TunnelGatewayMessage msg)
```
    Dispatch a TunnelGatewayMessage to the appropriate gateway
  - dispatchOutbound
```
public boolean dispatchOutbound(I2NPMessage msg,
                                TunnelId outboundTunnel,
                                Hash targetPeer)
```
    Dispatch an outbound message through a tunnel.
    Returns:
    true if the message was accepted by the tunnel gateway, false if dropped
  - dispatchOutbound
```
public boolean dispatchOutbound(I2NPMessage msg,
                                TunnelId outboundTunnel,
                                TunnelId targetTunnel,
                                Hash targetPeer)
```
    Dispatch an outbound message through a tunnel.
    Returns:
    true if the message was accepted by the tunnel gateway, false if dropped
  - freeBandwidth
```
public void freeBandwidth(int bw)
```
    Free allocated bandwidth for a tunnel. Called when dropping idle tunnels.
  - getAllocatedBW
```
public int getAllocatedBW()
```
    Get the total bandwidth allocated for participating tunnels
    Returns:
    the allocated b w
  - getLastParticipatingExpiration
```
public long getLastParticipatingExpiration()
```
    Returns the timestamp of the last participating tunnel expiration.
    Returns:
    last expiration in milliseconds since epoch, or -1 if none
  - getMaxIbMsgsPerPump
```
public static int getMaxIbMsgsPerPump()
```
  - getMaxObMsgsPerPump
```
public static int getMaxObMsgsPerPump()
```
  - getMaxPerTunnelBandwidth
```
int getMaxPerTunnelBandwidth(TunnelDispatcher.Location loc)
```
    Get the max bandwidth per transit tunnel. Scales with allocation: higher share = higher per-tunnel cap. Uses outbound bandwidth only — on floodfill routers inbound is far smaller than outbound and would create an artificial bottleneck.
  - getNewIBEPID
```
public TunnelId getNewIBEPID()
```
    Get a new random receive tunnel ID that isn't a duplicate
    Returns:
    the new i b e p i d
  - getNewIBZeroHopID
```
public TunnelId getNewIBZeroHopID()
```
    Get a new random receive tunnel ID that isn't a duplicate (zero hop)
    Returns:
    the new i b zero hop i d
  - getNewOBGWID
```
public TunnelId getNewOBGWID()
```
    Get a new random send tunnel ID that isn't a duplicate
    Returns:
    the new o b g w i d
  - getParticipatingCount
```
public int getParticipatingCount()
```
    Get the number of participating tunnels
    Returns:
    the participating count
  - getPumperMaxThreads
```
public static int getPumperMaxThreads()
```
  - getPumperQueueCapacity
```
public static int getPumperQueueCapacity()
```
  - getPumperUtilization
```
public static double getPumperUtilization()
```
    Get pumper pool utilization as a ratio (0.0-1.0). Returns NaN if not started.
    Returns:
    the pumper utilization
  - getRequeueTime
```
public static long getRequeueTime()
```
  - getShareBandwidth
```
public static int getShareBandwidth(RouterContext ctx)
```
    Get the current bandwidth share in KBps
    Returns:
    the share bandwidth
  - hasOutboundGateway
```
public boolean hasOutboundGateway(TunnelId tid)
```
    Returns:
    true if we currently have an outbound gateway for the given TunnelId. This helps callers determine if a tunnel is ready for outbound dispatch.
  - joinInbound
```
public boolean joinInbound(TunnelCreatorConfig cfg)
```
    We are the inbound endpoint - we created this tunnel
    Parameters:
    cfg - config for the inbound tunnel we created
    Returns:
    true if successful, false if tunnel ID is a duplicate
  - joinInboundGateway
```
public boolean joinInboundGateway(HopConfig cfg)
```
    We are the inbound gateway in this tunnel, and did not create it
    Returns:
    true if successful, false if tunnel ID is a duplicate
  - joinOutbound
```
public boolean joinOutbound(PooledTunnelCreatorConfig cfg)
```
    We are the outbound gateway - we created this tunnel
    Parameters:
    cfg - config for the outbound tunnel we created
    Returns:
    true if successful, false if tunnel ID is a duplicate
  - joinOutboundEndpoint
```
public boolean joinOutboundEndpoint(HopConfig cfg)
```
    We are the outbound endpoint in this tunnel, and did not create it
    Parameters:
    cfg - config for the tunnel we're joining as outbound endpoint
    Returns:
    true if successful, false if tunnel ID is a duplicate
  - joinParticipant
```
public boolean joinParticipant(HopConfig cfg)
```
    We are a participant in this tunnel, but not as the endpoint or gateway
    Parameters:
    cfg - config for the tunnel we're joining as participant
    Returns:
    true if successful, false if tunnel ID is a duplicate
  - listParticipatingTunnels
```
public List<HopConfig> listParticipatingTunnels()
```
    Get a list of participating tunnels (for console display). Filters out tunnels that are > 30 seconds past expiration.
  - remove
```
public void remove(HopConfig cfg)
```
    Remove a tunnel we're participating in
  - remove
```
public void remove(TunnelCreatorConfig cfg)
```
    Remove a tunnel we created
  - removeFromExpirationQueue
```
public void removeFromExpirationQueue(HopConfig cfg)
```
    Remove a tunnel from the expiration queue. Called when dropping idle tunnels to prevent memory leaks.
  - resizePumperQueue
```
public static void resizePumperQueue(int value)
```
  - restart
```
public void restart()
```
    Restart the TunnelDispatcher
    Specified by:
    restart in interface Service
  - setMaxIbMsgsPerPump
```
public static void setMaxIbMsgsPerPump(int val)
```
  - setMaxObMsgsPerPump
```
public static void setMaxObMsgsPerPump(int val)
```
  - setPumperMaxThreads
```
public static void setPumperMaxThreads(int value)
```
  - setPumperQueueCapacity
```
public static void setPumperQueueCapacity(int value)
```
  - setRequeueTime
```
public static void setRequeueTime(long ms)
```
  - shouldDropParticipatingInboundMessage
```
boolean shouldDropParticipatingInboundMessage(TunnelDispatcher.Location loc,
                                              int type,
                                              int length,
                                              SyntheticREDQueue bwe)
```
    Check if we should drop an inbound participating tunnel message. Implements symmetric throttling: both inbound and outbound transit traffic should be throttled equally to prevent inbound traffic from overwhelming outbound capacity.
    Parameters:
    loc - location in tunnel (IBGP, PARTICIPANT, OBEP)
    type - message type
    length - message size in bytes
    bwe - per-tunnel bandwidth estimator (may be null)
    Returns:
    true to drop, false to accept
  - shouldDropParticipatingMessage
```
boolean shouldDropParticipatingMessage(TunnelDispatcher.Location loc,
                                       int type,
                                       int length,
                                       SyntheticREDQueue bwe)
```
    Implement RED (Random Early Discard) to enforce bandwidth limits. Only active when queue size > minThreshold (congestion). When queue > maxThreshold, ALL messages are dropped (regardless of factor).
  - shutdown
```
public void shutdown()
```
    Shut down TunnelDispatcher
    Specified by:
    shutdown in interface Service
  - startup
```
public void startup()
```
    Start up the TunnelDispatcher
    Specified by:
    startup in interface Service
  - updateParticipatingStats
```
public void updateParticipatingStats(int ms)
```
    Update stats for participating tunnels
  - updateThrottleFactors
```
void updateThrottleFactors()
```
    Update cached transit throttle factors from router properties. Called on property change or periodically.

Class TunnelDispatcher

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface net.i2p.router.Service

Constructor Detail

TunnelDispatcher

Method Detail

adjustPumperThreads

dispatch

dispatch

dispatchOutbound

dispatchOutbound

freeBandwidth

getAllocatedBW

getLastParticipatingExpiration

getMaxIbMsgsPerPump

getMaxObMsgsPerPump

getMaxPerTunnelBandwidth

getNewIBEPID

getNewIBZeroHopID

getNewOBGWID

getParticipatingCount

getPumperMaxThreads

getPumperQueueCapacity

getPumperUtilization

getRequeueTime

getShareBandwidth

hasOutboundGateway

joinInbound

joinInboundGateway

joinOutbound

joinOutboundEndpoint

joinParticipant

listParticipatingTunnels

remove

remove

removeFromExpirationQueue

resizePumperQueue

restart

setMaxIbMsgsPerPump

setMaxObMsgsPerPump

setPumperMaxThreads

setPumperQueueCapacity

setRequeueTime

shouldDropParticipatingInboundMessage

shouldDropParticipatingMessage

shutdown

startup

updateParticipatingStats

updateThrottleFactors