@alteriom/painlessmesh 1.10.0 → 2.0.0

package/src/painlessMeshSTA.h

@@ -33,16 +33,64 @@ class StationScan {
             uint16_t port, uint8_t channel, bool hidden);
   void stationScan();
   void scanComplete();
+  // The scan-done event has arrived (ESP32: on the core's network-event
+  // task). The result is read by scanComplete() from the station task,
+  // in the loop, where the radio may be reconfigured.
+  void scanDone();
   void filterAPs();
   void connectToAP();
+  // Move both Wi-Fi interfaces to a bridge-announced channel immediately.
+  bool followBridgeChannel(uint8_t targetChannel);
+  // A bridge has spoken, from this channel: its status message carries the
+  // channel it is on, which is its router's, and a message just received
+  // is live — unlike a cached tree, which can carry a root that has gone.
+  // That channel is home.
+  void noteRooted(uint8_t channel) {
+    everRooted = true;
+    rootedChannel = channel;
+    homeStays = 0;
+  }
+  // The tree contains a root. Enough for the rules that ask whether this
+  // mesh ever had one; not enough to say which channel is home.
+  void noteEverRooted() { everRooted = true; }
+  // The station attempt requestIP() started is over: it got an address, or
+  // it was disconnected. The half-open guard judges only an attempt still
+  // in progress. Without this it judged a fresh association by the clock of
+  // an attempt made 109 s earlier — the node had followed the bridge to its
+  // channel in between — and dropped it, costing a scan interval.
+  void stationAttemptOver() { connectAttemptStarted = 0; }
+  // The station got an address: its link is up. Cleared once the drop
+  // callbacks have judged a disconnect, so they can tell a link that was
+  // up and went away from an attempt that never got that far.
+  void stationUp() { stationLinkUp = true; }
+  void stationDown() { stationLinkUp = false; }
+  bool stationLinkUp = false;
+  // The station link was closed by this node's own channel move a moment
+  // ago (followBridgeChannel() closes it and scans next). Not a loss.
+  bool droppedByMove() const {
+    return channelMovedAt != 0 && millis() - channelMovedAt < 5000;
+  }
+  // The next scan covers every channel. For a node whose uplink just went
+  // away in a mesh that should have a root: the AP it was on left for the
+  // bridge's channel, and so will whatever is still here.
+  void redetectOnNextScan() { redetectRequested = true; }
+  // On the channel the bridge's status named: the bridge's AP is here.
+  bool atHome() const { return rootedChannel != 0 && channel == rootedChannel; }
   // This one will call the connectToAP next in the task and should be used
   // instead of connectToAP
   void yieldConnectToAP() {
     task.yield([this]() { connectToAP(); });
   }
   
-  // Helper to scan all channels for a specific mesh SSID
-  static uint8_t scanForMeshChannel(TSTRING meshSSID, bool meshHidden);
+  // Scan every channel for the mesh SSID. With avoidChannel set, prefer a
+  // channel other than it: re-detection runs when the node's own partition
+  // has gone quiet, so the mesh on its current channel is the partition it
+  // is stranded in, not the one it is looking for.
+  // With routerSSID set, the mesh on the router's channel is preferred over
+  // every other: that is where a bridge, and so the mesh, lives.
+  static uint8_t scanForMeshChannel(TSTRING meshSSID, bool meshHidden,
+                                    uint8_t avoidChannel = 0,
+                                    TSTRING routerSSID = "");
   
   // Check if channel re-synchronization is needed or in progress
   bool isChannelResyncNeeded() const {
@@ -84,7 +132,91 @@ class StationScan {
   
   // Track consecutive scans with no mesh nodes found (for channel re-detection)
   uint16_t consecutiveEmptyScans = 0;
-  static const uint16_t EMPTY_SCAN_THRESHOLD = 6; // ~30 seconds at default SCAN_INTERVAL
+  // millis() of the last requestIP(), to tell a station that is still
+  // obtaining an address from one that associated and never got one.
+  uint32_t connectAttemptStarted = 0;
+  // millis() of the last followBridgeChannel(), for droppedByMove().
+  uint32_t channelMovedAt = 0;
+  // Whether the current attempt's half-open association has already been
+  // dropped. WiFi.disconnect() on a station that has nothing to disconnect
+  // leaves the status where it was, and a guard that fired on every pass
+  // held a node out of the mesh for the rest of a test.
+  bool halfOpenDropped = false;
+  // Set when this task starts an async scan, cleared when its result is
+  // consumed. The scan-done event also fires for the synchronous scans
+  // channel re-detection runs, and consuming those results here found them
+  // already deleted, reported "wifi scan failed", and rescanned at once.
+  bool scanRequested = false;
+  // Set when the next station scan must cover every channel: the empty
+  // scans have piled up and the node is looking for the channel the mesh
+  // moved to. The re-detection is this task's ordinary asynchronous scan
+  // with the channel left open, not a synchronous all-channel scan run
+  // inline. The synchronous one held the main loop and the radio for four
+  // to seven seconds; measured on the rig, an ACK owed through the node
+  // during that window came back after the sender's eight-second budget
+  // and counted as a loss — one in every two or three soak runs.
+  bool redetectRequested = false;
+  // The scan in flight covers every channel (the fast re-detection of a
+  // node with nothing under its AP), or is one slice of a sliced hunt.
+  bool scanAllChannels = false;
+  uint8_t scanSlice = 0;
+  // A re-detection with stations under this node's AP is done a channel at
+  // a time: an all-channel scan takes the AP off its channel for two to
+  // three seconds, and an ESP8266 station does not survive that — on the
+  // rig the soak's sender ran one with the ESP8266 as its child and lost
+  // it for the rest of the test. A slice is one channel for 120 ms, then
+  // 1.5 s at home; the mesh APs seen on each channel are tallied, and the
+  // decision is taken on the own-channel scan that follows the last slice,
+  // by the same rules as the all-channel scan.
+  uint8_t huntChannel = 0;
+  bool huntPending = false;
+  std::map<uint8_t, size_t> huntCounts;
+  std::map<uint8_t, int8_t> huntRssi;
+  // Doubles the scan interval of a connected node that keeps finding the
+  // mesh only on its own channel while told the mesh has a root: a mesh
+  // that is simply rootless would otherwise cost every node a full
+  // all-channel scan every half interval, for as long as it stays so.
+  uint8_t orphanScanBackoff = 0;
+  // Re-detections in a row, while connected and rootless, that found the
+  // mesh only on this channel and nothing new on it. Two, and a leaf
+  // drops its station link to look for the root with an empty tree.
+  uint8_t orphanRedetects = 0;
+  // Whether this node's tree has ever contained a root since the mesh
+  // started. A leaf leaves a rootless partition to look for the root only
+  // if there was one: a mesh that never had a bridge is rootless by
+  // design, and its leaves dropping their links every other minute to look
+  // for what does not exist cost the soak its deliveries.
+  bool everRooted = false;
+  // The channel the mesh was on the last time this node's tree had a root:
+  // the bridge's channel, which is its router's. A rootless node that has
+  // one treats it as home. It does not leave home for a partition on
+  // another channel, and away from home it goes back as soon as it sees
+  // the mesh there, whatever the sizes: a bridge that has just been
+  // promoted is one AP on the router's channel, and it is the one to join.
+  // On the rig, the node the failover test sends from followed a two-node
+  // partition off the router's channel while the backup was being elected
+  // beside it, then stayed away because its new partition was bigger than
+  // the lone bridge, and never heard the bridge's status.
+  uint8_t rootedChannel = 0;
+  // Re-detections in a row, at home, that declined to follow a partition
+  // seen elsewhere. A bridge that moves for good (its router changed
+  // channel) would otherwise keep the old channel rootless forever, so
+  // after enough of them home is forgotten and the ordinary rules apply.
+  uint8_t homeStays = 0;
+  // The other channel a disconnected node saw a smaller partition on, at
+  // its last re-detection: it follows only if the same channel shows the
+  // mesh again a scan later — a straggler is gone by then, a bridge is
+  // not.
+  uint8_t pendingElsewhere = 0;
+  // Consecutive scans, while connected and unrooted in a mesh that should
+  // have a root, that found nodes this node has no route to: a partition,
+  // with the root on the other side. Two of them and the node joins it.
+  uint8_t partitionScans = 0;
+  // Empty scans before re-detecting the mesh channel. A disconnected or
+  // orphaned node scans every 0.5 * SCAN_INTERVAL = 15 s, so 2 is ~30 s —
+  // what the old comment promised while the value of 6 delivered 90 s, long
+  // enough for a bridge's followers to miss a 120 s gateway contract.
+  static const uint16_t EMPTY_SCAN_THRESHOLD = 2;
   
   // TCP failure blocklist to prevent infinite retry loops
   // Maps nodeId -> blockUntil timestamp (millis())

package/src/painlessmesh/ack.hpp

@@ -0,0 +1,283 @@
+#ifndef PAINLESS_MESH_ACK_HPP
+#define PAINLESS_MESH_ACK_HPP
+
+#include <functional>
+#include <list>
+#include <map>
+#include <set>
+
+#include "painlessmesh/configuration.hpp"
+#include "painlessmesh/logger.hpp"
+#include "painlessmesh/plugin.hpp"
+
+extern painlessmesh::logger::LogClass Log;
+
+// Maximum number of messages that may await acknowledgment at once.
+// Bounded to protect the small ESP8266 heap; override at build time if
+// your application legitimately needs more concurrent tracked sends.
+#ifndef PAINLESSMESH_MAX_PENDING_ACKS
+#define PAINLESSMESH_MAX_PENDING_ACKS 32
+#endif
+
+// Maximum number of delayed broadcast acknowledgments queued by a receiver.
+// A single shared scheduler task drains the queue after the jitter delay.
+#ifndef PAINLESSMESH_MAX_QUEUED_BROADCAST_ACKS
+#define PAINLESSMESH_MAX_QUEUED_BROADCAST_ACKS 32
+#endif
+
+namespace painlessmesh {
+
+/**
+ * Per-message delivery confirmation (issue #379)
+ *
+ * When a delivery callback is passed to Mesh::sendSingle() or
+ * Mesh::sendBroadcast(), the outgoing package is tagged with a unique
+ * msgId. Receiving nodes automatically reply with a MessageAckPackage
+ * (type 630) and the sender's AckTracker matches the reply to the pending
+ * message, firing the callback with the measured round-trip latency.
+ * Messages that are not acknowledged within their timeout fire the
+ * callback with delivered = false.
+ */
+namespace ack {
+
+/**
+ * Callback type for delivery confirmation
+ *
+ * @param nodeId The destination node this result refers to
+ * @param delivered True when the node acknowledged the message, false when
+ *        the acknowledgment timed out
+ * @param latencyMs Round-trip time in ms when delivered, otherwise the
+ *        configured timeout
+ */
+typedef std::function<void(uint32_t nodeId, bool delivered, uint32_t latencyMs)>
+    deliveryCallback_t;
+
+/**
+ * Acknowledgment package sent back to the original sender
+ *
+ * Routed as a SINGLE package so it traverses multiple hops using the
+ * normal routing logic.
+ *
+ * Type ID: 630 (MESSAGE_ACK)
+ */
+class MessageAckPackage : public plugin::SinglePackage {
+ public:
+  /** ID of the message being acknowledged */
+  uint32_t messageId = 0;
+
+  MessageAckPackage() : SinglePackage(protocol::MESSAGE_ACK) {}
+
+  MessageAckPackage(uint32_t fromNode, uint32_t destNode, uint32_t msgId)
+      : SinglePackage(protocol::MESSAGE_ACK) {
+    from = fromNode;
+    dest = destNode;
+    messageId = msgId;
+  }
+
+  MessageAckPackage(JsonObject jsonObj) : SinglePackage(jsonObj) {
+    messageId = jsonObj["msgId"] | (uint32_t)0;
+  }
+
+  JsonObject addTo(JsonObject&& jsonObj) const {
+    jsonObj = SinglePackage::addTo(std::move(jsonObj));
+    jsonObj["msgId"] = messageId;
+    return jsonObj;
+  }
+
+#if ARDUINOJSON_VERSION_MAJOR < 7
+  size_t jsonObjectSize() const { return JSON_OBJECT_SIZE(noJsonFields + 1); }
+#endif
+};
+
+/**
+ * A message awaiting acknowledgment(s)
+ */
+struct PendingAck {
+  deliveryCallback_t callback;
+  uint32_t sentAt = 0;
+  uint32_t timeoutMs = 0;
+  std::set<uint32_t> waitingFor;
+};
+
+struct DeliveryResult {
+  deliveryCallback_t callback;
+  uint32_t nodeId = 0;
+  bool delivered = false;
+  uint32_t latencyMs = 0;
+
+  DeliveryResult(deliveryCallback_t callback, uint32_t nodeId, bool delivered,
+                 uint32_t latencyMs)
+      : callback(callback),
+        nodeId(nodeId),
+        delivered(delivered),
+        latencyMs(latencyMs) {}
+};
+
+/**
+ * AckTracker - tracks outgoing messages awaiting acknowledgment
+ *
+ * Time is passed in explicitly (millis() on device) so the tracker stays
+ * platform independent and unit testable. All time comparisons are
+ * uint32 wraparound safe.
+ */
+class AckTracker {
+ public:
+  /**
+   * Seed the message-id counter
+   *
+   * Called once at mesh init with a random value so ids do not restart
+   * at 1 after a reboot — a delayed ACK for a pre-reboot message could
+   * otherwise match a fresh message's id and report a false
+   * delivered = true.
+   */
+  void seed(uint32_t value) { counter = value; }
+
+  /** Generate the next unique, non-zero message id */
+  uint32_t nextMessageId() {
+    if (++counter == 0) ++counter;
+    return counter;
+  }
+
+  /** Whether the tracker is at its pending-message limit */
+  bool full() const { return entries.size() >= PAINLESSMESH_MAX_PENDING_ACKS; }
+
+  /**
+   * Start tracking a message
+   *
+   * @param msgId Unique id from nextMessageId()
+   * @param destinations Nodes expected to acknowledge
+   * @param callback Fired once per destination (ack or timeout)
+   * @param timeoutMs Time to wait for acknowledgments
+   * @param now Current time (millis())
+   * @return false when the callback/destinations are empty or the
+   *         tracker is full (PAINLESSMESH_MAX_PENDING_ACKS)
+   */
+  bool track(uint32_t msgId, const std::list<uint32_t>& destinations,
+             deliveryCallback_t callback, uint32_t timeoutMs, uint32_t now) {
+    if (!callback || destinations.empty()) return false;
+    if (full()) {
+      Log(logger::ERROR,
+          "AckTracker: pending-ack limit (%u) reached, not tracking %u\n",
+          (unsigned)PAINLESSMESH_MAX_PENDING_ACKS, msgId);
+      return false;
+    }
+    PendingAck entry;
+    entry.callback = callback;
+    entry.sentAt = now;
+    entry.timeoutMs = timeoutMs;
+    entry.waitingFor.insert(destinations.begin(), destinations.end());
+    entries[msgId] = std::move(entry);
+    return true;
+  }
+
+  /**
+   * Process an incoming acknowledgment
+   *
+   * Fires the callback with delivered = true and the measured latency.
+   *
+   * @return true when the ack matched a pending message/destination
+   */
+  bool handleAck(uint32_t msgId, uint32_t fromNode, uint32_t now) {
+    std::list<DeliveryResult> results;
+    auto matched = collectAck(msgId, fromNode, now, results);
+    for (auto&& result : results) {
+      result.callback(result.nodeId, result.delivered, result.latencyMs);
+    }
+    return matched;
+  }
+
+  /**
+   * Match an acknowledgment without invoking user code.
+   *
+   * Mesh receive dispatch uses this form so callbacks can be scheduled after
+   * the connection read task has unwound. Tracker state is still updated
+   * synchronously and exactly once.
+   */
+  bool collectAck(uint32_t msgId, uint32_t fromNode, uint32_t now,
+                  std::list<DeliveryResult>& results) {
+    auto it = entries.find(msgId);
+    if (it == entries.end()) return false;
+    if (it->second.waitingFor.count(fromNode) == 0) return false;
+    auto latency = (uint32_t)(now - it->second.sentAt);
+    if (latency >= it->second.timeoutMs) {
+      // The polling task may not have run exactly at the deadline. Reject
+      // this late ACK and expire every destination still waiting on the
+      // same message before invoking user code (callbacks may reenter us).
+      auto expired = std::move(it->second);
+      entries.erase(it);
+      for (auto&& nodeId : expired.waitingFor) {
+        Log(logger::COMMUNICATION,
+            "AckTracker: timeout waiting for ack from %u\n", nodeId);
+        results.push_back(
+            DeliveryResult(expired.callback, nodeId, false, expired.timeoutMs));
+      }
+      return false;
+    }
+    it->second.waitingFor.erase(fromNode);
+    auto callback = it->second.callback;
+    if (it->second.waitingFor.empty()) entries.erase(it);
+    results.push_back(DeliveryResult(callback, fromNode, true, latency));
+    return true;
+  }
+
+  /**
+   * Fire timeout callbacks for expired messages
+   *
+   * @param now Current time (millis())
+   * @return Number of messages still awaiting acknowledgment
+   */
+  size_t expire(uint32_t now) {
+    std::list<DeliveryResult> results;
+    collectExpired(now, results);
+    for (const auto& result : results) {
+      result.callback(result.nodeId, result.delivered, result.latencyMs);
+    }
+    return entries.size();
+  }
+
+  /**
+   * Collect timeout results without invoking user callbacks
+   *
+   * Mesh uses this form to defer callbacks until receive dispatch has
+   * unwound. Direct AckTracker users retain the synchronous expire() API.
+   */
+  size_t collectExpired(uint32_t now, std::list<DeliveryResult>& results) {
+    // Collect expired entries and erase them from the map BEFORE exposing
+    // results to user callbacks: a callback may reenter this tracker (track a
+    // retry, call clear() via mesh.stop(), or poll checkAcks()), which
+    // would invalidate a live iterator into `entries`.
+    std::list<PendingAck> expired;
+    for (auto it = entries.begin(); it != entries.end();) {
+      if ((uint32_t)(now - it->second.sentAt) >= it->second.timeoutMs) {
+        expired.push_back(std::move(it->second));
+        it = entries.erase(it);
+      } else {
+        ++it;
+      }
+    }
+    for (auto&& entry : expired) {
+      for (auto&& nodeId : entry.waitingFor) {
+        Log(logger::COMMUNICATION,
+            "AckTracker: timeout waiting for ack from %u\n", nodeId);
+        results.push_back(
+            DeliveryResult(entry.callback, nodeId, false, entry.timeoutMs));
+      }
+    }
+    return entries.size();
+  }
+
+  /** Number of messages awaiting acknowledgment */
+  size_t pending() const { return entries.size(); }
+
+  /** Drop all pending messages without firing callbacks */
+  void clear() { entries.clear(); }
+
+ protected:
+  std::map<uint32_t, PendingAck> entries;
+  uint32_t counter = 0;
+};
+
+}  // namespace ack
+}  // namespace painlessmesh
+
+#endif

package/src/painlessmesh/buffer.hpp

@@ -108,6 +108,16 @@ inline void ReceiveBuffer<std::string>::stringAppend(std::string &buffer,
 }
 #endif
 
+// Maximum number of messages a single connection's SentBuffer may hold
+// (issue #388). Without a cap, a peer that stops draining (stalled TCP
+// connection) grows the outbound list until allocation fails on the ESP8266
+// heap. When the buffer is full, an incoming message evicts the newest
+// message of a strictly lower priority class; if nothing lower-priority is
+// queued, the incoming message itself is rejected (push returns false).
+#ifndef PAINLESSMESH_MAX_SENT_BUFFER_MESSAGES
+#define PAINLESSMESH_MAX_SENT_BUFFER_MESSAGES 64
+#endif
+
 /**
  * Structure to hold a message with its priority level
  */
@@ -135,14 +145,16 @@ class SentBuffer {
    *
    * \param message The message to queue
    * \param priority Whether this is a high priority message (legacy bool API)
+   * \return true if the message was queued, false if the buffer is full and
+   *         nothing lower-priority could be evicted (issue #388)
    *
    * Legacy API: High priority messages (true) will be sent to the front of the buffer
    * This maintains backward compatibility with existing code.
    */
-  void push(const T &message, bool priority = false) {
+  bool push(const T &message, bool priority = false) {
     // Legacy API: map bool to uint8_t priority (false=2 NORMAL, true=1 HIGH)
     uint8_t priorityLevel = priority ? 1 : 2;
-    pushWithPriority(message, priorityLevel);
+    return pushWithPriority(message, priorityLevel);
   }
 
   /**
@@ -150,15 +162,31 @@ class SentBuffer {
    *
    * \param message The message to queue
    * \param priorityLevel Priority level: 0=CRITICAL, 1=HIGH, 2=NORMAL, 3=LOW
+   * \return true if the message was queued, false if the buffer is full and
+   *         nothing lower-priority could be evicted (issue #388)
    *
    * Messages are scheduled in priority order. Within same priority, FIFO order is maintained.
+   *
+   * The buffer holds at most PAINLESSMESH_MAX_SENT_BUFFER_MESSAGES entries.
+   * At the cap, the newest message of a strictly lower priority class is
+   * evicted to make room (mirroring MessageQueue::makeSpace(): CRITICAL
+   * evicts HIGH/NORMAL/LOW, HIGH evicts NORMAL/LOW, NORMAL evicts LOW, LOW
+   * evicts nothing); when no lower-priority message exists the incoming
+   * message is rejected. Either way the drop is counted in
+   * getStats().dropped.
    */
-  void pushWithPriority(const T &message, uint8_t priorityLevel) {
+  bool pushWithPriority(const T &message, uint8_t priorityLevel) {
     // Clamp priority to valid range
     if (priorityLevel > 3) priorityLevel = 3;
-    
+
+    if (prioritizedMessages.size() >= PAINLESSMESH_MAX_SENT_BUFFER_MESSAGES &&
+        !evictLowerPriority(priorityLevel)) {
+      messagesDropped++;
+      return false;
+    }
+
     prioritizedMessages.push_back(PrioritizedMessage<T>(message, priorityLevel));
-    
+
     // Track statistics
     totalMessagesQueued++;
     switch(priorityLevel) {
@@ -167,6 +195,7 @@ class SentBuffer {
       case 2: normalQueued++; break;
       case 3: lowQueued++; break;
     }
+    return true;
   }
 
   /**
@@ -264,9 +293,10 @@ class SentBuffer {
 
   bool empty() { return prioritizedMessages.empty(); }
 
-  void clear() { 
-    prioritizedMessages.clear(); 
+  void clear() {
+    prioritizedMessages.clear();
     current_read_iterator = prioritizedMessages.end();
+    messagesDropped = 0;
     totalMessagesQueued = 0;
     criticalQueued = highQueued = normalQueued = lowQueued = 0;
     criticalSent = highSent = normalSent = lowSent = 0;
@@ -292,10 +322,14 @@ class SentBuffer {
     uint32_t highSent;
     uint32_t normalSent;
     uint32_t lowSent;
+    // Messages lost to the PAINLESSMESH_MAX_SENT_BUFFER_MESSAGES cap:
+    // evicted from the buffer or rejected on push (issue #388)
+    uint32_t dropped;
   };
-  
+
   SendStats getStats() const {
     SendStats stats;
+    stats.dropped = messagesDropped;
     stats.totalQueued = totalMessagesQueued;
     stats.criticalQueued = criticalQueued;
     stats.highQueued = highQueued;
@@ -316,6 +350,7 @@ class SentBuffer {
   typename std::list<PrioritizedMessage<T>>::iterator current_read_iterator;
   
   // Statistics tracking
+  uint32_t messagesDropped = 0;
   uint32_t totalMessagesQueued = 0;
   uint32_t criticalQueued = 0;
   uint32_t highQueued = 0;
@@ -380,6 +415,33 @@ class SentBuffer {
     return 2;  // NORMAL default
   }
 
+  /**
+   * Evict a message of a strictly lower priority class than the incoming
+   * one to make room (issue #388). Prefers the newest message of the lowest
+   * class present; never evicts the message a partial read is in progress
+   * on. Returns false when nothing lower-priority is queued.
+   */
+  bool evictLowerPriority(uint8_t newPriority) {
+    auto victim = prioritizedMessages.end();
+    for (auto it = prioritizedMessages.begin();
+         it != prioritizedMessages.end(); ++it) {
+      if (!clean && it == current_read_iterator) continue;
+      if (it->priority <= newPriority) continue;
+      // >= keeps walking forward within the lowest class, so the newest
+      // (last-queued) entry of that class is the one dropped
+      if (victim == prioritizedMessages.end() ||
+          it->priority >= victim->priority)
+        victim = it;
+    }
+    if (victim == prioritizedMessages.end()) return false;
+    messagesDropped++;
+    prioritizedMessages.erase(victim);
+    // The cached read iterator may point at the erased node; recompute on
+    // the next read. A partial read in progress (!clean) is never evicted.
+    if (clean) current_read_iterator = prioritizedMessages.end();
+    return true;
+  }
+
   inline void stringEraseFront(T &string, size_t length) {
     string.remove(0, length);
   };

package/src/painlessmesh/callback.hpp

@@ -60,26 +60,59 @@ class PackageCallbackList {
    * Add a callback for specific package id
    */
   void onPackage(int id, std::function<void(Args...)> func) {
-    callbackMap[id].push_back(func);
+    if (clearPending) {
+      (*pendingCallbackMap)[id].push_back(func);
+    } else {
+      (*callbackMap)[id].push_back(func);
+    }
   }
 
   size_t size() {
     size_t size = 0;
-    for (auto&& key_value : callbackMap) {
+    auto generation = clearPending ? pendingCallbackMap : callbackMap;
+    for (auto&& key_value : *generation) {
       size += key_value.second.size();
     }
     return size;
   }
 
-  void clear() { callbackMap.clear(); }
+  void clear() {
+    if (dispatchDepth > 0) {
+      clearPending = true;
+      pendingCallbackMap = std::make_shared<CallbackMap>();
+      return;
+    }
+    callbackMap->clear();
+  }
 
   /**
    * Execute all the callbacks associated with a certain package
    */
-  int execute(int id, Args... args) { return callbackMap[id].execute(args...); }
+  int execute(int id, Args... args) {
+    // Retain the selected generation for the complete call. A nested callback
+    // may clear and replace the pending generation without destroying the
+    // List/std::function currently executing on this stack.
+    auto generation = clearPending ? pendingCallbackMap : callbackMap;
+    ++dispatchDepth;
+    auto result = (*generation)[id].execute(args...);
+    --dispatchDepth;
+    if (dispatchDepth == 0 && clearPending) {
+      callbackMap = pendingCallbackMap;
+      pendingCallbackMap.reset();
+      clearPending = false;
+    }
+    return result;
+  }
 
  protected:
-  std::map<int, List<Args...>> callbackMap;
+  using CallbackMap = std::map<int, List<Args...>>;
+  std::shared_ptr<CallbackMap> callbackMap = std::make_shared<CallbackMap>();
+  // Registrations made after clear() during an active dispatch belong to
+  // the next callback generation (for example stop(); init(); from a user
+  // callback) and must survive removal of the currently executing one.
+  std::shared_ptr<CallbackMap> pendingCallbackMap;
+  size_t dispatchDepth = 0;
+  bool clearPending = false;
 };
 
 template <typename T>