From 41f76924d06ad4b267c0c1e5c83acf666c07f34e Mon Sep 17 00:00:00 2001
From: pierwill <pierwill@users.noreply.github.com>
Date: Fri, 29 Oct 2021 12:14:17 -0500
Subject: [PATCH] Document all public items in `rustc_incremental`
Also:
- Review and edit current docs
- Enforce documentation for crate
Co-authored-by: r00ster <r00ster91@protonmail.com>
Co-authored-by: Camille Gillot <gillot.camille@gmail.com>
---
.../rustc_incremental/src/assert_dep_graph.rs | 2 ++
.../src/assert_module_sources.rs | 1 +
compiler/rustc_incremental/src/lib.rs | 1 +
compiler/rustc_incremental/src/persist/fs.rs | 34 ++++++++++++++-----
.../rustc_incremental/src/persist/load.rs | 17 ++++++++--
.../rustc_incremental/src/persist/save.rs | 15 ++++++--
.../src/persist/work_product.rs | 6 +++-
7 files changed, 63 insertions(+), 13 deletions(-)
diff --git a/compiler/rustc_incremental/src/assert_dep_graph.rs b/compiler/rustc_incremental/src/assert_dep_graph.rs
index 571337a8dcbc6..7b5b015d5a509 100644
--- a/compiler/rustc_incremental/src/assert_dep_graph.rs
+++ b/compiler/rustc_incremental/src/assert_dep_graph.rs
@@ -52,6 +52,7 @@ use std::env;
use std::fs::{self, File};
use std::io::{BufWriter, Write};
+#[allow(missing_docs)]
pub fn assert_dep_graph(tcx: TyCtxt<'_>) {
tcx.dep_graph.with_ignore(|| {
if tcx.sess.opts.debugging_opts.dump_dep_graph {
@@ -262,6 +263,7 @@ fn dump_graph(query: &DepGraphQuery) {
}
}
+#[allow(missing_docs)]
pub struct GraphvizDepGraph<'q>(FxHashSet<&'q DepNode>, Vec<(&'q DepNode, &'q DepNode)>);
impl<'a, 'q> dot::GraphWalk<'a> for GraphvizDepGraph<'q> {
diff --git a/compiler/rustc_incremental/src/assert_module_sources.rs b/compiler/rustc_incremental/src/assert_module_sources.rs
index a5f3e4553ce56..2cf8f9b08e190 100644
--- a/compiler/rustc_incremental/src/assert_module_sources.rs
+++ b/compiler/rustc_incremental/src/assert_module_sources.rs
@@ -29,6 +29,7 @@ use rustc_session::cgu_reuse_tracker::*;
use rustc_span::symbol::{sym, Symbol};
use std::collections::BTreeSet;
+#[allow(missing_docs)]
pub fn assert_module_sources(tcx: TyCtxt<'_>) {
tcx.dep_graph.with_ignore(|| {
if tcx.sess.opts.incremental.is_none() {
diff --git a/compiler/rustc_incremental/src/lib.rs b/compiler/rustc_incremental/src/lib.rs
index dd3f8c937f81a..07e9f8b00ca1b 100644
--- a/compiler/rustc_incremental/src/lib.rs
+++ b/compiler/rustc_incremental/src/lib.rs
@@ -1,5 +1,6 @@
//! Support for serializing the dep-graph and reloading it.
+#![deny(missing_docs)]
#![doc(html_root_url = "https://doc.rust-lang.org/nightly/nightly-rustc/")]
#![feature(in_band_lifetimes)]
#![feature(let_else)]
diff --git a/compiler/rustc_incremental/src/persist/fs.rs b/compiler/rustc_incremental/src/persist/fs.rs
index c0137fc7a5ac8..a49a1554d5bfe 100644
--- a/compiler/rustc_incremental/src/persist/fs.rs
+++ b/compiler/rustc_incremental/src/persist/fs.rs
@@ -133,21 +133,26 @@ const QUERY_CACHE_FILENAME: &str = "query-cache.bin";
// case-sensitive (as opposed to base64, for example).
const INT_ENCODE_BASE: usize = base_n::CASE_INSENSITIVE;
+/// Returns the path to a session's dependency graph.
pub fn dep_graph_path(sess: &Session) -> PathBuf {
in_incr_comp_dir_sess(sess, DEP_GRAPH_FILENAME)
}
+/// Returns the path to a session's staging dependency graph.
+///
+/// On the difference between dep-graph and staging dep-graph,
+/// see `build_dep_graph`.
pub fn staging_dep_graph_path(sess: &Session) -> PathBuf {
in_incr_comp_dir_sess(sess, STAGING_DEP_GRAPH_FILENAME)
}
-
pub fn work_products_path(sess: &Session) -> PathBuf {
in_incr_comp_dir_sess(sess, WORK_PRODUCTS_FILENAME)
}
-
+/// Returns the path to a session's query cache.
pub fn query_cache_path(sess: &Session) -> PathBuf {
in_incr_comp_dir_sess(sess, QUERY_CACHE_FILENAME)
}
+/// Locks a given session directory.
pub fn lock_file_path(session_dir: &Path) -> PathBuf {
let crate_dir = session_dir.parent().unwrap();
@@ -166,23 +171,35 @@ pub fn lock_file_path(session_dir: &Path) -> PathBuf {
crate_dir.join(&directory_name[0..dash_indices[2]]).with_extension(&LOCK_FILE_EXT[1..])
}
+/// Returns the path for a given filename within the incremental compilation directory
+/// in the current session.
pub fn in_incr_comp_dir_sess(sess: &Session, file_name: &str) -> PathBuf {
in_incr_comp_dir(&sess.incr_comp_session_dir(), file_name)
}
+/// Returns the path for a given filename within the incremental compilation directory,
+/// not necessarily from the current session.
+///
+/// To ensure the file is part of the current session, use [`in_incr_comp_dir_sess`].
pub fn in_incr_comp_dir(incr_comp_session_dir: &Path, file_name: &str) -> PathBuf {
incr_comp_session_dir.join(file_name)
}
-/// Allocates the private session directory. The boolean in the Ok() result
-/// indicates whether we should try loading a dep graph from the successfully
-/// initialized directory, or not.
-/// The post-condition of this fn is that we have a valid incremental
-/// compilation session directory, if the result is `Ok`. A valid session
+/// Allocates the private session directory.
+///
+/// If the result of this function is `Ok`, we have a valid incremental
+/// compilation session directory. A valid session
/// directory is one that contains a locked lock file. It may or may not contain
/// a dep-graph and work products from a previous session.
-/// If the call fails, the fn may leave behind an invalid session directory.
+///
+/// This always attempts to load a dep-graph from the directory.
+/// If loading fails for some reason, we fallback to a disabled `DepGraph`.
+/// See [`rustc_interface::queries::dep_graph`].
+///
+/// If this function returns an error, it may leave behind an invalid session directory.
/// The garbage collection will take care of it.
+///
+/// [`rustc_interface::queries::dep_graph`]: ../../rustc_interface/struct.Queries.html#structfield.dep_graph
pub fn prepare_session_directory(
sess: &Session,
crate_name: &str,
@@ -661,6 +678,7 @@ fn is_old_enough_to_be_collected(timestamp: SystemTime) -> bool {
timestamp < SystemTime::now() - Duration::from_secs(10)
}
+/// Runs garbage collection for the current session.
pub fn garbage_collect_session_directories(sess: &Session) -> io::Result<()> {
debug!("garbage_collect_session_directories() - begin");
diff --git a/compiler/rustc_incremental/src/persist/load.rs b/compiler/rustc_incremental/src/persist/load.rs
index 9c6e2aeb50a76..9cae4e9181899 100644
--- a/compiler/rustc_incremental/src/persist/load.rs
+++ b/compiler/rustc_incremental/src/persist/load.rs
@@ -18,13 +18,24 @@ use super::work_product;
type WorkProductMap = FxHashMap<WorkProductId, WorkProduct>;
#[derive(Debug)]
+/// Represents the result of an attempt to load incremental compilation data.
pub enum LoadResult<T> {
- Ok { data: T },
+ /// Loading was successful.
+ Ok {
+ #[allow(missing_docs)]
+ data: T,
+ },
+ /// The file either didn't exist or was produced by an incompatible compiler version.
DataOutOfDate,
- Error { message: String },
+ /// An error occured.
+ Error {
+ #[allow(missing_docs)]
+ message: String,
+ },
}
impl<T: Default> LoadResult<T> {
+ /// Accesses the data returned in [`LoadResult::Ok`].
pub fn open(self, sess: &Session) -> T {
// Check for errors when using `-Zassert-incremental-state`
match (sess.opts.assert_incr_state, &self) {
@@ -99,6 +110,7 @@ pub enum MaybeAsync<T> {
}
impl<T> MaybeAsync<LoadResult<T>> {
+ /// Accesses the data returned in [`LoadResult::Ok`] in an asynchronous way if possible.
pub fn open(self) -> LoadResult<T> {
match self {
MaybeAsync::Sync(result) => result,
@@ -109,6 +121,7 @@ impl<T> MaybeAsync<LoadResult<T>> {
}
}
+/// An asynchronous type for computing the dependency graph.
pub type DepGraphFuture = MaybeAsync<LoadResult<(SerializedDepGraph, WorkProductMap)>>;
/// Launch a thread and load the dependency graph in the background.
diff --git a/compiler/rustc_incremental/src/persist/save.rs b/compiler/rustc_incremental/src/persist/save.rs
index 6c683058b12d6..9601a49267f08 100644
--- a/compiler/rustc_incremental/src/persist/save.rs
+++ b/compiler/rustc_incremental/src/persist/save.rs
@@ -13,9 +13,13 @@ use super::file_format;
use super::fs::*;
use super::work_product;
-/// Save and dump the DepGraph.
+/// Saves and writes the [`DepGraph`] to the file system.
///
-/// No query must be invoked after this function.
+/// This function saves both the dep-graph and the query result cache,
+/// and drops the result cache.
+///
+/// This function should only run after all queries have completed.
+/// Trying to execute a query afterwards would attempt to read the result cache we just dropped.
pub fn save_dep_graph(tcx: TyCtxt<'_>) {
debug!("save_dep_graph()");
tcx.dep_graph.with_ignore(|| {
@@ -75,6 +79,7 @@ pub fn save_dep_graph(tcx: TyCtxt<'_>) {
})
}
+/// Saves the work product index.
pub fn save_work_product_index(
sess: &Session,
dep_graph: &DepGraph,
@@ -139,6 +144,12 @@ fn encode_query_cache(tcx: TyCtxt<'_>, encoder: &mut FileEncoder) -> FileEncodeR
tcx.sess.time("incr_comp_serialize_result_cache", || tcx.serialize_query_result_cache(encoder))
}
+/// Builds the dependency graph.
+///
+/// This function breates the *staging dep-graph*. When the dep-graph is modified by a query
+/// execution, the new dependency information is not kept in memory but directly
+/// output to this file. `save_dep_graph` then finalizes the staging dep-graph
+/// and moves it to the permanent dep-graph path
pub fn build_dep_graph(
sess: &Session,
prev_graph: SerializedDepGraph,
diff --git a/compiler/rustc_incremental/src/persist/work_product.rs b/compiler/rustc_incremental/src/persist/work_product.rs
index 19d64bda56d6d..85b44ed753192 100644
--- a/compiler/rustc_incremental/src/persist/work_product.rs
+++ b/compiler/rustc_incremental/src/persist/work_product.rs
@@ -1,4 +1,6 @@
-//! This module contains files for saving intermediate work-products.
+//! Functions for saving and removing intermediate [work products].
+//!
+//! [work products]: WorkProduct
use crate::persist::fs::*;
use rustc_fs_util::link_or_copy;
@@ -7,6 +9,7 @@ use rustc_session::Session;
use std::fs as std_fs;
use std::path::PathBuf;
+/// Copies a CGU work product to the incremental compilation directory, so next compilation can find and reuse it.
pub fn copy_cgu_workproduct_to_incr_comp_cache_dir(
sess: &Session,
cgu_name: &str,
@@ -40,6 +43,7 @@ pub fn copy_cgu_workproduct_to_incr_comp_cache_dir(
Some((work_product_id, work_product))
}
+/// Removes files for a given work product.
pub fn delete_workproduct_files(sess: &Session, work_product: &WorkProduct) {
if let Some(ref file_name) = work_product.saved_file {
let path = in_incr_comp_dir_sess(sess, file_name);