api_objects.h

/*
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 "../../application_api/helicsTypes.hpp"
#include "../../common/GuardedTypes.hpp"
#include "../../core/core-data.hpp"
#include "../api-data.h"
#include "gmlc/concurrency/TripWire.hpp"
 
#include <deque>
#include <exception>
#include <memory>
#include <mutex>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
static constexpr int gCoreValidationIdentifier = 0x3784'24EC;
static constexpr int gBrokerValidationIdentifier = 0xA346'7D20;
 
namespace helics {
class Core;
class Federate;
class Broker;
class ValueFederate;
class MessageFederate;
class CallbackFederate;
class FederateInfo;
class Input;
class Publication;
class Endpoint;
class Filter;
class Translator;
 
namespace apps {
    class App;
}
 
class FilterObject;
class TranslatorObject;
class SmallBuffer;
 
enum class FederateType : int { GENERIC, VALUE, MESSAGE, COMBINATION, CALLBACK, INVALID };
 
class BrokerObject {
  public:
    std::shared_ptr<Broker> brokerptr;
    int index{-2};
    int valid{0};
};
 
BrokerObject* getBrokerObject(HelicsBroker broker, HelicsError* err) noexcept;
class CoreObject {
  public:
    std::shared_ptr<Core> coreptr;
    std::vector<std::unique_ptr<FilterObject>> filters;  
    std::vector<std::unique_ptr<TranslatorObject>> translators;  
    int index{0};
    int valid{-2};
    CoreObject() = default;
    ~CoreObject();
};
 
CoreObject* getCoreObject(HelicsCore core, HelicsError* err) noexcept;
 
class AppObject {
  public:
    std::string type;  
    std::shared_ptr<apps::App> app;
    int index{-2};
    int valid{0};
};
 
class InputObject;
class PublicationObject;
class EndpointObject;
class MessageHolder {
  private:
    std::vector<std::unique_ptr<Message>> messages;
    std::vector<int> freeMessageSlots;
 
  public:
    Message* addMessage(std::unique_ptr<Message>& mess);
    Message* newMessage();
    std::unique_ptr<Message> extractMessage(int index);
    void freeMessage(int index);
    void clear();
};
class FedObject {
  public:
    FederateType type = FederateType::INVALID;
    int index{-2};
    int valid{0};
    std::shared_ptr<Federate> fedptr;
    MessageHolder messages;
    std::vector<std::unique_ptr<InputObject>> inputs;
    std::vector<std::unique_ptr<PublicationObject>> pubs;
    std::vector<std::unique_ptr<EndpointObject>> epts;
    std::vector<std::unique_ptr<FilterObject>> filters;
    std::vector<std::unique_ptr<TranslatorObject>> translators;
    std::pair<std::string, std::string> commandBuffer;
    FedObject() = default;
    ~FedObject();
};
 
FedObject* getFedObject(HelicsFederate fed, HelicsError* err) noexcept;
 
class InputObject {
  public:
    int valid{0};
    std::shared_ptr<ValueFederate> fedptr;
    Input* inputPtr{nullptr};
};
 
class PublicationObject {
  public:
    int valid{0};
    std::shared_ptr<ValueFederate> fedptr;
    Publication* pubPtr = nullptr;
};
class EndpointObject {
  public:
    Endpoint* endPtr{nullptr};
    FedObject* fed{nullptr};
    std::shared_ptr<MessageFederate> fedptr;
    int valid{0};
};
 
class FilterObject {
  public:
    bool cloning{false};  
    bool custom{false};  
    int valid{0};
    Filter* filtPtr{nullptr};
    std::unique_ptr<Filter> uFilter;
    std::shared_ptr<Federate> fedptr;
    std::shared_ptr<Core> corePtr;
    std::string buffer;
};
 
class TranslatorObject {
  public:
    bool custom{false};  
    int valid{0};
    Translator* transPtr{nullptr};
    std::unique_ptr<Translator> mTrans;
    std::shared_ptr<Federate> fedptr;
    std::shared_ptr<Core> corePtr;
};
 
class QueryObject {
  public:
    std::string target;  
    std::string query;  
    std::string response;  
    std::shared_ptr<Federate> activeFed;  
    bool activeAsync{false};
    HelicsSequencingModes mode{HELICS_SEQUENCING_MODE_FAST};  
    QueryId asyncIndexCode;  
    int valid{0};
};
 
}  // namespace helics
 
#define HELICS_ERROR_CHECK(err, retval)                                                                                                    \
    do {                                                                                                                                   \
        if (((err) != nullptr) && ((err)->error_code != 0)) {                                                                              \
            return (retval);                                                                                                               \
        }                                                                                                                                  \
    } while (false)
 
inline void assignError(HelicsError* err, int error_code, const char* string)
{
    if (err != nullptr) {
        err->error_code = error_code;
        err->message = string;
    }
}
 
extern const std::string gHelicsEmptyStr;
constexpr char gHelicsNullStringArgument[] = "The supplied string argument is null and therefore invalid";
#define AS_STRING(str) ((str) != nullptr) ? std::string(str) : gHelicsEmptyStr
 
#define AS_STRING_VIEW(str) ((str) != nullptr) ? std::string_view(str) : std::string_view(gHelicsEmptyStr)
 
#define CHECK_NULL_STRING(str, retval)                                                                                                     \
    do {                                                                                                                                   \
        if ((str) == nullptr) {                                                                                                            \
            assignError(err, HELICS_ERROR_INVALID_ARGUMENT, gHelicsNullStringArgument);                                                    \
            return (retval);                                                                                                               \
        }                                                                                                                                  \
    } while (false)
 
helics::Federate* getFed(HelicsFederate fed, HelicsError* err);
helics::ValueFederate* getValueFed(HelicsFederate fed, HelicsError* err);
helics::MessageFederate* getMessageFed(HelicsFederate fed, HelicsError* err);
helics::CallbackFederate* getCallbackFed(HelicsFederate fed, HelicsError* err);
helics::FederateInfo* getFedInfo(HelicsFederateInfo fedInfo, HelicsError* err);
helics::Core* getCore(HelicsCore core, HelicsError* err);
helics::Broker* getBroker(HelicsBroker broker, HelicsError* err);
helics::Message* getMessageObj(HelicsMessage message, HelicsError* err);
helics::apps::App* getApp(HelicsApp, HelicsError* err);
HelicsFederate generateNewHelicsFederateObject(std::shared_ptr<helics::Federate> fed, helics::FederateType type);
 
std::unique_ptr<helics::Message> getMessageUniquePtr(HelicsMessage message, HelicsError* err);
HelicsMessage createAPIMessage(std::unique_ptr<helics::Message>& mess);
 
HelicsDataBuffer createAPIDataBuffer(helics::SmallBuffer& buff);
helics::SmallBuffer* getBuffer(HelicsDataBuffer data);
 
std::shared_ptr<helics::Federate> getFedSharedPtr(HelicsFederate fed, HelicsError* err);
std::shared_ptr<helics::ValueFederate> getValueFedSharedPtr(HelicsFederate fed, HelicsError* err);
std::shared_ptr<helics::MessageFederate> getMessageFedSharedPtr(HelicsFederate fed, HelicsError* err);
std::shared_ptr<helics::CallbackFederate> getCallbackFedSharedPtr(HelicsFederate fed, HelicsError* err);
std::shared_ptr<helics::Core> getCoreSharedPtr(HelicsCore core, HelicsError* err);
 
std::shared_ptr<helics::apps::App> getAppSharedPtr(HelicsApp app, HelicsError* err);
void helicsErrorHandler(HelicsError* err) noexcept;
bool checkOutputArgString(const char* outputString, int maxlen, HelicsError* err);
 
class MasterObjectHolder {
  private:
    guarded<std::deque<std::unique_ptr<helics::BrokerObject>>> brokers;
    guarded<std::deque<std::unique_ptr<helics::CoreObject>>> cores;
    guarded<std::deque<std::unique_ptr<helics::FedObject>>> feds;
    guarded<std::deque<std::unique_ptr<helics::AppObject>>> apps;
    gmlc::concurrency::TripWireDetector tripDetect;  
    guarded<std::deque<std::string>> errorStrings;  
  public:
    MasterObjectHolder() noexcept;
    ~MasterObjectHolder();
    helics::FedObject* findFed(std::string_view fedName);
    helics::FedObject* findFed(std::string_view fedName, int validationCode);
    int addBroker(std::unique_ptr<helics::BrokerObject> broker);
    int addCore(std::unique_ptr<helics::CoreObject> core);
    int addFed(std::unique_ptr<helics::FedObject> fed);
    bool removeFed(std::string_view name, int validationCode);
    int addApp(std::unique_ptr<helics::AppObject> app);
 
    void clearBroker(int index);
    void clearCore(int index);
    void clearFed(int index);
    void clearApp(int index);
    void deleteAll();
    void abortAll(int errorCode, std::string_view error);
    const char* addErrorString(std::string_view newError);
};
 
std::shared_ptr<MasterObjectHolder> getMasterHolder();
void clearAllObjects();
 
double inline timeReturn(HelicsTime val)
{
    return (val < cHelicsTerminateTime) ? static_cast<double>(val) : HELICS_TIME_MAXTIME;
}