clarify timeouts a bit more

n0-computer · May 22, 2024 · d78c287 · d78c287
1 parent 03d9690
commit d78c287
Showing 1 changed file with 42 additions and 13 deletions.
diff --git a/iroh-net/src/dns.rs b/iroh-net/src/dns.rs
@@ -117,7 +117,10 @@ pub trait ResolverExt {
 
     /// Perform an ipv4 lookup with a timeout in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The `timeout` is applied to each call individually. The
+    /// result of the first successful call is returned, or a summary of all errors otherwise.
     fn lookup_ipv4_staggered<N: IntoName + Clone>(
         &self,
         host: N,
@@ -127,7 +130,10 @@ pub trait ResolverExt {
 
     /// Perform an ipv6 lookup with a timeout in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The `timeout` is applied to each call individually. The
+    /// result of the first successful call is returned, or a summary of all errors otherwise.
     fn lookup_ipv6_staggered<N: IntoName + Clone>(
         &self,
         host: N,
@@ -137,7 +143,11 @@ pub trait ResolverExt {
 
     /// Race an ipv4 and ipv6 lookup with a timeout in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The `timeout` is applied as stated in
+    /// [`Self::lookup_ipv4_ipv6`]. The result of the first successful call is returned, or a
+    /// summary of all errors otherwise.
     fn lookup_ipv4_ipv6_staggered<N: IntoName + Clone>(
         &self,
         host: N,
@@ -147,7 +157,10 @@ pub trait ResolverExt {
 
     /// Looks up node info by DNS name in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The result of the first successful call is returned, or a
+    /// summary of all errors otherwise.
     fn lookup_by_name_staggered(
         &self,
         name: &str,
@@ -156,7 +169,10 @@ pub trait ResolverExt {
 
     /// Looks up node info by [`NodeId`] and origin domain name.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The result of the first successful call is returned, or a
+    /// summary of all errors otherwise.
     fn lookup_by_id_staggered(
         &self,
         node_id: &NodeId,
@@ -229,8 +245,10 @@ impl ResolverExt for DnsResolver {
 
     /// Perform an ipv4 lookup with a timeout in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
-    /// The timeout is passed to every individual call to [`ResolverExt::lookup_ipv4`].
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The `timeout` is applied to each call individually. The
+    /// result of the first successful call is returned, or a summary of all errors otherwise.
     async fn lookup_ipv4_staggered<N: IntoName + Clone>(
         &self,
         host: N,
@@ -243,8 +261,10 @@ impl ResolverExt for DnsResolver {
 
     /// Perform an ipv6 lookup with a timeout in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
-    /// The timeout is passed to every individual call to [`ResolverExt::lookup_ipv6`].
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The `timeout` is applied to each call individually. The
+    /// result of the first successful call is returned, or a summary of all errors otherwise.
     async fn lookup_ipv6_staggered<N: IntoName + Clone>(
         &self,
         host: N,
@@ -257,8 +277,11 @@ impl ResolverExt for DnsResolver {
 
     /// Race an ipv4 and ipv6 lookup with a timeout in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
-    /// The timeout is passed to every individual call to [`ResolverExt::lookup_ipv4_ipv6`].
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The `timeout` is applied as stated in
+    /// [`Self::lookup_ipv4_ipv6`]. The result of the first successful call is returned, or a
+    /// summary of all errors otherwise.
     async fn lookup_ipv4_ipv6_staggered<N: IntoName + Clone>(
         &self,
         host: N,
@@ -271,15 +294,21 @@ impl ResolverExt for DnsResolver {
 
     /// Looks up node info by DNS name in a staggered fashion.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The result of the first successful call is returned, or a
+    /// summary of all errors otherwise.
     async fn lookup_by_name_staggered(&self, name: &str, delays_ms: &[u64]) -> Result<NodeAddr> {
         let f = || self.lookup_by_name(name);
         stagger_call(f, delays_ms).await
     }
 
     /// Looks up node info by [`NodeId`] and origin domain name.
     ///
-    /// The first call is done immediately, with added calls according to the staggering strategy.
+    /// From the moment this function is called, each lookup is scheduled after the delays in
+    /// [`delays_ms`] with the first call being done immediately. `[200ms, 300ms]` results in calls
+    /// at T+0ms, T+200ms and T+300ms. The result of the first successful call is returned, or a
+    /// summary of all errors otherwise.
     async fn lookup_by_id_staggered(
         &self,
         node_id: &NodeId,