lib: keep timestamp in easy handle

Use `data->progress.now` as the timestamp of proecssing a transfer.
Update it on significant events and refrain from calling `curlx_now()`
in many places.

The problem this addresses is
a) calling curlx_now() has costs, depending on platform. Calling it
   every time results in 25% increase `./runtest` duration on macOS.
b) we used to pass a `struct curltime *` around to save on calls, but
   when some method directly use `curx_now()` and some use the passed
   pointer, the transfer experienes non-linear time. This results in
   timeline checks to report events in the wrong order.

By keeping a timestamp in the easy handle and updating it there, no
longer invoking `curlx_now()` in the "lower" methods, the transfer
can observer a steady clock progression.

Add documentation in docs/internals/TIME-KEEPING.md

Reported-by: Viktor Szakats
Fixes #19935
Closes #19961

tests/unit/unit1303.c

@@ -147,7 +147,8 @@ static CURLcode test_unit1303(const char *arg)
     timediff_t timeout;
     NOW(run[i].now_s, run[i].now_us);
     TIMEOUTS(run[i].timeout_ms, run[i].connecttimeout_ms);
-    timeout = Curl_timeleft_ms(easy, &now, run[i].connecting);
+    easy->progress.now = now;
+    timeout = Curl_timeleft_ms(easy, run[i].connecting);
     if(timeout != run[i].result)
       fail(run[i].comment);
   }

tests/unit/unit1399.c

@@ -78,6 +78,7 @@ static CURLcode test_unit1399(const char *arg)
   struct Curl_easy data;
   struct curltime now = curlx_now();
 
+  data.progress.now = now;
   data.progress.t_nslookup = 0;
   data.progress.t_connect = 0;
   data.progress.t_appconnect = 0;

tests/unit/unit3216.c

@@ -33,71 +33,72 @@ static CURLcode test_unit3216(const char *arg)
 
   /* A ratelimit that is unlimited */
   ts = curlx_now();
-  Curl_rlimit_init(&r, 0, 0, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == CURL_OFF_T_MAX, "inf");
-  Curl_rlimit_drain(&r, 1000000, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == CURL_OFF_T_MAX, "drain keep inf");
-  fail_unless(Curl_rlimit_wait_ms(&r, ts) == 0, "inf never waits");
+  Curl_rlimit_init(&r, 0, 0, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == CURL_OFF_T_MAX, "inf");
+  Curl_rlimit_drain(&r, 1000000, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == CURL_OFF_T_MAX, "drain keep inf");
+  fail_unless(Curl_rlimit_wait_ms(&r, &ts) == 0, "inf never waits");
 
-  Curl_rlimit_block(&r, TRUE, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 0, "inf blocked to 0");
-  Curl_rlimit_drain(&r, 1000000, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 0, "blocked inf");
-  Curl_rlimit_block(&r, FALSE, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == CURL_OFF_T_MAX,
+  Curl_rlimit_block(&r, TRUE, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 0, "inf blocked to 0");
+  Curl_rlimit_drain(&r, 1000000, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 0, "blocked inf");
+  Curl_rlimit_block(&r, FALSE, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == CURL_OFF_T_MAX,
               "unblocked unlimited");
 
   /* A ratelimit that give 10 tokens per second */
   ts = curlx_now();
-  Curl_rlimit_init(&r, 10, 0, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 10, "initial 10");
-  Curl_rlimit_drain(&r, 5, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 5, "drain to 5");
-  Curl_rlimit_drain(&r, 3, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 2, "drain to 2");
+  Curl_rlimit_init(&r, 10, 0, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 10, "initial 10");
+  Curl_rlimit_drain(&r, 5, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 5, "drain to 5");
+  Curl_rlimit_drain(&r, 3, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 2, "drain to 2");
   ts.tv_usec += 1000; /* 1ms */
-  Curl_rlimit_drain(&r, 3, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == -1, "drain to -1");
-  fail_unless(Curl_rlimit_wait_ms(&r, ts) == 999, "wait 999ms");
+  Curl_rlimit_drain(&r, 3, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == -1, "drain to -1");
+  fail_unless(Curl_rlimit_wait_ms(&r, &ts) == 999, "wait 999ms");
   ts.tv_usec += 1000; /* 1ms */
-  fail_unless(Curl_rlimit_wait_ms(&r, ts) == 998, "wait 998ms");
+  fail_unless(Curl_rlimit_wait_ms(&r, &ts) == 998, "wait 998ms");
   ts.tv_sec += 1;
-  fail_unless(Curl_rlimit_avail(&r, ts) == 9, "10 inc per sec");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 9, "10 inc per sec");
   ts.tv_sec += 1;
-  fail_unless(Curl_rlimit_avail(&r, ts) == 19, "10 inc per sec(2)");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 19, "10 inc per sec(2)");
 
-  Curl_rlimit_block(&r, TRUE, curlx_now());
-  fail_unless(Curl_rlimit_avail(&r, curlx_now()) == 0, "10 blocked to 0");
-  Curl_rlimit_block(&r, FALSE, curlx_now());
-  fail_unless(Curl_rlimit_avail(&r, curlx_now()) == 10, "unblocked 10");
+  ts = curlx_now();
+  Curl_rlimit_block(&r, TRUE, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 0, "10 blocked to 0");
+  Curl_rlimit_block(&r, FALSE, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 10, "unblocked 10");
 
   /* A ratelimit that give 10 tokens per second, max burst 15/s */
   ts = curlx_now();
-  Curl_rlimit_init(&r, 10, 15, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 10, "initial 10");
-  Curl_rlimit_drain(&r, 5, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 5, "drain to 5");
-  Curl_rlimit_drain(&r, 3, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 2, "drain to 2");
-  Curl_rlimit_drain(&r, 3, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == -1, "drain to -1");
+  Curl_rlimit_init(&r, 10, 15, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 10, "initial 10");
+  Curl_rlimit_drain(&r, 5, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 5, "drain to 5");
+  Curl_rlimit_drain(&r, 3, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 2, "drain to 2");
+  Curl_rlimit_drain(&r, 3, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == -1, "drain to -1");
   ts.tv_sec += 1;
-  fail_unless(Curl_rlimit_avail(&r, ts) == 9, "10 inc per sec");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 9, "10 inc per sec");
   ts.tv_sec += 1;
-  fail_unless(Curl_rlimit_avail(&r, ts) == 15, "10/15 burst limit");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 15, "10/15 burst limit");
   ts.tv_sec += 1;
-  fail_unless(Curl_rlimit_avail(&r, ts) == 15, "10/15 burst limit(2)");
-  Curl_rlimit_drain(&r, 15, ts);
-  fail_unless(Curl_rlimit_avail(&r, ts) == 0, "drain to 0");
-  fail_unless(Curl_rlimit_wait_ms(&r, ts) == 1000, "wait 1 sec");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 15, "10/15 burst limit(2)");
+  Curl_rlimit_drain(&r, 15, &ts);
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 0, "drain to 0");
+  fail_unless(Curl_rlimit_wait_ms(&r, &ts) == 1000, "wait 1 sec");
   ts.tv_usec += 500000; /* half a sec, cheating on second carry */
-  fail_unless(Curl_rlimit_avail(&r, ts) == 0, "0 after 0.5 sec");
-  fail_unless(Curl_rlimit_wait_ms(&r, ts) == 500, "wait 0.5 sec");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 0, "0 after 0.5 sec");
+  fail_unless(Curl_rlimit_wait_ms(&r, &ts) == 500, "wait 0.5 sec");
   ts.tv_sec += 1;
-  fail_unless(Curl_rlimit_avail(&r, ts) == 10, "10 after 1.5 sec");
-  fail_unless(Curl_rlimit_wait_ms(&r, ts) == 0, "wait 0");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 10, "10 after 1.5 sec");
+  fail_unless(Curl_rlimit_wait_ms(&r, &ts) == 0, "wait 0");
   ts.tv_usec += 500000; /* half a sec, cheating on second carry */
-  fail_unless(Curl_rlimit_avail(&r, ts) == 15, "10 after 2 sec");
+  fail_unless(Curl_rlimit_avail(&r, &ts) == 15, "10 after 2 sec");
 
   UNITTEST_END_SIMPLE
 }