Task log buffer for ESP32 platform using FreeRTOS ring buffer. More...

#include <task_log_buffer_esp32.h>

Data Structures
struct	LogMessage

Public Member Functions
	TaskLogBuffer (size_t total_buffer_size)

	~TaskLogBuffer ()

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

bool HOT	has_messages () const

size_t	size () const

	TaskLogBuffer (size_t slot_count)
	Constructor that takes the number of message slots.

	~TaskLogBuffer ()

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

bool HOT	has_messages () const

size_t	size () const

	TaskLogBuffer (size_t total_buffer_size)

	~TaskLogBuffer ()

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

bool HOT	has_messages () const

size_t	size () const

	TaskLogBuffer (size_t total_buffer_size)

	~TaskLogBuffer ()

bool HOT	has_messages ()

size_t	size () const

bool	borrow_message_main_loop (LogMessage *&message, uint16_t &text_length)

void	release_message_main_loop ()

bool	send_message_thread_safe (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *format, va_list args)

Static Public Attributes
static constexpr size_t	DEFAULT_SLOT_COUNT = 64

static constexpr uint8_t	PADDING_MARKER_LEVEL = 0xFF

Protected Attributes
mpsc_pbuf_buffer_config	mpsc_config_ {}

mpsc_pbuf_buffer	log_buffer_ {}

const mpsc_pbuf_generic *	current_token_ {}

Detailed Description

Task log buffer for ESP32 platform using FreeRTOS ring buffer.

Task log buffer for LibreTiny platform using mutex-protected circular buffer.

Lock-free task log buffer for host platform.

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

Threading Model: Multi-Producer Single-Consumer (MPSC)

Multiple threads can safely call send_message_thread_safe() concurrently
Only the main loop thread calls borrow_message_main_loop() and release_message_main_loop()

Producers (multiple threads) Consumer (main loop only) │ │ ▼ ▼ acquire_write_slot_() bool borrow_message_main_loop() CAS on reserve_index_ read write_index_ │ check ready flag ▼ │ write to slot (exclusive) ▼ │ read slot data ▼ │ commit_write_slot_() ▼ set ready=true release_message_main_loop() advance write_index_ set ready=false advance read_index_

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 CAS for slot reservation allows multiple producers without locks
Single consumer (main loop) processes messages in order

Why This Is Critical: Without thread-safe logging, when a non-main task logs a message, it would directly call the logger which builds a protobuf message in a shared buffer. If this happens while the main loop is also using that buffer (e.g., sending API responses), the buffer gets corrupted, sending garbage to all connected API clients and breaking their connections. This buffer ensures log messages from other tasks are queued safely and processed only from the main loop.

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 a simple circular buffer protected by a FreeRTOS mutex. Unlike ESP32, LibreTiny lacks hardware atomic support (ARM968E-S has no LDREX/STREX), so we use a volatile counter for fast has_messages() checks instead of atomics.

Design:

Variable-size messages with header + text stored contiguously (NOSPLIT style)
FreeRTOS mutex protects all buffer operations
Volatile counter enables fast has_messages() without lock overhead
If message doesn't fit at end, padding is added and message wraps to start

Definition at line 18 of file task_log_buffer_zephyr.h.

Constructor & Destructor Documentation

◆ TaskLogBuffer() [1/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( size_t total_buffer_size )

explicit

Definition at line 11 of file task_log_buffer_esp32.cpp.

◆ ~TaskLogBuffer() [1/4]

esphome::logger::TaskLogBuffer::~TaskLogBuffer ( )

Definition at line 21 of file task_log_buffer_esp32.cpp.

◆ TaskLogBuffer() [2/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( size_t slot_count )

explicit

Constructor that takes the number of message slots.

◆ ~TaskLogBuffer() [2/4]

esphome::logger::TaskLogBuffer::~TaskLogBuffer ( )

◆ TaskLogBuffer() [3/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( size_t total_buffer_size )

explicit

◆ ~TaskLogBuffer() [3/4]

esphome::logger::TaskLogBuffer::~TaskLogBuffer ( )

◆ TaskLogBuffer() [4/4]

esphome::logger::TaskLogBuffer::TaskLogBuffer ( size_t total_buffer_size )

explicit

◆ ~TaskLogBuffer() [4/4]

esphome::logger::TaskLogBuffer::~TaskLogBuffer ( )

Member Function Documentation

◆ borrow_message_main_loop() [1/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

Definition at line 34 of file task_log_buffer_esp32.cpp.

◆ borrow_message_main_loop() [2/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

◆ borrow_message_main_loop() [3/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

◆ borrow_message_main_loop() [4/4]

bool esphome::logger::TaskLogBuffer::borrow_message_main_loop	(	LogMessage *&	message,
		uint16_t &	text_length )

◆ has_messages() [1/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( )

inline

Definition at line 41 of file task_log_buffer_zephyr.h.

◆ has_messages() [2/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( ) const

inline

Definition at line 65 of file task_log_buffer_esp32.h.

◆ has_messages() [3/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( ) const

inline

Definition at line 94 of file task_log_buffer_host.h.

◆ has_messages() [4/4]

bool HOT esphome::logger::TaskLogBuffer::has_messages ( ) const

inline

Definition at line 78 of file task_log_buffer_libretiny.h.

◆ release_message_main_loop() [1/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

Definition at line 53 of file task_log_buffer_esp32.cpp.

◆ release_message_main_loop() [2/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

◆ release_message_main_loop() [3/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

◆ release_message_main_loop() [4/4]

void esphome::logger::TaskLogBuffer::release_message_main_loop ( )

◆ send_message_thread_safe() [1/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

Definition at line 63 of file task_log_buffer_esp32.cpp.

◆ send_message_thread_safe() [2/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

◆ send_message_thread_safe() [3/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

◆ send_message_thread_safe() [4/4]

bool esphome::logger::TaskLogBuffer::send_message_thread_safe	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	format,
		va_list	args )

◆ size() [1/4]

size_t esphome::logger::TaskLogBuffer::size ( ) const

inline

Definition at line 70 of file task_log_buffer_esp32.h.

◆ size() [2/4]

size_t esphome::logger::TaskLogBuffer::size ( ) const

inline

Definition at line 99 of file task_log_buffer_host.h.

◆ size() [3/4]

size_t esphome::logger::TaskLogBuffer::size ( ) const

inline

Definition at line 81 of file task_log_buffer_libretiny.h.

◆ size() [4/4]

size_t esphome::logger::TaskLogBuffer::size ( ) const

inline

Definition at line 44 of file task_log_buffer_zephyr.h.

Field Documentation

◆ current_token_

const mpsc_pbuf_generic* esphome::logger::TaskLogBuffer::current_token_ {}

protected

Definition at line 59 of file task_log_buffer_zephyr.h.

◆ DEFAULT_SLOT_COUNT

size_t esphome::logger::TaskLogBuffer::DEFAULT_SLOT_COUNT = 64

staticconstexpr

Definition at line 54 of file task_log_buffer_host.h.

◆ log_buffer_

mpsc_pbuf_buffer esphome::logger::TaskLogBuffer::log_buffer_ {}

protected

Definition at line 58 of file task_log_buffer_zephyr.h.

◆ mpsc_config_

mpsc_pbuf_buffer_config esphome::logger::TaskLogBuffer::mpsc_config_ {}

protected

Definition at line 57 of file task_log_buffer_zephyr.h.

◆ PADDING_MARKER_LEVEL

uint8_t esphome::logger::TaskLogBuffer::PADDING_MARKER_LEVEL = 0xFF

staticconstexpr

Definition at line 60 of file task_log_buffer_libretiny.h.

The documentation for this class was generated from the following files:

esphome/components/logger/task_log_buffer_esp32.h
esphome/components/logger/task_log_buffer_host.h
esphome/components/logger/task_log_buffer_libretiny.h
esphome/components/logger/task_log_buffer_zephyr.h
esphome/components/logger/task_log_buffer_esp32.cpp
esphome/components/logger/task_log_buffer_host.cpp
esphome/components/logger/task_log_buffer_libretiny.cpp
esphome/components/logger/task_log_buffer_zephyr.cpp

Data Structures

Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TaskLogBuffer() [1/4]

◆ ~TaskLogBuffer() [1/4]

◆ TaskLogBuffer() [2/4]

◆ ~TaskLogBuffer() [2/4]

◆ TaskLogBuffer() [3/4]

◆ ~TaskLogBuffer() [3/4]

◆ TaskLogBuffer() [4/4]

◆ ~TaskLogBuffer() [4/4]

Member Function Documentation

◆ borrow_message_main_loop() [1/4]

◆ borrow_message_main_loop() [2/4]

◆ borrow_message_main_loop() [3/4]

◆ borrow_message_main_loop() [4/4]

◆ has_messages() [1/4]

◆ has_messages() [2/4]

◆ has_messages() [3/4]

◆ has_messages() [4/4]

◆ release_message_main_loop() [1/4]

◆ release_message_main_loop() [2/4]

◆ release_message_main_loop() [3/4]

◆ release_message_main_loop() [4/4]

◆ send_message_thread_safe() [1/4]

◆ send_message_thread_safe() [2/4]

◆ send_message_thread_safe() [3/4]

◆ send_message_thread_safe() [4/4]

◆ size() [1/4]

◆ size() [2/4]

◆ size() [3/4]

◆ size() [4/4]

Field Documentation

◆ current_token_

◆ DEFAULT_SLOT_COUNT

◆ log_buffer_

◆ mpsc_config_

◆ PADDING_MARKER_LEVEL