abstract static class Tuner.BaseParam extends Object implements Tuner.TunableParam
Each param wraps a single router configuration value. The tuning loop reads an observed stat, computes a target, and applies it:
observed = getObservedStat() target = computeTarget(observed) target = clamp(target, min, max) target = dampenByHealth(target, current) target = accelerateRollback(target, current, defaultValue) applyValue(target)
Min/max/step ranges are stored in autotune.config and
can be changed at runtime via the console UI (no restart needed).
Factory defaults are captured on first run and persisted for
auto-revert when system health is degraded.
Thread safety: all fields are accessed only from the Tuner
timer thread, except _override and _autoTuning
which are set from the console form handler.
| Modifier and Type | Field and Description |
|---|---|
protected Tuner.AutotuneConfig | _autotuneAutotune profile for this tunable parameter. |
protected boolean | _autoTuningWhether autotuning is active for this parameter. |
protected RouterContext | _ctxRouter context. |
protected int | _defaultMaxDefault maximum value from code or config. |
protected int | _defaultMinDefault minimum value from code or config. |
protected int | _defaultStepDefault step/increment size for adjustments. |
protected int | _defaultValueFactory default: value before any tuning. |
protected String | _descriptionHuman-readable label for display in the Tuner UI. |
protected boolean | _firstTickTrue until first update() call — applies persisted value from autotune.config. |
protected Tuner.SystemHealth | _healthHealth score and subsystem for autotune decisions. |
protected int | _historyCountNumber of valid entries in _valueHistory / _statHistory. |
protected int | _initialValueLast known value (from persistence or runtime default). |
protected Log | _logClass logger. |
protected int | _maxCurrent maximum value (may differ from default after tuning). |
protected int | _minCurrent minimum value (may differ from default after tuning). |
protected String | _nameInternal config property key (e.g. |
protected int | _overrideUser-set override value, or Integer.MIN_VALUE if unset. |
protected String | _propPrefixConfig key prefix for property lookups. |
(package private) static Tuner.AutotuneConfig | _sharedAutotuneShared instance — set once in Tuner constructor, used by all BaseParams |
protected double[] | _statHistoryRolling window of recent stat values for trend analysis. |
protected String | _statNameRouter stat name for observed value feedback. |
protected int | _stepCurrent step/increment size (may differ from default). |
protected String | _subsystemSubsystem identifier this parameter belongs to. |
protected int[] | _valueHistoryRolling window of recent tunable values for trend analysis. |
| Modifier | Constructor and Description |
|---|---|
protected | BaseParam(String name,
String description,
String subsystem,
int defaultMin,
int defaultMax,
int defaultStep,
String statName,
RouterContext ctx) |
protected | BaseParam(String name,
String description,
String subsystem,
int defaultMin,
int defaultMax,
int defaultStep,
String statName,
RouterContext ctx,
Tuner.AutotuneConfig autotune) |
| Modifier and Type | Method and Description |
|---|---|
protected abstract void | applyValue(int value) |
protected static int | clamp(int current,
int target,
int step)Move from current toward target, but at most one step per cycle. |
protected abstract int | computeTarget(double observed) |
protected double | getAdditionalEventCount(RouterContext ctx,
String statName)Fetch the event count for an additional stat using the 60s period. |
protected double | getAdditionalEventCountHourly(RouterContext ctx,
String statName)Fetch the event count for an additional stat using the 1-hour period. |
protected double | getAdditionalStat(RouterContext ctx,
String statName)Fetch an additional stat value for cross-reference decisions. |
protected double | getAdditionalStat5Min(RouterContext ctx,
String statName)Fetch an additional stat value using the 5-minute average. |
protected double | getAdditionalStatHourly(RouterContext ctx,
String statName)Fetch an additional stat value using the 1-hour average. |
protected double | getAdditionalStatLong(RouterContext ctx,
String statName)Fetch an additional stat value using the 10-minute average. |
protected double | getBuildSuccessRate(RouterContext ctx)Compute actual tunnel build success rate from event counts. |
protected double | getCoDelDropEventCount(RouterContext ctx,
String prefix)Fetch the total CoDel drop event count across all priority levels. |
int | getCurrentValue()Current value. |
protected int | getDefaultMax(RouterContext ctx)Effective default max — override for bandwidth-scaled params. |
protected int | getDefaultMin(RouterContext ctx)Effective default min — override for bandwidth-scaled params. |
protected int | getDefaultStep(RouterContext ctx)Effective default step — override for bandwidth-scaled params. |
int | getDefaultValue()Default value. |
String | getDescription()Param description. |
protected static int | getHeavyTransitThreshold(RouterContext ctx)Transit bandwidth threshold for "heavy" — 80% of configured share bandwidth. |
int | getMax()Maximum value. |
protected double | getMessageReceiverUtilization(RouterContext ctx)UDP message receiver pool utilization (0.0-1.0). |
int | getMin()Minimum value. |
String | getName()Param name. |
protected double | getObservedRTT(RouterContext ctx,
String primaryStat)Fetch observed RTT, falling back to udp.sendConfirmTime
when the primary stat has no events (lightly loaded router). |
protected abstract double | getObservedStat(RouterContext ctx) |
protected double | getPacketHandlerUtilization(RouterContext ctx)UDP packet handler pool utilization (0.0-1.0). |
protected double | getPumperUtilization(RouterContext ctx)Tunnel pumper pool utilization (0.0-1.0). |
protected double | getReaderUtilization(RouterContext ctx)NTCP reader pool utilization (0.0-1.0). |
protected abstract int | getRuntimeValue() |
protected double | getSendFinisherUtilization(RouterContext ctx)NTCP send finisher pool utilization (0.0-1.0). |
protected static int | getShareBps(RouterContext ctx)Current share bandwidth in bytes per second. |
double[] | getStatHistory()Sparkline stat history. |
int | getStep()Step size. |
String | getSubsystem()Subsystem name. |
protected static int | getSustainedHeavyTransitThreshold(RouterContext ctx)Transit bandwidth threshold for "sustained heavy" — 50% of configured share. |
int[] | getValueHistory()Sparkline value history. |
protected double | getWriterUtilization(RouterContext ctx)NTCP writer pool utilization (0.0-1.0). |
boolean | isAutoTuning()Whether auto-tuning is enabled. |
protected void | persistValue(RouterContext ctx,
int value)Persist a tuned value to autotune.config. |
protected static int | reclaimIfIdle(double utilization,
int current,
int min,
double idleThreshold)Reclaim parked threads from a thread pool that is massively
under-utilized. |
protected void | recordHistory(double observed)Record history. |
void | refreshDefault(RouterContext ctx)Re-read the default value from autotune.config — live update after form save. |
void | refreshRanges(RouterContext ctx)Re-read min/max/step from autotune.config — live update, no restart. |
(package private) void | setHealth(Tuner.SystemHealth health)The current system health score for this update cycle. |
void | setOverride(int value)Set a manual override value. |
Tuner.ParamSnapshot | snapshot()Capture snapshot of current tunable state for display. |
void | update()Main tuning loop for this param. |
protected final Tuner.AutotuneConfig _autotune
protected volatile boolean _autoTuning
protected final RouterContext _ctx
protected final int _defaultMax
protected final int _defaultMin
protected final int _defaultStep
protected int _defaultValue
protected final String _description
protected boolean _firstTick
protected Tuner.SystemHealth _health
protected int _historyCount
protected final int _initialValue
protected final Log _log
protected int _max
protected int _min
protected final String _name
protected volatile int _override
protected final String _propPrefix
static volatile Tuner.AutotuneConfig _sharedAutotune
protected final double[] _statHistory
protected final String _statName
protected int _step
protected final String _subsystem
protected final int[] _valueHistory
protected BaseParam(String name, String description, String subsystem, int defaultMin, int defaultMax, int defaultStep, String statName, RouterContext ctx)
name - internal property key (e.g. "i2p.tunnel.socketConnectTimeout")description - human-readable label shown in Tuner UI (e.g. "Socket connect timeout (ms)")
— keep short, include unit in parens; same convention for all new paramssubsystem - subsystem identifier (e.g. "i2ptunnel", "streaming")protected BaseParam(String name, String description, String subsystem, int defaultMin, int defaultMax, int defaultStep, String statName, RouterContext ctx, Tuner.AutotuneConfig autotune)
subsystem - subsystem identifier (e.g. "i2ptunnel", "streaming")protected abstract void applyValue(int value)
value - the tunable value to apply to router configurationprotected static int clamp(int current,
int target,
int step)current - the current runtime valuetarget - the desired target valuestep - the maximum change per cycleprotected abstract int computeTarget(double observed)
observed - current stat valueprotected double getAdditionalEventCount(RouterContext ctx, String statName)
For event-count stats where addRateData(name, 1) is called,
getAdditionalStat(net.i2p.router.RouterContext, java.lang.String) returns getAverageValue() which is
always 1.0 when events exist. This method returns the raw event count
instead, which is the correct metric for "how many events occurred".
ctx - the router contextstatName - the stat to queryprotected double getAdditionalEventCountHourly(RouterContext ctx, String statName)
ctx - the router contextstatName - the stat to queryprotected double getAdditionalStat(RouterContext ctx, String statName)
Cross-reference stats are used alongside the primary stat to
make more informed tuning decisions. For example, a streaming
param might use transport.sendProcessingTime as its
primary signal but also check jobQueue.jobLag to avoid
increasing load when the CPU is already saturated.
ctx - the router contextstatName - the stat to query (e.g. "jobQueue.jobLag")protected double getAdditionalStat5Min(RouterContext ctx, String statName)
Useful for medium-term decisions that need more signal than a 60s spike but faster reaction than a 1-hour trend. For example, retransmit ratio over 5 minutes filters out transient bursts while still catching sustained loss within a minute or two.
ctx - the router contextstatName - the stat to queryprotected double getAdditionalStatHourly(RouterContext ctx, String statName)
Useful for less time-sensitive decisions where we want to confirm a trend rather than react to a short-term spike. For example, build success rate should be checked over an hour to avoid over-reacting to a brief network glitch.
ctx - the router contextstatName - the stat to queryprotected double getAdditionalStatLong(RouterContext ctx, String statName)
The 10-minute period is a medium-term signal — slower to react than the 60s period but less prone to gaps from brief idle windows. Use this as the first fallback when the 60s stat has no recent events, since most streaming stats are registered with both ONE_MINUTE and TEN_MINUTES rates.
ctx - the router contextstatName - the stat to queryprotected double getBuildSuccessRate(RouterContext ctx)
The build success/failure/timeout stats are event-count markers
(addRateData(name, 100, 0)), so getAdditionalStat(net.i2p.router.RouterContext, java.lang.String)
BuildExecutor emits these stats as 0-100 integer percentages with
addRateData(name, rate, 0). The eventDuration=0 parameter is
not an event count delta — event count always increments by 1 per call.
getAdditionalStat(net.i2p.router.RouterContext, java.lang.String) returns getAverageValue() = average of emitted
rates, which is the correct success percentage. Do NOT use
getAdditionalEventCount(net.i2p.router.RouterContext, java.lang.String) here — it returns the call count (always 1.0
when all three stats are emitted together), not the rate value.
ctx - the router contextprotected double getCoDelDropEventCount(RouterContext ctx, String prefix)
CoDelPriorityBlockingQueue emits per-priority stats with names like
codel.UDP-Sender.drop.0, codel.UDP-Sender.drop.100, etc.
This method sums the event counts across all priorities.
ctx - the router contextprefix - the stat prefix (e.g. "codel.UDP-Sender.drop")public int getCurrentValue()
getCurrentValue in interface Tuner.TunableParamprotected int getDefaultMax(RouterContext ctx)
protected int getDefaultMin(RouterContext ctx)
protected int getDefaultStep(RouterContext ctx)
public int getDefaultValue()
public String getDescription()
getDescription in interface Tuner.TunableParamprotected static int getHeavyTransitThreshold(RouterContext ctx)
public int getMax()
getMax in interface Tuner.TunableParamprotected double getMessageReceiverUtilization(RouterContext ctx)
public int getMin()
getMin in interface Tuner.TunableParampublic String getName()
getName in interface Tuner.TunableParamprotected double getObservedRTT(RouterContext ctx, String primaryStat)
udp.sendConfirmTime
when the primary stat has no events (lightly loaded router).The primary stat is typically a streaming-specific metric
(e.g. stream.lifetimeRTT) which only fires when active
streaming connections exist. On a lightly loaded router, this
may be NaN. The fallback udp.sendConfirmTime is always
available when any UDP traffic is present.
ctx - the router contextprimaryStat - the streaming-specific RTT stat nameprotected abstract double getObservedStat(RouterContext ctx)
ctx - router contextprotected double getPacketHandlerUtilization(RouterContext ctx)
protected double getPumperUtilization(RouterContext ctx)
protected double getReaderUtilization(RouterContext ctx)
protected abstract int getRuntimeValue()
protected double getSendFinisherUtilization(RouterContext ctx)
protected static int getShareBps(RouterContext ctx)
public double[] getStatHistory()
Tuner.TunableParamgetStatHistory in interface Tuner.TunableParampublic int getStep()
getStep in interface Tuner.TunableParampublic String getSubsystem()
getSubsystem in interface Tuner.TunableParamprotected static int getSustainedHeavyTransitThreshold(RouterContext ctx)
public int[] getValueHistory()
Tuner.TunableParamgetValueHistory in interface Tuner.TunableParamprotected double getWriterUtilization(RouterContext ctx)
public boolean isAutoTuning()
isAutoTuning in interface Tuner.TunableParamprotected void persistValue(RouterContext ctx, int value)
Writes are throttled: the value is marked dirty and flushed
to disk at most once per 5 minutes by Tuner.AutotuneConfig.save().
This avoids excessive I/O from params that change every cycle.
ctx - the router contextvalue - the new value to persistprotected static int reclaimIfIdle(double utilization,
int current,
int min,
double idleThreshold)idleThreshold and more than min
threads are allocated, otherwise -1 (no change).Utilization is the ratio of threads actively doing work to the total pool size. When this sits near zero for an extended window the extra threads are just parked — there is no point keeping them around, so we shed one (or two, when extremely idle) to track demand.
utilization - current pool utilization (0.0–1.0), or NaNcurrent - current thread countmin - minimum thread count (floor)idleThreshold - utilization below which threads are reclaimedprotected void recordHistory(double observed)
public void refreshDefault(RouterContext ctx)
Called once per tuning cycle. When a user saves a new default via the console form, this method picks it up and uses it as the auto-revert target.
public void refreshRanges(RouterContext ctx)
Called once per tuning cycle before computeTarget(). Clamps loaded ranges to constructor limits to prevent stale config values from exceeding actual setter limits. Also clamps the persisted value to the new range if it was set before a code change lowered the max.
void setHealth(Tuner.SystemHealth health)
public void setOverride(int value)
Called from the console form handler when a user manually
sets a param value. Setting value < 0 re-enables auto-tuning.
The override is applied immediately via applyValue(int) and
persisted to autotune.config.
setOverride in interface Tuner.TunableParamvalue - the override value, or < 0 to re-enable auto-tuningpublic Tuner.ParamSnapshot snapshot()
snapshot in interface Tuner.TunableParampublic void update()
Sequence:
getObservedStat(net.i2p.router.RouterContext)computeTarget(double)applyValue(int) and persistValue(net.i2p.router.RouterContext, int)update in interface Tuner.TunableParam