Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions mkdocs/contributor_guide/style.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<state>(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
Expand Down
3 changes: 1 addition & 2 deletions mkdocs/education/adc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
}

Expand Down
1 change: 0 additions & 1 deletion mkdocs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,6 @@ supported by the `libhal-micromod` project.
} catch (...) {
while (true) {
// halt here and wait for a debugger to connect
continue;
}
}

Expand Down
Loading