helics  3.2.1
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
helics::Federate Class Reference

#include <Federate.hpp>

+ Inheritance diagram for helics::Federate:

Public Types

enum  Modes : char {
  Modes::STARTUP = 0, Modes::INITIALIZING = 1, Modes::EXECUTING = 2, Modes::FINALIZE = 3,
  Modes::ERROR_STATE = 4, Modes::PENDING_INIT = 5, Modes::PENDING_EXEC = 6, Modes::PENDING_TIME = 7,
  Modes::PENDING_ITERATIVE_TIME = 8, Modes::PENDING_FINALIZE = 9, Modes::FINISHED = 10
}
 

Public Member Functions

 Federate (std::string_view fedname, const FederateInfo &fi)
 
 Federate (std::string_view fedname, const std::shared_ptr< Core > &core, const FederateInfo &fi=FederateInfo{})
 
 Federate (std::string_view fedname, CoreApp &core, const FederateInfo &fi=FederateInfo{})
 
 Federate (const std::string &configString)
 
 Federate (std::string_view fedname, const std::string &configString)
 
 Federate () noexcept
 
 Federate (Federate &&fed) noexcept
 
 Federate (const Federate &fed)=delete
 
virtual ~Federate ()
 
Federateoperator= (Federate &&fed) noexcept
 
Federateoperator= (const Federate &fed)=delete
 
void enterInitializingMode ()
 
void enterInitializingModeAsync ()
 
bool isAsyncOperationCompleted () const
 
void enterInitializingModeComplete ()
 
IterationResult enterExecutingMode (IterationRequest iterate=IterationRequest::NO_ITERATIONS)
 
void enterExecutingModeAsync (IterationRequest iterate=IterationRequest::NO_ITERATIONS)
 
IterationResult enterExecutingModeComplete ()
 
void finalize ()
 
void finalizeAsync ()
 
void finalizeComplete ()
 
void processCommunication (std::chrono::milliseconds period=std::chrono::milliseconds(0))
 
virtual void disconnect ()
 
void localError (int errorcode, std::string_view message)
 
void globalError (int errorcode, std::string_view message)
 
void localError (int errorcode)
 
void globalError (int errorcode)
 
void setSeparator (char separator)
 
Time requestTime (Time nextInternalTimeStep)
 
Time requestNextStep ()
 
Time requestTimeAdvance (Time timeDelta)
 
iteration_time requestTimeIterative (Time nextInternalTimeStep, IterationRequest iterate)
 
void requestTimeAsync (Time nextInternalTimeStep)
 
void requestTimeIterativeAsync (Time nextInternalTimeStep, IterationRequest iterate)
 
Time requestTimeComplete ()
 
iteration_time requestTimeIterativeComplete ()
 
void setTag (std::string_view tag, std::string_view value)
 
const std::string & getTag (std::string_view tag) const
 
void setProperty (int32_t option, double timeValue)
 
void setProperty (int32_t option, Time timeValue)
 
virtual void setFlagOption (int flag, bool flagValue=true)
 
void setProperty (int32_t option, int32_t optionValue)
 
Time getTimeProperty (int32_t option) const
 
virtual bool getFlagOption (int flag) const
 
int getIntegerProperty (int32_t option) const
 
void setLoggingCallback (const std::function< void(int, std::string_view, std::string_view)> &logFunction)
 
void setTimeRequestEntryCallback (std::function< void(Time, Time, bool)> callback)
 
void setTimeUpdateCallback (std::function< void(Time, bool)> callback)
 
void setModeUpdateCallback (std::function< void(Modes, Modes)> callback)
 
void setTimeRequestReturnCallback (std::function< void(Time, bool)> callback)
 
std::string query (std::string_view target, std::string_view queryStr, HelicsSequencingModes mode=HELICS_SEQUENCING_MODE_FAST)
 
std::string query (std::string_view queryStr, HelicsSequencingModes mode=HELICS_SEQUENCING_MODE_FAST)
 
QueryId queryAsync (std::string_view target, std::string_view queryStr, HelicsSequencingModes mode=HELICS_SEQUENCING_MODE_FAST)
 
QueryId queryAsync (std::string_view queryStr, HelicsSequencingModes mode=HELICS_SEQUENCING_MODE_FAST)
 
std::string queryComplete (QueryId queryIndex)
 
bool isQueryCompleted (QueryId queryIndex) const
 
void setQueryCallback (const std::function< std::string(std::string_view)> &queryFunction)
 
void setGlobal (std::string_view valueName, std::string_view value)
 
void sendCommand (std::string_view target, std::string_view commandStr, HelicsSequencingModes mode=HelicsSequencingModes::HELICS_SEQUENCING_MODE_FAST)
 
std::pair< std::string, std::string > getCommand ()
 
std::pair< std::string, std::string > waitCommand ()
 
void addDependency (std::string_view fedName)
 
FilterregisterGlobalFilter (std::string_view filterName, std::string_view inputType=std::string_view{}, std::string_view outputType=std::string_view{})
 
CloningFilterregisterGlobalCloningFilter (std::string_view filterName, std::string_view inputType=std::string_view{}, std::string_view outputType=std::string_view{})
 
FilterregisterFilter (std::string_view filterName, std::string_view inputType=std::string_view{}, std::string_view outputType=std::string_view{})
 
CloningFilterregisterCloningFilter (std::string_view filterName, std::string_view inputType=std::string_view{}, std::string_view outputType=std::string_view{})
 
FilterregisterFilter ()
 
TranslatorregisterGlobalTranslator (std::int32_t translatorType, std::string_view translatorName, std::string_view endpointType=std::string_view{}, std::string_view units=std::string_view())
 
TranslatorregisterTranslator (std::int32_t translatorType, std::string_view translatorName, std::string_view endpointType=std::string_view{}, std::string_view units=std::string_view{})
 
TranslatorregisterGlobalTranslator (std::string_view translatorName, std::string_view endpointType=std::string_view{}, std::string_view units=std::string_view())
 
TranslatorregisterTranslator (std::string_view translatorName, std::string_view endpointType=std::string_view{}, std::string_view units=std::string_view{})
 
TranslatorregisterTranslator ()
 
CloningFilterregisterCloningFilter ()
 
const FiltergetFilter (std::string_view filterName) const
 
const FiltergetFilter (int index) const
 
FiltergetFilter (std::string_view filterName)
 
FiltergetFilter (int index)
 
void setFilterOperator (const Filter &filt, std::shared_ptr< FilterOperator > op)
 register a operator for the specified filter More...
 
int getFilterCount () const
 
const TranslatorgetTranslator (std::string_view translatorName) const
 
const TranslatorgetTranslator (int index) const
 
TranslatorgetTranslator (std::string_view translatorName)
 
TranslatorgetTranslator (int index)
 
void setTranslatorOperator (const Translator &trans, std::shared_ptr< TranslatorOperator > op)
 register an operator for the specified translator More...
 
int getTranslatorCount () const
 
virtual void registerInterfaces (const std::string &configString)
 
void registerFilterInterfaces (const std::string &configString)
 
auto getID () const noexcept
 
Modes getCurrentMode () const
 
Time getCurrentTime () const
 
const std::string & getName () const
 
const std::shared_ptr< Core > & getCorePointer ()
 
void logMessage (int level, std::string_view message) const
 
void logErrorMessage (std::string_view message) const
 
void logWarningMessage (std::string_view message) const
 
void logInfoMessage (std::string_view message) const
 
void logDebugMessage (std::string_view message) const
 
void completeOperation ()
 

Protected Member Functions

virtual void updateTime (Time newTime, Time oldTime)
 
virtual void startupToInitializeStateTransition ()
 
virtual void initializeToExecuteStateTransition (IterationResult iterate)
 
virtual void disconnectTransition ()
 
virtual std::string localQuery (std::string_view queryStr) const
 
std::string localNameGenerator (std::string_view localName) const
 

Protected Attributes

std::atomic< ModescurrentMode {Modes::STARTUP}
 the current state of the simulation
 
char nameSegmentSeparator = '/'
 the separator between automatically prependend names
 
bool strictConfigChecking {true}
 
bool useJsonSerialization {false}
 
bool observerMode {false}
 
std::shared_ptr< CorecoreObject
 reference to the core simulation API
 
Time currentTime = Time::minVal()
 the current simulation time
 

Detailed Description

base class for a federate in the application API

Member Enumeration Documentation

◆ Modes

enum helics::Federate::Modes : char
strong

the allowable operation modes of the federate

Enumerator
STARTUP 

when created the federate is in startup state

INITIALIZING 

entered after the enterInitializingMode call has returned

EXECUTING 

entered after the enterExectuationState call has returned

FINALIZE 

the federate has finished executing normally final values may be retrieved

ERROR_STATE 

error state no core communication is possible but values can be retrieved

PENDING_INIT 

indicator that the federate is pending entry to initialization state

PENDING_EXEC 

state pending EnterExecution State

PENDING_TIME 

state that the federate is pending a timeRequest

PENDING_ITERATIVE_TIME 

state that the federate is pending an iterative time request

PENDING_FINALIZE 

state that the federate is pending a finalize call

FINISHED 

the simulation has finished normally but everything is still connected

Constructor & Destructor Documentation

◆ Federate() [1/8]

helics::Federate::Federate ( std::string_view  fedname,
const FederateInfo fi 
)

◆ Federate() [2/8]

helics::Federate::Federate ( std::string_view  fedname,
const std::shared_ptr< Core > &  core,
const FederateInfo fi = FederateInfo{} 
)

constructor taking a core and a federate information structure

Parameters
fednamethe name of the federate can be empty to use a name from the federateInfo
corea shared pointer to a core object, the pointer will be copied
fia federate information structure

make sure the core is connected

References helics::FederateInfo::coreName, coreObject, helics::FederateInfo::coreType, currentTime, helics::FederateInfo::defName, helics::CoreFactory::findJoinableCoreOfType(), helics::CoreFactory::FindOrCreate(), helics::generateFullCoreInitString(), HELICS_FLAG_STRICT_CONFIG_CHECKING, nameSegmentSeparator, observerMode, helics::FederateInfo::separator, and strictConfigChecking.

◆ Federate() [3/8]

helics::Federate::Federate ( std::string_view  fedname,
CoreApp core,
const FederateInfo fi = FederateInfo{} 
)

constructor taking a CoreApp and a federate information structure

Parameters
fednamethe name of the federate can be empty to use a name from the federateInfo
corea CoreApp with the core core connect to.
fia federate information structure

◆ Federate() [4/8]

helics::Federate::Federate ( const std::string &  configString)
explicit

constructor taking a file with the required information

Parameters
configStringcan be either a JSON file or a string containing JSON code or a TOML file

◆ Federate() [5/8]

helics::Federate::Federate ( std::string_view  fedname,
const std::string &  configString 
)

constructor taking a file with the required information and the name of the federate

Parameters
fednamethe name of the federate
configStringcan be either a JSON file or a string containing JSON code or a TOML file with extension (.toml, .TOML)

References registerFilterInterfaces().

◆ Federate() [6/8]

helics::Federate::Federate ( )
noexcept

default constructor

◆ Federate() [7/8]

helics::Federate::Federate ( Federate &&  fed)
noexcept

move constructor

References helics::CoreFactory::getEmptyCore().

◆ Federate() [8/8]

helics::Federate::Federate ( const Federate fed)
delete

deleted copy constructor

◆ ~Federate()

helics::Federate::~Federate ( )
virtual

virtual destructor function

References currentMode, FINALIZE, and finalize().

Member Function Documentation

◆ addDependency()

void helics::Federate::addDependency ( std::string_view  fedName)

add a dependency for this federate

adds an additional internal time dependency for the federate

Parameters
fedNamethe name of the federate to add a dependency on

References coreObject.

◆ completeOperation()

void helics::Federate::completeOperation ( )

◆ disconnect()

void helics::Federate::disconnect ( )
virtual

disconnect a simulation from the core (will also call finalize before disconnecting if necessary)

Reimplemented in helics::ValueFederate, helics::MessageFederate, and helics::CombinationFederate.

References coreObject, finalize(), and helics::CoreFactory::getEmptyCore().

Referenced by helics::MessageFederate::disconnect(), and helics::ValueFederate::disconnect().

◆ disconnectTransition()

void helics::Federate::disconnectTransition ( )
protectedvirtual

function to handle any disconnect operations

◆ enterExecutingMode()

IterationResult helics::Federate::enterExecutingMode ( IterationRequest  iterate = IterationRequest::NO_ITERATIONS)

◆ enterExecutingModeAsync()

void helics::Federate::enterExecutingModeAsync ( IterationRequest  iterate = IterationRequest::NO_ITERATIONS)

enter the normal execution mode

call will return immediately but enterExecutingModeComplete should be called to complete the operation

Parameters
iteratean optional flag indicating the desired iteration mode

References coreObject, currentMode, currentTime, enterInitializingModeComplete(), EXECUTING, INITIALIZING, PENDING_EXEC, PENDING_INIT, PENDING_ITERATIVE_TIME, PENDING_TIME, STARTUP, and startupToInitializeStateTransition().

◆ enterExecutingModeComplete()

IterationResult helics::Federate::enterExecutingModeComplete ( )

complete the async call for entering Execution state

call will not block but will return quickly. The enterInitializingModeComplete must be called before doing other operations

References coreObject, currentMode, currentTime, enterExecutingMode(), helics::ERROR_RESULT, ERROR_STATE, EXECUTING, FINISHED, helics::HALTED, helics::initializationTime, initializeToExecuteStateTransition(), INITIALIZING, helics::ITERATING, helics::NEXT_STEP, observerMode, PENDING_EXEC, and helics::timeZero.

Referenced by completeOperation(), enterExecutingMode(), and finalizeAsync().

◆ enterInitializingMode()

void helics::Federate::enterInitializingMode ( )

enter the initialization mode after all interfaces have been defined

the call will block until all federates have entered initialization mode

References coreObject, currentMode, currentTime, enterInitializingModeComplete(), ERROR_STATE, INITIALIZING, PENDING_INIT, STARTUP, and startupToInitializeStateTransition().

Referenced by enterExecutingMode(), and enterInitializingModeComplete().

◆ enterInitializingModeAsync()

void helics::Federate::enterInitializingModeAsync ( )

enter the initialization mode after all interfaces have been defined

the call will not block but a call to enterInitializingModeComplete should be made to complete the call sequence

References coreObject, currentMode, INITIALIZING, PENDING_INIT, and STARTUP.

◆ enterInitializingModeComplete()

void helics::Federate::enterInitializingModeComplete ( )

second part of the async process for entering initializationState call after a call to enterInitializingModeAsync if call any other time it will throw an InvalidFunctionCall exception

References coreObject, currentMode, currentTime, enterInitializingMode(), ERROR_STATE, INITIALIZING, PENDING_INIT, STARTUP, and startupToInitializeStateTransition().

Referenced by completeOperation(), enterExecutingModeAsync(), enterInitializingMode(), and finalizeAsync().

◆ finalize()

void helics::Federate::finalize ( )

terminate the simulation

call is will block until the finalize has been acknowledged, no commands that interact with the core may be called after this function function

References coreObject, currentMode, ERROR_STATE, EXECUTING, FINALIZE, finalizeComplete(), FINISHED, INITIALIZING, PENDING_EXEC, PENDING_FINALIZE, PENDING_INIT, PENDING_ITERATIVE_TIME, PENDING_TIME, and STARTUP.

Referenced by disconnect(), finalizeComplete(), and ~Federate().

◆ finalizeAsync()

void helics::Federate::finalizeAsync ( )

terminate the simulation in a non-blocking call

finalizeComplete must be called after this call to complete the finalize procedure

References coreObject, currentMode, enterExecutingModeComplete(), enterInitializingModeComplete(), ERROR_STATE, FINALIZE, PENDING_EXEC, PENDING_FINALIZE, PENDING_INIT, PENDING_ITERATIVE_TIME, PENDING_TIME, requestTimeComplete(), and requestTimeIterativeComplete().

◆ finalizeComplete()

void helics::Federate::finalizeComplete ( )

complete the asynchronous terminate pair

References currentMode, FINALIZE, finalize(), and PENDING_FINALIZE.

Referenced by completeOperation(), and finalize().

◆ getCommand()

std::pair< std::string, std::string > helics::Federate::getCommand ( )

get a command for the Federate

Returns
a pair of strings <command,source> with the command instructions for the federate; the command string will be empty if no command is given

References coreObject.

◆ getCorePointer()

const std::shared_ptr<Core>& helics::Federate::getCorePointer ( )
inline

get a shared pointer to the core object used by the federate

Referenced by helics::make_cloning_filter().

◆ getCurrentMode()

Modes helics::Federate::getCurrentMode ( ) const
inline

◆ getCurrentTime()

Time helics::Federate::getCurrentTime ( ) const
inline

get the current Time

the most recent granted time of the federate

◆ getFilter() [1/4]

Filter & helics::Federate::getFilter ( int  index)

get a filter from its index

Parameters
indexthe index of a filter
Returns
a reference to a filter object which could be invalid if filterName is not valid

◆ getFilter() [2/4]

const Filter & helics::Federate::getFilter ( int  index) const

get a filter from its index

Parameters
indexthe index of a filter
Returns
a reference to a filter object which could be invalid if filterName is not valid

◆ getFilter() [3/4]

Filter & helics::Federate::getFilter ( std::string_view  filterName)

get a filter from its name

Parameters
filterNamethe name of the filter
Returns
a reference to a filter object which could be invalid if filterName is not valid

References helics::Interface::isValid(), and localNameGenerator().

◆ getFilter() [4/4]

const Filter & helics::Federate::getFilter ( std::string_view  filterName) const

get a filter from its name

Parameters
filterNamethe name of the filter
Returns
a reference to a filter object which could be invalid if filterName is not valid

References helics::Interface::isValid(), and localNameGenerator().

◆ getFilterCount()

int helics::Federate::getFilterCount ( ) const

get the number of filters registered through this federate

◆ getFlagOption()

bool helics::Federate::getFlagOption ( int  flag) const
virtual

get the value of a flag option

Parameters
flagan index into the flag /ref flag-definitions.h

References coreObject, HELICS_FLAG_USE_JSON_SERIALIZATION, and useJsonSerialization.

◆ getID()

auto helics::Federate::getID ( ) const
inlinenoexcept

get the underlying federateID for the core

Referenced by helics::MessageFederate::MessageFederate(), and helics::ValueFederate::ValueFederate().

◆ getIntegerProperty()

int32_t helics::Federate::getIntegerProperty ( int32_t  option) const

get an integer option for the federate

Parameters
optionthe option to inquire see /ref defs

References coreObject.

◆ getName()

const std::string& helics::Federate::getName ( ) const
inline

get the federate name

Referenced by localNameGenerator(), query(), and sendCommand().

◆ getTag()

const std::string & helics::Federate::getTag ( std::string_view  tag) const

get the value of a specific tag (key-value pair) for a federate

the tag is an arbitrary user defined string and value; the tags for a federate are queryable

Parameters
tagthe name of the tag to get the value for
Returns
a const std::string& containing the value of the tag, if the tag is not defined the value is an empty string

References coreObject.

◆ getTimeProperty()

Time helics::Federate::getTimeProperty ( int32_t  option) const

get the value of a time option for the federate

Parameters
optionthe option to get

References coreObject.

◆ getTranslator() [1/4]

Translator & helics::Federate::getTranslator ( int  index)

get a translator from its index

Parameters
indexthe index of a translator
Returns
a reference to a translator object which will be invalid if index is not valid

◆ getTranslator() [2/4]

const Translator & helics::Federate::getTranslator ( int  index) const

get a translator from its index

Parameters
indexthe index of a translator
Returns
a reference to a translator object which will be invalid if index is not valid

◆ getTranslator() [3/4]

Translator & helics::Federate::getTranslator ( std::string_view  translatorName)

get a translator from its name

Parameters
translatorNamethe name of the translator
Returns
a reference to a translator object which will be invalid if translatorName is not valid

References helics::Interface::isValid(), and localNameGenerator().

◆ getTranslator() [4/4]

const Translator & helics::Federate::getTranslator ( std::string_view  translatorName) const

get a translator from its name

Parameters
translatorNamethe name of the translator
Returns
a reference to a translator object which will be invalid if translatorName is not valid

References helics::Interface::isValid(), and localNameGenerator().

◆ getTranslatorCount()

int helics::Federate::getTranslatorCount ( ) const

get the number of translators registered through this federate

◆ globalError() [1/2]

void helics::Federate::globalError ( int  errorcode)

specify the simulator had a global error with error code

Parameters
errorcodean integral code for the error

References globalError().

◆ globalError() [2/2]

void helics::Federate::globalError ( int  errorcode,
std::string_view  message 
)

specify the simulator had a global error with error code and message

global errors propagate through the entire federation and will halt operations

Parameters
errorcodean integral code for the error
messagea string describing the error to display in the log

References completeOperation(), coreObject, and ERROR_STATE.

Referenced by globalError().

◆ initializeToExecuteStateTransition()

void helics::Federate::initializeToExecuteStateTransition ( IterationResult  iterate)
protectedvirtual

function to deal with any operations that need to occur on the transition from startup to initialize

Reimplemented in helics::ValueFederate, helics::MessageFederate, and helics::CombinationFederate.

Referenced by enterExecutingMode(), and enterExecutingModeComplete().

◆ isAsyncOperationCompleted()

bool helics::Federate::isAsyncOperationCompleted ( ) const

called after one of the async calls and will indicate true if an async operation has completed

only call from the same thread as the one that called the initial async call and will return false if called when no async operation is in flight

References currentMode, PENDING_EXEC, PENDING_FINALIZE, PENDING_INIT, PENDING_ITERATIVE_TIME, and PENDING_TIME.

◆ isQueryCompleted()

bool helics::Federate::isQueryCompleted ( QueryId  queryIndex) const

check if an asynchronous query call has been completed

Returns
true if the results are ready for /ref queryFinalize

◆ localError() [1/2]

void helics::Federate::localError ( int  errorcode)

specify the simulator had a local error with error code

Parameters
errorcodean integral code for the error

References localError().

◆ localError() [2/2]

void helics::Federate::localError ( int  errorcode,
std::string_view  message 
)

specify the simulator had a local error with error code and message

Parameters
errorcodean integral code for the error
messagea string describing the error to display in a log

References completeOperation(), coreObject, and ERROR_STATE.

Referenced by localError().

◆ localNameGenerator()

std::string helics::Federate::localNameGenerator ( std::string_view  localName) const
protected

◆ localQuery()

std::string helics::Federate::localQuery ( std::string_view  queryStr) const
protectedvirtual

function to generate results for a local Query

should return an empty string if the query is not recognized

Reimplemented in helics::ValueFederate, helics::MessageFederate, and helics::CombinationFederate.

Referenced by query().

◆ logDebugMessage()

void helics::Federate::logDebugMessage ( std::string_view  message) const
inline

log a debug message to the federate Logger

Parameters
messagethe message to log

References HELICS_LOG_LEVEL_DEBUG.

◆ logErrorMessage()

void helics::Federate::logErrorMessage ( std::string_view  message) const
inline

log an error message to the federate Logger

Parameters
messagethe message to log

References HELICS_LOG_LEVEL_ERROR.

◆ logInfoMessage()

void helics::Federate::logInfoMessage ( std::string_view  message) const
inline

log an info message to the federate Logger

Parameters
messagethe message to log

References HELICS_LOG_LEVEL_SUMMARY.

◆ logMessage()

void helics::Federate::logMessage ( int  level,
std::string_view  message 
) const

log a message to the federate Logger

Parameters
levelthe logging level of the message
messagethe message to log

References coreObject, and HELICS_LOG_LEVEL_WARNING.

◆ logWarningMessage()

void helics::Federate::logWarningMessage ( std::string_view  message) const
inline

log a warning message to the federate Logger

Parameters
messagethe message to log

References HELICS_LOG_LEVEL_WARNING.

Referenced by Federate().

◆ operator=() [1/2]

Federate& helics::Federate::operator= ( const Federate fed)
delete

delete copy assignment

◆ operator=() [2/2]

Federate & helics::Federate::operator= ( Federate &&  fed)
noexcept

◆ processCommunication()

void helics::Federate::processCommunication ( std::chrono::milliseconds  period = std::chrono::milliseconds(0))

Run a processing loop for X amount of time. If the period is set to 0 it just processes currently pending communications.

References coreObject.

◆ query() [1/2]

std::string helics::Federate::query ( std::string_view  queryStr,
HelicsSequencingModes  mode = HELICS_SEQUENCING_MODE_FAST 
)

make a query of the core

this call is blocking until the value is returned which make take some time depending on the size of the federation and the specific string being queried

Parameters
queryStra string with the query see other documentation for specific properties to query, can be defined by the federate if the local federate does not recognize the query it sends it on to the federation
modefast (asynchronous; default) means the query goes on priority channels, ordered (synchronous) is slower but has more ordering guarantees
Returns
a string with the value requested. this is either going to be a vector of strings value or a JSON string stored in the first element of the vector. The string "#invalid" is returned if the query was not valid

References coreObject, currentTime, getName(), and localQuery().

◆ query() [2/2]

std::string helics::Federate::query ( std::string_view  target,
std::string_view  queryStr,
HelicsSequencingModes  mode = HELICS_SEQUENCING_MODE_FAST 
)

make a query of the core

this call is blocking until the value is returned which make take some time depending on the size of the federation and the specific string being queried

Parameters
targetthe target of the query can be "federation", "federate", "broker", "core", or a specific name of a federate, core, or broker
queryStra string with the query see other documentation for specific properties to query, can be defined by the federate
modefast (asynchronous; default) means the query goes on priority channels, ordered (synchronous) is slower but has more ordering guarantees
Returns
a string with the value requested. this is either going to be a vector of strings value or a JSON string stored in the first element of the vector. The string "#invalid" is returned if the query was not valid

References coreObject, and getName().

Referenced by queryAsync(), helics::queryFederateSubscriptions(), helics::waitForFed(), and helics::waitForInit().

◆ queryAsync() [1/2]

QueryId helics::Federate::queryAsync ( std::string_view  queryStr,
HelicsSequencingModes  mode = HELICS_SEQUENCING_MODE_FAST 
)

make a query of the core in an async fashion

this call is blocking until the value is returned which make take some time depending on the size of the federation and the specific string being queried

Parameters
queryStra string with the query see other documentation for specific properties to query, can be defined by the federate
modefast (asynchronous; default) means the query goes on priority channels, ordered(synchronous) is slower but has more ordering guarantees
Returns
a QueryId used to get the results of the query in the future

References query().

◆ queryAsync() [2/2]

QueryId helics::Federate::queryAsync ( std::string_view  target,
std::string_view  queryStr,
HelicsSequencingModes  mode = HELICS_SEQUENCING_MODE_FAST 
)

make a query of the core in an async fashion

this call is blocking until the value is returned which make take some time depending on the size of the federation and the specific string being queried

Parameters
targetthe target of the query can be "federation", "federate", "broker", "core", or a specific name of a federate, core, or broker
queryStra string with the query see other documentation for specific properties to query, can be defined by the federate
modefast (asynchronous; default) means the query goes on priority channels, ordered(synchronous) is slower but has more ordering guarantees
Returns
a QueryId to use for returning the result

References coreObject.

◆ queryComplete()

std::string helics::Federate::queryComplete ( QueryId  queryIndex)

get the results of an async query

the call will block until the results are returned inquiry of queryCompleted() to check if the results have been returned or not yet

Parameters
queryIndexthe int value returned from the queryAsync call
Returns
a string with the value requested. the format of the string will be either a single string a string vector like "[string1; string2]" or JSON The string "#invalid" is returned if the query was not valid

References helics::generateJsonErrorResponse(), and helics::IdentifierId< BaseType, ID, invalidValue >::value().

◆ registerCloningFilter() [1/2]

CloningFilter& helics::Federate::registerCloningFilter ( )
inline

define a nameless cloning filter interface on a source

◆ registerCloningFilter() [2/2]

CloningFilter & helics::Federate::registerCloningFilter ( std::string_view  filterName,
std::string_view  inputType = std::string_view{},
std::string_view  outputType = std::string_view{} 
)

define a cloning filter interface on a source

a source filter will be sent any packets that come from a particular source if multiple filters are defined on the same source, they will be placed in some order defined by the core

Parameters
filterNamethe name of the filter
inputTypethe inputType which the filter can handle
outputTypethe outputType of the filter which the filter produces

References localNameGenerator().

Referenced by helics::CloningFilter::CloningFilter(), and helics::make_cloning_filter().

◆ registerFilter() [1/2]

Filter& helics::Federate::registerFilter ( )
inline

define a nameless filter interface

◆ registerFilter() [2/2]

Filter & helics::Federate::registerFilter ( std::string_view  filterName,
std::string_view  inputType = std::string_view{},
std::string_view  outputType = std::string_view{} 
)

define a filter interface

a filter will modify messages coming from or going to target endpoints

Parameters
filterNamethe name of the filter
inputTypethe inputType which the filter can handle
outputTypethe outputType of the filter which the filter produces

References localNameGenerator().

◆ registerFilterInterfaces()

void helics::Federate::registerFilterInterfaces ( const std::string &  configString)

register filter/translator interfaces defined in a file or string

call is only valid in startup mode

Parameters
configStringthe location of the file or config String to load to generate the interfaces

Referenced by Federate(), helics::CombinationFederate::registerInterfaces(), helics::MessageFederate::registerInterfaces(), and registerInterfaces().

◆ registerGlobalCloningFilter()

CloningFilter & helics::Federate::registerGlobalCloningFilter ( std::string_view  filterName,
std::string_view  inputType = std::string_view{},
std::string_view  outputType = std::string_view{} 
)

define a cloning filter interface on a source

a cloning filter will modify copy of messages coming from or going to target endpoints

Parameters
filterNamethe name of the filter
inputTypethe inputType which the filter can handle
outputTypethe outputType of the filter which the filter produces

◆ registerGlobalFilter()

Filter & helics::Federate::registerGlobalFilter ( std::string_view  filterName,
std::string_view  inputType = std::string_view{},
std::string_view  outputType = std::string_view{} 
)

define a named global filter interface

Parameters
filterNamethe name of the globally visible filter
inputTypethe inputType which the filter can handle
outputTypethe outputType of the filter which the filter produces

◆ registerGlobalTranslator() [1/2]

Translator & helics::Federate::registerGlobalTranslator ( std::int32_t  translatorType,
std::string_view  translatorName,
std::string_view  endpointType = std::string_view{},
std::string_view  units = std::string_view() 
)

define a named global translator interface

Parameters
translatorTypea code defining a known type of translator (0 for custom)
translatorNamethe name of the globally visible translator
endpointTypethe type associated with the translator endpoint
unitsthe units associated with the translator value interfaces

References helics::Translator::setTranslatorType().

◆ registerGlobalTranslator() [2/2]

Translator& helics::Federate::registerGlobalTranslator ( std::string_view  translatorName,
std::string_view  endpointType = std::string_view{},
std::string_view  units = std::string_view() 
)
inline

define a named global translator interface

Parameters
translatorNamethe name of the globally visible translator
endpointTypethe type associated with the translator endpoint
unitsthe units associated with the translator value interfaces

◆ registerInterfaces()

void helics::Federate::registerInterfaces ( const std::string &  configString)
virtual

register a set of interfaces defined in a file

call is only valid in startup mode

Parameters
configStringthe location of the file or config String to load to generate the interfaces

Reimplemented in helics::ValueFederate, helics::MessageFederate, and helics::CombinationFederate.

References registerFilterInterfaces().

Referenced by helics::ValueFederate::registerInterfaces().

◆ registerTranslator() [1/3]

Translator& helics::Federate::registerTranslator ( )
inline

define a nameless translator interface

◆ registerTranslator() [2/3]

Translator & helics::Federate::registerTranslator ( std::int32_t  translatorType,
std::string_view  translatorName,
std::string_view  endpointType = std::string_view{},
std::string_view  units = std::string_view{} 
)

define a translator interface

a translator acts as a bridge between value and message interfaces

Parameters
translatorTypea code defining a known type of translator (0 for custom)
translatorNamethe name of the translator; can be an empty string
endpointTypethe type associated with the translator endpoint
unitsthe units associated with the translator value interfaces

References localNameGenerator(), and helics::Translator::setTranslatorType().

◆ registerTranslator() [3/3]

Translator& helics::Federate::registerTranslator ( std::string_view  translatorName,
std::string_view  endpointType = std::string_view{},
std::string_view  units = std::string_view{} 
)
inline

define a translator interface

a translator acts as a bridge between value and message interfaces

Parameters
translatorNamethe name of the translator
endpointTypethe type associated with the translator endpoint
unitsthe units associated with the translator value interfaces

◆ requestNextStep()

Time helics::Federate::requestNextStep ( )
inline

request a time advancement to the next allowed time

Returns
the granted time step

References helics::timeZero.

◆ requestTime()

Time helics::Federate::requestTime ( Time  nextInternalTimeStep)

request a time advancement

Parameters
nextInternalTimeStepthe next requested time step
Returns
the granted time step

References coreObject, currentMode, currentTime, ERROR_STATE, EXECUTING, FINALIZE, and FINISHED.

◆ requestTimeAdvance()

Time helics::Federate::requestTimeAdvance ( Time  timeDelta)
inline

request a time advancement by a certain amount

Parameters
timeDeltathe amount of time to advance
Returns
the granted time step

◆ requestTimeAsync()

void helics::Federate::requestTimeAsync ( Time  nextInternalTimeStep)

request a time advancement and return immediately for asynchronous function.

/ref requestTimeComplete should be called to finish the operation and get the result

Parameters
nextInternalTimeStepthe next requested time step

References coreObject, currentMode, currentTime, EXECUTING, and PENDING_TIME.

◆ requestTimeComplete()

Time helics::Federate::requestTimeComplete ( )

request a time advancement

Returns
the granted time step

References currentMode, currentTime, EXECUTING, and PENDING_TIME.

Referenced by completeOperation(), enterExecutingMode(), and finalizeAsync().

◆ requestTimeIterative()

iteration_time helics::Federate::requestTimeIterative ( Time  nextInternalTimeStep,
IterationRequest  iterate 
)

request a time advancement

Parameters
nextInternalTimeStepthe next requested time step
iteratea requested iteration mode
Returns
the granted time step in a structure containing a return time and an IterationResult

References coreObject, currentMode, currentTime, helics::ERROR_RESULT, ERROR_STATE, EXECUTING, FINALIZE, FINISHED, helics::HALTED, helics::ITERATING, helics::NEXT_STEP, and helics::NO_ITERATIONS.

◆ requestTimeIterativeAsync()

void helics::Federate::requestTimeIterativeAsync ( Time  nextInternalTimeStep,
IterationRequest  iterate 
)

request a time advancement with iterative call and return for asynchronous function.

/ref requestTimeIterativeComplete should be called to finish the operation and get the result

Parameters
nextInternalTimeStepthe next requested time step
iteratea requested iteration level (none, require, optional)

References coreObject, currentMode, currentTime, EXECUTING, helics::NO_ITERATIONS, and PENDING_ITERATIVE_TIME.

◆ requestTimeIterativeComplete()

iteration_time helics::Federate::requestTimeIterativeComplete ( )

finalize the time advancement request

Returns
the granted time step in an iteration_time structure which contains a time and iteration result

finalize the time advancement request

Returns
the granted time step

References currentMode, currentTime, helics::ERROR_RESULT, ERROR_STATE, EXECUTING, FINISHED, helics::HALTED, helics::ITERATING, helics::NEXT_STEP, and PENDING_ITERATIVE_TIME.

Referenced by completeOperation(), enterExecutingMode(), and finalizeAsync().

◆ sendCommand()

void helics::Federate::sendCommand ( std::string_view  target,
std::string_view  commandStr,
HelicsSequencingModes  mode = HelicsSequencingModes::HELICS_SEQUENCING_MODE_FAST 
)

send a command to another core or federate

Parameters
targetthe target of the command can be "federation", "federate", "broker", "core", or a specific name of a federate, core, or broker
commandStra string with the command instructions, see other documentation for specific properties to command, can be defined by a federate
modefast (asynchronous; default) means the command goes on priority channels, ordered(synchronous) is slower but has more ordering guarantees

References coreObject, and getName().

◆ setFilterOperator()

void helics::Federate::setFilterOperator ( const Filter filt,
std::shared_ptr< FilterOperator op 
)

register a operator for the specified filter

The FilterOperator gets called when there is a message to filter, There is no order or state to this messages can come in any order.

Parameters
filtthe filter object to set the operation on
opa shared_ptr to a FilterOperator

References coreObject, and helics::Interface::getHandle().

◆ setFlagOption()

void helics::Federate::setFlagOption ( int  flag,
bool  flagValue = true 
)
virtual

set a flag for the federate

Parameters
flagan index into the flag /ref flag-definitions.h
flagValuethe value of the flag defaults to true

Reimplemented in helics::CombinationFederate, and helics::ValueFederate.

References coreObject, currentMode, HELICS_FLAG_OBSERVER, INITIALIZING, and observerMode.

Referenced by helics::ValueFederate::setFlagOption().

◆ setGlobal()

void helics::Federate::setGlobal ( std::string_view  valueName,
std::string_view  value 
)

set a federation global value

this overwrites any previous value for this name

Parameters
valueNamethe name of the global to set
valuethe value of the global

References coreObject.

◆ setLoggingCallback()

void helics::Federate::setLoggingCallback ( const std::function< void(int, std::string_view, std::string_view)> &  logFunction)

define a logging function to use for logging message and notices from the federation and individual federate

Parameters
logFunctionthe callback function for doing something with a log message it takes 3 inputs an integer for logLevel /ref helics_log_level A string indicating the source of the message and another string with the actual message

References coreObject.

◆ setModeUpdateCallback()

void helics::Federate::setModeUpdateCallback ( std::function< void(Modes, Modes)>  callback)

register a callback function to call when the federate mode is changed from one state to another

this callback is executed before other callbacks updating values and times, no values will have been updated when this callback is executed. It will execute before timeUpdateCallback in situations where both would be called.

Parameters
callbackthe function to call; the function signature is void(Modes, Modes) the first argument is the new Mode and the second is the old Mode

References currentMode, PENDING_EXEC, PENDING_FINALIZE, PENDING_INIT, PENDING_ITERATIVE_TIME, and PENDING_TIME.

◆ setProperty() [1/3]

void helics::Federate::setProperty ( int32_t  option,
double  timeValue 
)

set a time property for a federate

Parameters
optionthe option to set
timeValuethe value to be set

References coreObject.

◆ setProperty() [2/3]

void helics::Federate::setProperty ( int32_t  option,
int32_t  optionValue 
)

set an integer option for the federate

Parameters
optionan index of the option to set
optionValuean integer option value for an integer based property

References coreObject.

◆ setProperty() [3/3]

void helics::Federate::setProperty ( int32_t  option,
Time  timeValue 
)

set a time option for the federate

Parameters
optionthe option to set
timeValuethe value to be set

References coreObject.

◆ setQueryCallback()

void helics::Federate::setQueryCallback ( const std::function< std::string(std::string_view)> &  queryFunction)

supply a query callback function

the intention of the query callback is to allow federates to answer particular requests through the query interface this allows other federates to make requests or queries of other federates in an asynchronous fashion.

Parameters
queryFunctiona function object that returns a string as a result of a query in the form of const string ref. This callback will be called when a federate received a query that cannot be answered internally that is directed at that particular federate

References coreObject.

◆ setSeparator()

void helics::Federate::setSeparator ( char  separator)
inline

specify a separator to use for naming separation between the federate name and the interface name setSeparator('.') will result in future registrations of local endpoints such as fedName.endpoint setSeparator('/') will result in fedName/endpoint the default is '/' any character can be used though many will not make that much sense. This call is not thread safe and should be called before any local interfaces are created otherwise it may not be possible to retrieve them without using the full name. recommended possibilities are ('.','/', ':','-','_')

◆ setTag()

void helics::Federate::setTag ( std::string_view  tag,
std::string_view  value 
)

set a tag (key-value pair) for a federate

the tag is an arbitrary user defined string and value; the tags for a federate are queryable through a "tags" query or "tag/<tagname>"

Parameters
tagthe name of the tag to set the value for
valuethe value for the given tag

References coreObject.

◆ setTimeRequestEntryCallback()

void helics::Federate::setTimeRequestEntryCallback ( std::function< void(Time, Time, bool)>  callback)

register a callback function to call when a timeRequest function is called

this callback is executed prior to any blocking operation on any valid timeRequest method it will execute in the calling thread

Parameters
callbackthe function to call; the function signature is void(Time, Time, bool) where the first Time value is the current time and the second is the requested time. The boolean is set to true if the request is possibly iterating

References currentMode, PENDING_ITERATIVE_TIME, and PENDING_TIME.

◆ setTimeRequestReturnCallback()

void helics::Federate::setTimeRequestReturnCallback ( std::function< void(Time, bool)>  callback)

register a callback function to call when a timeRequest function returns

this callback is executed after all other callbacks and is the last thing executed before returning

Parameters
callbackthe function to call; the function signature is void(Time, bool) where the Time value is the new time and the boolean is set to true if the request is an iteration

References currentMode, PENDING_ITERATIVE_TIME, and PENDING_TIME.

◆ setTimeUpdateCallback()

void helics::Federate::setTimeUpdateCallback ( std::function< void(Time, bool)>  callback)

register a callback function to call when the time gets updated and before other value callbacks are executed

this callback is executed before other callbacks updating values, no values will have been updated when this callback is executed it is intended purely for updating time before value callbacks are executed.

Parameters
callbackthe function to call; the function signature is void(Time, bool) where the Time value is the new time and bool is true if this is an iteration

References currentMode, PENDING_ITERATIVE_TIME, and PENDING_TIME.

◆ setTranslatorOperator()

void helics::Federate::setTranslatorOperator ( const Translator trans,
std::shared_ptr< TranslatorOperator op 
)

register an operator for the specified translator

The TranslatorOperator gets called when there is a message or value to translate, there is no order or state to this as messages can come in any order.

Parameters
transthe translator object to set the operation on
opa shared_ptr to a TranslatorOperator

◆ startupToInitializeStateTransition()

void helics::Federate::startupToInitializeStateTransition ( )
protectedvirtual

function to deal with any operations that need to occur on the transition from startup to initialize

Reimplemented in helics::ValueFederate, helics::MessageFederate, and helics::CombinationFederate.

Referenced by enterExecutingModeAsync(), enterInitializingMode(), and enterInitializingModeComplete().

◆ updateTime()

void helics::Federate::updateTime ( Time  newTime,
Time  oldTime 
)
protectedvirtual

function to deal with any operations that need to occur on a time update

Reimplemented in helics::ValueFederate, helics::MessageFederate, and helics::CombinationFederate.

◆ waitCommand()

std::pair< std::string, std::string > helics::Federate::waitCommand ( )

get a command for the Federate, if there is none the call will block until a command is received

Returns
a pair of strings <command,source> with the command instructions for the federate

References coreObject.

Member Data Documentation

◆ observerMode

bool helics::Federate::observerMode {false}
protected

set to true for observer mode, no outgoing synchronized communications

Referenced by enterExecutingMode(), enterExecutingModeComplete(), Federate(), and setFlagOption().

◆ strictConfigChecking

bool helics::Federate::strictConfigChecking {true}
protected

set to false to allow some invalid configurations to be ignored instead of error

Referenced by Federate().

◆ useJsonSerialization

bool helics::Federate::useJsonSerialization {false}
protected

set to true to force all outgoing data to json serialization

Referenced by Federate(), getFlagOption(), helics::ValueFederate::setFlagOption(), and helics::ValueFederate::ValueFederate().


The documentation for this class was generated from the following files: