gaspersic/solana
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Eliminate doc warnings and fix some markdown (#18566)

Browse Source 
* Fix link target in doc comment

* Fix formatting of log examples in process_instruction

* Fix doc markdown in solana-gossip

* Fix doc markdown in solana-runtime

* Escape square braces in doc comments to avoid warnings

* Surround 'account references' doc items in code spans to avoid warnings

* Fix code block in loader_upgradeable_instruction

* Fix doctest for loader_upgradable_instruction
This commit is contained in:
Brian Anderson
2021-07-15 19:40:07 -05:00
committed by GitHub
parent aeb30fa873
commit 37ee0b5599
12 changed files with 208 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
gossip/src/crds_gossip.rs
View File

@ -1,4 +1,5 @@
//! Crds Gossip
//! Crds Gossip.
//!
//! This module ties together Crds and the push and pull gossip overlays. The interface is
//! designed to run with a simulator or over a UDP network connection with messages up to a
//! packet::PACKET_DATA_SIZE size.
@ -39,7 +40,8 @@ pub struct CrdsGossip {
}
impl CrdsGossip {
/// process a push message to the network
/// Process a push message to the network.
///
/// Returns unique origins' pubkeys of upserted values.
pub fn process_push_message(
&self,
@ -54,7 +56,7 @@ impl CrdsGossip {
.collect()
}
/// remove redundant paths in the network
/// Remove redundant paths in the network.
pub fn prune_received_cache<I>(
&self,
self_pubkey: &Pubkey,
@ -145,7 +147,7 @@ impl CrdsGossip {
Ok(())
}
/// add the `from` to the peer's filter of nodes
/// Add the `from` to the peer's filter of nodes.
pub fn process_prune_msg(
&self,
self_pubkey: &Pubkey,
@ -167,8 +169,7 @@ impl CrdsGossip {
}
}
/// refresh the push active set
/// * ratio - number of actives to rotate
/// Refresh the push active set.
pub fn refresh_push_active_set(
&self,
self_pubkey: &Pubkey,
@ -188,7 +189,7 @@ impl CrdsGossip {
)
}
/// generate a random request
/// Generate a random request.
#[allow(clippy::too_many_arguments)]
pub fn new_pull_request(
&self,
@ -216,14 +217,15 @@ impl CrdsGossip {
)
}
/// time when a request to `from` was initiated
/// Time when a request to `from` was initiated.
///
/// This is used for weighted random selection during `new_pull_request`
/// It's important to use the local nodes request creation time as the weight
/// instead of the response received time otherwise failed nodes will increase their weight.
pub fn mark_pull_request_creation_time(&self, from: Pubkey, now: u64) {
self.pull.mark_pull_request_creation_time(from, now)
}
/// process a pull request and create a response
/// Process a pull request and create a response.
pub fn process_pull_requests<I>(&self, callers: I, now: u64)
where
I: IntoIterator<Item = CrdsValue>,
@ -255,7 +257,7 @@ impl CrdsGossip {
.filter_pull_responses(&self.crds, timeouts, response, now, process_pull_stats)
}
/// process a pull response
/// Process a pull response.
pub fn process_pull_responses(
&self,
from: &Pubkey,
@ -322,14 +324,15 @@ impl CrdsGossip {
}
}
/// Computes a normalized(log of actual stake) stake
/// Computes a normalized (log of actual stake) stake.
pub fn get_stake<S: std::hash::BuildHasher>(id: &Pubkey, stakes: &HashMap<Pubkey, u64, S>) -> f32 {
// cap the max balance to u32 max (it should be plenty)
let bal = f64::from(u32::max_value()).min(*stakes.get(id).unwrap_or(&0) as f64);
1_f32.max((bal as f32).ln())
}
/// Computes bounded weight given some max, a time since last selected, and a stake value
/// Computes bounded weight given some max, a time since last selected, and a stake value.
///
/// The minimum stake is 1 and not 0 to allow 'time since last' picked to factor in.
pub fn get_weight(max_weight: f32, time_since_last_selected: u32, stake: f32) -> f32 {
let mut weight = time_since_last_selected as f32 * stake;

17
gossip/src/crds_gossip_pull.rs
View File

@ -1,7 +1,9 @@
//! Crds Gossip Pull overlay
//! Crds Gossip Pull overlay.
//!
//! This module implements the anti-entropy protocol for the network.
//!
//! The basic strategy is as follows:
//!
//! 1. Construct a bloom filter of the local data set
//! 2. Randomly ask a node on the network for data that is not contained in the bloom filter.
//!
@ -186,7 +188,7 @@ pub struct ProcessPullStats {
}
pub struct CrdsGossipPull {
/// timestamp of last request
/// Timestamp of last request
pull_request_time: RwLock<LruCache<Pubkey, /*timestamp:*/ u64>>,
// Hash value and record time (ms) of the pull responses which failed to be
// inserted in crds table; Preserved to stop the sender to send back the
@ -210,7 +212,7 @@ impl Default for CrdsGossipPull {
}
}
impl CrdsGossipPull {
/// generate a random request
/// Generate a random request
#[allow(clippy::too_many_arguments)]
pub(crate) fn new_pull_request(
&self,
@ -326,7 +328,8 @@ impl CrdsGossipPull {
.collect()
}
/// time when a request to `from` was initiated
/// Time when a request to `from` was initiated.
///
/// This is used for weighted random selection during `new_pull_request`
/// It's important to use the local nodes request creation time as the weight
/// instead of the response received time otherwise failed nodes will increase their weight.
@ -334,7 +337,7 @@ impl CrdsGossipPull {
self.pull_request_time.write().unwrap().put(from, now);
}
/// process a pull request
/// Process a pull request
pub(crate) fn process_pull_requests<I>(crds: &RwLock<Crds>, callers: I, now: u64)
where
I: IntoIterator<Item = CrdsValue>,
@ -409,7 +412,7 @@ impl CrdsGossipPull {
(active_values, expired_values, failed_inserts)
}
/// process a vec of pull responses
/// Process a vec of pull responses
pub(crate) fn process_pull_responses(
&self,
crds: &RwLock<Crds>,
@ -499,7 +502,7 @@ impl CrdsGossipPull {
filters.into()
}
/// filter values that fail the bloom filter up to max_bytes
/// Filter values that fail the bloom filter up to `max_bytes`.
fn filter_crds_values(
crds: &RwLock<Crds>,
filters: &[(CrdsValue, CrdsFilter)],

27
gossip/src/crds_gossip_push.rs
View File

@ -1,9 +1,12 @@
//! Crds Gossip Push overlay
//! Crds Gossip Push overlay.
//!
//! This module is used to propagate recently created CrdsValues across the network
//! Eager push strategy is based on Plumtree
//! http://asc.di.fct.unl.pt/~jleitao/pdf/srds07-leitao.pdf
//! Eager push strategy is based on [Plumtree].
//!
//! [Plumtree]: http://asc.di.fct.unl.pt/~jleitao/pdf/srds07-leitao.pdf
//!
//! Main differences are:
//!
//! 1. There is no `max hop`. Messages are signed with a local wallclock. If they are outside of
//! the local nodes wallclock window they are dropped silently.
//! 2. The prune set is stored in a Bloom filter.
@ -50,14 +53,15 @@ pub const CRDS_GOSSIP_PRUNE_MIN_INGRESS_NODES: usize = 3;
const PUSH_ACTIVE_TIMEOUT_MS: u64 = 60_000;
pub struct CrdsGossipPush {
/// max bytes per message
/// Max bytes per message
max_bytes: usize,
/// active set of validators for push
/// Active set of validators for push
active_set: RwLock<IndexMap<Pubkey, AtomicBloom<Pubkey>>>,
/// Cursor into the crds table for values to push.
crds_cursor: Mutex<Cursor>,
/// Cache that tracks which validators a message was received from
/// bool indicates it has been pruned.
///
/// This cache represents a lagging view of which validators
/// currently have this node in their `active_set`
#[allow(clippy::type_complexity)]
@ -199,7 +203,8 @@ impl CrdsGossipPush {
now.saturating_sub(self.msg_timeout)..=now.saturating_add(self.msg_timeout)
}
/// process a push message to the network
/// Process a push message to the network.
///
/// Returns origins' pubkeys of upserted values.
pub(crate) fn process_push_message(
&self,
@ -246,6 +251,7 @@ impl CrdsGossipPush {
}
/// New push message to broadcast to peers.
///
/// Returns a list of Pubkeys for the selected peers and a list of values to send to all the
/// peers.
/// The list of push messages is created such that all the randomly selected peers have not
@ -306,7 +312,7 @@ impl CrdsGossipPush {
push_messages
}
/// add the `from` to the peer's filter of nodes
/// Add the `from` to the peer's filter of nodes.
pub fn process_prune_msg(&self, self_pubkey: &Pubkey, peer: &Pubkey, origins: &[Pubkey]) {
if let Some(filter) = self.active_set.read().unwrap().get(peer) {
for origin in origins {
@ -322,7 +328,10 @@ impl CrdsGossipPush {
cmp::min(num_active, (num_active - active_set_len) + num)
}
/// refresh the push active set
/// Refresh the push active set.
///
/// # Arguments
///
/// * ratio - active_set.len()/ratio is the number of actives to rotate
pub(crate) fn refresh_push_active_set(
&self,
@ -429,7 +438,7 @@ impl CrdsGossipPush {
.collect()
}
/// purge received push message cache
/// Purge received push message cache
pub(crate) fn purge_old_received_cache(&self, min_time: u64) {
self.received_cache.lock().unwrap().retain(|_, v| {
v.retain(|_, (_, t)| *t > min_time);