Serialized pending-operation queue with coalescing, deduplication, and two-band ordering. More...

#include <operation_queue.h>

Collaboration diagram for esphome::home_io_control::OperationQueue:

Public Member Functions
bool	enqueue_set_position (const std::string &device_id, uint8_t position)
	Enqueue SET_POSITION, or coalesce with a pending SET_TILT into SET_POSITION_AND_TILT.
bool	enqueue_set_tilt (const std::string &device_id, uint8_t tilt_percent)
	Enqueue SET_TILT, or coalesce with a pending SET_POSITION into SET_POSITION_AND_TILT.
void	enqueue_set_position_and_tilt (const std::string &device_id, uint8_t position, uint8_t tilt_percent)
	Enqueue SET_POSITION_AND_TILT directly (no coalescing needed).
void	enqueue_device_command (const std::string &device_id, CoverCommand cmd)
void	enqueue_set_light_position (const std::string &device_id, uint8_t position)
	Enqueue SET_LIGHT_STATE with an arbitrary IO position (0-100), for dimmable lights.
void	enqueue_set_light_state (const std::string &device_id, bool on)
void	enqueue_set_lock_state (const std::string &device_id, bool locked)
void	enqueue_set_switch_state (const std::string &device_id, bool on)
bool	enqueue_request_status (const std::string &device_id)
	Enqueue REQUEST_STATUS, suppressing duplicates.
bool	enqueue_request_name (const std::string &device_id)
	Enqueue REQUEST_NAME, suppressing duplicates.
bool	enqueue_discover_and_pair ()
	Enqueue DISCOVER_AND_PAIR with elevated priority.
std::optional< PendingOperation >	pop ()
bool	empty () const
std::size_t	size () const
const PendingOperation &	front () const
const PendingOperation &	back () const
const PendingOperation &	operator[] (std::size_t index) const
std::deque< PendingOperation >::const_iterator	begin () const
std::deque< PendingOperation >::const_iterator	end () const

Static Public Member Functions
static bool	is_background_op (PendingOperationType t)
	True for background poll types (REQUEST_STATUS, REQUEST_NAME) that yield to control operations.

Detailed Description

Serialized pending-operation queue with coalescing, deduplication, and two-band ordering.

Ordering: DISCOVER_AND_PAIR > control operations > background polls. Control operations (SET_*, DEVICE_COMMAND) are inserted before any queued REQUEST_STATUS / REQUEST_NAME entries so user-visible commands execute with minimum queue latency. DISCOVER_AND_PAIR always front-inserts ahead of all other entries.

Stale-poll drop: enqueueing a control operation for device X drops any queued REQUEST_STATUS for X, since the command reply supersedes it and re-arms tracking.

Coalescing rules (both directions):

SET_POSITION arriving while SET_TILT is pending for the same device → SET_POSITION_AND_TILT.
SET_TILT arriving while SET_POSITION is pending for the same device → SET_POSITION_AND_TILT.

Deduplication rules:

At most one REQUEST_STATUS per device.
At most one REQUEST_NAME per device.
At most one DISCOVER_AND_PAIR (any pending REQUEST_STATUS / REQUEST_NAME entries are flushed and the discover entry is pushed to the front to minimize pairing-window latency).

All coalescing and deduplication log messages are suppressed here — callers are responsible for emitting them because OperationQueue must remain free of ESPHome logging dependencies.

Definition at line 71 of file operation_queue.h.

Member Function Documentation

◆ back()

const PendingOperation & esphome::home_io_control::OperationQueue::back ( ) const

nodiscard

Definition at line 134 of file operation_queue.cpp.

◆ begin()

std::deque< PendingOperation >::const_iterator esphome::home_io_control::OperationQueue::begin ( ) const

nodiscard

Definition at line 138 of file operation_queue.cpp.

◆ empty()

bool esphome::home_io_control::OperationQueue::empty ( ) const

nodiscard

Definition at line 128 of file operation_queue.cpp.

◆ end()

std::deque< PendingOperation >::const_iterator esphome::home_io_control::OperationQueue::end ( ) const

nodiscard

Definition at line 140 of file operation_queue.cpp.

◆ enqueue_device_command()

void esphome::home_io_control::OperationQueue::enqueue_device_command	(	const std::string &	device_id,
		CoverCommand	cmd )

Definition at line 61 of file operation_queue.cpp.

◆ enqueue_discover_and_pair()

bool esphome::home_io_control::OperationQueue::enqueue_discover_and_pair ( )

Enqueue DISCOVER_AND_PAIR with elevated priority.

Flushes pending REQUEST_STATUS / REQUEST_NAME entries and pushes to front.

Returns: true if pushed, false if a DISCOVER_AND_PAIR was already pending.

Definition at line 105 of file operation_queue.cpp.

◆ enqueue_request_name()

bool esphome::home_io_control::OperationQueue::enqueue_request_name ( const std::string & device_id )

Enqueue REQUEST_NAME, suppressing duplicates.

Returns: true if pushed, false if a duplicate was already pending.

Definition at line 96 of file operation_queue.cpp.

◆ enqueue_request_status()

bool esphome::home_io_control::OperationQueue::enqueue_request_status ( const std::string & device_id )

Enqueue REQUEST_STATUS, suppressing duplicates.

Returns: true if pushed, false if a duplicate was already pending.

Definition at line 87 of file operation_queue.cpp.

◆ enqueue_set_light_position()

void esphome::home_io_control::OperationQueue::enqueue_set_light_position	(	const std::string &	device_id,
		uint8_t	position )

Enqueue SET_LIGHT_STATE with an arbitrary IO position (0-100), for dimmable lights.

enqueue_set_light_state() is a thin binary-position wrapper around this.

Definition at line 69 of file operation_queue.cpp.

◆ enqueue_set_light_state()

void esphome::home_io_control::OperationQueue::enqueue_set_light_state	(	const std::string &	device_id,
		bool	on )

Definition at line 73 of file operation_queue.cpp.

Here is the call graph for this function:

◆ enqueue_set_lock_state()

void esphome::home_io_control::OperationQueue::enqueue_set_lock_state	(	const std::string &	device_id,
		bool	locked )

Definition at line 77 of file operation_queue.cpp.

◆ enqueue_set_position()

bool esphome::home_io_control::OperationQueue::enqueue_set_position	(	const std::string &	device_id,
		uint8_t	position )

Enqueue SET_POSITION, or coalesce with a pending SET_TILT into SET_POSITION_AND_TILT.

Returns: true if coalesced (caller should log the merge), false if a new entry was pushed.

Definition at line 28 of file operation_queue.cpp.

◆ enqueue_set_position_and_tilt()

void esphome::home_io_control::OperationQueue::enqueue_set_position_and_tilt	(	const std::string &	device_id,
		uint8_t	position,
		uint8_t	tilt_percent )

Enqueue SET_POSITION_AND_TILT directly (no coalescing needed).

Definition at line 56 of file operation_queue.cpp.

◆ enqueue_set_switch_state()

void esphome::home_io_control::OperationQueue::enqueue_set_switch_state	(	const std::string &	device_id,
		bool	on )

Definition at line 82 of file operation_queue.cpp.

◆ enqueue_set_tilt()

bool esphome::home_io_control::OperationQueue::enqueue_set_tilt	(	const std::string &	device_id,
		uint8_t	tilt_percent )

Enqueue SET_TILT, or coalesce with a pending SET_POSITION into SET_POSITION_AND_TILT.

Returns: true if coalesced (caller should log the merge), false if a new entry was pushed.

Definition at line 43 of file operation_queue.cpp.

◆ front()

const PendingOperation & esphome::home_io_control::OperationQueue::front ( ) const

nodiscard

Definition at line 132 of file operation_queue.cpp.

◆ is_background_op()

bool esphome::home_io_control::OperationQueue::is_background_op ( PendingOperationType t )

staticnodiscard

True for background poll types (REQUEST_STATUS, REQUEST_NAME) that yield to control operations.

Public because the dispatch gate in loop() defers only background work when a 1W remote is transmitting; a user command must never be held back for it.

Definition at line 12 of file operation_queue.cpp.

◆ operator[]()

const PendingOperation & esphome::home_io_control::OperationQueue::operator[] ( std::size_t index ) const

nodiscard

Definition at line 136 of file operation_queue.cpp.

◆ pop()

std::optional< PendingOperation > esphome::home_io_control::OperationQueue::pop ( )

nodiscard

Definition at line 120 of file operation_queue.cpp.

◆ size()

std::size_t esphome::home_io_control::OperationQueue::size ( ) const

nodiscard

Definition at line 130 of file operation_queue.cpp.

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

components/home_io_control/operation_queue.h
components/home_io_control/operation_queue.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ back()

◆ begin()

◆ empty()

◆ end()

◆ enqueue_device_command()

◆ enqueue_discover_and_pair()

◆ enqueue_request_name()

◆ enqueue_request_status()

◆ enqueue_set_light_position()

◆ enqueue_set_light_state()

◆ enqueue_set_lock_state()

◆ enqueue_set_position()

◆ enqueue_set_position_and_tilt()

◆ enqueue_set_switch_state()

◆ enqueue_set_tilt()

◆ front()

◆ is_background_op()

◆ operator[]()

◆ pop()

◆ size()