dirstate-v2: Change the on-disk format to be tree-shaped

Nodes are stored not only for tracked files but also for their ancestor
directories. A node has "pointers" (byte count from the start of the file)
to its direct child nodes. Everything can be accessed with zero copy.

Differential Revision: https://phab.mercurial-scm.org/D10722

rust/hg-core/src/dirstate_tree/dirstate_map.rs

@@ -1,665 +1,655 b''
 use bytes_cast::BytesCast;
 use micro_timer::timed;
 use std::borrow::Cow;
 use std::convert::TryInto;
 use std::path::PathBuf;
 
-use super::on_disk::V2_FORMAT_MARKER;
+use super::on_disk;
 use super::path_with_basename::WithBasename;
 use crate::dirstate::parsers::clear_ambiguous_mtime;
 use crate::dirstate::parsers::pack_entry;
 use crate::dirstate::parsers::packed_entry_size;
 use crate::dirstate::parsers::parse_dirstate_entries;
 use crate::dirstate::parsers::Timestamp;
-use crate::errors::HgError;
 use crate::matchers::Matcher;
 use crate::utils::hg_path::{HgPath, HgPathBuf};
-use crate::utils::SliceExt;
 use crate::CopyMapIter;
 use crate::DirstateEntry;
 use crate::DirstateError;
 use crate::DirstateMapError;
 use crate::DirstateParents;
 use crate::DirstateStatus;
 use crate::EntryState;
 use crate::FastHashMap;
 use crate::PatternFileWarning;
 use crate::StateMapIter;
 use crate::StatusError;
 use crate::StatusOptions;
 
 pub struct DirstateMap<'on_disk> {
     /// Contents of the `.hg/dirstate` file
-    on_disk: &'on_disk [u8],
+    pub(super) on_disk: &'on_disk [u8],
 
     pub(super) root: ChildNodes<'on_disk>,
 
     /// Number of nodes anywhere in the tree that have `.entry.is_some()`.
-    nodes_with_entry_count: usize,
+    pub(super) nodes_with_entry_count: u32,
 
     /// Number of nodes anywhere in the tree that have
     /// `.copy_source.is_some()`.
-    nodes_with_copy_source_count: usize,
+    pub(super) nodes_with_copy_source_count: u32,
 }
 
 /// Using a plain `HgPathBuf` of the full path from the repository root as a
 /// map key would also work: all paths in a given map have the same parent
 /// path, so comparing full paths gives the same result as comparing base
 /// names. However `HashMap` would waste time always re-hashing the same
 /// string prefix.
 pub(super) type NodeKey<'on_disk> = WithBasename<Cow<'on_disk, HgPath>>;
 pub(super) type ChildNodes<'on_disk> =
     FastHashMap<NodeKey<'on_disk>, Node<'on_disk>>;
 
 /// Represents a file or a directory
 #[derive(Default)]
 pub(super) struct Node<'on_disk> {
     /// `None` for directories
     pub(super) entry: Option<DirstateEntry>,
 
     pub(super) copy_source: Option<Cow<'on_disk, HgPath>>,
 
     pub(super) children: ChildNodes<'on_disk>,
 
     /// How many (non-inclusive) descendants of this node are tracked files
-    tracked_descendants_count: usize,
+    pub(super) tracked_descendants_count: u32,
 }
 
 impl<'on_disk> Node<'on_disk> {
     pub(super) fn state(&self) -> Option<EntryState> {
         self.entry.as_ref().map(|entry| entry.state)
     }
 
     pub(super) fn sorted<'tree>(
         nodes: &'tree mut ChildNodes<'on_disk>,
     ) -> Vec<(&'tree NodeKey<'on_disk>, &'tree mut Self)> {
         let mut vec: Vec<_> = nodes.iter_mut().collect();
         // `sort_unstable_by_key` doesn’t allow keys borrowing from the value:
         // https://github.com/rust-lang/rust/issues/34162
         vec.sort_unstable_by(|(path1, _), (path2, _)| path1.cmp(path2));
         vec
     }
 }
 
 /// `(full_path, entry, copy_source)`
 type NodeDataMut<'tree, 'on_disk> = (
     &'tree HgPath,
     &'tree mut Option<DirstateEntry>,
     &'tree mut Option<Cow<'on_disk, HgPath>>,
 );
 
 impl<'on_disk> DirstateMap<'on_disk> {
+    pub(super) fn empty(on_disk: &'on_disk [u8]) -> Self {
+        Self {
+            on_disk,
+            root: ChildNodes::default(),
+            nodes_with_entry_count: 0,
+            nodes_with_copy_source_count: 0,
+        }
+    }
+
     #[timed]
     pub fn new_v2(
         on_disk: &'on_disk [u8],
     ) -> Result<(Self, Option<DirstateParents>), DirstateError> {
-        if let Some(rest) = on_disk.drop_prefix(V2_FORMAT_MARKER) {
-            Self::new_v1(rest)
-        } else if on_disk.is_empty() {
-            Self::new_v1(on_disk)
-        } else {
-            return Err(HgError::corrupted(
-                "missing dirstate-v2 magic number",
-            )
-            .into());
-        }
+        on_disk::read(on_disk)
     }
 
     #[timed]
     pub fn new_v1(
         on_disk: &'on_disk [u8],
     ) -> Result<(Self, Option<DirstateParents>), DirstateError> {
-        let mut map = Self {
-            on_disk,
-            root: ChildNodes::default(),
-            nodes_with_entry_count: 0,
-            nodes_with_copy_source_count: 0,
-        };
+        let mut map = Self::empty(on_disk);
         if map.on_disk.is_empty() {
             return Ok((map, None));
         }
 
         let parents = parse_dirstate_entries(
             map.on_disk,
             |path, entry, copy_source| {
                 let tracked = entry.state.is_tracked();
                 let node = Self::get_or_insert_node(
                     &mut map.root,
                     path,
                     WithBasename::to_cow_borrowed,
                     |ancestor| {
                         if tracked {
                             ancestor.tracked_descendants_count += 1
                         }
                     },
                 );
                 assert!(
                     node.entry.is_none(),
                     "duplicate dirstate entry in read"
                 );
                 assert!(
                     node.copy_source.is_none(),
                     "duplicate dirstate entry in read"
                 );
                 node.entry = Some(*entry);
                 node.copy_source = copy_source.map(Cow::Borrowed);
                 map.nodes_with_entry_count += 1;
                 if copy_source.is_some() {
                     map.nodes_with_copy_source_count += 1
                 }
             },
         )?;
         let parents = Some(parents.clone());
 
         Ok((map, parents))
     }
 
     fn get_node(&self, path: &HgPath) -> Option<&Node> {
         let mut children = &self.root;
         let mut components = path.components();
         let mut component =
             components.next().expect("expected at least one components");
         loop {
             let child = children.get(component)?;
             if let Some(next_component) = components.next() {
                 component = next_component;
                 children = &child.children;
             } else {
                 return Some(child);
             }
         }
     }
 
     /// Returns a mutable reference to the node at `path` if it exists
     ///
     /// This takes `root` instead of `&mut self` so that callers can mutate
     /// other fields while the returned borrow is still valid
     fn get_node_mut<'tree>(
         root: &'tree mut ChildNodes<'on_disk>,
         path: &HgPath,
     ) -> Option<&'tree mut Node<'on_disk>> {
         let mut children = root;
         let mut components = path.components();
         let mut component =
             components.next().expect("expected at least one components");
         loop {
             let child = children.get_mut(component)?;
             if let Some(next_component) = components.next() {
                 component = next_component;
                 children = &mut child.children;
             } else {
                 return Some(child);
             }
         }
     }
 
     fn get_or_insert_node<'tree, 'path>(
         root: &'tree mut ChildNodes<'on_disk>,
         path: &'path HgPath,
         to_cow: impl Fn(
             WithBasename<&'path HgPath>,
         ) -> WithBasename<Cow<'on_disk, HgPath>>,
         mut each_ancestor: impl FnMut(&mut Node),
     ) -> &'tree mut Node<'on_disk> {
         let mut child_nodes = root;
         let mut inclusive_ancestor_paths =
             WithBasename::inclusive_ancestors_of(path);
         let mut ancestor_path = inclusive_ancestor_paths
             .next()
             .expect("expected at least one inclusive ancestor");
         loop {
             // TODO: can we avoid allocating an owned key in cases where the
             // map already contains that key, without introducing double
             // lookup?
             let child_node =
                 child_nodes.entry(to_cow(ancestor_path)).or_default();
             if let Some(next) = inclusive_ancestor_paths.next() {
                 each_ancestor(child_node);
                 ancestor_path = next;
                 child_nodes = &mut child_node.children;
             } else {
                 return child_node;
             }
         }
     }
 
     fn add_or_remove_file(
         &mut self,
         path: &HgPath,
         old_state: EntryState,
         new_entry: DirstateEntry,
     ) {
         let tracked_count_increment =
             match (old_state.is_tracked(), new_entry.state.is_tracked()) {
                 (false, true) => 1,
                 (true, false) => -1,
                 _ => 0,
             };
 
         let node = Self::get_or_insert_node(
             &mut self.root,
             path,
             WithBasename::to_cow_owned,
             |ancestor| {
                 // We can’t use `+= increment` because the counter is unsigned,
                 // and we want debug builds to detect accidental underflow
                 // through zero
                 match tracked_count_increment {
                     1 => ancestor.tracked_descendants_count += 1,
                     -1 => ancestor.tracked_descendants_count -= 1,
                     _ => {}
                 }
             },
         );
         if node.entry.is_none() {
             self.nodes_with_entry_count += 1
         }
         node.entry = Some(new_entry)
     }
 
     fn iter_nodes<'a>(
         &'a self,
     ) -> impl Iterator<Item = (&'a HgPath, &'a Node)> + 'a {
         // Depth first tree traversal.
         //
         // If we could afford internal iteration and recursion,
         // this would look like:
         //
         // ```
         // fn traverse_children(
         //     children: &ChildNodes,
         //     each: &mut impl FnMut(&Node),
         // ) {
         //     for child in children.values() {
         //         traverse_children(&child.children, each);
         //         each(child);
         //     }
         // }
         // ```
         //
         // However we want an external iterator and therefore can’t use the
         // call stack. Use an explicit stack instead:
         let mut stack = Vec::new();
         let mut iter = self.root.iter();
         std::iter::from_fn(move || {
             while let Some((key, child_node)) = iter.next() {
                 // Pseudo-recursion
                 let new_iter = child_node.children.iter();
                 let old_iter = std::mem::replace(&mut iter, new_iter);
                 let key = &**key.full_path();
                 stack.push((key, child_node, old_iter));
             }
             // Found the end of a `children.iter()` iterator.
             if let Some((key, child_node, next_iter)) = stack.pop() {
                 // "Return" from pseudo-recursion by restoring state from the
                 // explicit stack
                 iter = next_iter;
 
                 Some((key, child_node))
             } else {
                 // Reached the bottom of the stack, we’re done
                 None
             }
         })
     }
 
     /// Mutable iterator for the `(entry, copy source)` of each node.
     ///
     /// It would not be safe to yield mutable references to nodes themeselves
     /// with `-> impl Iterator<Item = &mut Node>` since child nodes are
     /// reachable from their ancestor nodes, potentially creating multiple
     /// `&mut` references to a given node.
     fn iter_node_data_mut<'tree>(
         &'tree mut self,
     ) -> impl Iterator<Item = NodeDataMut<'tree, 'on_disk>> + 'tree {
         // Explict stack for pseudo-recursion, see `iter_nodes` above.
         let mut stack = Vec::new();
         let mut iter = self.root.iter_mut();
         std::iter::from_fn(move || {
             while let Some((key, child_node)) = iter.next() {
                 // Pseudo-recursion
                 let data = (
                     &**key.full_path(),
                     &mut child_node.entry,
                     &mut child_node.copy_source,
                 );
                 let new_iter = child_node.children.iter_mut();
                 let old_iter = std::mem::replace(&mut iter, new_iter);
                 stack.push((data, old_iter));
             }
             // Found the end of a `children.values_mut()` iterator.
             if let Some((data, next_iter)) = stack.pop() {
                 // "Return" from pseudo-recursion by restoring state from the
                 // explicit stack
                 iter = next_iter;
 
                 Some(data)
             } else {
                 // Reached the bottom of the stack, we’re done
                 None
             }
         })
     }
 }
 
 impl<'on_disk> super::dispatch::DirstateMapMethods for DirstateMap<'on_disk> {
     fn clear(&mut self) {
         self.root.clear();
         self.nodes_with_entry_count = 0;
         self.nodes_with_copy_source_count = 0;
     }
 
     fn add_file(
         &mut self,
         filename: &HgPath,
         old_state: EntryState,
         entry: DirstateEntry,
     ) -> Result<(), DirstateMapError> {
         self.add_or_remove_file(filename, old_state, entry);
         Ok(())
     }
 
     fn remove_file(
         &mut self,
         filename: &HgPath,
         old_state: EntryState,
         size: i32,
     ) -> Result<(), DirstateMapError> {
         let entry = DirstateEntry {
             state: EntryState::Removed,
             mode: 0,
             size,
             mtime: 0,
         };
         self.add_or_remove_file(filename, old_state, entry);
         Ok(())
     }
 
     fn drop_file(
         &mut self,
         filename: &HgPath,
         old_state: EntryState,
     ) -> Result<bool, DirstateMapError> {
         struct Dropped {
             was_tracked: bool,
             had_entry: bool,
             had_copy_source: bool,
         }
         fn recur(nodes: &mut ChildNodes, path: &HgPath) -> Option<Dropped> {
             let (first_path_component, rest_of_path) =
                 path.split_first_component();
             let node = nodes.get_mut(first_path_component)?;
             let dropped;
             if let Some(rest) = rest_of_path {
                 dropped = recur(&mut node.children, rest)?;
                 if dropped.was_tracked {
                     node.tracked_descendants_count -= 1;
                 }
             } else {
                 dropped = Dropped {
                     was_tracked: node
                         .entry
                         .as_ref()
                         .map_or(false, |entry| entry.state.is_tracked()),
                     had_entry: node.entry.take().is_some(),
                     had_copy_source: node.copy_source.take().is_some(),
                 };
             }
             // After recursion, for both leaf (rest_of_path is None) nodes and
             // parent nodes, remove a node if it just became empty.
             if node.entry.is_none()
                 && node.copy_source.is_none()
                 && node.children.is_empty()
             {
                 nodes.remove(first_path_component);
             }
             Some(dropped)
         }
 
         if let Some(dropped) = recur(&mut self.root, filename) {
             if dropped.had_entry {
                 self.nodes_with_entry_count -= 1
             }
             if dropped.had_copy_source {
                 self.nodes_with_copy_source_count -= 1
             }
             Ok(dropped.had_entry)
         } else {
             debug_assert!(!old_state.is_tracked());
             Ok(false)
         }
     }
 
     fn clear_ambiguous_times(&mut self, filenames: Vec<HgPathBuf>, now: i32) {
         for filename in filenames {
             if let Some(node) = Self::get_node_mut(&mut self.root, &filename) {
                 if let Some(entry) = node.entry.as_mut() {
                     clear_ambiguous_mtime(entry, now);
                 }
             }
         }
     }
 
     fn non_normal_entries_contains(&mut self, key: &HgPath) -> bool {
         self.get_node(key)
             .and_then(|node| node.entry.as_ref())
             .map_or(false, DirstateEntry::is_non_normal)
     }
 
     fn non_normal_entries_remove(&mut self, _key: &HgPath) {
         // Do nothing, this `DirstateMap` does not have a separate "non normal
         // entries" set that need to be kept up to date
     }
 
     fn non_normal_or_other_parent_paths(
         &mut self,
     ) -> Box<dyn Iterator<Item = &HgPath> + '_> {
         Box::new(self.iter_nodes().filter_map(|(path, node)| {
             node.entry
                 .as_ref()
                 .filter(|entry| {
                     entry.is_non_normal() || entry.is_from_other_parent()
                 })
                 .map(|_| path)
         }))
     }
 
     fn set_non_normal_other_parent_entries(&mut self, _force: bool) {
         // Do nothing, this `DirstateMap` does not have a separate "non normal
         // entries" and "from other parent" sets that need to be recomputed
     }
 
     fn iter_non_normal_paths(
         &mut self,
     ) -> Box<dyn Iterator<Item = &HgPath> + Send + '_> {
         self.iter_non_normal_paths_panic()
     }
 
     fn iter_non_normal_paths_panic(
         &self,
     ) -> Box<dyn Iterator<Item = &HgPath> + Send + '_> {
         Box::new(self.iter_nodes().filter_map(|(path, node)| {
             node.entry
                 .as_ref()
                 .filter(|entry| entry.is_non_normal())
                 .map(|_| path)
         }))
     }
 
     fn iter_other_parent_paths(
         &mut self,
     ) -> Box<dyn Iterator<Item = &HgPath> + Send + '_> {
         Box::new(self.iter_nodes().filter_map(|(path, node)| {
             node.entry
                 .as_ref()
                 .filter(|entry| entry.is_from_other_parent())
                 .map(|_| path)
         }))
     }
 
     fn has_tracked_dir(
         &mut self,
         directory: &HgPath,
     ) -> Result<bool, DirstateMapError> {
         if let Some(node) = self.get_node(directory) {
             // A node without a `DirstateEntry` was created to hold child
             // nodes, and is therefore a directory.
             Ok(node.entry.is_none() && node.tracked_descendants_count > 0)
         } else {
             Ok(false)
         }
     }
 
     fn has_dir(
         &mut self,
         directory: &HgPath,
     ) -> Result<bool, DirstateMapError> {
         if let Some(node) = self.get_node(directory) {
             // A node without a `DirstateEntry` was created to hold child
             // nodes, and is therefore a directory.
             Ok(node.entry.is_none())
         } else {
             Ok(false)
         }
     }
 
     #[timed]
     fn pack_v1(
         &mut self,
         parents: DirstateParents,
         now: Timestamp,
     ) -> Result<Vec<u8>, DirstateError> {
         // Optizimation (to be measured?): pre-compute size to avoid `Vec`
         // reallocations
         let mut size = parents.as_bytes().len();
         for (path, node) in self.iter_nodes() {
             if node.entry.is_some() {
                 size += packed_entry_size(
                     path,
                     node.copy_source.as_ref().map(|p| &**p),
                 )
             }
         }
 
         let mut packed = Vec::with_capacity(size);
         packed.extend(parents.as_bytes());
 
         let now: i32 = now.0.try_into().expect("time overflow");
         for (path, opt_entry, copy_source) in self.iter_node_data_mut() {
             if let Some(entry) = opt_entry {
                 clear_ambiguous_mtime(entry, now);
                 pack_entry(
                     path,
                     entry,
                     copy_source.as_ref().map(|p| &**p),
                     &mut packed,
                 );
             }
         }
         Ok(packed)
     }
 
     #[timed]
     fn pack_v2(
         &mut self,
         parents: DirstateParents,
         now: Timestamp,
     ) -> Result<Vec<u8>, DirstateError> {
-        // Inefficient but temporary
-        let mut v2 = V2_FORMAT_MARKER.to_vec();
-        v2.append(&mut self.pack_v1(parents, now)?);
-        Ok(v2)
+        on_disk::write(self, parents, now)
     }
 
     fn set_all_dirs(&mut self) -> Result<(), DirstateMapError> {
         // Do nothing, this `DirstateMap` does not a separate `all_dirs` that
         // needs to be recomputed
         Ok(())
     }
 
     fn set_dirs(&mut self) -> Result<(), DirstateMapError> {
         // Do nothing, this `DirstateMap` does not a separate `dirs` that needs
         // to be recomputed
         Ok(())
     }
 
     fn status<'a>(
         &'a mut self,
         matcher: &'a (dyn Matcher + Sync),
         root_dir: PathBuf,
         ignore_files: Vec<PathBuf>,
         options: StatusOptions,
     ) -> Result<(DirstateStatus<'a>, Vec<PatternFileWarning>), StatusError>
     {
         super::status::status(self, matcher, root_dir, ignore_files, options)
     }
 
     fn copy_map_len(&self) -> usize {
-        self.nodes_with_copy_source_count
+        self.nodes_with_copy_source_count as usize
     }
 
     fn copy_map_iter(&self) -> CopyMapIter<'_> {
         Box::new(self.iter_nodes().filter_map(|(path, node)| {
             node.copy_source
                 .as_ref()
                 .map(|copy_source| (path, &**copy_source))
         }))
     }
 
     fn copy_map_contains_key(&self, key: &HgPath) -> bool {
         if let Some(node) = self.get_node(key) {
             node.copy_source.is_some()
         } else {
             false
         }
     }
 
     fn copy_map_get(&self, key: &HgPath) -> Option<&HgPath> {
         self.get_node(key)?.copy_source.as_ref().map(|p| &**p)
     }
 
     fn copy_map_remove(&mut self, key: &HgPath) -> Option<HgPathBuf> {
         let count = &mut self.nodes_with_copy_source_count;
         Self::get_node_mut(&mut self.root, key).and_then(|node| {
             if node.copy_source.is_some() {
                 *count -= 1
             }
             node.copy_source.take().map(Cow::into_owned)
         })
     }
 
     fn copy_map_insert(
         &mut self,
         key: HgPathBuf,
         value: HgPathBuf,
     ) -> Option<HgPathBuf> {
         let node = Self::get_or_insert_node(
             &mut self.root,
             &key,
             WithBasename::to_cow_owned,
             |_ancestor| {},
         );
         if node.copy_source.is_none() {
             self.nodes_with_copy_source_count += 1
         }
         node.copy_source.replace(value.into()).map(Cow::into_owned)
     }
 
     fn len(&self) -> usize {
-        self.nodes_with_entry_count
+        self.nodes_with_entry_count as usize
     }
 
     fn contains_key(&self, key: &HgPath) -> bool {
         self.get(key).is_some()
     }
 
     fn get(&self, key: &HgPath) -> Option<&DirstateEntry> {
         self.get_node(key)?.entry.as_ref()
     }
 
     fn iter(&self) -> StateMapIter<'_> {
         Box::new(self.iter_nodes().filter_map(|(path, node)| {
             node.entry.as_ref().map(|entry| (path, entry))
         }))
     }
 }

rust/hg-core/src/dirstate_tree/on_disk.rs

@@ -1,4 +1,335 b''
+//! The "version 2" disk representation of the dirstate
+//!
+//! # File format
+//!
+//! The file starts with a fixed-sized header, whose layout is defined by the
+//! `Header` struct. Its `root` field contains the slice (offset and length) to
+//! the nodes representing the files and directories at the root of the
+//! repository. Each node is also fixed-size, defined by the `Node` struct.
+//! Nodes in turn contain slices to variable-size paths, and to their own child
+//! nodes (if any) for nested files and directories.
+
+use crate::dirstate::parsers::clear_ambiguous_mtime;
+use crate::dirstate::parsers::Timestamp;
+use crate::dirstate_tree::dirstate_map::{self, DirstateMap};
+use crate::dirstate_tree::path_with_basename::WithBasename;
+use crate::errors::HgError;
+use crate::utils::hg_path::HgPath;
+use crate::DirstateEntry;
+use crate::DirstateError;
+use crate::DirstateParents;
+use bytes_cast::unaligned::{I32Be, U32Be, U64Be};
+use bytes_cast::BytesCast;
+use std::borrow::Cow;
+use std::convert::{TryFrom, TryInto};
+
 /// Added at the start of `.hg/dirstate` when the "v2" format is used.
-/// Acts like a "magic number". This is a sanity check, not strictly necessary
-/// since `.hg/requires` already governs which format should be used.
+/// This a redundant sanity check more than an actual "magic number" since
+/// `.hg/requires` already governs which format should be used.
 pub const V2_FORMAT_MARKER: &[u8; 12] = b"dirstate-v2\n";
+
+#[derive(BytesCast)]
+#[repr(C)]
+struct Header {
+    marker: [u8; V2_FORMAT_MARKER.len()],
+
+    /// `dirstatemap.parents()` in `mercurial/dirstate.py` relies on this
+    /// `parents` field being at this offset, immediately after `marker`.
+    parents: DirstateParents,
+
+    root: ChildNodes,
+    nodes_with_entry_count: Size,
+    nodes_with_copy_source_count: Size,
+}
+
+#[derive(BytesCast)]
+#[repr(C)]
+struct Node {
+    full_path: PathSlice,
+
+    /// In bytes from `self.full_path.start`
+    base_name_start: Size,
+
+    copy_source: OptPathSlice,
+    entry: OptEntry,
+    children: ChildNodes,
+    tracked_descendants_count: Size,
+}
+
+/// Either nothing if `state == b'\0'`, or a dirstate entry like in the v1
+/// format
+#[derive(BytesCast)]
+#[repr(C)]
+struct OptEntry {
+    state: u8,
+    mode: I32Be,
+    mtime: I32Be,
+    size: I32Be,
+}
+
+/// Counted in bytes from the start of the file
+///
+/// NOTE: If we decide to never support `.hg/dirstate` files larger than 4 GiB
+/// we could save space by using `U32Be` instead.
+type Offset = U64Be;
+
+/// Counted in number of items
+///
+/// NOTE: not supporting directories with more than 4 billion direct children,
+/// or filenames more than 4 GiB.
+type Size = U32Be;
+
+/// Location of consecutive, fixed-size items.
+///
+/// An item can be a single byte for paths, or a struct with
+/// `derive(BytesCast)`.
+#[derive(BytesCast, Copy, Clone)]
+#[repr(C)]
+struct Slice {
+    start: Offset,
+    len: Size,
+}
+
+/// A contiguous sequence of `len` times `Node`, representing the child nodes
+/// of either some other node or of the repository root.
+///
+/// Always sorted by ascending `full_path`, to allow binary search.
+/// Since nodes with the same parent nodes also have the same parent path,
+/// only the `base_name`s need to be compared during binary search.
+type ChildNodes = Slice;
+
+/// A `HgPath` of `len` bytes
+type PathSlice = Slice;
+
+/// Either nothing if `start == 0`, or a `HgPath` of `len` bytes
+type OptPathSlice = Slice;
+
+/// Make sure that size-affecting changes are made knowingly
+fn _static_assert_size_of() {
+    let _ = std::mem::transmute::<Header, [u8; 72]>;
+    let _ = std::mem::transmute::<Node, [u8; 57]>;
+}
+
+pub(super) fn read<'on_disk>(
+    on_disk: &'on_disk [u8],
+) -> Result<(DirstateMap<'on_disk>, Option<DirstateParents>), DirstateError> {
+    if on_disk.is_empty() {
+        return Ok((DirstateMap::empty(on_disk), None));
+    }
+    let (header, _) = Header::from_bytes(on_disk)
+        .map_err(|_| HgError::corrupted("truncated dirstate-v2"))?;
+    let Header {
+        marker,
+        parents,
+        root,
+        nodes_with_entry_count,
+        nodes_with_copy_source_count,
+    } = header;
+    if marker != V2_FORMAT_MARKER {
+        return Err(HgError::corrupted("missing dirstated-v2 marker").into());
+    }
+    let dirstate_map = DirstateMap {
+        on_disk,
+        root: read_nodes(on_disk, *root)?,
+        nodes_with_entry_count: nodes_with_entry_count.get(),
+        nodes_with_copy_source_count: nodes_with_copy_source_count.get(),
+    };
+    let parents = Some(parents.clone());
+    Ok((dirstate_map, parents))
+}
+
+impl Node {
+    pub(super) fn path<'on_disk>(
+        &self,
+        on_disk: &'on_disk [u8],
+    ) -> Result<dirstate_map::NodeKey<'on_disk>, HgError> {
+        let full_path = read_hg_path(on_disk, self.full_path)?;
+        let base_name_start = usize::try_from(self.base_name_start.get())
+            // u32 -> usize, could only panic on a 16-bit CPU
+            .expect("dirstate-v2 base_name_start out of bounds");
+        if base_name_start < full_path.len() {
+            Ok(WithBasename::from_raw_parts(full_path, base_name_start))
+        } else {
+            Err(HgError::corrupted(
+                "dirstate-v2 base_name_start out of bounds",
+            ))
+        }
+    }
+
+    pub(super) fn copy_source<'on_disk>(
+        &self,
+        on_disk: &'on_disk [u8],
+    ) -> Result<Option<Cow<'on_disk, HgPath>>, HgError> {
+        Ok(if self.copy_source.start.get() != 0 {
+            Some(read_hg_path(on_disk, self.copy_source)?)
+        } else {
+            None
+        })
+    }
+
+    pub(super) fn entry(&self) -> Result<Option<DirstateEntry>, HgError> {
+        Ok(if self.entry.state != b'\0' {
+            Some(DirstateEntry {
+                state: self.entry.state.try_into()?,
+                mode: self.entry.mode.get(),
+                mtime: self.entry.mtime.get(),
+                size: self.entry.size.get(),
+            })
+        } else {
+            None
+        })
+    }
+
+    pub(super) fn to_in_memory_node<'on_disk>(
+        &self,
+        on_disk: &'on_disk [u8],
+    ) -> Result<dirstate_map::Node<'on_disk>, HgError> {
+        Ok(dirstate_map::Node {
+            children: read_nodes(on_disk, self.children)?,
+            copy_source: self.copy_source(on_disk)?,
+            entry: self.entry()?,
+            tracked_descendants_count: self.tracked_descendants_count.get(),
+        })
+    }
+}
+
+fn read_nodes(
+    on_disk: &[u8],
+    slice: ChildNodes,
+) -> Result<dirstate_map::ChildNodes, HgError> {
+    read_slice::<Node>(on_disk, slice)?
+        .iter()
+        .map(|node| {
+            Ok((node.path(on_disk)?, node.to_in_memory_node(on_disk)?))
+        })
+        .collect()
+}
+
+fn read_hg_path(on_disk: &[u8], slice: Slice) -> Result<Cow<HgPath>, HgError> {
+    let bytes = read_slice::<u8>(on_disk, slice)?;
+    Ok(Cow::Borrowed(HgPath::new(bytes)))
+}
+
+fn read_slice<T>(on_disk: &[u8], slice: Slice) -> Result<&[T], HgError>
+where
+    T: BytesCast,
+{
+    // Either `usize::MAX` would result in "out of bounds" error since a single
+    // `&[u8]` cannot occupy the entire addess space.
+    let start = usize::try_from(slice.start.get()).unwrap_or(std::usize::MAX);
+    let len = usize::try_from(slice.len.get()).unwrap_or(std::usize::MAX);
+    on_disk
+        .get(start..)
+        .and_then(|bytes| T::slice_from_bytes(bytes, len).ok())
+        .map(|(slice, _rest)| slice)
+        .ok_or_else(|| {
+            HgError::corrupted("dirstate v2 slice is out of bounds")
+        })
+}
+
+pub(super) fn write(
+    dirstate_map: &mut DirstateMap,
+    parents: DirstateParents,
+    now: Timestamp,
+) -> Result<Vec<u8>, DirstateError> {
+    // TODO: how do we want to handle this in 2038?
+    let now: i32 = now.0.try_into().expect("time overflow");
+
+    let header_len = std::mem::size_of::<Header>();
+
+    // This ignores the space for paths, and for nodes without an entry.
+    // TODO: better estimate? Skip the `Vec` and write to a file directly?
+    let size_guess = header_len
+        + std::mem::size_of::<Node>()
+            * dirstate_map.nodes_with_entry_count as usize;
+    let mut out = Vec::with_capacity(size_guess);
+
+    // Keep space for the header. We’ll fill it out at the end when we know the
+    // actual offset for the root nodes.
+    out.resize(header_len, 0_u8);
+
+    let root = write_nodes(&mut dirstate_map.root, now, &mut out)?;
+
+    let header = Header {
+        marker: *V2_FORMAT_MARKER,
+        parents: parents,
+        root,
+        nodes_with_entry_count: dirstate_map.nodes_with_entry_count.into(),
+        nodes_with_copy_source_count: dirstate_map
+            .nodes_with_copy_source_count
+            .into(),
+    };
+    out[..header_len].copy_from_slice(header.as_bytes());
+    Ok(out)
+}
+
+/// Serialize the dirstate to the `v2` format after clearing ambigous `mtime`s.
+fn write_nodes(
+    nodes: &mut dirstate_map::ChildNodes,
+    now: i32,
+    out: &mut Vec<u8>,
+) -> Result<ChildNodes, DirstateError> {
+    // `dirstate_map::ChildNodes` is a `HashMap` with undefined iteration
+    // order. Sort to enable binary search in the written file.
+    let nodes = dirstate_map::Node::sorted(nodes);
+
+    // First accumulate serialized nodes in a `Vec`
+    let mut on_disk_nodes = Vec::with_capacity(nodes.len());
+    for (full_path, node) in nodes {
+        on_disk_nodes.push(Node {
+            children: write_nodes(&mut node.children, now, out)?,
+            tracked_descendants_count: node.tracked_descendants_count.into(),
+            full_path: write_slice::<u8>(
+                full_path.full_path().as_bytes(),
+                out,
+            ),
+            base_name_start: u32::try_from(full_path.base_name_start())
+                // Could only panic for paths over 4 GiB
+                .expect("dirstate-v2 offset overflow")
+                .into(),
+            copy_source: if let Some(source) = &node.copy_source {
+                write_slice::<u8>(source.as_bytes(), out)
+            } else {
+                Slice {
+                    start: 0.into(),
+                    len: 0.into(),
+                }
+            },
+            entry: if let Some(entry) = &mut node.entry {
+                clear_ambiguous_mtime(entry, now);
+                OptEntry {
+                    state: entry.state.into(),
+                    mode: entry.mode.into(),
+                    mtime: entry.mtime.into(),
+                    size: entry.size.into(),
+                }
+            } else {
+                OptEntry {
+                    state: b'\0',
+                    mode: 0.into(),
+                    mtime: 0.into(),
+                    size: 0.into(),
+                }
+            },
+        })
+    }
+    // … so we can write them contiguously
+    Ok(write_slice::<Node>(&on_disk_nodes, out))
+}
+
+fn write_slice<T>(slice: &[T], out: &mut Vec<u8>) -> Slice
+where
+    T: BytesCast,
+{
+    let start = u64::try_from(out.len())
+        // Could only panic on a 128-bit CPU with a dirstate over 16 EiB
+        .expect("dirstate-v2 offset overflow")
+        .into();
+    let len = u32::try_from(slice.len())
+        // Could only panic for paths over 4 GiB or nodes with over 4 billions
+        // child nodes
+        .expect("dirstate-v2 offset overflow")
+        .into();
+    out.extend(slice.as_bytes());
+    Slice { start, len }
+}

rust/hg-core/src/dirstate_tree/path_with_basename.rs

@@ -1,172 +1,187 b''
 use crate::utils::hg_path::HgPath;
 use std::borrow::{Borrow, Cow};
 
 /// Wraps `HgPath` or `HgPathBuf` to make it behave "as" its last path
 /// component, a.k.a. its base name (as in Python’s `os.path.basename`), but
 /// also allow recovering the full path.
 ///
 /// "Behaving as" means that equality and comparison consider only the base
 /// name, and `std::borrow::Borrow` is implemented to return only the base
 /// name. This allows using the base name as a map key while still being able
 /// to recover the full path, in a single memory allocation.
 #[derive(Debug)]
 pub struct WithBasename<T> {
     full_path: T,
 
     /// The position after the last slash separator in `full_path`, or `0`
     /// if there is no slash.
     base_name_start: usize,
 }
 
 impl<T> WithBasename<T> {
     pub fn full_path(&self) -> &T {
         &self.full_path
     }
 }
 
+fn find_base_name_start(full_path: &HgPath) -> usize {
+    if let Some(last_slash_position) =
+        full_path.as_bytes().iter().rposition(|&byte| byte == b'/')
+    {
+        last_slash_position + 1
+    } else {
+        0
+    }
+}
+
 impl<T: AsRef<HgPath>> WithBasename<T> {
     pub fn new(full_path: T) -> Self {
-        let base_name_start = if let Some(last_slash_position) = full_path
-            .as_ref()
-            .as_bytes()
-            .iter()
-            .rposition(|&byte| byte == b'/')
-        {
-            last_slash_position + 1
-        } else {
-            0
-        };
+        Self {
+            base_name_start: find_base_name_start(full_path.as_ref()),
+            full_path,
+        }
+    }
+
+    pub fn from_raw_parts(full_path: T, base_name_start: usize) -> Self {
+        debug_assert_eq!(
+            base_name_start,
+            find_base_name_start(full_path.as_ref())
+        );
         Self {
             base_name_start,
             full_path,
         }
     }
 
     pub fn base_name(&self) -> &HgPath {
         HgPath::new(
             &self.full_path.as_ref().as_bytes()[self.base_name_start..],
         )
     }
+
+    pub fn base_name_start(&self) -> usize {
+        self.base_name_start
+    }
 }
 
 impl<T: AsRef<HgPath>> Borrow<HgPath> for WithBasename<T> {
     fn borrow(&self) -> &HgPath {
         self.base_name()
     }
 }
 
 impl<T: AsRef<HgPath>> std::hash::Hash for WithBasename<T> {
     fn hash<H: std::hash::Hasher>(&self, hasher: &mut H) {
         self.base_name().hash(hasher)
     }
 }
 
 impl<T: AsRef<HgPath> + PartialEq> PartialEq for WithBasename<T> {
     fn eq(&self, other: &Self) -> bool {
         self.base_name() == other.base_name()
     }
 }
 
 impl<T: AsRef<HgPath> + Eq> Eq for WithBasename<T> {}
 
 impl<T: AsRef<HgPath> + PartialOrd> PartialOrd for WithBasename<T> {
     fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
         self.base_name().partial_cmp(other.base_name())
     }
 }
 
 impl<T: AsRef<HgPath> + Ord> Ord for WithBasename<T> {
     fn cmp(&self, other: &Self) -> std::cmp::Ordering {
         self.base_name().cmp(other.base_name())
     }
 }
 
 impl<'a> WithBasename<&'a HgPath> {
     pub fn to_cow_borrowed(self) -> WithBasename<Cow<'a, HgPath>> {
         WithBasename {
             full_path: Cow::Borrowed(self.full_path),
             base_name_start: self.base_name_start,
         }
     }
 
     pub fn to_cow_owned<'b>(self) -> WithBasename<Cow<'b, HgPath>> {
         WithBasename {
             full_path: Cow::Owned(self.full_path.to_owned()),
             base_name_start: self.base_name_start,
         }
     }
 }
 
 impl<'a> WithBasename<&'a HgPath> {
     /// Returns an iterator of `WithBasename<&HgPath>` for the ancestor
     /// directory paths of the given `path`, as well as `path` itself.
     ///
     /// For example, the full paths of inclusive ancestors of "a/b/c" are "a",
     /// "a/b", and "a/b/c" in that order.
     pub fn inclusive_ancestors_of(
         path: &'a HgPath,
     ) -> impl Iterator<Item = WithBasename<&'a HgPath>> {
         let mut slash_positions =
             path.as_bytes().iter().enumerate().filter_map(|(i, &byte)| {
                 if byte == b'/' {
                     Some(i)
                 } else {
                     None
                 }
             });
         let mut opt_next_component_start = Some(0);
         std::iter::from_fn(move || {
             opt_next_component_start.take().map(|next_component_start| {
                 if let Some(slash_pos) = slash_positions.next() {
                     opt_next_component_start = Some(slash_pos + 1);
                     Self {
                         full_path: HgPath::new(&path.as_bytes()[..slash_pos]),
                         base_name_start: next_component_start,
                     }
                 } else {
                     // Not setting `opt_next_component_start` here: there will
                     // be no iteration after this one because `.take()` set it
                     // to `None`.
                     Self {
                         full_path: path,
                         base_name_start: next_component_start,
                     }
                 }
             })
         })
     }
 }
 
 #[test]
 fn test() {
     let a = WithBasename::new(HgPath::new("a").to_owned());
     assert_eq!(&**a.full_path(), HgPath::new(b"a"));
     assert_eq!(a.base_name(), HgPath::new(b"a"));
 
     let cba = WithBasename::new(HgPath::new("c/b/a").to_owned());
     assert_eq!(&**cba.full_path(), HgPath::new(b"c/b/a"));
     assert_eq!(cba.base_name(), HgPath::new(b"a"));
 
     assert_eq!(a, cba);
     let borrowed: &HgPath = cba.borrow();
     assert_eq!(borrowed, HgPath::new("a"));
 }
 
 #[test]
 fn test_inclusive_ancestors() {
     let mut iter = WithBasename::inclusive_ancestors_of(HgPath::new("a/bb/c"));
 
     let next = iter.next().unwrap();
     assert_eq!(*next.full_path(), HgPath::new("a"));
     assert_eq!(next.base_name(), HgPath::new("a"));
 
     let next = iter.next().unwrap();
     assert_eq!(*next.full_path(), HgPath::new("a/bb"));
     assert_eq!(next.base_name(), HgPath::new("bb"));
 
     let next = iter.next().unwrap();
     assert_eq!(*next.full_path(), HgPath::new("a/bb/c"));
     assert_eq!(next.base_name(), HgPath::new("c"));
 
     assert!(iter.next().is_none());
 }