tweak

esphome/components/logger/task_log_buffer_esp32.h

@@ -15,6 +15,22 @@
 
 namespace esphome::logger {
 
+/**
+ * @brief Task log buffer for ESP32 platform using FreeRTOS ring buffer.
+ *
+ * Threading Model: Multi-Producer Single-Consumer (MPSC)
+ * - Multiple FreeRTOS tasks can safely call send_message_thread_safe() concurrently
+ * - Only the main loop task calls borrow_message_main_loop() and release_message_main_loop()
+ *
+ * This uses the FreeRTOS ring buffer (RINGBUF_TYPE_NOSPLIT) which provides
+ * built-in thread-safety for the MPSC pattern. The ring buffer ensures
+ * message integrity - each message is stored contiguously.
+ *
+ * Design:
+ * - Variable-size messages with header + text stored contiguously
+ * - FreeRTOS ring buffer handles synchronization internally
+ * - Atomic counter for fast has_messages() check without ring buffer lock
+ */
 class TaskLogBuffer {
  public:
   // Structure for a log message header (text data follows immediately after)

esphome/components/logger/task_log_buffer_host.h

@@ -19,15 +19,19 @@ namespace esphome::logger {
 /**
  * @brief Lock-free task log buffer for host platform.
  *
- * This implements a Multi-Producer Single-Consumer (MPSC) lock-free ring buffer
- * for log messages on the host platform. It uses atomic operations for thread-safety
+ * Threading Model: Multi-Producer Single-Consumer (MPSC)
+ * - Multiple threads can safely call send_message_thread_safe() concurrently
+ * - Only the main loop thread calls get_message_main_loop() and release_message_main_loop()
+ *
+ * This implements a lock-free ring buffer for log messages on the host platform.
+ * It uses atomic compare-and-swap (CAS) operations for thread-safe slot reservation
  * without requiring mutexes in the hot path.
  *
  * Design:
  * - Fixed number of pre-allocated message slots to avoid dynamic allocation
  * - Each slot contains a header and fixed-size text buffer
- * - Atomic indices for lock-free push/pop operations
- * - Thread-safe for multiple producers, single consumer (main loop)
+ * - Atomic CAS for slot reservation allows multiple producers without locks
+ * - Single consumer (main loop) processes messages in order
  *
  * Host platform has much more memory than embedded devices, so we use larger
  * buffer sizes for better log message handling.