gsadmin/garage
1
0
Fork 0
mirror of https://github.com/deuxfleurs-org/garage.git synced 2026-08-08 13:53:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add missing backticks in documentation

Browse Source 
this improve readability of documentation.
enable associated clippy lint `doc_markdown`
This commit is contained in:
Gwen Lg
2026-01-25 23:46:05 +01:00
committed by Alex
parent 6cde00073f
commit 08fd6e659f
58 changed files with 175 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/rpc/layout/graph_algo.rs
+6 -6
View File
@@ -42,7 +42,7 @@ impl Edge for WeightedEdge {}
/// Struct for the graph structure. We do encapsulation here to be able to both
/// provide user friendly Vertex enum to address vertices, and to use internally usize
/// indices and Vec instead of HashMap in the graph algorithm to optimize execution speed.
/// indices and Vec instead of `HashMap` in the graph algorithm to optimize execution speed.
pub struct Graph<E: Edge> {
vertex_to_id: HashMap<Vertex, usize>,
id_to_vertex: Vec<Vertex>,
@@ -253,7 +253,7 @@ impl Graph<FlowEdge> {
/// This function takes a flow, and a cost function on the edges, and tries to find an
/// equivalent flow with a better cost, by finding improving overflow cycles. It uses
/// as subroutine the Bellman Ford algorithm run up to path_length.
/// as subroutine the Bellman Ford algorithm run up to `path_length`.
/// We assume that the cost of edge (u,v) is the opposite of the cost of (v,u), and
/// only one needs to be present in the cost function.
pub fn optimize_flow_with_cost(
@@ -290,7 +290,7 @@ impl Graph<FlowEdge> {
Ok(())
}
/// Construct the weighted graph G_f from the flow and the cost function
/// Construct the weighted graph `G_f` from the flow and the cost function
fn build_cost_graph(&self, cost: &CostFunction) -> Result<Graph<WeightedEdge>, String> {
let mut g = Graph::<WeightedEdge>::new(&self.id_to_vertex);
let nb_vertices = self.id_to_vertex.len();
@@ -323,11 +323,11 @@ impl Graph<WeightedEdge> {
Ok(())
}
/// This function lists the negative cycles it manages to find after path_length
/// This function lists the negative cycles it manages to find after `path_length`
/// iterations of the main loop of the Bellman-Ford algorithm. For the classical
/// algorithm, path_length needs to be equal to the number of vertices. However,
/// algorithm, `path_length` needs to be equal to the number of vertices. However,
/// for particular graph structures like in our case, the algorithm is still correct
/// when path_length is the length of the longest possible simple path.
/// when `path_length` is the length of the longest possible simple path.
/// See the formal description of the algorithm for more details.
fn list_negative_cycles(&self, path_length: usize) -> Vec<Vec<Vertex>> {
let nb_vertices = self.graph.len();
src/rpc/layout/helper.rs
+1 -1
View File
@@ -162,7 +162,7 @@ impl LayoutHelper {
}
/// Returns the latest layout version for which it is safe to read data from,
/// i.e. the version whose version number is sync_map_min
/// i.e. the version whose version number is `sync_map_min`
pub fn read_version(&self) -> Result<&LayoutVersion, Error> {
let sync_min = self.sync_map_min;
let versions = self.versions()?;
src/rpc/layout/mod.rs
+9 -9
View File
@@ -23,7 +23,7 @@ pub use version::*;
/// A partition id, which is stored on 16 bits
/// i.e. we have up to 2**16 partitions.
/// (in practice we have exactly 2**PARTITION_BITS partitions)
/// (in practice we have exactly 2**`PARTITION_BITS` partitions)
pub type Partition = u16;
// TODO: make this constant parametrizable in the config file
@@ -114,7 +114,7 @@ mod v09 {
/// to know to what extent does it change with the layout update.
pub partition_size: u64,
/// Parameters used to compute the assignment currently given by
/// ring_assignment_data
/// `ring_assignment_data`
pub parameters: LayoutParameters,
pub roles: LwwMap<Uuid, NodeRoleV>,
@@ -229,7 +229,7 @@ mod v010 {
use std::collections::BTreeMap;
pub use v09::{LayoutParameters, NodeRole, NodeRoleV, ZoneRedundancy};
/// Number of old (non-live) versions to keep, see LayoutHistory::old_versions
/// Number of old (non-live) versions to keep, see `LayoutHistory::old_versions`
pub const OLD_VERSION_COUNT: usize = 5;
/// The history of cluster layouts, with trackers to keep a record
@@ -238,8 +238,8 @@ mod v010 {
pub struct LayoutHistory {
/// The versions currently in use in the cluster
pub versions: Vec<LayoutVersion>,
/// At most 5 of the previous versions, not used by the garage_table
/// module, but useful for the garage_block module to find data blocks
/// At most 5 of the previous versions, not used by the `garage_table`
/// module, but useful for the `garage_block` module to find data blocks
/// that have not yet been moved
pub old_versions: Vec<LayoutVersion>,
@@ -260,7 +260,7 @@ mod v010 {
/// Roles assigned to nodes in this version
pub roles: LwwMap<Uuid, NodeRoleV>,
/// Parameters used to compute the assignment currently given by
/// ring_assignment_data
/// `ring_assignment_data`
pub parameters: LayoutParameters,
/// The number of replicas for each data partition
@@ -269,17 +269,17 @@ mod v010 {
/// to know to what extent does it change with the layout update.
pub partition_size: u64,
/// node_id_vec: a vector of node IDs with a role assigned
/// `node_id_vec`: a vector of node IDs with a role assigned
/// in the system (this includes gateway nodes).
/// The order here is different than the vec stored by `roles`, because:
/// 1. non-gateway nodes are first so that they have lower numbers
/// 2. nodes that don't have a role are excluded (but they need to
/// stay in the CRDT as tombstones)
pub node_id_vec: Vec<Uuid>,
/// number of non-gateway nodes, which are the first ids in node_id_vec
/// number of non-gateway nodes, which are the first ids in `node_id_vec`
pub nongateway_node_count: usize,
/// The assignation of data partitions to nodes, the values
/// are indices in node_id_vec
/// are indices in `node_id_vec`
#[serde(with = "serde_bytes")]
pub ring_assignment_data: Vec<CompactNodeType>,
}
src/rpc/layout/version.rs
+7 -7
View File
@@ -164,7 +164,7 @@ impl LayoutVersion {
total_capacity
}
/// Returns the effective value of the zone_redundancy parameter
/// Returns the effective value of the `zone_redundancy` parameter
pub(crate) fn effective_zone_redundancy(&self) -> usize {
match self.parameters.zone_redundancy {
ZoneRedundancy::AtLeast(v) => v,
@@ -311,7 +311,7 @@ impl LayoutVersion {
/// the former assignment (if any) to minimize the amount of
/// data to be moved.
/// Staged role changes must be merged with nodes roles before calling this function,
/// hence it must only be called from apply_staged_changes() and hence is not public.
/// hence it must only be called from `apply_staged_changes()` and hence is not public.
fn calculate_partition_assignment(&mut self) -> Result<Message, Error> {
// We update the node ids, since the node role list might have changed with the
// changes in the layout. We retrieve the old_assignment reframed with new ids
@@ -402,11 +402,11 @@ impl LayoutVersion {
Ok(msg)
}
/// The LwwMap of node roles might have changed. This function updates the node_id_vec
/// The `LwwMap` of node roles might have changed. This function updates the `node_id_vec`
/// and returns the assignment given by ring, with the new indices of the nodes, and
/// None if the node is not present anymore.
/// We work with the assumption that only this function and calculate_new_assignment
/// do modify assignment_ring and node_id_vec.
/// We work with the assumption that only this function and `calculate_new_assignment`
/// do modify `assignment_ring` and `node_id_vec`.
fn update_node_id_vec(&mut self) -> Result<Option<Vec<Vec<usize>>>, Error> {
// (1) We compute the new node list
// Non gateway nodes should be coded on 8bits, hence they must be first in the list
@@ -488,7 +488,7 @@ impl LayoutVersion {
}
/// This function generates ids for the zone of the nodes appearing in
/// self.node_id_vec.
/// `self.node_id_vec`.
pub(crate) fn generate_nongateway_zone_ids(
&self,
) -> Result<(Vec<String>, HashMap<String, usize>), Error> {
@@ -560,7 +560,7 @@ impl LayoutVersion {
/// Generates the graph to compute the maximal flow corresponding to the optimal
/// partition assignment.
/// exclude_assoc is the set of (partition, node) association that we are forbidden
/// `exclude_assoc` is the set of (partition, node) association that we are forbidden
/// to use (hence we do not add the corresponding edge to the graph). This parameter
/// is used to compute a first flow that uses only edges appearing in the previous
/// assignment. This produces a solution that heuristically should be close to the
src/rpc/metrics.rs
+1 -1
View File
@@ -1,6 +1,6 @@
use opentelemetry::{global, metrics::*};
/// TableMetrics reference all counter used for metrics
/// `TableMetrics` reference all counter used for metrics
pub struct RpcMetrics {
pub(crate) rpc_counter: Counter<u64>,
pub(crate) rpc_timeout_counter: Counter<u64>,
src/rpc/rpc_helper.rs
+4 -4
View File
@@ -66,7 +66,7 @@ impl Clone for RequestStrategy<()> {
}
impl RequestStrategy<()> {
/// Create a RequestStrategy with default timeout and not interrupting when quorum reached
/// Create a `RequestStrategy` with default timeout and not interrupting when quorum reached
pub fn with_priority(prio: RequestPriority) -> Self {
RequestStrategy {
rs_quorum: None,
@@ -109,7 +109,7 @@ impl<T> RequestStrategy<T> {
self.rs_timeout = Timeout::Custom(timeout);
self
}
/// Extract drop_on_complete item
/// Extract `drop_on_complete` item
fn extract_drop_on_complete(self) -> (RequestStrategy<()>, T) {
(
RequestStrategy {
@@ -272,7 +272,7 @@ impl RpcHelper {
/// Make a RPC call to multiple servers, returning either a Vec of responses,
/// or an error if quorum could not be reached due to too many errors
///
/// If RequestStrategy has send_all_at_once set, then all requests will be
/// If `RequestStrategy` has `send_all_at_once` set, then all requests will be
/// sent at once, and `try_call_many` will return as soon as a quorum of
/// responses is achieved, dropping and cancelling the remaining requests.
///
@@ -413,7 +413,7 @@ impl RpcHelper {
/// Make a RPC call to multiple servers, returning either a Vec of responses,
/// or an error if quorum could not be reached due to too many errors
///
/// Contrary to try_call_many, this function is especially made for broadcast
/// Contrary to `try_call_many`, this function is especially made for broadcast
/// write operations. In particular:
///
/// - The request are sent to all specified nodes as soon as `try_write_many_sets`
src/rpc/system.rs
+4 -4
View File
@@ -57,7 +57,7 @@ pub enum SystemRpc {
Ok,
/// Request to connect to a specific node (in `<pubkey>@<host>:<port>` format, pubkey = full-length node ID)
Connect(String),
/// Advertise Garage status. Answered with another AdvertiseStatus.
/// Advertise Garage status. Answered with another `AdvertiseStatus`.
/// Exchanged with every node on a regular basis.
AdvertiseStatus(NodeStatus),
/// Get known nodes states
@@ -65,9 +65,9 @@ pub enum SystemRpc {
/// Return known nodes
ReturnKnownNodes(Vec<KnownNodeInfo>),
/// Ask other node its cluster layout. Answered with AdvertiseClusterLayout
/// Ask other node its cluster layout. Answered with `AdvertiseClusterLayout`
PullClusterLayout,
/// Advertisement of cluster layout. Sent spontanously or in response to PullClusterLayout
/// Advertisement of cluster layout. Sent spontanously or in response to `PullClusterLayout`
AdvertiseClusterLayout(LayoutHistory),
/// Ask other node its cluster layout update trackers.
PullClusterLayoutTrackers,
@@ -908,7 +908,7 @@ impl NodeStatus {
}
/// Obtain the list of currently available IP addresses on all non-loopback
/// interfaces, optionally filtering them to be inside a given IpNet.
/// interfaces, optionally filtering them to be inside a given `IpNet`.
fn get_default_ip(filter_ipnet: Option<ipnet::IpNet>) -> Option<IpAddr> {
pnet_datalink::interfaces()
.into_iter()
src/rpc/system_metrics.rs
+1 -1
View File
@@ -5,7 +5,7 @@ use opentelemetry::{global, metrics::*, KeyValue};
use crate::system::{ClusterHealthStatus, System};
/// TableMetrics reference all counter used for metrics
/// `TableMetrics` reference all counter used for metrics
pub struct SystemMetrics {
// Static values
pub(crate) _garage_build_info: ValueObserver<u64>,