SystemClock time vs. ProcessCPUClock's real time

[qiolol]

Thank you for this library!

A thing that confuses me is the difference between

let wall_clock = howlong::HighResolutionClock::now();
let elapsed_wall_time = howlong::HighResolutionClock::now() - wall_clock;

println!(elapsed_wall_time);

and

let cpu_clock = howlong::ProcessCPUClock::now();
let elapsed_cpu_time = howlong::ProcessCPUClock::now() - cpu_clock;

println!(elapsed_cpu_time.real);

Colloquially, "real" time is "wall clock" time, which seems to correspond to SystemClock (which is aliased by HighResolutionClock) per this crate's docs and in the parlance of the Boost library's docs with their system_clock.

But "CPU time" is colloquially "process user (out-of-kernel) time + process system (in-kernel) time", which would seem to correspond to:

elapsed_cpu_time.user.as_secs() + elapsed_cpu_time.system.as_secs()

But then what's elapsed_cpu_time.real? Boost docs corroborate this terminology ("timing information is broken down into real (wall clock) time, CPU time spent by the user, and CPU time spent by the operating system servicing user requests.") but don't seem to explain what the difference is between their process_real_cpu_clock and system_clock.

Some clarification in the docs would be great!

[xu-cheng]

I think there is no too much difference between wall clock and process real clock sementically. The only difference lies in the implementation details, where different system APIs are used for the respective clocks. See https://docs.rs/howlong/0.1.5/howlong/clock/index.html#implementations-2 for more details.

For the purpose of using this crate, I think you should use ProcessCPUClock if you want to have a breakdown between user cpu time and system cpu time. Otherwise, HighResolutionClock is preferred.

But "CPU time" is colloquially "process user (out-of-kernel) time + process system (in-kernel) time"

It is important to note that elapsed_cpu_time.user + elapsed_cpu_time.system does not equal to the elapsed_cpu_time.real. If the process is sleeping or yields its execution, then user + system < real. Alternatively, when running a multi-core program, user + system > real.

Some clarification in the docs would be great!

I would accept a PR for this.

[qiolol]

I think there is no too much difference between wall clock and process real clock sementically. The only difference lies in the implementation details, where different system APIs are used for the respective clocks. See https://docs.rs/howlong/0.1.5/howlong/clock/index.html#implementations-2 for more details.

To check my understanding, would it be correct to phrase this as

• the real field of ProcessCPUClock's ProcessTimePoint
• ProcessRealCPUClock
• and SystemClock

are semantically identical in that all three mean to provide real, "wall clock" time, but that this is implementation-dependent by operating system (as shown in the table of the underlying APIs)?

[xu-cheng]

• The real field of ProcessCPUClock and ProcessRealCPUClock are identical. They are using the same implementation.
• There is not much semantical difference between wall clock (i.e., HighResolutionClock, which by default is SteadyClock) and ProcessRealCPUClock. But their implementations are different.
• There is a slight difference between SteadyClock and SystemClock in that the former one guarantees to be increasing monotonically.