diff --git a/mkdocs/contributor_guide/style.md b/mkdocs/contributor_guide/style.md index 5f1792a3..89327e12 100644 --- a/mkdocs/contributor_guide/style.md +++ b/mkdocs/contributor_guide/style.md @@ -222,6 +222,43 @@ Only the logical operators become words. References keep `&` and `&&` (`T&&`, `spi(spi&&) = delete`, `auto& regs`), and address-of, the bitwise operators and `!=` stay as symbols. +### S.3.7 Leave an infinite loop's body empty + +When a loop with a constant condition, such as `while (true)`, has nothing to +do, leave its body empty and put a comment inside the braces saying why. Do not +write `continue;` in it. + +The compiler may assume that a loop ends unless it performs I/O, a `volatile` +access, or an atomic or synchronization operation. A body of `continue;` does +none of these, so Clang deletes the loop, and execution falls through into +whatever code follows it. An empty body with a constant condition is exempt +(P2809), so that loop stays. + +```cpp +// ❌ Clang deletes this loop and falls into the next function +while (true) { + continue; +} + +// ✅ Spins forever +while (true) { + // Halt here and wait for a debugger to connect. +} +``` + +A loop whose condition reads `volatile` or atomic memory, such as polling a +register or a spin lock, can keep `continue;`. The read is a side effect, so +the loop stays. + +```cpp +while (hal::bit_extract(reg->status) == states::busy) { + continue; +} +``` + +Google's C++ style guide allows either `{}` or `continue` for an empty loop +body. For a loop with a constant condition, only `{}` is safe. + ## S.4 Modules libhal v5 and all libraries in the ecosystem use C++20 modules as the primary diff --git a/mkdocs/education/adc.md b/mkdocs/education/adc.md index 16d57088..77f25002 100644 --- a/mkdocs/education/adc.md +++ b/mkdocs/education/adc.md @@ -400,9 +400,8 @@ resource_list resources{}; bool valid = resources.status_led && resources.clock; if (not valid) { - // spin here until debugger is connected while (true) { - continue; + // spin here until debugger is connected } } diff --git a/mkdocs/index.md b/mkdocs/index.md index b169522a..cc052781 100644 --- a/mkdocs/index.md +++ b/mkdocs/index.md @@ -72,7 +72,6 @@ supported by the `libhal-micromod` project. } catch (...) { while (true) { // halt here and wait for a debugger to connect - continue; } }