Loading...
Searching...
No Matches
Normative conventions that apply to every interface

Ownership. A method that returns an existing object — an accessor, a lookup, a parent/child navigation — returns a non-owning raw pointer or reference that stays valid for the lifetime of the object it was obtained from (or until that object's documented invalidation event, e.g. "until the mesh topology changes"). A method that creates an object returns std::unique_ptr and the caller owns the result. No interface method returns a raw pointer the caller must delete. Containers of pointers (std::vector<IInput*>) are snapshots of non-owning observers.

Lifetime and teardown. The objects a component hands out — its exchange items, arguments, results, states and their metadata — stay valid until the component is destroyed or re-initialized (initialize() may rebuild them). finish() releases computational resources, not these objects (see ComponentStatus::Finished), so a finished component's items may still be read and unwired. A connection must never outlive either of its ends, so an orchestrator dismantles a composition in this order:

  1. destroy the adapted outputs it owns, the consumer end of each chain first; each deregisters itself from its adaptee (IOutput::addAdaptedOutput());
  2. call IOutput::removeConsumer() for every remaining connection;
  3. destroy the components (finish() them first, before or after steps 1–2);
  4. unload the libraries they came from (hydrocouplecomponentabi.h). Steps 1–2 also precede re-initializing a component that has connections. An implementation may tolerate other orders, but none may rely on another implementation doing so.

Error channel. The errors() diagnostic queue is the normative failure channel: it is the only one that crosses process, C-ABI and language boundaries. Every method that reports failure does so in one of two shapes, and both feed the queue:

  • lifecycle methods (initialize(), validate(), prepare(), update(), finish()) set status() to Failed, queue a Severity::Fatal entry, and may additionally throw locally; validate()'s returned messages are also queued (Error when the component is Invalid, Warning otherwise);
  • every bool + message method queues an Error entry whenever it returns false. A consumer that reads only the queue therefore misses nothing. The one object with no queue of its own is an adapted output (its factory may belong to no component): an adapter's bool + message methods report through the message alone, and the orchestrator calling them queues it where it belongs.

Toolchain. STL types (std::string, std::vector, std::set, std::shared_ptr, ...) cross the plugin boundary by value. A host and the components it loads must therefore be built with the same compiler, standard library and runtime: the interfaces themselves are a C++ ABI, not a C one. What the standard does define in C is the narrow door a library is loaded through — hydrocouplecomponentabi.h: two extern "C" entry points, the first of which returns a toolchain-and-interface stamp a host compares before calling anything that crosses a vtable. The stamp turns this paragraph's "must be built with the same toolchain" from a requirement a host trusts into one it checks, and is tied to HYDROCOUPLE_ABI_VERSION by a static_assert. Cross-process and cross-language use goes through a transport (hydrocoupledistributed.h) or the Python bridge, never through a foreign-toolchain vtable. The visibility pragma below is GCC/Clang only; MSVC compares RTTI by name and needs nothing.

Threading. status() on every component and workflow is safe to call from any thread at any time (implementations keep it atomic). All other thread-safety guarantees are stated on the interface that gives them.

Signals. Classes that inherit two ISignal<> instantiations (a component is both an IPropertyChanged and a status signal) bring both connect/disconnect/blockSignals overload sets into scope with using-declarations, so callers never need to qualify.