java.lang.Object
net.i2p.router.networkdb.kademlia.SearchState
class SearchStateextends Object
Manages state for network database search operations.

Tracks peer interaction status, timing information, and search progress for iterative Kademlia searches. Maintains separate sets for pending, attempted, failed, successful, and replied peers to coordinate concurrent search operations and prevent duplicate queries.

Thread safety: the collections are plain and guarded by synchronized blocks on each collection, with volatile timing fields; a few read-only size checks in toString() run unlocked. Safe for concurrent access from multiple search jobs.

  • Field Details

    • _context

      private final RouterContext _context
      The router context.

    • _pendingPeers

      private final Set<Hash> _pendingPeers
      Peers asked, waiting for a reply.

    • _pendingPeerTimes

      private final Map<Hash,Long> _pendingPeerTimes
      When each pending peer was asked.

    • _attemptedPeers

      private final Set<Hash> _attemptedPeers
      Peers asked at any point in the search.

    • _failedPeers

      private final Set<Hash> _failedPeers
      Peers that failed to reply.

    • _successfulPeers

      private final Set<Hash> _successfulPeers
      Peers that replied with results.

    • _repliedPeers

      private final Set<Hash> _repliedPeers
      Peers that replied at all.

    • _searchKey

      private final Hash _searchKey
      The hash being searched for.

    • _completed

      private volatile long _completed
      When the search completed, 0 until then.

    • _started

      private volatile long _started
      When the search started.

    • _aborted

      private volatile boolean _aborted
      True if the search was aborted.

    • _log

      private final Log _log
      Logger for the lookup search.

    • _leaseSetResponses

      private final Map<Hash,LeaseSet> _leaseSetResponses
      Lease sets found, by hash.

    • _firstLeaseSetTime

      private long _firstLeaseSetTime
      When the first lease set arrived.

    • _initialResponseCount

      private final AtomicInteger _initialResponseCount
      Initial responses received so far.

    • _initialResponseStart

      private volatile long _initialResponseStart
      When waiting for the initial responses began.

    • INITIAL_RESPONSE_TARGET

      private static final int INITIAL_RESPONSE_TARGET
      Initial responses waited for.
      See Also:

    • INITIAL_RESPONSE_TIMEOUT

      private static final long INITIAL_RESPONSE_TIMEOUT
      Time waited for the initial responses.
      See Also:

    • _storedLeaseDate

      private volatile long _storedLeaseDate
      Publish date of the lease set stored.

  • Constructor Details

    • SearchState

      public SearchState(RouterContext context, Hash key)
      Opens the search's log, records the start time and initializes the peer-tracking sets.
      Parameters:
      context - the context supplying the log and the clock this search is timed against
      key - the search target that peers are ranked against by XOR distance

  • Method Details

    • getTarget

      public Hash getTarget()
      The search target.
      Returns:
      the hash being searched for

    • getPendingSize

      public int getPendingSize()
      Number of pending peers.
      Returns:
      the pending size

    • getPending

      public Set<Hash> getPending()
      Copy of the pending peers.
      Returns:
      a snapshot safe to iterate without holding the lock

    • getAttempted

      public Set<Hash> getAttempted()
      Copy of the attempted peers.
      Returns:
      a snapshot safe to iterate without holding the lock

    • getAttemptedSize

      public int getAttemptedSize()
      Number of attempted peers.
      Returns:
      the attempted size

    • getClosestAttempted

      public Set<Hash> getClosestAttempted(int max)
      Up to max attempted peers closest to the target.
      Parameters:
      max - the largest number of peers to return
      Returns:
      the closest attempted

    • locked_getClosest

      private Set<Hash> locked_getClosest(Set<Hash> peers, int max, Hash target)
      Picks the peers closest to the target.
      Parameters:
      peers - the peers to choose from
      max - the number of peers wanted
      target - the hash to measure distance to
      Returns:
      the closest peers chosen

    • wasAttempted

      public boolean wasAttempted(Hash peer)
      Whether the peer was attempted.
      Parameters:
      peer - the peer to look for in the attempted set
      Returns:
      true if this peer has already been queried for this search

    • getSuccessful

      public Set<Hash> getSuccessful()
      Copy of the successful peers.
      Returns:
      a snapshot safe to iterate without holding the lock

    • getFailed

      public Set<Hash> getFailed()
      Copy of the failed peers.
      Returns:
      a snapshot safe to iterate without holding the lock

    • getFailedSize

      public int getFailedSize()
      Number of failed peers.
      Returns:
      the failed size

    • getSuccessfulSize

      public int getSuccessfulSize()
      Number of successful peers.
      Returns:
      the successful size

    • completed

      public boolean completed()
      Whether the search has completed.
      Returns:
      true once a completion time has been recorded

    • complete

      public void complete()
      Mark the search as completed at the current time.

    • isAborted

      public boolean isAborted()
      Checks if this search state has been aborted.
      Returns:
      true once abort() has been called

    • abort

      public void abort()
      Aborts this search state.

    • getWhenStarted

      public long getWhenStarted()
      Time the search started.
      Returns:
      the when started

    • getWhenCompleted

      public long getWhenCompleted()
      Time the search completed, or -1 if not yet completed.
      Returns:
      the when completed

    • addPending

      public void addPending(Collection<Hash> pending)
      Add the peers to the pending and attempted sets.
      Parameters:
      pending - the peers to add

    • addPending

      public void addPending(Hash peer)
      Add the peer to the pending and attempted sets.
      Parameters:
      peer - the peer to add

    • removePending

      public void removePending(Hash peer)
      We didn't actually want to add this peer as part of the pending list...
      Parameters:
      peer - the peer to take back out of the pending and attempted sets

    • dataFound

      public long dataFound(Hash peer)
      How long it took to get the reply, or -1 if we don't know.
      Parameters:
      peer - the peer that answered with data for this search
      Returns:
      the milliseconds between request and reply, or -1 if the request was never recorded

    • replyFound

      public long replyFound(Hash peer)
      How long it took to get the reply, or -1 if we don't know.
      Parameters:
      peer - the peer that answered this search without data
      Returns:
      the milliseconds between request and reply, or -1 if the request was never recorded

    • getRepliedPeers

      public Set<Hash> getRepliedPeers()
      Copy of the peers that replied.
      Returns:
      the replied peers

    • replyTimeout

      public void replyTimeout(Hash peer)
      Move the peer from pending to failed on timeout.
      Parameters:
      peer - the peer that timed out

    • addLeaseSetResponse

      public void addLeaseSetResponse(Hash peer, LeaseSet ls)
      Record the peer's LeaseSet response.
      Parameters:
      peer - the peer that responded
      ls - the received LeaseSet

    • getNewestLeaseSet

      public LeaseSet getNewestLeaseSet()
      LeaseSet with the newest lease date among the responses.
      Returns:
      the newest lease set

    • addInitialLeaseSetResponse

      public void addInitialLeaseSetResponse(Hash peer, LeaseSet ls)
      Record the peer's LeaseSet response from the initial phase.
      Parameters:
      peer - the peer that responded
      ls - the received LeaseSet

    • shouldStoreInitial

      public boolean shouldStoreInitial()
      Whether enough initial responses have been received to store.
      Returns:
      whether store initial

    • getBestInitialLeaseSet

      public LeaseSet getBestInitialLeaseSet()
      LeaseSet with the newest lease date among the initial responses.
      Returns:
      the best initial lease set

    • clearInitialTracking

      public void clearInitialTracking()
      Clear the initial response tracking state.

    • getStoredLeaseDate

      public long getStoredLeaseDate()
      Stored lease date of the last accepted LeaseSet.
      Returns:
      the stored lease date

    • setStoredLeaseDate

      public void setStoredLeaseDate(long date)
      Record the stored lease date.
      Parameters:
      date - the new stored lease date

    • shouldUpdateStored

      public boolean shouldUpdateStored(LeaseSet ls)
      Whether the given LeaseSet is newer than the stored one.
      Parameters:
      ls - the LeaseSet to compare
      Returns:
      whether update stored

    • toString

      public String toString()
      Debug string for this search state.
      Overrides:
      toString in class Object