docs(appdev): update best practices for loop throttling

This commit is contained in:
boreddevnl
2026-05-11 19:52:48 +02:00
parent a3a4494265
commit d45a19aac1
4 changed files with 14 additions and 13 deletions

View File

@@ -11,7 +11,7 @@ This example demonstrates how to create an empty window that stays active on the
* Including `libui.h` and the event structure.
* Creating a `ui_window_t` handle.
* Creating an infinite event loop using `ui_get_event()`.
* Yielding CPU time to the kernel via `sys_yield()`.
* Yielding CPU time via `sleep(ms)`.
* Declaring app metadata via source annotations.
---
@@ -50,10 +50,11 @@ int main(void) {
}
}
// 4. CRITICAL: Yield the remainder of our timeslice
// 4. CRITICAL: Throttle our loop to save CPU
// If we don't do this, the while(1) loop will consume 100% of the CPU
// and starve the rest of the OS!
sys_yield();
// and starve the rest of the OS! A 10ms sleep allows for ~100 FPS
// event polling while letting the CPU actually idle.
sys_system(SYSTEM_CMD_SLEEP, 10, 0, 0, 0);
}
// Returning from main will automatically destroy the window and exit the process.
@@ -66,7 +67,7 @@ int main(void) {
1. **Window Handle (`wid`)**: `ui_window_create` sends a request to the kernel. The kernel allocates the memory for the window and returns a numerical ID (the handle) that we use for all future interactions with that specific window.
2. **The Event Loop**: Graphical programs run forever until closed. The `while (1)` loop serves this purpose.
3. **Polling**: `ui_get_event` asks the kernel, "Hey, did the user click my window or press a key since the last time I asked?". It is non-blocking, so it immediately returns `false` if nothing happened.
4. **CPU Yielding**: Since we are constantly polling in a tight loop, we call `sys_yield()` at the end of the loop frame. This politely tells the OS scheduler, "I'm done checking for events, go ahead and let another program run for a bit."
4. **CPU Throttling**: Since we are constantly polling in a loop, we call `sys_system(SYSTEM_CMD_SLEEP, 10, ...)` at the end of the loop frame. This tells the OS scheduler, "I'm done checking for events, don't run me again for at least 10ms." This allows the CPU to actually enter a low-power state and makes the system much smoother.
5. **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: Embedded into the `.elf` by the build system as a BoredOS NOTE section. The Window Manager reads this at runtime to render the app's icon on the Desktop and in the File Explorer. See [`elf_metadata.md`](../elf_metadata.md) for full details.
## Running It