Per-device periodic poll schedule, miss retry and miss counter for one poll kind. More...

#include <periodic_poll_policy.h>

Collaboration diagram for esphome::home_io_control::PeriodicPollPolicy:

Public Member Functions
void	set_interval (const std::string &device_id, uint32_t interval_ms, uint32_t now, uint32_t random)
	Set the poll interval and schedule the first poll at periodic_poll_first_delay_ms(`random`) after `now`.
uint32_t	get_interval (const std::string &device_id) const
	Return the configured interval (0 when the device is not scheduled).
bool	has_due (uint32_t now) const
	True when any device's poll is due at `now`.
std::optional< std::string >	pop_due_device (uint32_t now, uint32_t random)
	Return one device whose poll is due and immediately schedule its next poll at periodic_poll_jittered_interval_ms() after `now`, so a poll that is later dropped from the operation queue (pairing flushes background work) is skipped rather than lost forever.
void	defer (const std::string &device_id, uint32_t delay_ms, uint32_t now)
	Pull the device's next poll forward to `delay_ms` after `now`. Never pushes it later.
void	restart_interval (const std::string &device_id, uint32_t now, uint32_t random)
	The device has just given what the poll asks for without being polled: schedule its next poll periodic_poll_jittered_interval_ms() after `now`, earlier or later than it was, and drop an armed retry.
bool	on_poll_failed (const std::string &device_id)
	Count one failed poll (saturating), with no retry: for a poll the device answered with something that is not a reading (an error reply, an unexpected shape), which asking again soon would not change.
bool	on_poll_unanswered (const std::string &device_id, uint32_t now)
	Handle a poll the device left unanswered.
bool	retry_armed (const std::string &device_id) const
	True while a retry armed by on_poll_unanswered() has not been popped yet.
void	on_poll_succeeded (const std::string &device_id)
	Clear the unanswered-poll count.
bool	first_error_reply (const std::string &device_id)
	True the first time it is called for a device that answered the poll's request with an error reply, false afterwards, so the log names that once instead of every poll.
uint8_t	get_failures (const std::string &device_id) const
	Consecutive failed polls (0 for an unscheduled device).
uint32_t	get_next_poll (const std::string &device_id) const
	Absolute millis() time of the device's next poll (0 for an unscheduled device).

Detailed Description

Per-device periodic poll schedule, miss retry and miss counter for one poll kind.

Definition at line 69 of file periodic_poll_policy.h.

Member Function Documentation

◆ defer()

void esphome::home_io_control::PeriodicPollPolicy::defer	(	const std::string &	device_id,
		uint32_t	delay_ms,
		uint32_t	now )

Pull the device's next poll forward to delay_ms after now. Never pushes it later.

Definition at line 57 of file periodic_poll_policy.cpp.

◆ first_error_reply()

bool esphome::home_io_control::PeriodicPollPolicy::first_error_reply ( const std::string & device_id )

nodiscard

True the first time it is called for a device that answered the poll's request with an error reply, false afterwards, so the log names that once instead of every poll.

Definition at line 106 of file periodic_poll_policy.cpp.

◆ get_failures()

uint8_t esphome::home_io_control::PeriodicPollPolicy::get_failures ( const std::string & device_id ) const

nodiscard

Consecutive failed polls (0 for an unscheduled device).

Definition at line 114 of file periodic_poll_policy.cpp.

◆ get_interval()

uint32_t esphome::home_io_control::PeriodicPollPolicy::get_interval ( const std::string & device_id ) const

nodiscard

Return the configured interval (0 when the device is not scheduled).

Definition at line 33 of file periodic_poll_policy.cpp.

◆ get_next_poll()

uint32_t esphome::home_io_control::PeriodicPollPolicy::get_next_poll ( const std::string & device_id ) const

nodiscard

Absolute millis() time of the device's next poll (0 for an unscheduled device).

Definition at line 119 of file periodic_poll_policy.cpp.

◆ has_due()

bool esphome::home_io_control::PeriodicPollPolicy::has_due ( uint32_t now ) const

nodiscard

True when any device's poll is due at now.

Lets the caller draw a random number only when pop_due_device() will use it.

Definition at line 38 of file periodic_poll_policy.cpp.

◆ on_poll_failed()

bool esphome::home_io_control::PeriodicPollPolicy::on_poll_failed ( const std::string & device_id )

Count one failed poll (saturating), with no retry: for a poll the device answered with something that is not a reading (an error reply, an unexpected shape), which asking again soon would not change.

Returns: True once PERIODIC_POLL_FAILURES_BEFORE_UNKNOWN is reached, i.e. the last reading is no longer usable. Stays true until on_poll_succeeded().

Definition at line 74 of file periodic_poll_policy.cpp.

◆ on_poll_succeeded()

void esphome::home_io_control::PeriodicPollPolicy::on_poll_succeeded ( const std::string & device_id )

Clear the unanswered-poll count.

Definition at line 100 of file periodic_poll_policy.cpp.

◆ on_poll_unanswered()

bool esphome::home_io_control::PeriodicPollPolicy::on_poll_unanswered	(	const std::string &	device_id,
		uint32_t	now )

Handle a poll the device left unanswered.

A scheduled poll arms one retry PERIODIC_POLL_MISS_RETRY_MS after now (pulled forward like defer()) and counts nothing; the retry, if it is left unanswered too, counts one miss like on_poll_failed().

Returns: Same as on_poll_failed(): true while the last reading is no longer usable.

Definition at line 83 of file periodic_poll_policy.cpp.

Here is the call graph for this function:

◆ pop_due_device()

std::optional< std::string > esphome::home_io_control::PeriodicPollPolicy::pop_due_device	(	uint32_t	now,
		uint32_t	random )

nodiscard

Return one device whose poll is due and immediately schedule its next poll at periodic_poll_jittered_interval_ms() after now, so a poll that is later dropped from the operation queue (pairing flushes background work) is skipped rather than lost forever.

Returns nullopt when nothing is due. Comparison is wrap-safe across the 32-bit millis() rollover.

Definition at line 43 of file periodic_poll_policy.cpp.

Here is the call graph for this function:

◆ restart_interval()

void esphome::home_io_control::PeriodicPollPolicy::restart_interval	(	const std::string &	device_id,
		uint32_t	now,
		uint32_t	random )

The device has just given what the poll asks for without being polled: schedule its next poll periodic_poll_jittered_interval_ms() after now, earlier or later than it was, and drop an armed retry.

No-op for an unscheduled device.

Definition at line 66 of file periodic_poll_policy.cpp.

Here is the call graph for this function:

◆ retry_armed()

bool esphome::home_io_control::PeriodicPollPolicy::retry_armed ( const std::string & device_id ) const

nodiscard

True while a retry armed by on_poll_unanswered() has not been popped yet.

Definition at line 95 of file periodic_poll_policy.cpp.

◆ set_interval()

void esphome::home_io_control::PeriodicPollPolicy::set_interval	(	const std::string &	device_id,
		uint32_t	interval_ms,
		uint32_t	now,
		uint32_t	random )

Set the poll interval and schedule the first poll at periodic_poll_first_delay_ms(random) after now.

0 removes the device from the schedule.

Definition at line 19 of file periodic_poll_policy.cpp.

Here is the call graph for this function:

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

components/home_io_control/periodic_poll_policy.h
components/home_io_control/periodic_poll_policy.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ defer()

◆ first_error_reply()

◆ get_failures()

◆ get_interval()

◆ get_next_poll()

◆ has_due()

◆ on_poll_failed()

◆ on_poll_succeeded()

◆ on_poll_unanswered()

◆ pop_due_device()

◆ restart_interval()

◆ retry_armed()

◆ set_interval()