IModelComponent interface is the core interface in the HydroCouple standard defining a model component. More...
#include <hydrocouple.h>
Public Types | |
| enum class | ComponentStatus : uint8_t { Created = 0 , Initializing = 1 , Initialized = 2 , Validating = 3 , Valid = 4 , WaitingForData = 5 , Invalid = 6 , Preparing = 7 , Updating = 8 , Updated = 9 , Checkpointing = 10 , Done = 11 , Finishing = 12 , Finished = 13 , Failed = 14 } |
| HydroCouple::ComponentStatus is an enumerator that describes the status of a component over the course of its lifetime. More... | |
Public Member Functions | |
| virtual | ~IModelComponent ()=default |
| IModelComponent::~IModelComponent destructor. | |
| virtual IModelComponentInfo * | componentInfo () const =0 |
| Contains the metadata about this IModelComponent instance. | |
| virtual ComponentStatus | status () const =0 |
| Defines current status of the IModelComponent. | |
| virtual std::vector< IArgument * > | arguments () const =0 |
| Arguments needed to let the component do its work. | |
| virtual std::vector< IInput * > | inputs () const =0 |
| The list of consumer items for which a component can receive values. | |
| virtual std::vector< IOutput * > | outputs () const =0 |
| The list of IOutputs for which a component can produce results. | |
| virtual std::vector< IComponentDataItem * > | results () const =0 |
| List of the model's output results. | |
| virtual std::vector< IComponentDataItem * > | states () const =0 |
| The data items that make up the state carried from one update() to the next. | |
| virtual void | initialize ()=0 |
| Initializes the current IModelComponent. | |
| virtual std::vector< std::string > | validate ()=0 |
| Validates the populated instance of the IModelComponent. | |
| virtual void | prepare ()=0 |
| Prepares the IModelComponent for calls to the update() method. | |
| virtual void | update (const std::vector< IOutput * > &requiredOutputs={})=0 |
| This method is called to let the component update itself, thus reaching its next state. | |
| virtual void | finish ()=0 |
| finish() must be invoked as the last of any methods in the IModelComponent interface. | |
| virtual const IWorkflowComponent * | workflow () const =0 |
| Gets the workflow that this component is part of. | |
| virtual void | setWorkflow (const IWorkflowComponent *workflow)=0 |
| Sets the workflow that this component is part of. | |
| virtual std::set< Capability > | capabilities () const =0 |
| The set of optional capabilities this component supports. | |
| virtual std::vector< ErrorEntry > | errors (bool clearAfterRead=false)=0 |
| Drains this component's diagnostic queue. | |
| virtual std::string | referenceDirectory () const =0 |
| Gets the reference directory for this component instance. | |
| virtual void | setReferenceDirectory (const std::string &referenceDirectory)=0 |
| setReferenceDirectory Sets the reference directory for this component instance. | |
Public Member Functions inherited from HydroCouple::IIdentity | |
| virtual | ~IIdentity ()=default |
| IIdentity::~IIdentity is a virtual destructor. | |
| virtual const std::string & | id () const =0 |
| Gets a unique identifier for the entity. | |
Public Member Functions inherited from HydroCouple::IDescription | |
| virtual | ~IDescription ()=default |
| IDescription::~IDescription is a virtual destructor. | |
| virtual const std::string & | caption () const =0 |
| Gets caption for the entity. | |
| virtual void | setCaption (const std::string &caption)=0 |
| Sets caption for the entity. | |
| virtual const std::string & | description () const =0 |
| Gets additional descriptive information for the entity. | |
| virtual void | setDescription (const std::string &description)=0 |
| Gets additional descriptive information for the entity. | |
Public Member Functions inherited from HydroCouple::IPropertyChanged | |
| virtual | ~IPropertyChanged ()=default |
| IPropertyChanged::~IPropertyChanged is a virtual destructor. | |
Public Member Functions inherited from HydroCouple::ISignal< std::string > | |
| virtual | ~ISignal ()=default |
| ISignal::~ISignal is a virtual destructor. | |
| virtual void | connect (const std::shared_ptr< ISlot< Args... > > &slot)=0 |
| connect is used to connect a slot to the signal. | |
| virtual void | disconnect (const std::shared_ptr< ISlot< Args... > > &slot)=0 |
| disconnect is used to disconnect a slot from the signal. | |
| virtual void | blockSignals (bool block)=0 |
| blockSignals is used to block signals from being emitted. | |
Public Member Functions inherited from HydroCouple::ISignal< const std::shared_ptr< IComponentStatusChangeEventArgs > & > | |
| virtual | ~ISignal ()=default |
| ISignal::~ISignal is a virtual destructor. | |
| virtual void | connect (const std::shared_ptr< ISlot< Args... > > &slot)=0 |
| connect is used to connect a slot to the signal. | |
| virtual void | disconnect (const std::shared_ptr< ISlot< Args... > > &slot)=0 |
| disconnect is used to disconnect a slot from the signal. | |
| virtual void | blockSignals (bool block)=0 |
| blockSignals is used to block signals from being emitted. | |
Additional Inherited Members | |
Protected Member Functions inherited from HydroCouple::ISignal< std::string > | |
| virtual void | emit (Args... args)=0 |
| emit is used to emit the signal. | |
Protected Member Functions inherited from HydroCouple::ISignal< const std::shared_ptr< IComponentStatusChangeEventArgs > & > | |
| virtual void | emit (Args... args)=0 |
| emit is used to emit the signal. | |
IModelComponent interface is the core interface in the HydroCouple standard defining a model component.
|
strong |
HydroCouple::ComponentStatus is an enumerator that describes the status of a component over the course of its lifetime.
The values are pinned: proxies carry them across processes and the language bindings mirror them, so a value never changes meaning and new statuses are appended.
| Enumerator | |
|---|---|
| Created | The IModelComponent instance has just been created. This status must and will be followed by HydroCouple::Initializing. |
| Initializing | The IModelComponent is initializing itself. This status will end in a status change to HydroCouple::Initialized or HydroCouple::Failed. |
| Initialized | The IModelComponent has successfully initialized itself by calling IModelComponent::initialize(). The connections between its inputs/outputs and those of other components can be established. |
| Validating | After links between an IModelComponent's inputs/outputs and those of other components have been established, the IModelComponent is HydroCouple::Validating whether its required input will be available when it updates itself, and whether indeed it will be able to provide the required output during this update. This Validating status will when the IModelComponent::status() changes to HydroCouple::Valid or HydroCouple::Invalid. |
| Valid | The IModelComponent is in a HydroCouple::Valid state. When updating itself its required input will be available, and it will be able to provide the required output. |
| WaitingForData | The IModelComponent wants to update itself, but is not yet able to perform the actual computation, because it is still waiting for input data from other components. |
| Invalid | The IModelComponent is in an HydroCouple::Invalid state. When updating itself not all required input will be available, and/or it will not be able to provide the required output. After the user has modified the connections between the IModelComponent's inputs/outputs and those of other components, the HydroCouple::Validating state can be entered again |
| Preparing | The IModelComponent is preparing itself for the first update() and the first IComponentDataItem::getValuesInto() call. This HydroCouple::Preparing state will end in a status change to HydroCouple::Updated or HydroCouple::Failed. |
| Updating | The IModelComponent is updating itself. It has received all required input data from other components, and is now performing the actual computation. This HydroCouple::Updating state will end in a status change to HydroCouple::Updated, HydroCouple::Done or HydroCouple::Failed. |
| Updated | The IModelComponent has successfully updated itself. |
| Checkpointing | The IModelComponent is saving or restoring a checkpoint of its state (see ICheckpointableModelComponent). A save returns to the status it was entered from (HydroCouple::Updated or HydroCouple::Done); a successful restore always lands in HydroCouple::Updated; a failure lands in HydroCouple::Failed. |
| Done | The last update process that the IModelComponent performed was the final one. A next call to the IModelComponent::update() method will leave the IModelComponent's internal state unchanged. |
| Finishing | The IModelComponent was requested to perform the actions to be performed before it will either be disposed or re-initialized again.Typical actions would be writing the final result files, close all open files, free memory, etc. When all required actions have been performed, the status switches to HydroCouple::Created when re-initialization is possible. The status switches to HydroCouple::Finished when the IModelComponent is to be disposed |
| Finished | The IModelComponent has successfully performed its finalization actions. Re-initialization of the IModelComponent instance is not possible and should not be attempted. Instead the instance should be destroyed by its owner, after its connections are dismantled (see the lifetime convention). What a component releases in this state is its computational resources — solver state, threads, scratch memory. Its data items may remain readable: a component backed by previously recorded results is Finished from the moment it is initialized, and exists precisely so its results() and outputs() can be read afterwards for analysis and visualization. Consumers must therefore not assume that Finished implies unreadable values; a component that genuinely cannot serve values after finalization should say so through its data items. |
| Failed | The IModelComponent has encountered an unrecoverable error. Reachable from every status except Finished: a failure can be detected while the component rests (a proxy whose peer dies while it is Updated). Diagnostics describing the failure must be available from IModelComponent::errors(). From this state the component may be re-initialized by calling initialize() if it supports re-initialization, or finished and disposed via finish(). |
|
virtualdefault |
|
nodiscardpure virtual |
Arguments needed to let the component do its work.
An unmodifiable list of (modifiable) arguments must be returned that is to be used to get information about the arguments and to set argument values.
Validation of changes can be done either when they occur (e.g., using notifications) or when the initialize method is called. Initialize will always be called before any call to the update method of the IModelComponent.
This property must be available as soon is the IModelComponent instance is created Arguments describes the arguments that can be set before the initialize() method is called.
|
nodiscardpure virtual |
The set of optional capabilities this component supports.
This is the discovery mechanism for every optional interface in the standard (see Capability): an orchestrator consults the set and then dynamic_casts only to what is advertised. A component must list every capability it or its data items implement. Components with no optional capabilities return an empty set. Available in every status, including Created.
|
nodiscardpure virtual |
Contains the metadata about this IModelComponent instance.
|
nodiscardpure virtual |
Drains this component's diagnostic queue.
The error queue is the normative failure channel (see the error-channel convention): implementations must queue an ErrorEntry for every Warning-or-worse condition, must queue a Severity::Fatal entry whenever status() transitions to HydroCouple::Failed, must queue every message validate() returns, and must queue a Severity::Error entry whenever a bool-returning method returns false. Exceptions may additionally be thrown locally but do not replace the queue, because they cannot cross process, C-ABI, or language boundaries. Available in every status, including Created.
| [in] | clearAfterRead | indicates whether the queue is cleared after being read. |
|
pure virtual |
finish() must be invoked as the last of any methods in the IModelComponent interface.
Legal from HydroCouple::Initialized, HydroCouple::Valid, HydroCouple::Invalid, HydroCouple::Updated, HydroCouple::Done and HydroCouple::Failed, so that a composition can be torn down cleanly from any resting state — including one that never validated or was abandoned before prepare(). A component that has nothing to release in the earlier states simply transitions.
Immediately after the method is invoked, it changes the IModelComponent's status() to HydroCouple::Finishing. Once finishing is complete, the status becomes HydroCouple::Finished if the component cannot be restarted, or HydroCouple::Created if it can.
|
pure virtual |
Initializes the current IModelComponent.
The initialize() method must be invoked before any other method or property in the IModelComponent interface is invoked or accessed, except for arguments(), status(), capabilities(), errors() and componentInfo().
Immediately after the method is invoked, it changes the IModelComponent's status to HydroCouple::Initializing. On success the status becomes HydroCouple::Initialized and id(), caption(), description(), inputs(), outputs() and states() are populated. On failure the status becomes HydroCouple::Failed and a Severity::Fatal entry is queued (see the error-channel convention); an exception may additionally be thrown.
Legal from HydroCouple::Created, HydroCouple::Failed and HydroCouple::Initialized (re-initialization).
|
nodiscardpure virtual |
The list of consumer items for which a component can receive values.
Available from the moment initialize() succeeds: orchestrators wire connections between Initialized and Validating, and providers read their consumers' inputs during every update(). Accessing the list before initialize() is an error (see the error-channel convention). The set of inputs is fixed after initialize(); their values change.
|
nodiscardpure virtual |
The list of IOutputs for which a component can produce results.
Available from the moment initialize() succeeds, under the same rules as inputs().
The list only contains the core IOutput items of the IModelComponent, not the IAdaptedOutput items derived from each IOutput. To get a complete list of outputs, traverse the chain of IAdaptedOutput items that start with the IOutput items returned in the list.
|
pure virtual |
Prepares the IModelComponent for calls to the update() method.
Before prepare() is called, the IModelComponent is not required to honor any request that retrieves values from it. After prepare() has succeeded it must be ready to provide values, and any device-resident buffers it exports must keep a stable address until finish().
Legal from HydroCouple::Valid only. Immediately after the method is invoked the status becomes HydroCouple::Preparing; on success it becomes HydroCouple::Updated (meaning "ready to update, nothing computed yet" — there is no separate Prepared status), on failure HydroCouple::Failed with a queued Severity::Fatal entry.
prepare() is invoked at most once per initialize()/finish() cycle.
|
nodiscardpure virtual |
Gets the reference directory for this component instance.
All relative file paths specified that are associated with this component instance are referenced from this directory. Typically, this will be the directory for the project file for the current composition. Values are typically set from the Composition GUI and can be referenced internally for saving files and writing arguments for the component.
|
nodiscardpure virtual |
List of the model's output results.
|
pure virtual |
setReferenceDirectory Sets the reference directory for this component instance.
| [in] | referenceDirectory | path to the reference directory. |
|
pure virtual |
Sets the workflow that this component is part of.
| [in] | workflow | is the workflow that this component is part of. |
|
nodiscardpure virtual |
The data items that make up the state carried from one update() to the next.
The prognostic variables — what a checkpoint must capture, what a data-assimilation driver perturbs, what an ensemble generator copies, and what IDifferentiableModelComponent::differentiableStates() is a subset of. Diagnostic quantities that update() recomputes from scratch are not state and belong in results() or outputs(). A component whose update() does not depend on its past returns an empty vector. Items may appear here and in outputs() at once.
Available under the same rules as inputs(): from initialize(); non-owning observers valid until the component is destroyed or re-initialized.
|
nodiscardpure virtual |
Defines current status of the IModelComponent.
See IModelComponent::ComponentStatus for the possible values.
The first status that a component sets is ComponentStatus::Created, as soon after it has been created. In this status, arguments() is the only property that may be accessed.
Thread-safety: safe to call from any thread at any time; implementations keep the status atomic. A proxy for a remote component updates it from the peer's notifications on whatever thread services the transport.
|
pure virtual |
This method is called to let the component update itself, thus reaching its next state.
Legal from HydroCouple::Updated and HydroCouple::WaitingForData (the retry after a provider has caught up). Immediately after this method is invoked, it changes the component's status() to HydroCouple::Updating.
The type of actions a component takes during update() depends on the type of component. A numerical model that progresses in time will typically compute a time step. A database would typically look at the consumers of its output items, and perform one or more queries to be able to provide the values that the consumers require. A GIS system would typically re-evaluate the values in a grid coverage, so that its output items can provide up-to-date values.
On success the component sets its status to HydroCouple::Updated, or to HydroCouple::Done when this update was the final one. A component that cannot proceed because a provider has not yet produced the values it needs may set HydroCouple::WaitingForData and return; the orchestrator is then responsible for updating the provider and calling update() again. An orchestrator that finds every component of a cycle WaitingForData must declare the composition deadlocked and fail it — no component retries on its own. On failure the status becomes HydroCouple::Failed with a queued Severity::Fatal entry; an exception may additionally be thrown.
| [in] | requiredOutputs | is an optional parameter lets the caller specify the specific producer items that should be updated. If the length is 0, the component will at least update its producer items that have consumers, or all its output items, depending on the component's implementation. |
|
nodiscardpure virtual |
Validates the populated instance of the IModelComponent.
Legal from HydroCouple::Initialized, HydroCouple::Valid and HydroCouple::Invalid — i.e. after initialize() and after the provider/consumer relations between this component's exchange items and those of other components in the composition have been established; it may be repeated after connections change.
Immediately after the method is invoked, it changes the IModelComponent's status to HydroCouple::Validating; when it has finished the status is either HydroCouple::Valid or HydroCouple::Invalid.
|
nodiscardpure virtual |
Gets the workflow that this component is part of.