| helics 3.6.1

api_objects.h
1 /*
2 Copyright (c) 2017-2025,
3 Battelle Memorial Institute; Lawrence Livermore National Security, LLC; Alliance for Sustainable Energy, LLC. See the top-level NOTICE for
4 additional details. All rights reserved.
5 SPDX-License-Identifier: BSD-3-Clause
6 */
7 #pragma once
8
9 #include "../../application_api/helicsTypes.hpp"
10 #include "../../common/GuardedTypes.hpp"
11 #include "../../core/core-data.hpp"
12 #include "../api-data.h"
13 #include "gmlc/concurrency/TripWire.hpp"
14
15 #include <deque>
16 #include <exception>
17 #include <memory>
18 #include <mutex>
19 #include <string>
20 #include <string_view>
21 #include <utility>
22 #include <vector>
23
25 static constexpr int gCoreValidationIdentifier = 0x3784'24EC;
26 static constexpr int gBrokerValidationIdentifier = 0xA346'7D20;
27
28 namespace helics {
29 class Core;
30 class Federate;
31 class Broker;
32 class ValueFederate;
33 class MessageFederate;
34 class CallbackFederate;
35 class FederateInfo;
36 class Input;
37 class Publication;
38 class Endpoint;
39 class Filter;
40 class Translator;
41
42 namespace apps {
43 class App;
44 }
45
46 class FilterObject;
47 class TranslatorObject;
48 class SmallBuffer;
49
51 enum class FederateType : int { GENERIC, VALUE, MESSAGE, COMBINATION, CALLBACK, INVALID };
52
54 class BrokerObject {
55 public:
56 std::shared_ptr<Broker> brokerptr;
57 int index{-2};
58 int valid{0};
59 };
60
62 BrokerObject* getBrokerObject(HelicsBroker broker, HelicsError* err) noexcept;
64 class CoreObject {
65 public:
66 std::shared_ptr<Core> coreptr;
67 std::vector<std::unique_ptr<FilterObject>> filters;
68 std::vector<std::unique_ptr<TranslatorObject>> translators;
69 int index{0};
70 int valid{-2};
71 CoreObject() = default;
72 ~CoreObject();
73 };
74
76 CoreObject* getCoreObject(HelicsCore core, HelicsError* err) noexcept;
77
79 class AppObject {
80 public:
81 std::string type;
82 std::shared_ptr<apps::App> app;
83 int index{-2};
84 int valid{0};
85 };
86
87 class InputObject;
88 class PublicationObject;
89 class EndpointObject;
91 class MessageHolder {
92 private:
93 std::vector<std::unique_ptr<Message>> messages;
94 std::vector<int> freeMessageSlots;
95
96 public:
97 Message* addMessage(std::unique_ptr<Message>& mess);
98 Message* newMessage();
99 std::unique_ptr<Message> extractMessage(int index);
100 void freeMessage(int index);
101 void clear();
102 };
104 class FedObject {
105 public:
106 FederateType type = FederateType::INVALID;
107 int index{-2};
108 int valid{0};
109 std::shared_ptr<Federate> fedptr;
110 MessageHolder messages;
111 std::vector<std::unique_ptr<InputObject>> inputs;
112 std::vector<std::unique_ptr<PublicationObject>> pubs;
113 std::vector<std::unique_ptr<EndpointObject>> epts;
114 std::vector<std::unique_ptr<FilterObject>> filters;
115 std::vector<std::unique_ptr<TranslatorObject>> translators;
116 std::pair<std::string, std::string> commandBuffer;
117 FedObject() = default;
118 ~FedObject();
119 };
120
122 FedObject* getFedObject(HelicsFederate fed, HelicsError* err) noexcept;
123
125 class InputObject {
126 public:
127 int valid{0};
128 std::shared_ptr<ValueFederate> fedptr;
129 Input* inputPtr{nullptr};
130 };
131
133 class PublicationObject {
134 public:
135 int valid{0};
136 std::shared_ptr<ValueFederate> fedptr;
137 Publication* pubPtr = nullptr;
138 };
140 class EndpointObject {
141 public:
142 Endpoint* endPtr{nullptr};
143 FedObject* fed{nullptr};
144 std::shared_ptr<MessageFederate> fedptr;
145 int valid{0};
146 };
147
149 class FilterObject {
150 public:
151 bool cloning{false};
152 bool custom{false};
153 int valid{0};
154 Filter* filtPtr{nullptr};
155 std::unique_ptr<Filter> uFilter;
156 std::shared_ptr<Federate> fedptr;
157 std::shared_ptr<Core> corePtr;
158 std::string buffer;
159 };
160
162 class TranslatorObject {
163 public:
164 bool custom{false};
165 int valid{0};
166 Translator* transPtr{nullptr};
167 std::unique_ptr<Translator> mTrans;
168 std::shared_ptr<Federate> fedptr;
169 std::shared_ptr<Core> corePtr;
170 };
171
173 class QueryObject {
174 public:
175 std::string target;
176 std::string query;
177 std::string response;
178 std::shared_ptr<Federate> activeFed;
179 bool activeAsync{false};
180 HelicsSequencingModes mode{HELICS_SEQUENCING_MODE_FAST};
181 QueryId asyncIndexCode;
182 int valid{0};
183 };
184
185 } // namespace helics
186
188 #define HELICS_ERROR_CHECK(err, retval) \
189 do { \
190 if (((err) != nullptr) && ((err)->error_code != 0)) { \
191 return (retval); \
192 } \
193 } while (false)
194
196 inline void assignError(HelicsError* err, int error_code, const char* string)
197 {
198 if (err != nullptr) {
199 err->error_code = error_code;
200 err->message = string;
201 }
202 }
203
204 extern const std::string gHelicsEmptyStr;
205 constexpr char gHelicsNullStringArgument[] = "The supplied string argument is null and therefore invalid";
206 #define AS_STRING(str) ((str) != nullptr) ? std::string(str) : gHelicsEmptyStr
207
208 #define AS_STRING_VIEW(str) ((str) != nullptr) ? std::string_view(str) : std::string_view(gHelicsEmptyStr)
209
210 #define CHECK_NULL_STRING(str, retval) \
211 do { \
212 if ((str) == nullptr) { \
213 assignError(err, HELICS_ERROR_INVALID_ARGUMENT, gHelicsNullStringArgument); \
214 return (retval); \
215 } \
216 } while (false)
217
218 helics::Federate* getFed(HelicsFederate fed, HelicsError* err);
219 helics::ValueFederate* getValueFed(HelicsFederate fed, HelicsError* err);
220 helics::MessageFederate* getMessageFed(HelicsFederate fed, HelicsError* err);
221 helics::CallbackFederate* getCallbackFed(HelicsFederate fed, HelicsError* err);
222 helics::FederateInfo* getFedInfo(HelicsFederateInfo fedInfo, HelicsError* err);
223 helics::Core* getCore(HelicsCore core, HelicsError* err);
224 helics::Broker* getBroker(HelicsBroker broker, HelicsError* err);
225 helics::Message* getMessageObj(HelicsMessage message, HelicsError* err);
226 helics::apps::App* getApp(HelicsApp, HelicsError* err);
228 HelicsFederate generateNewHelicsFederateObject(std::shared_ptr<helics::Federate> fed, helics::FederateType type);
229
230 std::unique_ptr<helics::Message> getMessageUniquePtr(HelicsMessage message, HelicsError* err);
232 HelicsMessage createAPIMessage(std::unique_ptr<helics::Message>& mess);
233
235 HelicsDataBuffer createAPIDataBuffer(helics::SmallBuffer& buff);
237 helics::SmallBuffer* getBuffer(HelicsDataBuffer data);
238
239 std::shared_ptr<helics::Federate> getFedSharedPtr(HelicsFederate fed, HelicsError* err);
240 std::shared_ptr<helics::ValueFederate> getValueFedSharedPtr(HelicsFederate fed, HelicsError* err);
241 std::shared_ptr<helics::MessageFederate> getMessageFedSharedPtr(HelicsFederate fed, HelicsError* err);
242 std::shared_ptr<helics::CallbackFederate> getCallbackFedSharedPtr(HelicsFederate fed, HelicsError* err);
243 std::shared_ptr<helics::Core> getCoreSharedPtr(HelicsCore core, HelicsError* err);
244
245 std::shared_ptr<helics::apps::App> getAppSharedPtr(HelicsApp app, HelicsError* err);
247 void helicsErrorHandler(HelicsError* err) noexcept;
254 bool checkOutputArgString(const char* outputString, int maxlen, HelicsError* err);
255
257 class MasterObjectHolder {
258 private:
259 guarded<std::deque<std::unique_ptr<helics::BrokerObject>>> brokers;
260 guarded<std::deque<std::unique_ptr<helics::CoreObject>>> cores;
261 guarded<std::deque<std::unique_ptr<helics::FedObject>>> feds;
262 guarded<std::deque<std::unique_ptr<helics::AppObject>>> apps;
263 gmlc::concurrency::TripWireDetector tripDetect;
264 guarded<std::deque<std::string>> errorStrings;
265 public:
266 MasterObjectHolder() noexcept;
267 ~MasterObjectHolder();
268 helics::FedObject* findFed(std::string_view fedName);
270 helics::FedObject* findFed(std::string_view fedName, int validationCode);
272 int addBroker(std::unique_ptr<helics::BrokerObject> broker);
274 int addCore(std::unique_ptr<helics::CoreObject> core);
276 int addFed(std::unique_ptr<helics::FedObject> fed);
278 bool removeFed(std::string_view name, int validationCode);
280 int addApp(std::unique_ptr<helics::AppObject> app);
281
282 void clearBroker(int index);
283 void clearCore(int index);
284 void clearFed(int index);
285 void clearApp(int index);
286 void deleteAll();
287 void abortAll(int errorCode, std::string_view error);
290 const char* addErrorString(std::string_view newError);
291 };
292
293 std::shared_ptr<MasterObjectHolder> getMasterHolder();
294 void clearAllObjects();
HelicsDataBuffer
void * HelicsDataBuffer
Definition: api-data.h:88
HelicsFederateInfo
void * HelicsFederateInfo
Definition: api-data.h:77
HelicsCore
void * HelicsCore
Definition: api-data.h:54
HelicsApp
void * HelicsApp
Definition: api-data.h:71
HelicsMessage
void * HelicsMessage
Definition: api-data.h:100
HelicsFederate
void * HelicsFederate
Definition: api-data.h:65
HelicsBroker
void * HelicsBroker
Definition: api-data.h:60
MasterObjectHolder
Definition: api_objects.h:257
MasterObjectHolder::addErrorString
const char * addErrorString(std::string_view newError)
Definition: helicsExport.cpp:1544
MasterObjectHolder::removeFed
bool removeFed(std::string_view name, int validationCode)
Definition: helicsExport.cpp:1408
MasterObjectHolder::addApp
int addApp(std::unique_ptr< helics::AppObject > app)
Definition: helicsExport.cpp:1372
MasterObjectHolder::addBroker
int addBroker(std::unique_ptr< helics::BrokerObject > broker)
Definition: helicsExport.cpp:1345
MasterObjectHolder::addFed
int addFed(std::unique_ptr< helics::FedObject > fed)
Definition: helicsExport.cpp:1363
MasterObjectHolder::addCore
int addCore(std::unique_ptr< helics::CoreObject > core)
Definition: helicsExport.cpp:1354
helics::AppObject
Definition: api_objects.h:79
helics::AppObject::type
std::string type
the target of the query
Definition: api_objects.h:81
helics::BrokerObject
Definition: api_objects.h:54
helics::Broker
Definition: core/Broker.hpp:18
helics::CallbackFederate
Definition: CallbackFederate.hpp:19
helics::CoreObject
Definition: api_objects.h:64
helics::CoreObject::filters
std::vector< std::unique_ptr< FilterObject > > filters
list of filters created directly through the core
Definition: api_objects.h:67
helics::CoreObject::translators
std::vector< std::unique_ptr< TranslatorObject > > translators
list of filters created directly through the core
Definition: api_objects.h:68
helics::Core
Definition: core/Core.hpp:41
helics::EndpointObject
Definition: api_objects.h:140
helics::Endpoint
Definition: Endpoints.hpp:21
helics::FedObject
Definition: api_objects.h:104
helics::FederateInfo
Definition: FederateInfo.hpp:28
helics::Federate
Definition: application_api/Federate.hpp:48
helics::FilterObject
Definition: api_objects.h:149
helics::FilterObject::custom
bool custom
indicator that the filter is a custom filter and requires a callback
Definition: api_objects.h:152
helics::FilterObject::cloning
bool cloning
indicator that the filter is a cloning filter
Definition: api_objects.h:151
helics::IdentifierId< IdentifierType, Identifiers::QUERY, invalid_id_value >
helics::InputObject
Definition: api_objects.h:125
helics::Input
Definition: Inputs.hpp:38
helics::MessageFederate
Definition: application_api/MessageFederate.hpp:24
helics::MessageHolder
Definition: api_objects.h:91
helics::Message
Definition: core-data.hpp:29
helics::PublicationObject
Definition: api_objects.h:133
helics::Publication
Definition: Publications.hpp:25
helics::QueryObject
Definition: api_objects.h:173
helics::QueryObject::mode
HelicsSequencingModes mode
the ordering mode used for the query
Definition: api_objects.h:180
helics::QueryObject::query
std::string query
the actual query itself
Definition: api_objects.h:176
helics::QueryObject::target
std::string target
the target of the query
Definition: api_objects.h:175
helics::QueryObject::asyncIndexCode
QueryId asyncIndexCode
the index to use for the queryComplete call
Definition: api_objects.h:181
helics::QueryObject::response
std::string response
the response to the query
Definition: api_objects.h:177
helics::QueryObject::activeFed
std::shared_ptr< Federate > activeFed
pointer to the fed with the active Query
Definition: api_objects.h:178
helics::SmallBuffer
Definition: SmallBuffer.hpp:25
helics::TranslatorObject
Definition: api_objects.h:162
helics::TranslatorObject::custom
bool custom
indicator that the translator is a custom translator and requires callbacks
Definition: api_objects.h:164
helics::ValueFederate
Definition: application_api/ValueFederate.hpp:28
helics::apps::App
Definition: helicsApp.hpp:32
HelicsSequencingModes
HelicsSequencingModes
Definition: helics_enums.h:427
HELICS_SEQUENCING_MODE_FAST
@ HELICS_SEQUENCING_MODE_FAST
Definition: helics_enums.h:429
helics
the main namespace for the helics co-simulation library User functions will be in the helics namespac...
Definition: AsyncFedCallInfo.hpp:14
helics::getBrokerObject
BrokerObject * getBrokerObject(HelicsBroker broker, HelicsError *err) noexcept
Definition: helicsExport.cpp:323
helics::FederateType
FederateType
Definition: api_objects.h:51
helics::getFedObject
FedObject * getFedObject(HelicsFederate fed, HelicsError *err) noexcept
Definition: FederateExport.cpp:36
helics::getCoreObject
CoreObject * getCoreObject(HelicsCore core, HelicsError *err) noexcept
Definition: helicsExport.cpp:306
HelicsError
Definition: api-data.h:177
HelicsError::message
const char * message
Definition: api-data.h:179
HelicsError::error_code
int32_t error_code
Definition: api-data.h:178