Improve API and docs of fxprof-processed-profile and wholesym slightly (#545)

The only actual API change in this PR is the renaming of a few
SymbolManagerConfig methods from `symbols_*` to `symbol_*`, e.g.
`windows_symbols_server` to `windows_symbol_server`.

Author: mstange

fxprof-processed-profile/README.md

@@ -15,16 +15,26 @@ example [`serde_json::to_writer`] or [`serde_json::to_string`].
 use fxprof_processed_profile::{Profile, CategoryHandle, CpuDelta, Frame, FrameInfo, FrameFlags, SamplingInterval, Timestamp};
 use std::time::SystemTime;
 
+// Creates the following call tree:
+//
+// App process (pid: 54132) > Main thread (tid: 54132000)
+//
+// 1  0  Root node
+// 1  1  - First callee
+
 let mut profile = Profile::new("My app", SystemTime::now().into(), SamplingInterval::from_millis(1));
 let process = profile.add_process("App process", 54132, Timestamp::from_millis_since_reference(0.0));
 let thread = profile.add_thread(process, 54132000, Timestamp::from_millis_since_reference(0.0), true);
 profile.set_thread_name(thread, "Main thread");
-let stack_frames = vec![
-    FrameInfo { frame: Frame::Label(profile.handle_for_string("Root node")), subcategory: CategoryHandle::OTHER.into(), flags: FrameFlags::empty() },
-    FrameInfo { frame: Frame::Label(profile.handle_for_string("First callee")), subcategory: CategoryHandle::OTHER.into(), flags: FrameFlags::empty() }
-];
-let stack = profile.handle_for_stack_frames(thread, stack_frames.into_iter());
-profile.add_sample(thread, Timestamp::from_millis_since_reference(0.0), stack, CpuDelta::ZERO, 1);
+
+let root_node_string = profile.handle_for_string("Root node");
+let root_frame = profile.handle_for_frame_with_label(thread, root_node_string, CategoryHandle::OTHER, FrameFlags::empty());
+let first_callee_string = profile.handle_for_string("First callee");
+let first_callee_frame = profile.handle_for_frame_with_label(thread, first_callee_string, CategoryHandle::OTHER, FrameFlags::empty());
+
+let root_stack_node = profile.handle_for_stack(thread, root_frame, None);
+let first_callee_node = profile.handle_for_stack(thread, first_callee_frame, Some(root_stack_node));
+profile.add_sample(thread, Timestamp::from_millis_since_reference(0.0), Some(first_callee_node), CpuDelta::ZERO, 1);
 
 let writer = std::io::BufWriter::new(output_file);
 serde_json::to_writer(writer, &profile)?;

fxprof-processed-profile/src/global_lib_table.rs

@@ -95,6 +95,10 @@ impl Serialize for GlobalLibIndex {
 #[derive(Debug, Clone, Copy, PartialOrd, Ord, PartialEq, Eq, Hash)]
 pub struct LibraryHandle(usize);
 
+/// An iterator returned by [`Profile::lib_used_rva_iter`](crate::Profile::lib_used_rva_iter).
+///
+/// Yields the set of relative addresses, per library, that are used by stack frames
+/// in the profile.
 pub struct UsedLibraryAddressesIterator<'a> {
     next_used_lib_index: usize,
     global_lib_table: &'a GlobalLibTable,

fxprof-processed-profile/src/lib.rs

@@ -13,6 +13,13 @@
 //! use fxprof_processed_profile::{Profile, CategoryHandle, CpuDelta, FrameHandle, FrameFlags, SamplingInterval, Timestamp};
 //! use std::time::SystemTime;
 //!
+//! // Creates the following call tree:
+//! //
+//! // App process (pid: 54132) > Main thread (tid: 54132000)
+//! //
+//! // 1  0  Root node
+//! // 1  1  - First callee
+//!
 //! # fn write_profile(output_file: std::fs::File) -> Result<(), Box<dyn std::error::Error>> {
 //! let mut profile = Profile::new("My app", SystemTime::now().into(), SamplingInterval::from_millis(1));
 //! let process = profile.add_process("App process", 54132, Timestamp::from_millis_since_reference(0.0));

fxprof-processed-profile/src/profile.rs

@@ -127,8 +127,12 @@ pub struct SourceLocation {
     pub col: Option<u32>,
 }
 
-#[derive(Debug, Clone, Copy, PartialOrd, Ord, PartialEq, Eq, Hash)]
+/// The unit that should be used for the timeline at the top of the profiler UI.
+///
+/// Used in [`Profile::set_timeline_unit`].
+#[derive(Debug, Default, Clone, Copy, PartialOrd, Ord, PartialEq, Eq, Hash)]
 pub enum TimelineUnit {
+    #[default]
     Milliseconds,
     Bytes,
 }
@@ -1145,6 +1149,12 @@ impl Profile {
         self.counters[counter.0].add_sample(timestamp, value_delta, number_of_operations_delta)
     }
 
+    /// Returns an iterator with information about which native library addresses
+    /// are used by any stack frames stored in this profile.
+    pub fn lib_used_rva_iter(&self) -> UsedLibraryAddressesIterator {
+        self.global_libs.lib_used_rva_iter()
+    }
+
     fn resolve_frame_address(
         process: &mut Process,
         frame_address: FrameAddress,
@@ -1284,10 +1294,6 @@ impl Profile {
     fn contains_js_frame(&self) -> bool {
         self.threads.iter().any(|t| t.contains_js_frame())
     }
-
-    pub fn lib_used_rva_iter(&self) -> UsedLibraryAddressesIterator {
-        self.global_libs.lib_used_rva_iter()
-    }
 }
 
 impl Serialize for Profile {