Mirrors/curl
0
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-01-18 17:21:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

TIME-KEEPING.md: fold long lines

Browse Source
This commit is contained in:
Viktor Szakats
2025-12-18 23:00:06 +01:00
parent b4be1f271e
commit 1e0865b630
2 changed files with 29 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/internals/TIME-KEEPING.md
View 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.

3
docs/internals/UINT_SETS.md
View 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