libp2p_kad/query/
peers.rs

1// Copyright 2019 Parity Technologies (UK) Ltd.
2//
3// Permission is hereby granted, free of charge, to any person obtaining a
4// copy of this software and associated documentation files (the "Software"),
5// to deal in the Software without restriction, including without limitation
6// the rights to use, copy, modify, merge, publish, distribute, sublicense,
7// and/or sell copies of the Software, and to permit persons to whom the
8// Software is furnished to do so, subject to the following conditions:
9//
10// The above copyright notice and this permission notice shall be included in
11// all copies or substantial portions of the Software.
12//
13// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
19// DEALINGS IN THE SOFTWARE.
20
21//! Peer selection strategies for queries in the form of iterator-like state machines.
22//!
23//! Using a peer iterator in a query involves performing the following steps
24//! repeatedly and in an alternating fashion:
25//!
26//!   1. Calling `next` to observe the next state of the iterator and determine
27//!      what to do, which is to either issue new requests to peers or continue
28//!      waiting for responses.
29//!
30//!   2. When responses are received or requests fail, providing input to the
31//!      iterator via the `on_success` and `on_failure` callbacks,
32//!      respectively, followed by repeating step (1).
33//!
34//! When a call to `next` returns [`Finished`], no more peers can be obtained
35//! from the iterator and the results can be obtained from `into_result`.
36//!
37//! A peer iterator can be finished prematurely at any time through `finish`.
38//!
39//! [`Finished`]: PeersIterState::Finished
40
41pub(crate) mod closest;
42pub(crate) mod fixed;
43use libp2p_identity::PeerId;
44use std::borrow::Cow;
45
46/// The state of a peer iterator.
47#[derive(Debug, Clone, PartialEq, Eq)]
48pub enum PeersIterState<'a> {
49    /// The iterator is waiting for results.
50    ///
51    /// `Some(peer)` indicates that the iterator is now waiting for a result
52    /// from `peer`, in addition to any other peers for which it is already
53    /// waiting for results.
54    ///
55    /// `None` indicates that the iterator is waiting for results and there is no
56    /// new peer to contact, despite the iterator not being at capacity w.r.t.
57    /// the permitted parallelism.
58    Waiting(Option<Cow<'a, PeerId>>),
59
60    /// The iterator is waiting for results and is at capacity w.r.t. the
61    /// permitted parallelism.
62    WaitingAtCapacity,
63
64    /// The iterator finished.
65    Finished,
66}
libp2p_kad/query/peers.rs

libp2p_kad/query/
peers.rs
