BaseTimeCoordinator.hpp

/*
Copyright (c) 2017-2026,
Battelle Memorial Institute; Lawrence Livermore National Security, LLC; Alliance for Energy
Innovation LLC.  See the top-level NOTICE for additional details. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
*/
#pragma once
 
#include "ActionMessage.hpp"
#include "CoreFederateInfo.hpp"
#include "TimeDependencies.hpp"
#include "nlohmann/json_fwd.hpp"
 
#include <atomic>
#include <cstdint>
#include <functional>
#include <limits>
#include <string>
#include <utility>
#include <vector>
 
namespace helics {
 
class BaseTimeCoordinator {
  protected:
    TimeDependencies dependencies;  
    std::function<void(const ActionMessage&)> sendMessageFunction;
 
    GlobalFederateId mSourceId{0};
    std::int32_t sequenceCounter{0};  
    bool noParent{true};  
    bool federatesOnly{false};  
    bool checkingExec{false};
    bool executionMode{false};  
    bool restrictive_time_policy{false};
    bool nonGranting{false};
    bool delayedTiming{false};
    bool disconnected{false};
 
  public:
    static constexpr std::int32_t TIME_COORDINATOR_VERSION{1};
 
  protected:
    // Timing sequence counters are echoed through several compatibility paths; keep them in the
    // positive signed 16-bit range even though ActionMessage stores the counter as uint16_t.
    static constexpr auto maxTimingSequenceCounter = std::numeric_limits<std::int16_t>::max();
 
    static void incrementSequenceCounter(std::int32_t& counter)
    {
        ++counter;
        if (counter > maxTimingSequenceCounter) {
            counter = 1;
        }
    }
 
    static void normalizeSequenceCounter(std::int32_t& counter)
    {
        if (counter > maxTimingSequenceCounter) {
            counter = 1;
        }
    }
 
  public:
    BaseTimeCoordinator();
    explicit BaseTimeCoordinator(std::function<void(const ActionMessage&)> userSendMessageFunction);
    virtual ~BaseTimeCoordinator() = default;
    void setMessageSender(std::function<void(const ActionMessage&)> userSendMessageFunction);
 
    void setRestrictivePolicy(bool policy) { restrictive_time_policy = policy; }
    std::vector<GlobalFederateId> getDependencies() const;
    std::vector<GlobalFederateId> getDependents() const;
    Time getLastGrant(GlobalFederateId fedId) const;
    void setSourceId(GlobalFederateId sourceId) { mSourceId = sourceId; }
    GlobalFederateId sourceId() const { return mSourceId; }
    virtual bool updateTimeFactors() = 0;
 
    const DependencyInfo* getDependencyInfo(GlobalFederateId ofed) const;
    bool isDependency(GlobalFederateId ofed) const;
    bool empty() const { return dependencies.empty(); }
 
  protected:
    ActionMessage generateTimeRequest(const TimeData& dep,
                                      GlobalFederateId fed,
                                      std::int32_t responseCode) const;
    void sendTimingInfo();
 
  public:
    virtual TimeProcessingResult processTimeMessage(const ActionMessage& cmd);
 
    void processDependencyUpdateMessage(const ActionMessage& cmd);
    virtual bool addDependency(GlobalFederateId fedID);
    virtual bool addDependent(GlobalFederateId fedID);
    virtual void removeDependency(GlobalFederateId fedID);
    virtual void removeDependent(GlobalFederateId fedID);
    virtual void resetDependency(GlobalFederateId fedID);
 
    void setAsChild(GlobalFederateId fedID);
    void setAsParent(GlobalFederateId fedID);
    void setVersion(GlobalFederateId fedID, std::int8_t version);
    GlobalFederateId getParent() const;
 
    void disconnect();
    virtual MessageProcessingResult
        checkExecEntry(GlobalFederateId triggerFed = GlobalFederateId{}) = 0;
 
    virtual void enteringExecMode(IterationRequest mode = IterationRequest::NO_ITERATIONS);
 
    virtual std::string printTimeStatus() const = 0;
    virtual void generateDebuggingTimeInfo(nlohmann::json& base) const;
 
    bool hasActiveTimeDependencies() const;
 
    int dependencyCount() const;
    GlobalFederateId getMinDependency() const;
 
    nlohmann::json grantTimeoutCheck(const ActionMessage& cmd);
    virtual Time getNextTime() const = 0;
};
}  // namespace helics