helics  2.5.2
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,
  modes::error = 4, modes::pending_init = 5, modes::pending_exec = 6, modes::pending_time = 7,
  modes::pending_iterative_time, modes::pending_finalize = 9
}
 

Public Member Functions

 Federate (const std::string &fedname, const FederateInfo &fi)
 
 Federate (const std::string &fedname, const std::shared_ptr< Core > &core, const FederateInfo &fi=FederateInfo{})
 
 Federate (const std::string &fedname, CoreApp &core, const FederateInfo &fi=FederateInfo{})
 
 Federate (const std::string &configString)
 
 Federate (const std::string &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 ()
 
iteration_result enterExecutingMode (iteration_request iterate=iteration_request::no_iterations)
 
void enterExecutingModeAsync (iteration_request iterate=iteration_request::no_iterations)
 
iteration_result enterExecutingModeComplete ()
 
void finalize ()
 
void finalizeAsync ()
 
void finalizeComplete ()
 
virtual void disconnect ()
 
void error (int errorcode)
 
void error (int errorcode, const std::string &message)
 
void localError (int errorcode, const std::string &message)
 
void globalError (int errorcode, const std::string &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, iteration_request iterate)
 
void requestTimeAsync (Time nextInternalTimeStep)
 
void requestTimeIterativeAsync (Time nextInternalTimeStep, iteration_request iterate)
 
Time requestTimeComplete ()
 
iteration_time requestTimeIterativeComplete ()
 
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, const std::string &, const std::string &)> &logFunction)
 
std::string query (const std::string &target, const std::string &queryStr)
 
std::string query (const std::string &queryStr)
 
query_id_t queryAsync (const std::string &target, const std::string &queryStr)
 
query_id_t queryAsync (const std::string &queryStr)
 
std::string queryComplete (query_id_t queryIndex)
 
bool isQueryCompleted (query_id_t queryIndex) const
 
void setGlobal (const std::string &valueName, const std::string &value)
 
void addDependency (const std::string &fedName)
 
FilterregisterGlobalFilter (const std::string &filterName, const std::string &inputType=std::string(), const std::string &outputType=std::string())
 
CloningFilterregisterGlobalCloningFilter (const std::string &filterName, const std::string &inputType=std::string(), const std::string &outputType=std::string())
 
FilterregisterFilter (const std::string &filterName, const std::string &inputType=std::string(), const std::string &outputType=std::string())
 
CloningFilterregisterCloningFilter (const std::string &filterName, const std::string &inputType=std::string(), const std::string &outputType=std::string())
 
FilterregisterFilter ()
 
CloningFilterregisterCloningFilter ()
 
void addSourceTarget (const Filter &filt, const std::string &targetEndpoint)
 
void addDestinationTarget (const Filter &filt, const std::string &targetEndpoint)
 
const std::string & getInterfaceName (interface_handle handle) const
 
const FiltergetFilter (const std::string &filterName) const
 
const FiltergetFilter (int index) const
 
FiltergetFilter (const std::string &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
 
virtual void registerInterfaces (const std::string &configString)
 
void registerFilterInterfaces (const std::string &configString)
 
void closeInterface (interface_handle handle)
 
auto getID () const noexcept
 
modes getCurrentMode () const
 
Time getCurrentTime () const
 
const std::string & getName () const
 
const std::shared_ptr< Core > & getCorePointer ()
 
int filterCount () const
 
void setInfo (interface_handle handle, const std::string &info)
 
const std::string & getInfo (interface_handle handle)
 
void setInterfaceOption (interface_handle handle, int32_t option, int32_t option_value=1)
 
int32_t getInterfaceOption (interface_handle handle, int32_t option)
 
const std::string & getInjectionType (interface_handle handle) const
 
const std::string & getExtractionType (interface_handle handle) const
 
const std::string & getInjectionUnits (interface_handle handle) const
 
const std::string & getExtractionUnits (interface_handle handle) const
 
const std::string & getInterfaceUnits (interface_handle handle) const
 
void logMessage (int level, const std::string &message) const
 
void logErrorMessage (const std::string &message) const
 
void logWarningMessage (const std::string &message) const
 
void logInfoMessage (const std::string &message) const
 
void logDebugMessage (const std::string &message) const
 
void completeOperation ()
 

Protected Member Functions

virtual void updateTime (Time newTime, Time oldTime)
 
virtual void startupToInitializeStateTransition ()
 
virtual void initializeToExecuteStateTransition ()
 
virtual std::string localQuery (const std::string &queryStr) const
 

Protected Attributes

std::atomic< modescurrentMode {modes::startup}
 the current state of the simulation
 
char nameSegmentSeparator = '/'
 the separator between automatically prependend names
 
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 

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

Constructor & Destructor Documentation

◆ Federate() [1/8]

helics::Federate::Federate ( const std::string &  fedname,
const FederateInfo fi 
)

constructor taking a federate information structure

Parameters
fednamethe name of the federate can be empty to use a name from the federateInfo
fia federate information structure

make sure the core is connected

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

◆ Federate() [2/8]

helics::Federate::Federate ( const std::string &  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(), nameSegmentSeparator, and helics::FederateInfo::separator.

◆ Federate() [3/8]

helics::Federate::Federate ( const std::string &  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 ( const std::string &  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 coreObject, currentMode, currentTime, and nameSegmentSeparator.

◆ Federate() [8/8]

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

deleted copy constructor

◆ ~Federate()

helics::Federate::~Federate ( )
virtual

virtual destructor function

References coreObject, and finalize().

Member Function Documentation

◆ addDependency()

void helics::Federate::addDependency ( const std::string &  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.

◆ addDestinationTarget()

void helics::Federate::addDestinationTarget ( const Filter filt,
const std::string &  targetEndpoint 
)

add a destination target to a filter

Parameters
filta filter object
targetEndpointthe name of the endpoint to filter the data going to

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

◆ addSourceTarget()

void helics::Federate::addSourceTarget ( const Filter filt,
const std::string &  targetEndpoint 
)

add a source target to a filter

Parameters
filtthe filter object to add a source endpoint to
targetEndpointthe name of the endpoint to filter the data from

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

◆ closeInterface()

void helics::Federate::closeInterface ( interface_handle  handle)

disconnect an interface from its targets and remove it from consideration

References coreObject.

Referenced by helics::Input::close().

◆ 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, and finalize().

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

◆ enterExecutingMode()

iteration_result helics::Federate::enterExecutingMode ( iteration_request  iterate = iteration_request::no_iterations)

◆ enterExecutingModeAsync()

void helics::Federate::enterExecutingModeAsync ( iteration_request  iterate = iteration_request::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()

iteration_result 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 currentMode, currentTime, enterExecutingMode(), error, helics::error, executing, finalize, getCurrentTime(), helics::halted, initializeToExecuteStateTransition(), initializing, helics::iterating, helics::next_step, pending_exec, helics::timeZero, and updateTime().

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, 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, initializing, pending_init, startup, and startupToInitializeStateTransition().

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

◆ error() [1/2]

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

specify the simulator had an unrecoverable error

Parameters
errorcodean integral code for the error
Deprecated:
please use localError instead

References localError().

◆ error() [2/2]

void helics::Federate::error ( int  errorcode,
const std::string &  message 
)

specify the simulator had an error with error code and message

Parameters
errorcodean integral code for the error
messagea string describing the error to display in a log
Deprecated:
please use localError instead

References localError().

◆ filterCount()

int helics::Federate::filterCount ( ) const

get a count of the number of filter objects stored in the federate

◆ 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, executing, finalize, finalizeComplete(), 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, 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, and pending_finalize.

Referenced by completeOperation(), and finalize().

◆ 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::CloningFilter::CloningFilter(), helics::Filter::Filter(), and helics::make_cloning_filter().

◆ getCurrentMode()

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

get the current state of the federate

◆ getCurrentTime()

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

get the current Time

the most recent granted time of the federate

Referenced by enterExecutingMode(), and enterExecutingModeComplete().

◆ getExtractionType()

const std::string & helics::Federate::getExtractionType ( interface_handle  handle) const

get the extraction type for an interface, this is the type for data coming out of interface

for filters this is the output type, for publications this is the specified type, for endpoints this is the specified type and for inputs this is the specified type

Parameters
handlethe interface handle to get the injection type for
Returns
a const ref to std::string

References coreObject.

Referenced by helics::Input::getType().

◆ getExtractionUnits()

const std::string & helics::Federate::getExtractionUnits ( interface_handle  handle) const

get the extraction type for an interface, this is the units associated with data coming out of an interface

for publications this is the specified units, for inputs this is the specified type

Parameters
handlethe interface handle to get the injection type for
Returns
a const ref to std::string

References coreObject.

Referenced by helics::Input::getUnits().

◆ getFilter() [1/4]

const Filter & helics::Federate::getFilter ( const std::string &  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 getName(), helics::Filter::isValid(), and nameSegmentSeparator.

◆ 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 ( const std::string &  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 getName(), helics::Filter::isValid(), and nameSegmentSeparator.

◆ getFilter() [4/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

◆ 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.

◆ getID()

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

◆ getInfo()

std::string const & helics::Federate::getInfo ( interface_handle  handle)

get the data currently stored for a particular interface handle

Parameters
handlethe handle to get the information for
Returns
a string with the data for the information

References coreObject.

Referenced by helics::Input::getInfo().

◆ getInjectionType()

const std::string & helics::Federate::getInjectionType ( interface_handle  handle) const

get the injection type for an interface, this is the type for data coming into an interface

for filters this is the input type, for publications this is type used to transmit data, for endpoints this is the specified type and for inputs this is the type of the transmitting publication

Parameters
handlethe interface handle to get the injection type for
Returns
a const ref to std::string

References coreObject.

Referenced by helics::Input::getPublicationType().

◆ getInjectionUnits()

const std::string & helics::Federate::getInjectionUnits ( interface_handle  handle) const

get the injection units for an interface, this is the units associated with data coming into an interface

for inputs this is the input type, for publications this is the units used to transmit data, and for inputs this is the units of the transmitting publication

Parameters
handlethe interface handle to get the injection units for
Returns
a const ref to std::string

References coreObject.

Referenced by helics::Input::getInjectionUnits().

◆ 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.

◆ getInterfaceName()

const std::string & helics::Federate::getInterfaceName ( interface_handle  handle) const

get the name/key associated with an interface

Parameters
handlethe interface handle to query
Returns
empty string if an invalid id is passed otherwise the interface name or key (could be empty if the interface was nameless

References coreObject.

Referenced by helics::Input::getKey().

◆ getInterfaceOption()

int32_t helics::Federate::getInterfaceOption ( interface_handle  handle,
int32_t  option 
)

get the current value for an interface option

Parameters
handlethe handle of an interface to modify
optionthe option field to modify
Returns
the current value of the interface option will be 0 for false 1 for true for boolean options

get the current value for an interface option

References coreObject.

Referenced by helics::Input::getOption().

◆ getInterfaceUnits()

const std::string& helics::Federate::getInterfaceUnits ( interface_handle  handle) const
inline

get the units associated with an interface

this function will is identical to getExtractionUnits

Parameters
handlethe interface handle to get the extraction units for
Returns
a const ref to std::string containing the units

◆ getName()

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

◆ 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.

◆ globalError() [1/2]

void helics::Federate::globalError ( int  errorcode,
const std::string &  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, currentMode, and error.

Referenced by globalError().

◆ globalError() [2/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().

◆ initializeToExecuteStateTransition()

void helics::Federate::initializeToExecuteStateTransition ( )
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 aysnc operation is in flight

References currentMode, pending_exec, pending_finalize, pending_init, pending_iterative_time, and pending_time.

◆ isQueryCompleted()

bool helics::Federate::isQueryCompleted ( query_id_t  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,
const std::string &  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, currentMode, and error.

Referenced by error(), and localError().

◆ localError() [2/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().

◆ localQuery()

std::string helics::Federate::localQuery ( const std::string &  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 ( const std::string &  message) const
inline

log a debug message to the federate Logger

Parameters
messagethe message to log

References helics::cleanupHelicsLibrary(), and helics_log_level_data.

◆ logErrorMessage()

void helics::Federate::logErrorMessage ( const std::string &  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 ( const std::string &  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,
const std::string &  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 ( const std::string &  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= ( Federate &&  fed)
noexcept

◆ operator=() [2/2]

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

delete copy assignment

◆ query() [1/2]

std::string helics::Federate::query ( const std::string &  target,
const std::string &  queryStr 
)

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
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().

◆ query() [2/2]

std::string helics::Federate::query ( const std::string &  queryStr)

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
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().

◆ queryAsync() [1/2]

query_id_t helics::Federate::queryAsync ( const std::string &  target,
const std::string &  queryStr 
)

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
Returns
a query_id_t to use for returning the result

References coreObject.

◆ queryAsync() [2/2]

query_id_t helics::Federate::queryAsync ( const std::string &  queryStr)

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
Returns
a query_id_t used to get the results of the query in the future

References query().

◆ queryComplete()

std::string helics::Federate::queryComplete ( query_id_t  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::identifier_id_t< BaseType, ID, invalidValue >::value().

◆ registerCloningFilter() [1/2]

CloningFilter & helics::Federate::registerCloningFilter ( const std::string &  filterName,
const std::string &  inputType = std::string(),
const std::string &  outputType = std::string() 
)

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 getName(), and nameSegmentSeparator.

Referenced by helics::make_cloning_filter().

◆ registerCloningFilter() [2/2]

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

define a nameless cloning filter interface on a source

◆ registerFilter() [1/2]

Filter & helics::Federate::registerFilter ( const std::string &  filterName,
const std::string &  inputType = std::string(),
const std::string &  outputType = std::string() 
)

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 getName(), and nameSegmentSeparator.

◆ registerFilter() [2/2]

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

define a nameless filter interface

◆ registerFilterInterfaces()

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

register filter interfaces defined in 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 ( const std::string &  filterName,
const std::string &  inputType = std::string(),
const std::string &  outputType = std::string() 
)

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 ( const std::string &  filterName,
const std::string &  inputType = std::string(),
const std::string &  outputType = std::string() 
)

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

◆ 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().

◆ 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, executing, finalize, and updateTime().

◆ 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, executing, and pending_time.

◆ requestTimeComplete()

Time helics::Federate::requestTimeComplete ( )

request a time advancement

Returns
the granted time step

References currentMode, currentTime, executing, pending_time, and updateTime().

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

◆ requestTimeIterative()

iteration_time helics::Federate::requestTimeIterative ( Time  nextInternalTimeStep,
iteration_request  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 iteration_result

References coreObject, currentMode, currentTime, error, helics::error, executing, finalize, helics::halted, helics::iterating, helics::next_step, and updateTime().

◆ requestTimeIterativeAsync()

void helics::Federate::requestTimeIterativeAsync ( Time  nextInternalTimeStep,
iteration_request  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, executing, 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, error, helics::error, executing, finalize, helics::halted, helics::iterating, helics::next_step, pending_iterative_time, and updateTime().

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

◆ 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::Filter::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

References coreObject.

◆ setGlobal()

void helics::Federate::setGlobal ( const std::string &  valueName,
const std::string &  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.

◆ setInfo()

void helics::Federate::setInfo ( interface_handle  handle,
const std::string &  info 
)

set the information field for an interface

Parameters
handlethe interface handle for any interface, the interface handle can be created from any interface object automatically
infothe information to store

References coreObject.

Referenced by helics::Input::setInfo().

◆ setInterfaceOption()

void helics::Federate::setInterfaceOption ( interface_handle  handle,
int32_t  option,
int32_t  option_value = 1 
)

set an interface option

Parameters
handlethe handle of an interface to modify
optionthe option field to modify
option_valuethe value to set (defaults to 1 or true), most options are boolean but some allow for other values

References coreObject.

Referenced by helics::Input::setOption().

◆ setLoggingCallback()

void helics::Federate::setLoggingCallback ( const std::function< void(int, const std::string &, const std::string &)> &  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.

◆ setProperty() [1/3]

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

set a time option for the federate

Parameters
optionthe option to set
timeValuethe value to be set

References coreObject.

◆ setProperty() [2/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.

◆ setProperty() [3/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.

◆ 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 ('.','/', ':','-','_')

◆ 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

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