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_fan_position (const std::string &device_id, uint8_t position)
	Enqueue SET_FAN_POSITION with an IO position (0-100; 0 = full heat, 100 = off).
void	enqueue_set_lock_state (const std::string &device_id, bool locked)
void	enqueue_set_switch_state (const std::string &device_id, bool on)
void	enqueue_oneway_command (const std::string &controller_id, CoverCommand cmd)
	Enqueue a 1W named command for a controller identity.
void	enqueue_oneway_position (const std::string &controller_id, uint8_t position)
	Enqueue a 1W numeric position for a controller identity.
void	enqueue_oneway_enroll (const std::string &controller_id)
	Enqueue a 1W enrollment (add-controller) for a controller identity.
void	enqueue_oneway_unenroll (const std::string &controller_id)
	Enqueue a 1W un-enrollment (remove-controller) for a controller identity.
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_request_limitation (const std::string &device_id)
	Enqueue REQUEST_LIMITATION, 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, REQUEST_LIMITATION) 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 background polls (REQUEST_STATUS, REQUEST_NAME, REQUEST_LIMITATION) 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. A queued REQUEST_LIMITATION is kept: a status reply does not answer it.

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 REQUEST_LIMITATION per device.
At most one DISCOVER_AND_PAIR (every pending background poll is 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 84 of file operation_queue.h.

Member Function Documentation

◆ back()

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

nodiscard

Definition at line 169 of file operation_queue.cpp.

◆ begin()

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

nodiscard

Definition at line 173 of file operation_queue.cpp.

◆ empty()

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

nodiscard

Definition at line 163 of file operation_queue.cpp.

◆ end()

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

nodiscard

Definition at line 175 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 72 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 every pending background poll (see is_background_op()) and pushes to front.

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

Definition at line 143 of file operation_queue.cpp.

◆ enqueue_oneway_command()

void esphome::home_io_control::OperationQueue::enqueue_oneway_command	(	const std::string &	controller_id,
		CoverCommand	cmd )

Enqueue a 1W named command for a controller identity.

Deliberately neither coalesced nor deduplicated, unlike their 2W counterparts. A 2W command can be superseded because the device reports back what it did; a 1W command cannot be confirmed at all, so dropping one is dropping a press the user made with nothing to notice it. Each press also consumes its own sequence, and merging two would leave a gap that looks like a lost frame to a device tracking the counter.

Parameters

controller_id	Controller-identity handle (see PendingOperation::device_id).
cmd	Named command to send.

Definition at line 80 of file operation_queue.cpp.

◆ enqueue_oneway_enroll()

void esphome::home_io_control::OperationQueue::enqueue_oneway_enroll ( const std::string & controller_id )

Enqueue a 1W enrollment (add-controller) for a controller identity.

Same no-coalesce, no-dedup contract as the other 1W ops, for the same reason.

Parameters

controller_id Controller-identity handle (see PendingOperation::device_id).

Definition at line 92 of file operation_queue.cpp.

◆ enqueue_oneway_position()

void esphome::home_io_control::OperationQueue::enqueue_oneway_position	(	const std::string &	controller_id,
		uint8_t	position )

Enqueue a 1W numeric position for a controller identity.

Parameters

controller_id	Controller-identity handle (see PendingOperation::device_id).
position	Target position 0–100.

Definition at line 88 of file operation_queue.cpp.

◆ enqueue_oneway_unenroll()

void esphome::home_io_control::OperationQueue::enqueue_oneway_unenroll ( const std::string & controller_id )

Enqueue a 1W un-enrollment (remove-controller) for a controller identity.

Parameters

controller_id Controller-identity handle (see PendingOperation::device_id).

Definition at line 96 of file operation_queue.cpp.

◆ enqueue_request_limitation()

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

Enqueue REQUEST_LIMITATION, suppressing duplicates.

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

Definition at line 139 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 135 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 131 of file operation_queue.cpp.

◆ enqueue_set_fan_position()

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

Enqueue SET_FAN_POSITION with an IO position (0-100; 0 = full heat, 100 = off).

Definition at line 104 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 100 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 108 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 112 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 39 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 67 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 117 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 54 of file operation_queue.cpp.

◆ front()

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

nodiscard

Definition at line 167 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, REQUEST_LIMITATION) 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 171 of file operation_queue.cpp.

◆ pop()

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

nodiscard

Definition at line 155 of file operation_queue.cpp.

◆ size()

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

nodiscard

Definition at line 165 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_oneway_command()

◆ enqueue_oneway_enroll()

◆ enqueue_oneway_position()

◆ enqueue_oneway_unenroll()

◆ enqueue_request_limitation()

◆ enqueue_request_name()

◆ enqueue_request_status()

◆ enqueue_set_fan_position()

◆ 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()