diff --git a/README.md b/README.md index d0418d5..3c1d378 100644 --- a/README.md +++ b/README.md @@ -165,14 +165,14 @@ The JSON export includes the following metrics for each measured run (excluding | `time_wall_clock` | second | Elapsed time, including time spent waiting or descheduled. Available on all platforms. | | `time_user` | second | CPU time spent in user mode, accumulated across threads. On Unix, includes descendants whose usage propagates through parents waiting for them. On Windows, includes processes associated with the benchmark's job object. | | `time_system` | second | CPU time spent in kernel mode, with the same process accounting as `time_user`. | -| `peak_memory_usage` | byte | Peak resident set size (RSS) on Linux and macOS; omitted on Windows. This is the largest per-process peak among the command and descendants whose usage is collected by waiting for them, **not the simultaneous total memory of the process tree**. Linux's KiB counter and macOS's byte counter are both exported in bytes. On macOS, this is RSS, not Apple's separate memory-footprint metric. | +| `memory_peak_resident` | byte | Peak resident set size (RSS) on Linux and macOS; omitted on Windows. This is the largest per-process peak among the command and descendants whose usage is collected by waiting for them, **not the simultaneous total memory of the process tree**. Linux's KiB counter and macOS's byte counter are both exported in bytes. On macOS, this is RSS, not Apple's separate memory-footprint metric. | Metrics unavailable on a platform are omitted, rather than reported as zero. Time values are always exported in seconds, regardless of `--time-unit`. When using a shell, the estimated shell startup CPU and wall-clock times are subtracted; memory usage is not adjusted. For example, two concurrent worker processes that each use 128 MiB can produce a -`peak_memory_usage` of about 128 MiB, even though their combined memory use is about 256 MiB. +`memory_peak_resident` of about 128 MiB, even though their combined memory use is about 256 MiB. Threads share a process's address space and are covered by its RSS measurement. The JSON output is useful if you want to analyze the benchmark results in more detail. The diff --git a/src/benchmark/executor.rs b/src/benchmark/executor.rs index dce30cd..de077b7 100644 --- a/src/benchmark/executor.rs +++ b/src/benchmark/executor.rs @@ -277,7 +277,7 @@ impl Executor for ShellExecutor<'_> { time_wall_clock: measurements.time_wall_clock_mean(), time_user: measurements.time_user_mean(), time_system: measurements.time_system_mean(), - peak_memory_usage: None, + memory_peak_resident: None, exit_status: ExitStatus::default(), }); @@ -335,7 +335,7 @@ impl Executor for MockExecutor { time_wall_clock: Self::extract_time(command.get_command_line()), time_user: Time::zero(), time_system: Time::zero(), - peak_memory_usage: Some(Information::zero()), + memory_peak_resident: Some(Information::zero()), exit_status, }) } diff --git a/src/benchmark/measurement.rs b/src/benchmark/measurement.rs index faff776..0c2e4ea 100644 --- a/src/benchmark/measurement.rs +++ b/src/benchmark/measurement.rs @@ -49,7 +49,7 @@ pub struct Measurement { skip_serializing_if = "Option::is_none", serialize_with = "serialize_optional_information" )] - pub peak_memory_usage: Option, + pub memory_peak_resident: Option, // The exit status of the process #[serde(rename = "exit_code", serialize_with = "serialize_exit_status")] diff --git a/src/benchmark/scheduler.rs b/src/benchmark/scheduler.rs index 0621555..f618b73 100644 --- a/src/benchmark/scheduler.rs +++ b/src/benchmark/scheduler.rs @@ -215,7 +215,7 @@ fn scheduler_basic() -> Result<()> { time_system: value: 0 unit: second - peak_memory_usage: + memory_peak_resident: value: 0 unit: byte exit_code: 0 @@ -228,7 +228,7 @@ fn scheduler_basic() -> Result<()> { time_system: value: 0 unit: second - peak_memory_usage: + memory_peak_resident: value: 0 unit: byte exit_code: 0 @@ -243,7 +243,7 @@ fn scheduler_basic() -> Result<()> { time_system: value: 0 unit: second - peak_memory_usage: + memory_peak_resident: value: 0 unit: byte exit_code: 0 @@ -256,7 +256,7 @@ fn scheduler_basic() -> Result<()> { time_system: value: 0 unit: second - peak_memory_usage: + memory_peak_resident: value: 0 unit: byte exit_code: 0 diff --git a/src/export/csv.rs b/src/export/csv.rs index c7900b3..e1b9098 100644 --- a/src/export/csv.rs +++ b/src/export/csv.rs @@ -87,21 +87,21 @@ fn test_csv() { time_wall_clock: Time::new::(7.0), time_user: Time::new::(7.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(8.0), time_user: Time::new::(8.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(12.0), time_user: Time::new::(12.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -132,21 +132,21 @@ fn test_csv() { time_wall_clock: Time::new::(17.0), time_user: Time::new::(17.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(18.0), time_user: Time::new::(18.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(19.0), time_user: Time::new::(19.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), diff --git a/src/export/json.rs b/src/export/json.rs index 6911ecb..72ba517 100644 --- a/src/export/json.rs +++ b/src/export/json.rs @@ -37,13 +37,16 @@ struct BenchmarkSummary { time_user: StatisticalSummary, time_system: StatisticalSummary, #[serde(skip_serializing_if = "Option::is_none")] - peak_memory_usage: Option, + memory_peak_resident: Option, } impl BenchmarkSummary { fn from_measurements(measurements: &Measurements) -> Self { let values = &measurements.measurements; - let mut memory_values = values.iter().filter_map(|m| m.peak_memory_usage).peekable(); + let mut memory_values = values + .iter() + .filter_map(|m| m.memory_peak_resident) + .peekable(); Self { time_wall_clock: StatisticalSummary::from_values( values.iter().map(|m| m.time_wall_clock), @@ -54,7 +57,7 @@ impl BenchmarkSummary { values.iter().map(|m| m.time_system), second, ), - peak_memory_usage: memory_values + memory_peak_resident: memory_values .peek() .is_some() .then(|| StatisticalSummary::from_values(memory_values, byte)), @@ -188,7 +191,7 @@ fn test_json_optional_memory() { command: "example".into(), name: None, measurements: Measurements::new(vec![Measurement { - peak_memory_usage: memory, + memory_peak_resident: memory, ..Measurement::default() }]), ..BenchmarkResult::default() @@ -233,11 +236,11 @@ fn test_json_optional_memory() { } if let Some(memory) = expected_memory { let value = memory["value"].clone(); - expected["results"][0]["summary"]["peak_memory_usage"] = json!({ + expected["results"][0]["summary"]["memory_peak_resident"] = json!({ "unit": "byte", "count": 1, "mean": value, "stddev": null, "median": value, "min": value, "max": value }); - expected["results"][0]["measurements"][0]["peak_memory_usage"] = memory; + expected["results"][0]["measurements"][0]["memory_peak_resident"] = memory; } assert_eq!(actual, expected); } @@ -313,7 +316,7 @@ fn test_json_summary_metrics_and_missing_samples() { time_wall_clock: Time::new::(time), time_user: Time::new::(time * 2.0), time_system: Time::new::(time * 3.0), - peak_memory_usage: memory.map(Information::new::), + memory_peak_resident: memory.map(Information::new::), ..Measurement::default() }) .collect(), @@ -334,7 +337,7 @@ fn test_json_summary_metrics_and_missing_samples() { "unit": "second", "count": 3, "mean": 6.0, "stddev": 3.0, "median": 6.0, "min": 3.0, "max": 9.0 }, - "peak_memory_usage": { + "memory_peak_resident": { "unit": "byte", "count": 2, "mean": 2048.0, "stddev": 1024.0 * 2.0_f64.sqrt(), "median": 2048.0, "min": 1024.0, "max": 3072.0 diff --git a/src/export/tests.rs b/src/export/tests.rs index cc67c09..5dc186f 100644 --- a/src/export/tests.rs +++ b/src/export/tests.rs @@ -34,21 +34,21 @@ fn test_markup_export_auto_ms() { time_wall_clock: Time::new::(0.09), time_user: Time::new::(0.09), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.10), time_user: Time::new::(0.10), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.14), time_user: Time::new::(0.14), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -62,21 +62,21 @@ fn test_markup_export_auto_ms() { time_wall_clock: Time::new::(2.0), time_user: Time::new::(2.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(3.0), time_user: Time::new::(3.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(4.0), time_user: Time::new::(4.0), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -135,21 +135,21 @@ fn test_markup_export_auto_s() { time_wall_clock: Time::new::(2.1), time_user: Time::new::(2.1), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(2.2), time_user: Time::new::(2.2), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(2.3), time_user: Time::new::(2.3), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -163,21 +163,21 @@ fn test_markup_export_auto_s() { time_wall_clock: Time::new::(0.1), time_user: Time::new::(0.1), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.2), time_user: Time::new::(0.2), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.3), time_user: Time::new::(0.3), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -236,21 +236,21 @@ fn test_markup_export_manual_ms() { time_wall_clock: Time::new::(2.1), time_user: Time::new::(2.1), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(2.2), time_user: Time::new::(2.2), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(2.3), time_user: Time::new::(2.3), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -264,21 +264,21 @@ fn test_markup_export_manual_ms() { time_wall_clock: Time::new::(0.1), time_user: Time::new::(0.1), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.2), time_user: Time::new::(0.2), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.3), time_user: Time::new::(0.3), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -336,21 +336,21 @@ fn test_markup_export_manual_s() { time_wall_clock: Time::new::(2.01), time_user: Time::new::(2.01), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(2.02), time_user: Time::new::(2.02), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(2.03), time_user: Time::new::(2.03), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), @@ -364,21 +364,21 @@ fn test_markup_export_manual_s() { time_wall_clock: Time::new::(0.11), time_user: Time::new::(0.11), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.12), time_user: Time::new::(0.12), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, Measurement { time_wall_clock: Time::new::(0.13), time_user: Time::new::(0.13), time_system: Time::zero(), - peak_memory_usage: Some(Information::new::(1024.)), + memory_peak_resident: Some(Information::new::(1024.)), exit_status: ExitStatus::default(), }, ]), diff --git a/src/quantity/mod.rs b/src/quantity/mod.rs index 8eea62b..87cfc7a 100644 --- a/src/quantity/mod.rs +++ b/src/quantity/mod.rs @@ -222,11 +222,11 @@ fn test_format() { assert_eq!(time.format_auto(), "123.4 ms"); assert_eq!(time.format(TimeUnit::MicroSecond), "123400.0 µs"); - let peak_memory_usage = Information::new::(8.); - assert_eq!(peak_memory_usage.format_auto(), "8.0 KiB"); - assert_eq!(peak_memory_usage.format(InformationUnit::Byte), "8192 B"); + let memory_peak_resident = Information::new::(8.); + assert_eq!(memory_peak_resident.format_auto(), "8.0 KiB"); + assert_eq!(memory_peak_resident.format(InformationUnit::Byte), "8192 B"); assert_eq!( - peak_memory_usage.format(InformationUnit::KibiByte), + memory_peak_resident.format(InformationUnit::KibiByte), "8.0 KiB" ); } diff --git a/src/timer/mod.rs b/src/timer/mod.rs index be00286..4d38a8a 100644 --- a/src/timer/mod.rs +++ b/src/timer/mod.rs @@ -82,14 +82,14 @@ pub fn execute_and_measure(mut command: Command) -> Result { discard(output); } - let (time_user, time_system, peak_memory_usage, exit_status) = cpu_timer.stop(child)?; + let (time_user, time_system, memory_peak_resident, exit_status) = cpu_timer.stop(child)?; let time_wall_clock = wallclock_timer.stop(); Ok(Measurement { time_wall_clock, time_user, time_system, - peak_memory_usage, + memory_peak_resident, exit_status, }) } diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs index cbfe33a..e07adf2 100644 --- a/tests/integration_tests.rs +++ b/tests/integration_tests.rs @@ -112,7 +112,7 @@ fn json_memory_availability_matches_platform() { assert!(output.status.success()); let export: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap(); let measurement = &export["results"][0]["measurements"][0]; - let memory = measurement.get("peak_memory_usage"); + let memory = measurement.get("memory_peak_resident"); if cfg!(windows) { assert!(memory.is_none(), "unavailable memory must be omitted"); } else {