ant_router_logic.h

Go to the documentation of this file.

// SPDX-License-Identifier: MIT OR GPL-2.0-only
// Copyright (C) 2026 Daniel Henrique Joppi
 
/**
 * AntRouterLogic: the shared, simulator-agnostic AntHocNet state machine.
 *
 * This is the former AntNest + the decision parts of the AntHocNet agent,
 * with all NS-2 packet/scheduler coupling removed. It owns a node's routing
 * state (pheromone table, dedup history, sequence counter) and turns received
 * ants and local data demands into RouteDecisions for the adapter to execute.
 *
 * It is deliberately free of I/O: time and randomness come through ports, and
 * outputs are returned as values. That makes the routing behaviour identical
 * across NS-2 and NS-3 and testable on its own.
 */
#ifndef ANTHOCNET_CORE_ANT_ROUTER_LOGIC_H
#define ANTHOCNET_CORE_ANT_ROUTER_LOGIC_H
 
#include <map>
#include <utility>
#include <vector>
 
#include "anthocnet/core/ant_history.h"
#include "anthocnet/core/ant_message.h"
#include "anthocnet/core/config.h"
#include "anthocnet/core/link_metric.h"
#include "anthocnet/core/pheromone_engine.h"
#include "anthocnet/core/pheromone_table.h"
#include "anthocnet/core/ports.h"
#include "anthocnet/core/route_decision.h"
#include "anthocnet/core/types.h"
 
namespace anthocnet {
namespace core {
 
class AntRouterLogic {
public:
    /// `metric` selects the pheromone formula (item 16); nullptr uses the
    /// canonical ClassicMetric. `linkState` supplies MAC-layer congestion
    /// signals for the item-10/A2 metric (nullptr => wall-clock per-hop time).
    /// Both default to null, so existing adapter call sites are unchanged.
    AntRouterLogic(NodeAddress address, const Config& config, IClock& clock, IRng& rng,
                   const ILinkMetric* metric = nullptr, const ILinkState* linkState = nullptr,
                   const ILinkQuality* linkQuality = nullptr);
 
    NodeAddress address() const { return address_; }
    const Config& config() const { return config_; }
    PheromoneTable& table() { return table_; }
    const PheromoneTable& table() const { return table_; }
    PheromoneEngine& engine() { return engine_; }
 
    // --- observability (item 15) -----------------------------------------
    /// Attach an optional observer for ant/route events (nullptr to detach).
    /// Zero-overhead when unset; the observer only reports, never decides.
    void setObserver(IRouterObserver* observer) { observer_ = observer; }
    /// Attach the port that says where this node is (ADR-0025; nullptr =
    /// unknown). Read only when Config::shareKinematics is on.
    void setKinematics(const IKinematics* kinematics) { kinematics_ = kinematics; }
    /// #574: the next-hop weight link-lifetime prediction gives `neighbor`
    /// now: 1 when the gate is off or either side's kinematics are unknown.
    double linkLifetimeWeight(NodeAddress neighbor) const;
    /// Attach the residual-energy port (#145; nullptr = unknown). Read only
    /// by a metric that prices hops by energy.
    void setEnergy(const IEnergy* energy) { energy_ = energy; }
    /// What `neighbor`'s last hello said about its position and velocity,
    /// extrapolated to now (p + v*(now - t_rx)). False when it is unknown: no
    /// hello from it carried a section, the last one did not, or the
    /// neighbour was lost since (ADR-0025: absent, not zero).
    bool neighborKinematics(NodeAddress neighbor, Kinematics& out) const;
    /// Ants of `type` this node has put on the medium (origination + forward).
    std::uint64_t antsSent(AntType type) const;
    /// Non-duplicate ants of `type` this node has received and processed.
    std::uint64_t antsReceived(AntType type) const;
    /// Total ant control packets sent across all types (routing overhead).
    std::uint64_t controlPacketsSent() const;
    /// LinkFail notes this node re-broadcast on another reporter's behalf
    /// (issue #20: origins = antsSent(LinkFail) − propagations).
    std::uint64_t linkfailPropagations() const { return linkfailPropagations_; }
    /// LinkFail propagations suppressed by an exhausted inherited
    /// broadcastBudget — how often the depth bound actually bites (issue #20).
    std::uint64_t linkfailBudgetDrops() const { return linkfailBudgetDrops_; }
    /// Per-destination advertisements dropped by the origin cooldown
    /// (config.linkfailNotifyInterval, issue #20).
    std::uint64_t linkfailOriginsSuppressed() const { return linkfailOriginsSuppressed_; }
    /// Reactive forward ants steered along the diffusion gradient instead of
    /// being broadcast (config.enableDirectedReactive). This is the number that
    /// says whether directed discovery is doing anything at all: zero means the
    /// virtual table never held a hint where the regular one was empty, so the
    /// gate is inert rather than harmful.
    std::uint64_t directedSteers() const { return directedSteers_; }
    /// Local repairs that expired without a backward ant and therefore released
    /// the data buffered for their destination — the number of DiscardPending
    /// decisions this node has emitted ([1] §3.5, D6; drop-cause breakdown,
    /// issue #215). This is the *event* count: the adapter owns the pending
    /// queue, so only it knows how many packets each discard released. Counted
    /// here so the cause stays simulator-agnostic and both adapters get it.
    std::uint64_t repairDiscards() const { return repairDiscards_; }
    /// #572: the decay multiplier `dest` got at the last maintenance tick (1
    /// when the gate is off or the destination is new).
    double evaporationMultiplier(NodeAddress dest) const {
        auto it = evapMultiplier_.find(dest);
        return it == evapMultiplier_.end() ? 1.0 : it->second;
    }
 
    // --- neighbour learning ----------------------------------------------
    /// Record that `neighbor` is reachable (link-layer detection / hello),
    /// seeding an equal-weight regular pheromone entry as the legacy code did.
    void learnNeighbor(NodeAddress neighbor);
    void loseNeighbor(NodeAddress neighbor);
 
    /// Periodic liveness/maintenance tick (driven by the adapter hello timer):
    /// expire neighbours not heard from within helloInterval*allowedHelloLoss
    /// (the portable, NS-3-mandatory detector — ADR-0008) and return any
    /// link-failure notifications to broadcast. Also expires timed-out local
    /// repairs ([1] §3.5, D6): a repair with no backward ant within its wait
    /// window yields a DiscardPending for the destination's buffered packets
    /// plus a LinkFail notification.
    std::vector<RouteDecision> onMaintenanceTick();
 
    /// Remove neighbour `n` and, for every destination whose best path it
    /// carried, broadcast a LinkFail notification with the new best (0 if the
    /// route is gone). Used by both the maintenance tick and an adapter's
    /// MAC transmit-failure hook (ADR-0008 detectors A and D converge here).
    std::vector<RouteDecision> reportNeighborLoss(NodeAddress n);
 
    /// Adapter MAC transmit-failure hook (ADR-0008 detector D): a failed unicast
    /// to `next` means the link is down. Prune the neighbour (emitting any
    /// LinkFail notifications, exactly as detector A does) and, when the failed
    /// packet was *data* (`dataDest` set), broadcast a bounded, counted local
    /// repair ant toward it so the route is rebuilt immediately ([1] §3.5).
    /// Mirrors the NS-2 `ahn_router` linkFailed path; both adapters call this.
    std::vector<RouteDecision> reportTxFailure(NodeAddress next,
                                               NodeAddress dataDest = kInvalidAddress);
 
    // --- active sessions (proactive monitoring, item 04) ------------------
    /// Record that this node just originated data for `dest`, making it an
    /// active session that proactive ants will monitor (call from the adapter
    /// data path when the packet is locally originated).
    void noteDataSession(NodeAddress dest);
    /// Destinations with data sent within `config_.sessionTtl` (const query).
    std::vector<NodeAddress> activeDestinations() const;
    /// One proactive forward ant per active destination (empty if none or if
    /// `!config_.enableProactive`), subject to the thesis emission gate
    /// `shouldSendProactive()`. Also prunes expired sessions.
    std::vector<AntMessage> createProactiveAnts();
    /// The thesis's emission gate, re-derived per-link (#180, ADR-0018): true
    /// when some neighbour's virtual pheromone for `dest` beats the regular
    /// pheromone ON THE SAME LINK by `config_.proactiveVirtualMargin`, or the
    /// hint sits on an unsampled link (or the gate does not apply — see the
    /// definition for the boundary cases). Exposed for tests/observability;
    /// `createProactiveAnts()` calls it.
    bool shouldSendProactive(NodeAddress dest) const;
 
    // --- ant construction -------------------------------------------------
    AntMessage createForwardAnt(AntType type, NodeAddress dest);
    AntMessage createHelloAnt();  // caps adverts at Config::maxHelloAdverts
    AntMessage createHelloAnt(std::size_t maxAdverts);
    /// Build the backward ant for a forward ant that reached this node
    /// (this == dst). The returned message's `nextHop` is via firstBackHop().
    AntMessage createBackAnt(const AntMessage& forward);
 
    // --- routing primitives ----------------------------------------------
    /// Stochastic next hop for `dest` using the ant exponent betaAnts
    /// (kInvalidAddress if no route). Serves reactive and proactive ants.
    NodeAddress selectNextHop(NodeAddress dest, bool proactive);
    /// Stochastic next hop for a *data* packet, using the greedier data
    /// exponent betaData (kInvalidAddress if no route). `prevHop` is excluded
    /// unless it is the only option, to suppress data loops (A1).
    NodeAddress nextHopForData(NodeAddress dest, NodeAddress prevHop = kInvalidAddress);
    /// Pick a random known destination for a proactive ant (or kInvalidAddress).
    NodeAddress randomDestination();
 
    /// Append this node to a forward ant's visited stack, recording this hop's
    /// cost (congestion-aware MAC estimate when enabled, else wall-clock delta).
    /// `nextHop` is the interface the ant leaves by, so the congestion signal
    /// is read for the queue it will actually wait in; kInvalidAddress when
    /// there is no single one (broadcast, or this node is the destination) —
    /// the ILinkState then aggregates (#206). Bounded by Config::maxPathLength.
    void stampForward(AntMessage& ant, NodeAddress nextHop) const;
 
    /// One hop of path cost from this node to `neighbor`, in the metric's units
    /// (#181): the SINR link cost (eq. 4.11) when the metric uses link quality,
    /// else the unloaded reference hop time T_hop as before.
    double linkCost(NodeAddress neighbor) const;
 
    /// Advance a backward ant by one hop: move this node from the visited stack
    /// onto `history` and return the next hop (path management only; the deposit
    /// state is reconstructed at the receiver from `history`, ADR-0009).
    NodeAddress advanceBackAnt(AntMessage& ant) const;
 
    /// Pheromone this back ant would deposit at the current node, reconstructed
    /// from its `history` (hops + summed per-hop times) via the link metric.
    double backAntPheromone(const AntMessage& ant) const;
 
    /// Update the regular pheromone table from a backward ant that arrived
    /// here (reinforce the link it came from).
    void reinforceFromBackAnt(const AntMessage& ant);
 
    // --- consolidated receive --------------------------------------------
    /// Process a received ant arriving from `prevHop`. Performs (src,seq)
    /// dedup and neighbour learning, then dispatches by type/direction,
    /// returning the actions the adapter must carry out. May return an empty
    /// vector (nothing to do) or a single Drop.
    std::vector<RouteDecision> onReceiveAnt(const AntMessage& ant, NodeAddress prevHop);
 
    /// Decide what to do with a locally-originated or in-transit *data* packet
    /// destined for `dest`: route it (Unicast), or (no route) request one and
    /// Queue it. The adapter emits the returned reactive forward ant, if any.
    std::vector<RouteDecision> onDataPacket(NodeAddress dest,
                                            NodeAddress prevHop = kInvalidAddress);
 
private:
    std::uint32_t nextSeq() { return seqNum_++; }
 
    /// Turn a forward/notification ant into a Broadcast decision, honouring its
    /// broadcastBudget: an untracked ant (-1) always broadcasts; a budgeted ant
    /// decrements and broadcasts while >0, and is Dropped once exhausted.
    RouteDecision broadcastForward(AntMessage& ant);
    /// Build a Unicast/Broadcast decision carrying `ant`, counting it as sent
    /// and notifying the observer (the single choke point for ant emission).
    RouteDecision sendAnt(RouteAction action, NodeAddress nextHop, const AntMessage& ant);
    /// Apply a received LinkFail notification and, if it costs this node its own
    /// best path, return a bounded propagated notification.
    std::vector<RouteDecision> handleLinkFail(const AntMessage& note, NodeAddress reporter);
 
    /// Fill the transient deposit state (prevHop/hops/pathTime/pheromone) of a
    /// received backward ant from its `history`, before reinforcement.
    void computeBackAntState(AntMessage& ant) const;
 
    /// This node's contribution to a forward ant's path-time estimate: the
    /// congestion-aware MAC cost (Q_mac+1)*T̂_mac toward `nextHop` when enabled
    /// and available, else the ant's wall-clock transit delta since the
    /// previous stamp.
    double localHopCost(const AntMessage& ant, NodeAddress nextHop) const;
 
    NodeAddress address_;
    Config config_;
    IClock& clock_;
    IRng& rng_;
    PheromoneTable table_;
    PheromoneEngine engine_;
    ClassicMetric defaultMetric_;      ///< used when no metric is injected
    const ILinkMetric* metric_;        ///< pheromone strategy (item 16)
    const ILinkState* linkState_;      ///< MAC congestion signals (item 10/A2), optional
    const ILinkQuality* linkQuality_;  ///< per-neighbour SINR (#181), optional
    AntHistoryTracker history_;
    GenerationTracker genQuality_;  ///< multipath acceptance filter (#96)
    std::uint32_t seqNum_ = 0;
    std::map<NodeAddress, double> activeSessions_;  ///< dest -> last data-send time
    std::map<NodeAddress, double> lastSeen_;        ///< neighbor -> last reception time
    const IKinematics* kinematics_ = nullptr;       ///< own position (ADR-0025), optional
    const IEnergy* energy_ = nullptr;               ///< own battery (#145), optional
    /// ADR-0025: neighbour -> (kinematics its last hello carried, receive
    /// time). Only filled when Config::shareKinematics is on; erased with the
    /// neighbour (loseNeighbor) and by a hello that carries no section.
    std::map<NodeAddress, std::pair<Kinematics, double>> neighborKinematics_;
    /// #574: per-neighbour next-hop weights, refreshed before each choice
    /// and handed to the pheromone table (only when enableLinkLifetime).
    std::map<NodeAddress, double> linkWeights_;
    /// shareKinematics, or implied by a consumer that needs it (#574).
    bool sharingKinematics() const { return config_.shareKinematics || config_.enableLinkLifetime; }
    /// Recompute linkWeights_ for the current neighbours (#574).
    void refreshLinkWeights();
    /// #185: smoothed hop count ĥ per (destination, next hop), the thesis's
    /// eq. 4.2 state. Only populated when Config::hopCountAlpha > 0; entries for
    /// a neighbour are erased with it (loseNeighbor), so it is bounded by the
    /// same (dest, neighbour) set as the regular pheromone table.
    std::map<std::pair<NodeAddress, NodeAddress>, double> hopEstimate_;
    std::map<NodeAddress, double> lastReactive_;    ///< dest -> last reactive-ant time
    std::map<NodeAddress, double> lastRepair_;      ///< dest -> last repair-ant time
    std::map<NodeAddress, double> repairDeadline_;  ///< dest -> repair wait expiry (D6)
    std::map<NodeAddress, int>
        txFailures_;  ///< next hop -> consecutive MAC tx-failures (detector D debounce)
    double lastEvaporation_ = 0.0;  ///< last evaporateAll time
 
    IRouterObserver* observer_ = nullptr;            ///< optional, item 15
    std::map<AntType, std::uint64_t> antsSent_;      ///< sent counters by type
    std::map<AntType, std::uint64_t> antsReceived_;  ///< received counters by type
    std::uint64_t linkfailPropagations_ = 0;         ///< re-broadcast LinkFails (issue #20)
    std::uint64_t linkfailBudgetDrops_ = 0;          ///< budget-suppressed propagations (issue #20)
    std::uint64_t linkfailOriginsSuppressed_ =
        0;  ///< cooldown-suppressed advertisements (issue #20)
    std::uint64_t repairDiscards_ =
        0;  ///< expired local repairs that discarded pending data (#215)
    std::uint64_t directedSteers_ = 0;  ///< reactive ants unicast along the diffusion gradient
    std::map<NodeAddress, double> lastLinkfailNotify_;  ///< dest -> last originated LinkFail time
 
    /// #571 quiet mode, per active destination: the route last seen and how
    /// long it has been stable. Only used when Config::enableQuietMode.
    struct QuietState {
        NodeAddress best = kInvalidAddress;  ///< best regular next hop last round
        double pheromone = 0.0;              ///< its pheromone last round
        int stable = 0;                      ///< consecutive stable rounds
        int skipped = 0;                     ///< rounds since this dest's last ant
    };
    std::map<NodeAddress, QuietState> quiet_;
    /// True when quiet mode lets `dest`'s proactive ant go this round (and
    /// advances its state). Always true with the gate off.
    bool quietAllows(NodeAddress dest);
    /// #572 adaptive evaporation, per destination: the best regular next hop
    /// at the last tick and the smoothed rate (1/s) at which it changes.
    struct ChurnState {
        NodeAddress best = kInvalidAddress;
        double rate = 0.0;
    };
    std::map<NodeAddress, ChurnState> churn_;
    std::map<NodeAddress, double> evapMultiplier_;  ///< dest -> decay multiplier
    /// Update churn_ for a tick `dt` seconds after the last, and refill
    /// evapMultiplier_ (only when Config::enableAdaptiveEvaporation).
    void updateChurn(double dt);
};
 
}  // namespace core
}  // namespace anthocnet
 
#endif  // ANTHOCNET_CORE_ANT_ROUTER_LOGIC_H