ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
api_deferred_batch.h
Go to the documentation of this file.
1#pragma once
2
4#ifdef USE_API
5#include "api_pb2.h"
7
8#include <algorithm>
9#include <cstdint>
10#include <limits>
11#include <vector>
12
13namespace esphome::api {
14
15// Generic batching mechanism for both state updates and entity info
17 // Sentinel value for unused aux_data_index
18 static constexpr uint8_t AUX_DATA_UNUSED = std::numeric_limits<uint8_t>::max();
19
20 struct BatchItem {
21 EntityBase *entity; // 4 bytes - Entity pointer
22 uint16_t message_type; // 2 bytes - Message type for protocol and dispatch
23 uint8_t estimated_size; // 1 byte - Estimated message size (max 255 bytes)
24 uint8_t aux_data_index{AUX_DATA_UNUSED}; // 1 byte - For events: index into entity's event_types
25 };
26
27 std::vector<BatchItem> items;
29
30 // No pre-allocation - log connections never use batching, and for
31 // connections that do, buffers are released after initial sync anyway
32
33 // O(n) scan but optimized for RAM over performance
34 bool contains(EntityBase *entity, uint16_t message_type) const {
35 for (const auto &item : this->items) {
36 if (item.entity == entity && item.message_type == message_type)
37 return true;
38 }
39 return false;
40 }
41
42 // Add item to the batch (with deduplication)
43 void add_item(EntityBase *entity, uint16_t message_type, uint8_t estimated_size,
44 uint8_t aux_data_index = AUX_DATA_UNUSED) {
45 // Skip deduplication for events - they are edge-triggered, every occurrence matters
46#ifdef USE_EVENT
47 if (message_type != EventResponse::MESSAGE_TYPE)
48#endif
49 {
50 if (this->contains(entity, message_type))
51 return; // Already queued
52 }
53 this->items.push_back({entity, message_type, estimated_size, aux_data_index});
54 }
55 // Add item to the front of the batch (for high priority messages like ping)
56 void add_item_front(EntityBase *entity, uint16_t message_type, uint8_t estimated_size) {
57 // Shift rather than swap, so the queued items keep their order (two events of one entity must not swap)
58 this->items.push_back({});
59 std::move_backward(this->items.begin(), this->items.end() - 1, this->items.end());
60 this->items.front() = {entity, message_type, estimated_size, AUX_DATA_UNUSED};
61 }
62
63 // Clear all items
64 void clear() {
65 items.clear();
67 }
68
69 // Remove processed items from the front — noinline to keep memmove out of warm callers
70 void remove_front(size_t count) __attribute__((noinline)) { items.erase(items.begin(), items.begin() + count); }
71
72 bool empty() const { return items.empty(); }
73 size_t size() const { return items.size(); }
74 const BatchItem &operator[](size_t index) const { return items[index]; }
75
76 // Release excess capacity - only releases if items already empty
78 // Safe to call: batch is processed before release_buffer is called,
79 // and if any items remain (partial processing), we must not clear them.
80 // Use swap trick since shrink_to_fit() is non-binding and may be ignored.
81 if (items.empty()) {
82 std::vector<BatchItem>().swap(items);
83 }
84 }
85};
86
87} // namespace esphome::api
88#endif // USE_API
static constexpr uint16_t MESSAGE_TYPE
Definition api_pb2.h:3495
struct @66::@67 __attribute__
Wake the main loop task from an ISR. ISR-safe.
Definition main_task.h:45
unsigned count
Definition gif.cpp:51
static void uint32_t
void remove_front(size_t count) __attribute__((noinline))
static constexpr uint8_t AUX_DATA_UNUSED
std::vector< BatchItem > items
void add_item_front(EntityBase *entity, uint16_t message_type, uint8_t estimated_size)
const BatchItem & operator[](size_t index) const
void add_item(EntityBase *entity, uint16_t message_type, uint8_t estimated_size, uint8_t aux_data_index=AUX_DATA_UNUSED)
bool contains(EntityBase *entity, uint16_t message_type) const