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
        FragmentHandler ->  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
         FragmentHandler -> 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()` 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)` The max bandwidth per transit tunnel.
`TunnelId`	`getNewIBEPID()` A random receive tunnel ID that isn't a duplicate.
`TunnelId`	`getNewIBZeroHopID()` A random receive tunnel ID that isn't a duplicate (zero hop).
`TunnelId`	`getNewOBGWID()` A random send tunnel ID that isn't a duplicate.
`int`	`getParticipatingCount()` The number of participating tunnels.
`static int`	`getPumperMaxThreads()`
`static int`	`getPumperQueueCapacity()`
`static double`	`getPumperUtilization()` The pumper pool utilization as a ratio (0.0-1.0).
`static long`	`getRequeueTime()`
`static int`	`getShareBandwidth(RouterContext ctx)` The current bandwidth share in KBps.
`boolean`	`hasOutboundGateway(TunnelId tid)` Whether an outbound gateway exists for the given TunnelId.
`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(TunnelCreatorConfig 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()` The 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.
`void`	`renderStatusHTML(Writer out)` Required by `Service`; status rendering moved to routerconsole.
`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

- 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()
```
    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)
```
    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()
```
    A random receive tunnel ID that isn't a duplicate.
    Returns:
    the new i b e p i d
  - getNewIBZeroHopID
```
public TunnelId getNewIBZeroHopID()
```
    A random receive tunnel ID that isn't a duplicate (zero hop).
    Returns:
    the new i b zero hop i d
  - getNewOBGWID
```
public TunnelId getNewOBGWID()
```
    A random send tunnel ID that isn't a duplicate.
    Returns:
    the new o b g w i d
  - getParticipatingCount
```
public int getParticipatingCount()
```
    The number of participating tunnels.
    Returns:
    the participating count
  - getPumperMaxThreads
```
public static int getPumperMaxThreads()
```
  - getPumperQueueCapacity
```
public static int getPumperQueueCapacity()
```
  - getPumperUtilization
```
public static double getPumperUtilization()
```
    The 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)
```
    The current bandwidth share in KBps.
    Returns:
    the share bandwidth
  - hasOutboundGateway
```
public boolean hasOutboundGateway(TunnelId tid)
```
    Whether an outbound gateway exists for the given TunnelId. This helps callers determine if a tunnel is ready for outbound dispatch.
    Returns:
    true if we currently have an outbound gateway for the given TunnelId.
  - 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(TunnelCreatorConfig 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()
```
    The 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.
  - renderStatusHTML
```
public void renderStatusHTML(Writer out)
                      throws IOException
```
    Required by Service; status rendering moved to routerconsole.
    Specified by:
    renderStatusHTML in interface Service
    Parameters:
    out - the writer to write to
    Throws:
    IOException - if an error occurs writing
  - 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

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

renderStatusHTML

resizePumperQueue

restart

setMaxIbMsgsPerPump

setMaxObMsgsPerPump

setPumperMaxThreads

setPumperQueueCapacity

setRequeueTime

shouldDropParticipatingInboundMessage

shouldDropParticipatingMessage

shutdown

startup

updateParticipatingStats

updateThrottleFactors