Browse Source

fix docs #(67)

pull/80/head
Sebastian Thiel 4 weeks ago
parent
commit
01db10a274
No known key found for this signature in database GPG Key ID: 9CB5EE7895E8268B
  1. 22
      git-features/src/parallel/mod.rs
  2. 5
      git-odb/src/borrowed.rs
  3. 4
      git-odb/src/pack/data/encode.rs

22
git-features/src/parallel/mod.rs

@ -3,11 +3,11 @@
//! ### in_parallel(…)
//!
//! The [`in_parallel(…)`][in_parallel()] is the typical fan-out-fan-in mode of parallelism, with thread local storage
//! made available to a `consume(…)` function to process input. The result is sent to the [`Reducer`] running in the calling
//! made available to a `consume(…)` function to process input. The result is sent to the [`Reduce`] running in the calling
//! thread to aggregate the results into a single output, which is returned by [`in_parallel()`].
//!
//! Interruptions can be achieved by checking for [`is_interrupted()`][crate::interrupt::is_triggered()] in the input iterator
//! or by letting the reducers [`feed(…)`][Reducer::feed()]` method fail.
//! or by letting the reducers [`feed(…)`][Reduce::feed()]` method fail.
//!
//! It gets a boost in usability as it allows threads to borrow variables from the stack, most commonly the repository itself
//! or the data to work on.
@ -16,13 +16,13 @@
//! operation which runs as fast as possible, which is cancellable only by merit of stopping the input or stopping the output
//! aggregation.
//!
//! ### `SteppedReduce`
//! ### `reduce::Stepwise`
//!
//! The [`SteppedReduce`] iterator works exactly as [`in_parallel()`] except that the processing of the output produced by
//! The [`Stepwise`][reduce::Stepwise] iterator works exactly as [`in_parallel()`] except that the processing of the output produced by
//! `consume(I, &mut State) -> O` is made accessible by the `Iterator` trait's `next()` method. As produced work is not
//! buffered, the owner of the iterator controls the progress made.
//!
//! Getting the final output of the [`Reducer`] is achieved through the consuming [`SteppedReduce::finalize()`] method, which
//! Getting the final output of the [`Reduce`] is achieved through the consuming [`Stepwise::finalize()`][reduce::Stepwise::finalize()] method, which
//! is functionally equivalent to calling [`in_parallel()`].
//!
//! In an `async` context this means that progress is only made each time `next()` is called on the iterator, while merely dropping
@ -135,7 +135,7 @@ pub mod reduce {
mod stepped {
use crate::parallel::num_threads;
/// An iterator adaptor to allow running computations using [`in_parallel()`] in a step-wise manner, see the [module docs][crate::parallel]
/// An iterator adaptor to allow running computations using [`in_parallel()`][crate::parallel::in_parallel()] in a step-wise manner, see the [module docs][crate::parallel]
/// for details.
pub struct Stepwise<Reduce: super::Reduce> {
/// This field is first to assure it's dropped first and cause threads that are dropped next to stop their loops
@ -167,7 +167,7 @@ pub mod reduce {
impl<Reduce: super::Reduce> Stepwise<Reduce> {
/// Instantiate a new iterator and start working in threads.
/// For a description of parameters, see [`in_parallel()`].
/// For a description of parameters, see [`in_parallel()`][crate::parallel::in_parallel()].
pub fn new<InputIter, ThreadStateFn, ConsumeFn, I, O, S>(
input: InputIter,
thread_limit: Option<usize>,
@ -315,16 +315,16 @@ pub mod reduce {
/// An trait for aggregating items commonly produced in threads into a single result, without itself
/// needing to be thread safe.
pub trait Reduce {
/// The type fed to the reducer in the [`feed()`][Reducer::feed()] method.
/// The type fed to the reducer in the [`feed()`][Reduce::feed()] method.
///
/// It's produced by a function that may run on multiple threads.
type Input;
/// The type produced in Ok(…) by [`feed()`][Reducer::feed()].
/// The type produced in Ok(…) by [`feed()`][Reduce::feed()].
/// Most reducers by nature use `()` here as the value is in the aggregation.
/// However, some may use it to collect statistics only and return their Input
/// in some form as a result here for [`SteppedReduce`] to be useful.
/// in some form as a result here for [`Stepwise`] to be useful.
type FeedProduce;
/// The type produced once by the [`finalize()`][Reducer::finalize()] method.
/// The type produced once by the [`finalize()`][Reduce::finalize()] method.
///
/// For traditional reducers, this is the value produced by the entire operation.
/// For those made for step-wise iteration this may be aggregated statistics.

5
git-odb/src/borrowed.rs

@ -10,11 +10,12 @@ pub struct Object<'a> {
}
impl<'a> Object<'a> {
/// Decodes the data in the backing slice into a [`crate::borrowed::Object`], allowing to access all of its data
/// Decodes the data in the backing slice into a [`git_object::borrowed::Object`], allowing to access all of its data
/// conveniently. The cost of parsing an object is negligible.
///
/// **Note** that [owned, decoded objects][git_object::owned::Object] can be created from a [`crate::borrowed::Object`]
/// using [`crate::borrowed::Object::into_owned()`].
///
/// using [`git_object::borrowed::Object::into_owned()`].
pub fn decode(&self) -> Result<git_object::borrowed::Object<'_>, git_object::borrowed::Error> {
Ok(match self.kind {
git_object::Kind::Tree => {

4
git-odb/src/pack/data/encode.rs

@ -2,7 +2,7 @@ use git_features::progress::Progress;
use git_hash::{oid, ObjectId};
use std::convert::TryInto;
/// The error returned the pack generation functions in [this module][crate::pack::generate].
/// The error returned the pack generation functions in [this module][crate::pack::data::encode].
#[derive(Debug, thiserror::Error)]
#[allow(missing_docs)]
pub enum Error {
@ -10,7 +10,7 @@ pub enum Error {
Tbd,
}
/// Configuration options for the pack generation functions provied in [this module][crate::pack::generate].
/// Configuration options for the pack generation functions provied in [this module][crate::pack::data::encode].
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
pub struct Options {

Loading…
Cancel
Save