Loading...
Searching...
No Matches
hydrocouplecomponentabi.h File Reference

The convention by which a shared library publishes a HydroCouple component, and the ABI stamp that makes loading it safe. More...

#include "hydrocouple.h"
Include dependency graph for hydrocouplecomponentabi.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.
 

Detailed Description

The convention by which a shared library publishes a HydroCouple component, and the ABI stamp that makes loading it safe.

Author
Caleb Buahin

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.

Provenance
Upstreamed 2026-09-30 from HydroCoupleComposer's 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.

Why an ABI stamp
Passing C++ objects across a shared-library boundary is only defined when both sides were built with the same toolchain and standard library. There is no portable way to recover from a mismatch once a mismatched C++ function has been called, so the mismatch has to be detected before that happens. 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.
Ownership
The 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.

Macro Definition Documentation

◆ HYDROCOUPLE_ABI_COMPILER

#define HYDROCOUPLE_ABI_COMPILER   "unknown"

◆ HYDROCOUPLE_ABI_CRT

#define HYDROCOUPLE_ABI_CRT   ""

◆ HYDROCOUPLE_ABI_STDLIB

#define HYDROCOUPLE_ABI_STDLIB   "unknown"

◆ HYDROCOUPLE_ABI_STRINGIFY

#define HYDROCOUPLE_ABI_STRINGIFY ( x)
Value:
#define HYDROCOUPLE_ABI_STRINGIFY_(x)
Definition hydrocouplecomponentabi.h:71

◆ HYDROCOUPLE_ABI_STRINGIFY_

#define HYDROCOUPLE_ABI_STRINGIFY_ ( x)
Value:
#x

◆ HYDROCOUPLE_COMPONENT_ABI_REVISION

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

◆ HYDROCOUPLE_COMPONENT_ABI_STAMP

#define HYDROCOUPLE_COMPONENT_ABI_STAMP
Value:
";stdlib=" HYDROCOUPLE_ABI_STDLIB \
HYDROCOUPLE_ABI_CRT \
";ptr=" HYDROCOUPLE_ABI_POINTER_BYTES
#define HYDROCOUPLE_COMPONENT_ABI_REVISION
Revision of this loading convention itself (not of the interfaces).
Definition hydrocouplecomponentabi.h:80
#define HYDROCOUPLE_ABI_COMPILER
Definition hydrocouplecomponentabi.h:120
#define HYDROCOUPLE_COMPONENT_IFACE_VERSION
Definition hydrocouplecomponentabi.h:93

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.

◆ HYDROCOUPLE_COMPONENT_ABI_SYMBOL

#define HYDROCOUPLE_COMPONENT_ABI_SYMBOL   "hydrocouple_component_abi_v1"

◆ HYDROCOUPLE_COMPONENT_EXPORT

#define HYDROCOUPLE_COMPONENT_EXPORT   __attribute__((visibility("default")))

◆ HYDROCOUPLE_COMPONENT_IFACE_VERSION

#define HYDROCOUPLE_COMPONENT_IFACE_VERSION    HYDROCOUPLE_ABI_STRINGIFY(HYDROCOUPLE_COMPONENT_IFACE_VERSION_NUMBER)

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

◆ HYDROCOUPLE_COMPONENT_INFO_SYMBOL

#define HYDROCOUPLE_COMPONENT_INFO_SYMBOL   "hydrocouple_component_info_v1"

◆ HYDROCOUPLE_COMPONENT_LEGACY_INFO_SYMBOL

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

◆ HYDROCOUPLE_COMPONENT_UNSTAMPED

#define HYDROCOUPLE_COMPONENT_UNSTAMPED   "unstamped(legacy CreateComponentInfo)"

Reported as the stamp of a library that carries no stamp of its own.

◆ HYDROCOUPLE_DECLARE_COMPONENT

#define HYDROCOUPLE_DECLARE_COMPONENT ( InfoType)
Value:
extern "C" HYDROCOUPLE_COMPONENT_EXPORT const char * \
hydrocouple_component_abi_v1(void) \
{ \
} \
\
hydrocouple_component_info_v1(void) \
{ \
static InfoType s_info; \
return &s_info; \
}
IComponentInfo interface class is a factory that provides detailed metadata about a component and cre...
Definition hydrocouple.h:505
#define HYDROCOUPLE_COMPONENT_EXPORT
Definition hydrocouplecomponentabi.h:67
#define HYDROCOUPLE_COMPONENT_ABI_STAMP
The toolchain fingerprint both sides must agree on.
Definition hydrocouplecomponentabi.h:185

Emits both entry points for a component library.

Parameters
InfoTypeA default-constructible HydroCouple::IComponentInfo subclass.

Place once in exactly one translation unit of the component library:

HYDROCOUPLE_DECLARE_COMPONENT(MyModelComponentInfo)
#define HYDROCOUPLE_DECLARE_COMPONENT(InfoType)
Emits both entry points for a component library.
Definition hydrocouplecomponentabi.h:237

Typedef Documentation

◆ HydroCoupleComponentAbiFn

typedef const char *(* HydroCoupleComponentAbiFn) (void)

Signature of the ABI stamp entry point. Safe to call across a mismatch.

◆ HydroCoupleComponentInfoFn

typedef HydroCouple::IComponentInfo *(* HydroCoupleComponentInfoFn) (void)

Signature of the component-info entry point. Only safe once the stamp matches.

◆ HydroCoupleLegacyComponentInfoFn

typedef HydroCouple::IModelComponentInfo *(* HydroCoupleLegacyComponentInfoFn) (void)

Signature of the legacy factory, which returns the narrower model-info type.