ExploreJob

net.i2p.router.networkdb.kademlia.ExploreJob

All Implemented Interfaces:: Job

public class ExploreJobextends SearchJob

Represents an exploratory search job for a particular key in the Kademlia network database. This job performs an exploratory search until it gets a Database Search Reply Message (DSRM). It selects peers to send queries to based on floodfill capabilities and excludes peers already queried or close to the target key to avoid redundancy. The concurrency level ("bredth") for this search is calculated once during construction based on system and network conditions, and does not change during the lifetime of the job.

Nested Class Summary
Nested classes/interfaces inherited from class SearchJob
SearchJob.FailedJob
Modifier and Type
Class
Description
protected class
SearchJob.FailedJob
Called when a particular peer failed to respond before the timeout was reached, or if the peer could not be contacted at all.
Field Summary
Modifier and Type
Field
Description
private final int
_bredth
Cached concurrency level (bredth) for this exploratory search instance.
private final boolean
_isRealExplore
False for a search that only keeps the router active.
private Hash
_lastReplyFrom
The peer that answered the last explore.
private final FloodfillPeerSelector
_peerSelector
Chooses the floodfills to explore through.
private static int
_tunedExploreBredth
Tuned exploratory breadth, or -1 when no tuned value has been applied.
static final int
EXPLORE_BREDTH
Default number of concurrent exploratory searches, adjusted for slower systems.
(package private) static final int
MAX_CLOSEST
Maximum number of closest peers to exclude in queries.
private static final long
MAX_EXPLORE_TIME
Maximum duration for each exploration in milliseconds.
(package private) static final int
PER_FLOODFILL_PEER_TIMEOUT
Timeout per floodfill peer in milliseconds; shorter to avoid delays with unresponsive peers.
static final String
PROP_EXPLORE_BREDTH
Configuration property key for controlling the maximum concurrent exploratory searches.
Fields inherited from class SearchJob
_facade, _log, MIN_TIMEOUT
Modifier and Type
Field
Description
protected final KademliaNetworkDatabaseFacade
_facade
Network database facade for peer lookups and storage.
protected final Log
_log
Class logger.
(package private) static final long
MIN_TIMEOUT
Minimum timeout in ms.
Fields inherited from class JobImpl
_id
Modifier and Type
Field
Description
final long
_id
Unique job identifier.
Constructor Summary
Constructors
Constructor
Description
ExploreJob(RouterContext context, KademliaNetworkDatabaseFacade facade, Hash key, boolean isRealExplore, long msgIDBloomXor)
New exploratory search with the given parameters and calculated concurrency level.
Method Summary
Modifier and Type
Method
Description
(package private) boolean
add(Hash peer)
This is called from SearchReplyJob.
protected I2NPMessage
buildMessage(TunnelId replyTunnelId, Hash replyGateway, long expiration, RouterInfo peer)
Builds the database lookup message to send to a peer.
private int
calculateBredth()
Computes the concurrency level (bredth) for exploratory searches based on configured property, network size, and system speed.
protected int
getBredth()
Returns the maximum number of concurrent exploratory searches to run.
static int
getExploreBredth(RouterContext ctx)
The tuned exploratory breadth, or -1 when no tuned value has been applied.
String
getName()
Descriptive name of the task.
protected void
newPeersFound(int numNewPeers)
Called when the search has returned new peers that were previously unknown.
(package private) void
replyFound(DatabaseSearchReplyMessage message, Hash peer)
Process a reply listing routers that hold the key.
static void
setExploreBredth(int bredth)
Set the exploratory search breadth (called by Tuner).
Methods inherited from class SearchJob
addDeferred, continueSearch, decrementOutstandingFloodfillSearches, fail, getExpiration, getFacade, getLeaseResendCount, getPerPeerTimeoutMs, getPerPeerTimeoutMs, getResendTimeout, getState, getTimeoutMs, onlyQueryFloodfillPeers, runJob, searchNext, sendLeaseSearch, sendRouterSearch, sendSearch, setLeaseResendCount, setResendTimeout, timeoutMs, toString, wasAttempted
Modifier and Type
Method
Description
int
addDeferred(Job onFind, Job onFail, long expiration, boolean isLease)
Add a deferred search to run on completion of this search.
protected void
continueSearch()
Send a series of searches to the next available peers as selected by the routing table, but making sure no more than SEARCH_BREDTH are outstanding at any time.
(package private) void
decrementOutstandingFloodfillSearches()
Decrement the count of outstanding floodfill searches.
protected void
fail()
Search totally failed.
long
getExpiration()
When this search gives up if no peer has answered.
protected KademliaNetworkDatabaseFacade
getFacade()
Get the netdb that started this search.
static int
getLeaseResendCount()
The current max peers that get a lease republish after a search.
protected int
getPerPeerTimeoutMs()
Let each peer take up to the average successful search RTT.
protected int
getPerPeerTimeoutMs(Hash peer)
Per-peer timeout adjusted for floodfill and remaining time.
static long
getResendTimeout()
The current lease republish message window.
protected SearchState
getState()
Get the per-search record of which peers have been tried.
long
getTimeoutMs()
How long the search is allowed to run before it is abandoned.
(package private) static boolean
onlyQueryFloodfillPeers(RouterContext ctx)
This is now misnamed, as it is only used to determine whether to return floodfill peers only.
void
runJob()
Execute the next step of the iterative search.
protected void
searchNext()
Send the next search, or stop if its completed.
protected void
sendLeaseSearch(RouterInfo router)
We're (probably) searching for a LeaseSet, so to be (overly) cautious, we're sending the request out through a tunnel w/ reply back through another tunnel.
protected void
sendRouterSearch(RouterInfo router)
We're searching for a router, so we can just send direct.
protected void
sendSearch(RouterInfo router)
Send a search to the given peer.
static void
setLeaseResendCount(int val)
Max peers that get a lease republish after a search.
static void
setResendTimeout(int val)
Lease republish message window.
(package private) long
timeoutMs()
The timeout this search was created with, for other netdb classes.
String
toString()
Describe the search, and how long it has been running, for the logs.
(package private) boolean
wasAttempted(Hash peer)
Whether the peer was already queried.
Methods inherited from class JobImpl
dropped, getContext, getJobId, getMadeReadyOn, getTiming, madeReady, requeue
Modifier and Type
Method
Description
void
dropped()
Default implementation does nothing.
final RouterContext
getContext()
The router context that this job belongs to.
long
getJobId()
The unique job ID for this job.
long
getMadeReadyOn()
The timestamp when this job was last made ready for execution.
JobTiming
getTiming()
The timing object for this job.
void
madeReady(long now)
For JobQueue only, not for external use.
protected void
requeue(long delayMs)
Requeue this job to run after the specified delay.
Methods inherited from class Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details
- _peerSelector
  private final FloodfillPeerSelector _peerSelector
  Chooses the floodfills to explore through.
- _isRealExplore
  private final boolean _isRealExplore
  False for a search that only keeps the router active.
- _lastReplyFrom
  private volatile Hash _lastReplyFrom
  The peer that answered the last explore.
- MAX_EXPLORE_TIME
  private static final long MAX_EXPLORE_TIME
  Maximum duration for each exploration in milliseconds. Explorations run relatively long since they seek multiple peers without expecting a quick success.
  See Also:
  Constant Field Values
- PROP_EXPLORE_BREDTH
  public static final String PROP_EXPLORE_BREDTH
  Configuration property key for controlling the maximum concurrent exploratory searches.
  See Also:
  Constant Field Values
- EXPLORE_BREDTH
  public static final int EXPLORE_BREDTH
  Default number of concurrent exploratory searches, adjusted for slower systems.
- _tunedExploreBredth
  private static volatile int _tunedExploreBredth
  Tuned exploratory breadth, or -1 when no tuned value has been applied. Set via setExploreBredth(int) by the Tuner; takes priority over the router.exploreBredth config read in calculateBredth().
- MAX_CLOSEST
  static final int MAX_CLOSEST
  Maximum number of closest peers to exclude in queries. This is intentionally larger to include floodfill and previously queried peers.
  See Also:
  Constant Field Values
- PER_FLOODFILL_PEER_TIMEOUT
  static final int PER_FLOODFILL_PEER_TIMEOUT
  Timeout per floodfill peer in milliseconds; shorter to avoid delays with unresponsive peers.
  See Also:
  Constant Field Values
- _bredth
  private final int _bredth
  Cached concurrency level (bredth) for this exploratory search instance.
Constructor Details
- ExploreJob
  public ExploreJob(RouterContext context, KademliaNetworkDatabaseFacade facade, Hash key, boolean isRealExplore, long msgIDBloomXor)
  New exploratory search with the given parameters and calculated concurrency level.
  Parameters:
  context - Router context providing environment and config access
  facade - Facade handling the Kademlia network database operations
  key - Target key to explore/search for
  isRealExplore - True if this is a standard exploration (no floodfills returned), false if a standard lookup (floodfills returned, useful when floodfill count is low)
  msgIDBloomXor - XOR value for message ID Bloom filter (used internally)
Method Details
- setExploreBredth
 public static void setExploreBredth(int bredth)
 Set the exploratory search breadth (called by Tuner).
 Parameters:
 bredth - the concurrent search count
- getExploreBredth
 public static int getExploreBredth(RouterContext ctx)
 The tuned exploratory breadth, or -1 when no tuned value has been applied.
 Parameters:
 ctx - the router context (unused, kept for symmetry with other Tuner bridges)
 Returns:
 the tuned concurrent search count, or -1 if none
- buildMessage
 protected I2NPMessage buildMessage(TunnelId replyTunnelId, Hash replyGateway, long expiration, RouterInfo peer)
 Builds the database lookup message to send to a peer. Unlike normal searches, this method explicitly excludes certain peers: those previously queried, and those close to the target key in routing space, to avoid repeatedly querying the same nodes. The floodfill peers are also handled specially.
 Overrides:
 buildMessage in class SearchJob
 Parameters:
 replyTunnelId - Tunnel ID for receiving replies, or null to send direct (no encryption)
 replyGateway - Gateway for the reply tunnel, or null for direct sending
 expiration - Absolute time when the message expires
 peer - RouterInfo object representing the peer to which the message will be sent
 Returns:
 an encrypted or plain DatabaseLookupMessage wrapped as an I2NPMessage, or null on error
- getBredth
 protected int getBredth()
 Returns the maximum number of concurrent exploratory searches to run. This value is computed once at construction based on configuration and network state.
 Overrides:
 getBredth in class SearchJob
 Returns:
 maximum concurrent exploratory searches (bredth)
- calculateBredth
 private int calculateBredth()
 Computes the concurrency level (bredth) for exploratory searches based on configured property, network size, and system speed. If the "router.exploreBredth" property is defined and parseable, it is used. Otherwise, network size and system speed heuristics determine the bredth.
 Returns:
 computed maximum concurrency level for exploration
- newPeersFound
 protected void newPeersFound(int numNewPeers)
 Called when the search has returned new peers that were previously unknown. Logs the number of newly discovered peers and updates the last explore timestamp.
 Overrides:
 newPeersFound in class SearchJob
 Parameters:
 numNewPeers - number of newly discovered peers
- replyFound
 void replyFound(DatabaseSearchReplyMessage message, Hash peer)
 Process a reply listing routers that hold the key.
 Overrides:
 replyFound in class SearchJob
 Parameters:
 message - search reply received from the peer
 peer - router hash that sent it, which is cleared from the pending set and recorded as having replied
- add
 boolean add(Hash peer)
 This is called from SearchReplyJob.
 Overrides:
 add in class SearchJob
 Parameters:
 peer - router hash to add to the kbuckets, and to queue for exploration if it was not already there
 Returns:
 true if peer was new
- getName
 public String getName()
 Description copied from interface: Job
 Descriptive name of the task.
 Specified by:
 getName in interface Job
 Overrides:
 getName in class SearchJob
 Returns:
 the descriptive name of the task

Nested Class Summary

Nested classes/interfaces inherited from class SearchJob

Field Summary

Fields inherited from class SearchJob

Fields inherited from class JobImpl

Constructor Summary

Method Summary

Methods inherited from class SearchJob

Methods inherited from class JobImpl

Methods inherited from class Object

Field Details

_peerSelector

_isRealExplore

_lastReplyFrom

MAX_EXPLORE_TIME

PROP_EXPLORE_BREDTH

EXPLORE_BREDTH

_tunedExploreBredth

MAX_CLOSEST

PER_FLOODFILL_PEER_TIMEOUT

_bredth

Constructor Details

Method Details

setExploreBredth

getExploreBredth

buildMessage

getBredth

calculateBredth

newPeersFound

replyFound

add

getName