diff --git a/docs/internals/TIME-KEEPING.md b/docs/internals/TIME-KEEPING.md index 769c195d1c..91ac4d9cad 100644 --- a/docs/internals/TIME-KEEPING.md +++ b/docs/internals/TIME-KEEPING.md @@ -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. diff --git a/docs/internals/UINT_SETS.md b/docs/internals/UINT_SETS.md index 5158d7e6bd..963cc82d48 100644 --- a/docs/internals/UINT_SETS.md +++ b/docs/internals/UINT_SETS.md @@ -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