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

Class DhtLookup

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

DhtLookup

Method Details

swig

type

outstandingRequests

timeouts

responses

branchFactor

nodesLeft

lastSent

firstTimeout

target