The convention by which a shared library publishes a HydroCouple component, and the ABI stamp that makes loading it safe. More...
#include "hydrocouple.h"Go to the source code of this file.
Macros | |
| #define | HYDROCOUPLE_COMPONENT_EXPORT __attribute__((visibility("default"))) |
| #define | HYDROCOUPLE_ABI_STRINGIFY_(x) |
| #define | HYDROCOUPLE_ABI_STRINGIFY(x) |
| #define | HYDROCOUPLE_COMPONENT_ABI_REVISION "2" |
| Revision of this loading convention itself (not of the interfaces). | |
| #define | HYDROCOUPLE_COMPONENT_IFACE_VERSION_NUMBER 5 |
| Interface ABI this convention targets, as a number the preprocessor can stringify into the stamp. | |
| #define | HYDROCOUPLE_COMPONENT_IFACE_VERSION HYDROCOUPLE_ABI_STRINGIFY(HYDROCOUPLE_COMPONENT_IFACE_VERSION_NUMBER) |
| #define | HYDROCOUPLE_ABI_COMPILER "unknown" |
| #define | HYDROCOUPLE_ABI_STDLIB "unknown" |
| #define | HYDROCOUPLE_ABI_CRT "" |
| #define | HYDROCOUPLE_COMPONENT_ABI_STAMP |
| The toolchain fingerprint both sides must agree on. | |
| #define | HYDROCOUPLE_COMPONENT_ABI_SYMBOL "hydrocouple_component_abi_v1" |
| #define | HYDROCOUPLE_COMPONENT_INFO_SYMBOL "hydrocouple_component_info_v1" |
| #define | HYDROCOUPLE_COMPONENT_LEGACY_INFO_SYMBOL "CreateComponentInfo" |
| The pre-existing, unstamped factory symbol. | |
| #define | HYDROCOUPLE_COMPONENT_UNSTAMPED "unstamped(legacy CreateComponentInfo)" |
| Reported as the stamp of a library that carries no stamp of its own. | |
| #define | HYDROCOUPLE_DECLARE_COMPONENT(InfoType) |
| Emits both entry points for a component library. | |
Typedefs | |
| typedef const char *(* | HydroCoupleComponentAbiFn) (void) |
| Signature of the ABI stamp entry point. Safe to call across a mismatch. | |
| typedef HydroCouple::IComponentInfo *(* | HydroCoupleComponentInfoFn) (void) |
| Signature of the component-info entry point. Only safe once the stamp matches. | |
| typedef HydroCouple::IModelComponentInfo *(* | HydroCoupleLegacyComponentInfoFn) (void) |
| Signature of the legacy factory, which returns the narrower model-info type. | |
The convention by which a shared library publishes a HydroCouple component, and the ABI stamp that makes loading it safe.
HydroCouple v2 components are plain C++ objects — there is no QObject and therefore no Qt plugin system to lean on, and the SDK deliberately ships no loader (ModelInitializer takes a caller-supplied resolver). A host that wants to load components from disk must define the contract itself; this header is that contract, kept free of Qt and of Composer types.
include/plugins/componentabi.h (openswmm program plan §B.2.1, phase D0), so every host and every component — Composer, the openswmm engine, SWMMVis, third-party libraries — includes ONE copy of the contract from the interface package instead of carrying its own. Before this there were three: Composer's, one under hydrocouplesdk/, and none here.It was meant to move unchanged, and did, except for one line that could not: HYDROCOUPLE_COMPONENT_IFACE_VERSION was hardcoded to "2" while the interfaces had moved to ABI 3 (releaseState) and then 4 (the contract-consistency round). Every component built against ABI 3 or 4 with the old header stamped itself iface=2, so a host would have accepted an ABI-2 component beside an ABI-4 one — the stamp's one job, defeated. The iface number is now a macro the stamp can stringify AND a static_assert against HydroCouple::HYDROCOUPLE_ABI_VERSION, so bumping the interface ABI without bumping this line is a compile error in every includer.
A component library exports exactly two C functions:
const char *hydrocouple_component_abi_v1(void); HydroCouple::IComponentInfo *hydrocouple_component_info_v1(void);
HYDROCOUPLE_DECLARE_COMPONENT(InfoType) emits both.
hydrocouple_component_abi_v1 is pure C returning a string, which is safe to call across any mismatch; the host compares it against its own HYDROCOUPLE_COMPONENT_ABI_STAMP and refuses the library on disagreement. The stamp is therefore the only symbol that may be called before the check succeeds.IComponentInfo returned by hydrocouple_component_info_v1 is owned by the library (a function-local static) and must not be deleted by the host; it stays valid until the library is unloaded. Component instances created through IModelComponentInfo::createComponentInstance() are owned by the host, and — as a direct consequence — must be destroyed before the library that allocated them is unloaded. | #define HYDROCOUPLE_ABI_COMPILER "unknown" |
| #define HYDROCOUPLE_ABI_CRT "" |
| #define HYDROCOUPLE_ABI_STDLIB "unknown" |
| #define HYDROCOUPLE_ABI_STRINGIFY | ( | x | ) |
| #define HYDROCOUPLE_ABI_STRINGIFY_ | ( | x | ) |
| #define HYDROCOUPLE_COMPONENT_ABI_REVISION "2" |
Revision of this loading convention itself (not of the interfaces).
2 (ABI 5): the stamp names the standard library's ABI variant and, on Windows, the C runtime and iterator-debug level; MSVC is named by its binary-compatible toolset family instead of its exact version; the pointer width no longer depends on a GCC/Clang-only macro and is labelled ptr (it is a size in bytes, which the old bits label misstated).
| #define HYDROCOUPLE_COMPONENT_ABI_STAMP |
The toolchain fingerprint both sides must agree on.
Deliberately coarse: compiler family (and major version for GCC and Clang), standard library and its ABI-affecting settings, the C runtime on Windows, pointer width, and the interface ABI. Finer granularity would reject libraries that are in fact compatible; coarser would admit ones that are not. The iface field is second and followed by ;, so tools may locate it.
| #define HYDROCOUPLE_COMPONENT_ABI_SYMBOL "hydrocouple_component_abi_v1" |
| #define HYDROCOUPLE_COMPONENT_EXPORT __attribute__((visibility("default"))) |
| #define HYDROCOUPLE_COMPONENT_IFACE_VERSION HYDROCOUPLE_ABI_STRINGIFY(HYDROCOUPLE_COMPONENT_IFACE_VERSION_NUMBER) |
| #define HYDROCOUPLE_COMPONENT_IFACE_VERSION_NUMBER 5 |
Interface ABI this convention targets, as a number the preprocessor can stringify into the stamp.
A macro because the stamp is a string literal assembled by the preprocessor, which cannot read HydroCouple::HYDROCOUPLE_ABI_VERSION (a constexpr int). Not read from version.h either: that header exports only generically-named macros (PROJECT_VERSION_MAJOR) any other project may also define. The duplication this forces is closed by the static_assert below.
| #define HYDROCOUPLE_COMPONENT_INFO_SYMBOL "hydrocouple_component_info_v1" |
| #define HYDROCOUPLE_COMPONENT_LEGACY_INFO_SYMBOL "CreateComponentInfo" |
The pre-existing, unstamped factory symbol.
HydroCouple's Python bindings (hydrocouple.loader.load) already load components through an extern "C" factory named CreateComponentInfo returning IModelComponentInfo *, with no ABI stamp. Components written against that convention predate this header, and refusing them would split the component ecosystem in two — Python-loadable versus Composer-loadable.
Composer therefore accepts both: the stamped entry points when present, and this legacy factory otherwise. Legacy libraries are loaded on a best-effort basis and reported as unstamped, because there is genuinely no way to verify their toolchain before calling into them.
| #define HYDROCOUPLE_COMPONENT_UNSTAMPED "unstamped(legacy CreateComponentInfo)" |
Reported as the stamp of a library that carries no stamp of its own.
| #define HYDROCOUPLE_DECLARE_COMPONENT | ( | InfoType | ) |
Emits both entry points for a component library.
| InfoType | A default-constructible HydroCouple::IComponentInfo subclass. |
Place once in exactly one translation unit of the component library:
| typedef const char *(* HydroCoupleComponentAbiFn) (void) |
Signature of the ABI stamp entry point. Safe to call across a mismatch.
| typedef HydroCouple::IComponentInfo *(* HydroCoupleComponentInfoFn) (void) |
Signature of the component-info entry point. Only safe once the stamp matches.
| typedef HydroCouple::IModelComponentInfo *(* HydroCoupleLegacyComponentInfoFn) (void) |
Signature of the legacy factory, which returns the narrower model-info type.