doc times: do not use now (and also epochTime) for benchmarking

[timotheecour]

common pitfall, eg now is used in nim-lang/website#274

rationale:

• epochTime uses (on osx) gettimeofday which is non-monotonic, eg see [1]
• now has same problems as epochTime, and on top of that has overhead (which is really bad for benchmarking, depending on the time scales involved), and deals with timezones, and return type DateTime is a heavy object;

links

• [1] https://news.ycombinator.com/item?id=12089632

gettimeofday() is totally inappropriate for benchmarking. Any time the system clock is being adjusted by NTP, for instance, your benchmark timing will be skewed.They should be using the following API if they're going to use the system time to measure time differences:clock_gettime(CLOCK_MONOTONIC, &timespec);It's a really good clue that a timing function is inappropriate for benchmarking when the man page talks about time zones.

• https://blog.habets.se/2010/09/gettimeofday-should-never-be-used-to-measure-time.html
• https://stackoverflow.com/questions/14270300/what-is-the-difference-between-clock-monotonic-clock-monotonic-raw

future work

• finish [TODO] [WIP] new std/timers module for high performance / low overhead timers and benchmarking (formerly system/timers include) #13617 which will allow having even less overhead than getMonoTime
• give more options than CLOCK_MONOTONIC, see https://linux.die.net/man/2/clock_gettime, on systems that have those options (and find nearest equivalent on osx):

CLOCK_MONOTONIC_COARSE (since Linux 2.6.32; Linux-specific)
A faster but less precise version of CLOCK_MONOTONIC. Use when you need very fast, but not fine-grained timestamps.
CLOCK_MONOTONIC_RAW (since Linux 2.6.28; Linux-specific)
Similar to CLOCK_MONOTONIC, but provides access to a raw hardware-based time that is not subject to NTP adjustments or the incremental adjustments performed by adjtime(3).
CLOCK_BOOTTIME (since Linux 2.6.39; Linux-specific)
Identical to CLOCK_MONOTONIC, except it also includes any time that the system is suspended. This allows applications to get a suspend-aware monotonic clock without having to deal with the complications of CLOCK_REALTIME, which may have discontinuities if the time is changed using settimeofday(2).
CLOCK_PROCESS_CPUTIME_ID
High-resolution per-process timer from the CPU.
CLOCK_THREAD_CPUTIME_ID
Thread-specific CPU-time clock.