]> git.ipfire.org Git - thirdparty/curl.git/commitdiff
TIME-KEEPING.md: fold long lines
authorViktor Szakats <commit@vsz.me>
Thu, 18 Dec 2025 22:00:06 +0000 (23:00 +0100)
committerViktor Szakats <commit@vsz.me>
Thu, 18 Dec 2025 22:00:06 +0000 (23:00 +0100)
docs/internals/TIME-KEEPING.md
docs/internals/UINT_SETS.md

index 769c195d1c77e7043871f783d52fb61f6c7b8023..91ac4d9cadc94cf6faf39fa22786a6b887e97004 100644 (file)
@@ -6,40 +6,48 @@ SPDX-License-Identifier: curl
 
 # Keeping Time
 
-Transfers need the current time to handle timeouts and keep a record of events. The current
-time function is `curlx_now()` and it uses a **monotonic** clock on most platforms. This
-ensures that time only ever increases (the timestamps it gives are however not the "real"
-world clock).
+Transfers need the current time to handle timeouts and keep a record of
+events. The current time function is `curlx_now()` and it uses a **monotonic**
+clock on most platforms. This ensures that time only ever increases (the
+timestamps it gives are however not the "real" world clock).
 
 ## Initial Approach (now historic)
 
-The loop processing functions called `curlx_now()` at the beginning and then passed
-a pointer to the `struct curltime now` to functions to save them the calls. Passing
-this pointer down to all functions possibly involved was not done as this pollutes
-the internal APIs.
+The loop processing functions called `curlx_now()` at the beginning and then
+passed a pointer to the `struct curltime now` to functions to save them the
+calls. Passing this pointer down to all functions possibly involved was not
+done as this pollutes the internal APIs.
 
-So, some functions continued to call `curlx_now()` on their own while others used the
-passed pointer *to a timestamp in the past*. This led to a transfer experiencing *jumps*
-in time, reversing cause and effect. On fast systems, this was mostly not noticeable. On
-slow machines or in CI, this led to rare and annoying test failures.
+So, some functions continued to call `curlx_now()` on their own while others
+used the passed pointer *to a timestamp in the past*. This led to a transfer
+experiencing *jumps* in time, reversing cause and effect. On fast systems,
+this was mostly not noticeable. On slow machines or in CI, this led to rare
+and annoying test failures.
 
-(Especially when we added assertions that the reported "timeline" of a transfer was
-in the correct order: *queue -> nameloopup -> connect -> appconnect ->...*.)
+(Especially when we added assertions that the reported "timeline" of a
+transfer was in the correct order: *queue -> nameloopup -> connect ->
+appconnect ->...*.)
 
 ## Revised Approach
 
 The strategy of handling transfer's time is now:
 
-* Keep a "now" timestamp in the multi handle. Keep a fallback "now" timestamp in the easy handle.
+* Keep a "now" timestamp in the multi handle. Keep a fallback "now" timestamp
+  in the easy handle.
 * Always use `Curl_pgrs_now(data)` to get the current time of a transfer.
-* Do not use `curlx_now()` directly for transfer handling (exceptions apply for loops).
+* Do not use `curlx_now()` directly for transfer handling (exceptions apply
+  for loops).
 
 This has the following advantages:
 
-* No need to pass a `struct curltime` around or pass a pointer to an outdated timestamp to other functions.
+* No need to pass a `struct curltime` around or pass a pointer to an outdated
+  timestamp to other functions.
 * No need to calculate the exact `now` until it is really used.
-* Passing a `const` pointer is better than struct passing. Updating and passing a pointer to the same memory location for all transfers is even better.
+* Passing a `const` pointer is better than struct passing. Updating and
+  passing a pointer to the same memory location for all transfers is even
+  better.
 
 Caveats:
 
-* do not store the pointer returned by `Curl_pgrs_now(data)` anywhere that outlives the current code invocation.
+* do not store the pointer returned by `Curl_pgrs_now(data)` anywhere that
+  outlives the current code invocation.
index 5158d7e6bdde359c6e4e0c57846654bb407d05f1..963cc82d48fe81836b46e8da06f23c8e96a8fbbd 100644 (file)
@@ -44,7 +44,8 @@ This iteration has the following properties:
 
 * entries in the table can be added/removed safely.
 * all entries that are not removed during the iteration are visited.
-* the table may be resized to a larger capacity without affecting visited entries.
+* the table may be resized to a larger capacity without affecting visited
+  entries.
 * entries added with a larger index than the current are visited.
 
 ### Memory