Package com.frostwire.jlibtorrent

Class DhtLookup

java.lang.Object
com.frostwire.jlibtorrent.DhtLookup
public final class DhtLookup extends Object
Statistics for an active Distributed Hash Table (DHT) lookup operation.

DhtLookup provides real-time metrics about a DHT query in progress. DHT lookups are the fundamental operation for peer discovery and DHT item retrieval in distributed networks. This class gives visibility into the performance and state of individual lookup operations.

Understanding DHT Lookups:
A DHT lookup is a network traversal algorithm (like Kademlia) that:

  • Starts with a target (node-id or info-hash)
  • Queries nodes in parallel (branch factor)
  • Receives routing information pointing closer to target
  • Iteratively narrows down to target or nearby nodes
  • Collects results (peers for info-hash, values for DHT items)
  • Eventually completes when no closer nodes can be found

Common DHT Lookup Types: 

 // "get_peers" - Find peers for an info-hash (peer discovery)
 // "get" - Retrieve an immutable DHT item
 // "put" - Store an immutable DHT item
 // "find_node" - Locate specific DHT nodes

Monitoring DHT Lookups: 

 // Lookups are reported via DhtGetPeersReplyAlert
 sm.addListener(new AlertListener() {
     public int[] types() {
         return new int[] {AlertType.DHT_GET_PEERS_REPLY.swig()};
     }

     public void alert(Alert<?> alert) {
         DhtGetPeersReplyAlert a = (DhtGetPeersReplyAlert) alert;

         // Get lookup statistics
         DhtLookup lookup = a.lookupData();
         System.out.println("Lookup type: " + lookup.type());
         System.out.println("Target: " + lookup.target().toHex());
         System.out.println("Outstanding requests: " + lookup.outstandingRequests());
         System.out.println("Responses received: " + lookup.responses());
         System.out.println("Timeouts: " + lookup.timeouts());
     }
 });

Lookup Metrics Interpretation: 

 DhtLookup lookup = ...;

 // Branch factor: how many nodes are queried in parallel
 // Typically 20 for get_peers, 3-4 for get/put
 int branchFactor = lookup.branchFactor();
 System.out.println("Parallel queries: " + branchFactor);

 // Outstanding requests: how many queries are awaiting response
 int outstanding = lookup.outstandingRequests();
 System.out.println("Pending responses: " + outstanding);

 // Responses: successful replies from nodes
 int responses = lookup.responses();
 System.out.println("Nodes responded: " + responses);

 // Timeouts: requests that failed (no response)
 int timeouts = lookup.timeouts();
 System.out.println("Failed requests: " + timeouts);

 // Nodes left: additional candidates not yet queried
 int remaining = lookup.nodesLeft();
 System.out.println("Candidates remaining: " + remaining);

 // Last message sent: seconds since most recent query
 int lastSent = lookup.lastSent();
 System.out.println("Time since last query: " + lastSent + "s");

Lookup Performance Analysis: 

 DhtLookup lookup = ...;

 // Success rate
 int totalRequests = lookup.responses() + lookup.timeouts();
 double successRate = (double) lookup.responses() / totalRequests * 100;
 System.out.println("Success rate: " + successRate + "%");

 // Is lookup stalled?
 if (lookup.outstandingRequests() == 0 && lookup.nodesLeft() > 0) {
     System.out.println("Lookup stalled - no pending requests but more nodes available");
 }

 // Lookup is completing
 if (lookup.outstandingRequests() == 0 && lookup.nodesLeft() == 0) {
     System.out.println("Lookup complete!");
 }

 // Lookup is active
 if (lookup.outstandingRequests() > 0) {
     System.out.println("Lookup in progress, " + lookup.outstandingRequests() + " requests pending");
 }

Real-World Example - Peer Discovery: 

 // Finding peers for a torrent
 Sha1Hash infoHash = new Sha1Hash("d8e8fca2dc0f896fd7cb4cb0031ba249");

 // Initiate DHT get_peers lookup
 sm.dhtGetPeers(infoHash);

 // Listen for results
 sm.addListener(new AlertListener() {
     public int[] types() {
         return new int[] {AlertType.DHT_GET_PEERS_REPLY.swig()};
     }

     public void alert(Alert<?> alert) {
         DhtGetPeersReplyAlert a = (DhtGetPeersReplyAlert) alert;
         DhtLookup lookup = a.lookupData();

         System.out.println("===== DHT Lookup Statistics =====");
         System.out.println("Type: " + lookup.type());
         System.out.println("Target: " + lookup.target().toHex());
         System.out.println("Outstanding: " + lookup.outstandingRequests());
         System.out.println("Responses: " + lookup.responses());
         System.out.println("Timeouts: " + lookup.timeouts());
         System.out.println("Branch factor: " + lookup.branchFactor());
         System.out.println("Nodes left: " + lookup.nodesLeft());

         // Get actual peers from alert
         List<TcpEndpoint> peers = a.peers();
         System.out.println("Peers found: " + peers.size());
         for (TcpEndpoint peer : peers) {
             System.out.println("  " + peer.toString());
         }
     }
 });

DHT Lookup Types and Their Branch Factors: 

 get_peers (find peers)       - Branch factor ~20 (aggressive search)
 get (retrieve item)          - Branch factor ~3-4 (conservative)
 put (store item)             - Branch factor ~3-4 (conservative)
 find_node (locate nodes)     - Branch factor ~3-4 (conservative)
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    DhtLookup(com.frostwire.jlibtorrent.swig.dht_lookup l)
    internal use

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    branchFactor()
    the branch factor for this lookup.
    int
    firstTimeout()
    the number of outstanding requests that have exceeded the short timeout and are considered timed out in the sense that they increased the branch factor.
    int
    lastSent()
    the number of seconds ago the last message was sent that's still outstanding.
    int
    nodesLeft()
    the number of nodes left that could be queries for this lookup.
    int
    outstandingRequests()
    the number of outstanding request to individual nodes this lookup has right now.
    int
    responses()
    the total number of responses we have received for this lookup so far for this lookup.
    com.frostwire.jlibtorrent.swig.dht_lookup
    swig()
    The native object.
    Sha1Hash
    target()
    The node-id or info-hash target for this lookup.
    int
    timeouts()
    the total number of requests that have timed out so far for this lookup.
    String
    type()
    string literal indicating which kind of lookup this is.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DhtLookup

      public DhtLookup(com.frostwire.jlibtorrent.swig.dht_lookup l)
      internal use
      Parameters:
      l -

  • Method Details

    • swig

      public com.frostwire.jlibtorrent.swig.dht_lookup swig()
      The native object.
      Returns:
      the native object

    • type

      public String type()
      string literal indicating which kind of lookup this is.
      Returns:

    • outstandingRequests

      public int outstandingRequests()
      the number of outstanding request to individual nodes this lookup has right now.
      Returns:

    • timeouts

      public int timeouts()
      the total number of requests that have timed out so far for this lookup.
      Returns:

    • responses

      public int responses()
      the total number of responses we have received for this lookup so far for this lookup.
      Returns:

    • branchFactor

      public int branchFactor()
      the branch factor for this lookup. This is the number of nodes we keep outstanding requests to in parallel by default. when nodes time out we may increase this.
      Returns:

    • nodesLeft

      public int nodesLeft()
      the number of nodes left that could be queries for this lookup. Many of these are likely to be part of the trail while performing the lookup and would never end up actually being queried.
      Returns:

    • lastSent

      public int lastSent()
      the number of seconds ago the last message was sent that's still outstanding.
      Returns:

    • firstTimeout

      public int firstTimeout()
      the number of outstanding requests that have exceeded the short timeout and are considered timed out in the sense that they increased the branch factor.
      Returns:

    • target

      public Sha1Hash target()
      The node-id or info-hash target for this lookup.
      Returns:
      the target