PERF/STYLE: Investigate code bloat from inline destructors vs. out-of-line definitions

[hjmjohnson]

Background

During review of PR #5995 (and related smart-pointer PRs #5994–#5997), N-Dekker raised two
concerns about moving class destructors from .cxx to inline = default in headers:

1. Code bloat — an inline destructor is emitted in every translation unit (TU) that
   destroys an instance; a non-inline definition is emitted once and shared via the DSO.
2. ABI break — for ITKFEM_EXPORT (and other ITK*_EXPORT) classes, moving the
   destructor from a non-inline exported symbol to an inline one is a binary-incompatible
   change for downstream shared-library consumers.

This issue records a plan to measure the magnitude of the effect and produce data to inform
a policy decision for the ITK codebase.

Research Questions

1. What is the measured difference in object-file and shared-library size when destructors
   are inline = default vs. defined in .cxx?
2. Does the effect vary by compiler (GCC, Clang, MSVC) or optimization level (-O0, -O2, -Os)?
3. Is the effect significant enough to warrant a blanket policy, or only for specific
   high-fan-out classes (e.g., image filters instantiated across many TUs)?
4. What ABI/symbol-visibility change does each approach produce (check with nm/objdump)?

Proposed Investigation Plan

Step 1 — Enumerate candidate destructors

# Find exported ITK classes that have an out-of-line destructor defined in a .cxx
grep -rn "^[A-Za-z:]*::~[A-Za-z]*()" Modules/*/src/ Modules/*/include/ \
  | grep "= default" | grep -v ThirdParty

Produce a representative sample of:

• Leaf classes (no subclasses) — destructor called in many TUs
• Abstract base classes — virtual destructor, called through pointer
• Template-explicit-instantiation classes — e.g., itkImage.hxx

Step 2 — Build baseline (all destructors in .cxx)

cmake -DITK_BUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_CXX_FLAGS="-Os" ..
ninja ITKCommon ITKFEM ITKIOImageBase
# Record: .so sizes, nm --defined-only -S output for each DSO
du -sh lib/libITKCommon*.so lib/libITKFEM*.so lib/libITKIOImageBase*.so
nm --defined-only -S lib/libITKCommon*.so | grep " T " | wc -l

Step 3 — Apply patch (move destructors to inline = default)

Write a script that:

1. Detects ClassName::~ClassName() = default; in .cxx files
2. Moves them to = default on the declaration in the .h file
3. Removes the .cxx entry

# Suggested script location
Utilities/Scripts/move_destructors_to_header.py

Rebuild with identical flags and record the same metrics.

Step 4 — Measure per-TU object file size

For a high-fan-out class (e.g., itk::DataObject), compare:

# Count how many TUs emit the destructor symbol
nm --defined-only build/CMakeFiles/**/*.o | grep "DataObject::~DataObject" | wc -l
# Compare total size of all .o files before and after
find build/CMakeFiles -name "*.o" | xargs du -c | tail -1

Step 5 — Measure link-time and startup overhead

time ninja ITKCommon   # full rebuild link time
ldd --verbose lib/libITKCommon*.so | grep "lazy"   # optional: startup cost

Step 6 — Check ABI / symbol visibility

# Before (out-of-line):
nm -D lib/libITKCommon*.so | grep "~DataObject"
# Expected: T (strong global text symbol)

# After (inline = default):
nm -D lib/libITKCommon*.so | grep "~DataObject"
# Expected: W (weak symbol) or absent

Document whether moving to inline changes from T → W and whether this is
an ABI concern for ITK's versioned shared libraries.

Step 7 — Compiler matrix

Repeat Steps 2–6 with:

Compiler	Version	Flags
GCC	12	-O2 -Os
Clang	16	-O2 -Os
MSVC	2022	/O2 /Os

Step 8 — Summarize and propose policy

Based on measurements, recommend one of:

• A: Keep all destructors out-of-line in .cxx (minimize bloat, preserve ABI stability)
• B: Allow inline = default only for non-exported helper/internal classes
• C: Allow inline = default everywhere — bloat is negligible at ITK's scale
• D: Adopt a per-class decision based on fan-out heuristic

Acceptance Criteria

• Numerical binary-size data for at least 3 ITK modules under GCC and Clang
• Symbol-visibility comparison (nm output) before/after for at least one exported class
• Recommendation with justification posted as a comment on this issue
• Update Documentation/AI/compiler-cautions.md (section 1b) with the adopted policy

References

• PR COMP: Use std::unique_ptr in FEMLinearSystemWrapperDenseVNL #5995 (N-Dekker review comment): COMP: Use std::unique_ptr in FEMLinearSystemWrapperDenseVNL #5995 (comment)
• Scott Meyers, Effective Modern C++, Item 22
• Itanium C++ ABI — Vague Linkage (weak symbols for inline functions)
• GCC documentation on -fvisibility and inline destructors

🤖 Generated with Claude Code (claude-sonnet-4-6)

[hjmjohnson]

Experimental Results

Measurements performed on macOS ARM64 (Apple M-series), compiler: Apple Clang 17 (arm64-apple-darwin), build type: RelWithDebInfo (-O2 -g), BUILD_SHARED_LIBS=OFF.

---

Setup

ITK builds 164 out-of-line = default destructor definitions across its modules (excluding ThirdParty). This experiment targeted two categories:

Category A — Abstract class, destructor is sole out-of-line virtual function:
itk::fem::Solution — one pure virtual method (GetSolutionValue = 0), destructor is the only non-pure virtual. Fan-out: 6 direct includers.

Category B — Concrete class, destructor is sole out-of-line virtual function:
itk::HexahedronCellTopology (and 4 sibling topology classes) — destructor is the only virtual function, but an out-of-line constructor (= default in .cxx) also exists. Fan-out: 3 direct includers each.

---

Experiment: Move destructor to inline = default

For each class: add = default to the header declaration; remove the definition from the .cxx (leave other .cxx content intact). Rebuild with ninja. Measure with size and nm.

---

Results

Category A: itk::fem::Solution (abstract)

Metric	Before	After	Delta
libITKFEM-6.0.a TEXT	387,677 B	387,669 B	−8 B
libITKFEM-6.0.a DATA	24,976 B	24,936 B	−40 B
Strong (T) destructor symbols	220	217	−3 (D0/D1/D2 removed)
Strong (S) vtable symbols	95	94	−1
Weak (W) vtable symbols	0	0	0
Weak (W) destructor symbols	0	0	0

The vtable for Solution disappeared entirely. With no non-pure, non-inline virtual function to serve as a key function, and no concrete TU directly instantiating Solution, Clang dropped the vtable. Typeinfo (__ZTI) and type-name string (__ZTS) survived (in the subclass TU that also defines LinearSystemWrapper, which inherits from Solution).

Conclusion for abstract classes: inline = default is strictly smaller — no duplication occurs.

---

Category B: itk::HexahedronCellTopology (concrete, out-of-line constructor)

Metric	Before	After	Delta
itkHexahedronCellTopology.cxx.o TEXT	271 B	275 B	+4 B
itkHexahedronCellTopology.cxx.o DATA	48 B	48 B	0 B
Vtable symbol	Strong S	Strong S	unchanged
D2Ev (base destructor)	Present (T)	Gone (inlined)	−4 B text
D1Ev (complete destructor)	Present (T)	Present (T)	unchanged
D0Ev (deleting destructor)	Present (T)	Present (T)	unchanged
Weak vtable symbols (whole archive)	0	0	0

The vtable did not become weak. It remained as a single strong S symbol anchored in the .cxx file — because the out-of-line constructor (HexahedronCellTopology::HexahedronCellTopology() = default in the .cxx) sets the vptr, which causes Clang to emit the vtable as a strong symbol in that TU regardless of the virtual function key-function rule.

The +4 B increase comes from the C1Ev (complete object constructor) body growing by one instruction, offsetting the removal of D2Ev.

Batch: all 5 topology classes (concrete, out-of-line constructors)

Class	TEXT before	TEXT after	Delta
HexahedronCellTopology	271	275	+4
QuadraticTriangleCellTopology	122	126	+4
QuadrilateralCellTopology	114	118	+4
TetrahedronCellTopology	176	180	+4
TriangleCellTopology	101	105	+4

Archive metric	Before	After	Delta
libITKCommon-6.0.a TEXT	608,271 B	608,291 B	+20 B
Strong vtables	159	159	0
Strong destructors	421	416	−5
Weak vtables	0	0	0
Weak destructors	0	0	0

Consistent +4 bytes per class, zero vtable duplication, zero weak symbol proliferation.

---

Key Findings

1. No vtable code bloat from inline = default destructors, provided the class has an out-of-line constructor definition in a .cxx file. The constructor's body sets the vptr, which causes Clang to anchor the vtable as a strong symbol in that TU — the vtable key-function rule is moot when the constructor is out-of-line.

2. Abstract classes benefit from inline destructors. When the destructor was the sole non-pure virtual, moving it inline eliminates the vtable and destructor stubs entirely (the abstract class is never directly instantiated, so no TU needs these symbols). Archive size decreases.

3. Concrete classes: net +4 bytes TEXT per class (one extra ARM64 instruction in the complete-object constructor). This is entirely negligible at ITK's scale — for 164 candidate sites: worst-case +656 bytes of total TEXT growth across all ITK modules.

4. ABI concern is real but narrow. Moving D2Ev (base object destructor) from a strong T symbol to inline eliminates it from the archive. Any pre-compiled object code that took the address of ~ClassName (e.g., for function pointer tables or runtime introspection) would break. In practice, ITK classes are not used this way. D1Ev and D0Ev (the virtual dispatch targets in the vtable) remain as strong symbols, so virtual destruction continues to work correctly.

5. -fvisibility-inlines-hidden (which ITK builds with) hides inline function symbols from the link interface. Combined with the out-of-line constructor anchoring the vtable, there is no dynamic linking concern for the static-library build.

Action Items

• Measure binary size difference (static archives)
• Measure symbol-visibility change (nm before/after)
• Confirm vtable anchoring behavior with out-of-line constructor
• Test abstract class case separately

---

Measurements performed by Claude Code (claude-sonnet-4-6) on 2026-04-01.

[hjmjohnson]

Follow-up: Does a Shared Library Build Change the Answers?

Yes, significantly. A minimal shared library compiled with ITK's exact flags (-fvisibility-inlines-hidden -O2 -fPIC -std=c++17) reveals that moving a destructor to inline = default hides the vtable, typeinfo, and destructor thunks from the DSO's exported symbol table — even when the class itself is declared __attribute__((visibility(\"default\"))).

---

Experiment

Five class patterns were compiled as a shared library (.dylib) with ITK's flags. Each class has __attribute__((visibility(\"default\"))) on the class declaration (matching ITKFEM_EXPORT / ITKCommon_EXPORT).

Symbol type	Meaning
T / S	Exported — visible to DSO consumers
t / s	Hidden — local to the DSO, invisible to consumers

Results

Pattern	Description	D1Ev	D0Ev	vtable	typeinfo
A — Abstract, inline = default dtor	virtual ~Foo() = default;	gone	gone	gone	gone
B — Abstract, out-of-line dtor	virtual ~Foo(); in .cxx	T ✓	T ✓	S ✓	S ✓
C — Concrete, inline dtor + out-of-line ctor	~Foo() = default; in header	t ✗	t ✗	s ✗	s ✗
D — Concrete, out-of-line dtor + out-of-line ctor	~Foo(); in .cxx	T ✓	T ✓	S ✓	S ✓
E — Concrete, both ctor and dtor inline	both = default in header	gone	gone	gone	gone

Pattern C is the ITK case from PR #5995: exported class, out-of-line constructor (still in .cxx), destructor moved to inline = default.

Consequences for Shared Library Consumers

When the vtable, typeinfo, and destructor thunks are hidden (t/s):

1. dynamic_cast<Base*>(derived) across DSO boundaries fails. The typeinfo object used for RTTI comparison is hidden inside the producing DSO — consumers cannot find it. dynamic_cast returns nullptr instead of a valid pointer.

2. typeid(obj) == typeid(other) across DSO boundaries fails. For the same reason — two different DSOs each see a hidden (DSO-local) typeinfo pointer, which compares unequal even for the same type.

3. Virtual destruction from outside the DSO can fail. If a consumer DSO deletes a pointer-to-base, the virtual dispatch through D0Ev / D1Ev requires those symbols to be exported. Hidden thunks cannot be found across the DSO boundary.

4. Subclasses in other DSOs cannot properly inherit. A subclass in DSO B that inherits from a class in DSO A needs access to DSO A's vtable. If the base vtable is hidden, the subclass vtable construction is broken.

These failures are silent at link time — the shared library compiles and links without errors. The breakage only manifests at runtime.

Why This Happens

-fvisibility-inlines-hidden (which ITK builds with globally) gives hidden visibility to all inline function definitions. When ~Foo() = default; is in the header, it becomes an inline function. The -fvisibility-inlines-hidden flag then overrides the __attribute__((visibility(\"default\"))) on the class declaration for that specific inline member. The vtable, which contains function pointers to the now-hidden destructor thunks, also becomes hidden.

The out-of-line constructor (Foo::Foo() = default; in the .cxx) anchors the vtable in that TU — confirmed by the static lib experiments. But with shared libs, anchoring the vtable is not enough: the vtable also needs default visibility to be exported. Since its destructor entries point to hidden symbols, the vtable itself is emitted with hidden visibility.

Revised Conclusions

The static-library conclusions from the previous comment remain valid for BUILD_SHARED_LIBS=OFF (no code bloat, vtable anchored by constructor). However:

Scenario	Static lib (BUILD_SHARED_LIBS=OFF)	Shared lib (BUILD_SHARED_LIBS=ON)
Abstract class, inline dtor	✅ Smaller (vtable/RTTI gone)	✅ Safe (abstract — never directly destructed cross-DSO)
Concrete, inline dtor, out-of-line ctor	✅ +4 B, vtable stays strong	❌ vtable/typeinfo/D1/D0 become HIDDEN
Concrete, out-of-line dtor, out-of-line ctor	✅ Baseline	✅ Baseline — all symbols exported

Revised Recommendation: Option A for exported classes

Keep destructors out-of-line in .cxx for any class declared with ITK*_EXPORT.

Moving the destructor to inline = default is safe only for:

1. Abstract classes — never directly instantiated cross-DSO; RTTI comparison for abstract base pointers still works via the concrete subclass typeinfo.
2. Non-exported (internal) classes — those not tagged with ITK*_EXPORT and not used across DSO boundaries.

For exported concrete classes, the -fvisibility-inlines-hidden flag combined with an inline destructor silently produces a DSO with hidden vtable/typeinfo — a runtime correctness bug for shared-library builds.

This makes N-Dekker's ABI concern more serious than the static-lib measurement suggested. The concern is not theoretical code bloat but a concrete runtime failure mode when BUILD_SHARED_LIBS=ON.

---

Action Items (updated)

• Measure binary size difference (static archives)
• Measure symbol-visibility change with nm (static archives)
• Confirm vtable anchoring behavior (static archives)
• Test abstract class case
• Test shared library symbol visibility — confirms vtable/typeinfo hidden for inline dtors on exported classes
• Update Documentation/AI/compiler-cautions.md (section 1b) with the adopted policy (Option A: keep destructors out-of-line for ITK*_EXPORT classes) — done in PR DOC: Add compiler-cautions.md — compiler-specific pitfalls from 10 years of COMP: commits #5999
• Fix all actionable concrete non-template exported classes — 30 classes fixed in PR COMP: Move inline = default destructors to .cxx for 30 exported classes #6002 (initial audit over-counted to 56 by including 26 template classes that cannot be fixed this way)

---

Shared library experiment performed by Claude Code (claude-sonnet-4-6) on 2026-04-01.

[hjmjohnson]

Full Codebase Audit: Exported Classes With Inline = default Destructors

Methodology

Searched all non-ThirdParty Modules/ headers for:

1. ~ClassName() override = default; defined inline in the class body
2. Class declared with any *_EXPORT macro
3. A corresponding .cxx file exists (non-template classes only)

Classified each match as abstract (has = 0 pure virtual methods) or concrete.

---

Summary

Category	Count	Action
Inline = default destructors in exported headers (initial scan)	75	—
Template classes (incorrectly included in initial scan)	26	⚠️ Cannot be fixed by moving to .cxx without explicit instantiation
Abstract classes (has pure virtual methods)	19	✅ Safe as-is
Concrete exported non-template classes	30	✅ Fixed in PR #6002

Note: The initial audit claimed 56 concrete classes. When the mechanical fix was applied and the build attempted, 26 of those turned out to be template classes (ITK_TEMPLATE_EXPORT or declared with template <). Template class destructors cannot be defined in a .cxx without full explicit-instantiation boilerplate. Those 26 were reverted; the remaining 30 true non-template concrete classes were fixed.

---

Severity Assessment

All 30 concrete classes use itkOverrideGetNameOfClassMacro, which provides an out-of-line GetNameOfClass() override — this serves as the vtable key function. Therefore:

Symbol	With inline = default dtor	With out-of-line dtor
vtable	S exported ✓	S exported ✓
typeinfo	S exported ✓	S exported ✓
D2Ev (base dtor body)	gone (inlined)	T exported
D1Ev (complete dtor)	t hidden ✗	T exported ✓
D0Ev (deleting dtor)	t hidden ✗	T exported ✓

The vtable and typeinfo remain exported, so dynamic_cast and normal virtual destruction via pointer continue to work. However, D1Ev and D0Ev are hidden symbols, which is an ABI break:

• Any pre-compiled binary (.so, .o, Python extension) that was linked against a version of ITK where these symbols were exported will fail to load against a version where they are hidden.
• Explicit destructor calls (obj.~ClassName()) from outside the DSO also require visible D1Ev.

This is precisely the concern N-Dekker raised in PR #5995.

---

The 30 Concrete Classes Fixed in PR #6002

Click to expand full list

Module	Header	Line
Core/Common	itkEquivalencyTable.h	175
Core/Common	itkLoggerManager.h	104
Core/Common	itkLoggerOutput.h	112
IO/ImageBase	itkArchetypeSeriesFileNames.h	111
IO/ImageBase	itkNumericSeriesFileNames.h	105
IO/ImageBase	itkRegularExpressionSeriesFileNames.h	122
Numerics/FEM	itkFEMLightObject.h	78
Numerics/Optimizers	itkExhaustiveOptimizer.h	139
Numerics/Optimizers	itkGradientDescentOptimizer.h	173
Numerics/Optimizers	itkInitializationBiasedParticleSwarmOptimizer.h	116
Numerics/Optimizers	itkMultipleValuedNonLinearOptimizer.h	75
Numerics/Optimizers	itkOnePlusOneEvolutionaryOptimizer.h	196
Numerics/Optimizers	itkOptimizer.h	97
Numerics/Optimizers	itkQuaternionRigidTransformGradientDescentOptimizer.h	79
Numerics/Optimizers	itkRegularStepGradientDescentBaseOptimizer.h	150
Numerics/Optimizers	itkRegularStepGradientDescentOptimizer.h	56
Numerics/Optimizers	itkSingleValuedNonLinearOptimizer.h	81
Numerics/Optimizers	itkSPSAOptimizer.h	262
Numerics/Optimizers	itkVersorTransformOptimizer.h	79
Numerics/Statistics	itkChiSquareDistribution.h	229
Numerics/Statistics	itkDenseFrequencyContainer2.h	113
Numerics/Statistics	itkGaussianDistribution.h	264
Numerics/Statistics	itkMaximumDecisionRule.h	70
Numerics/Statistics	itkMaximumRatioDecisionRule.h	107
Numerics/Statistics	itkMinimumDecisionRule.h	67
Numerics/Statistics	itkSparseFrequencyContainer2.h	107
Numerics/Statistics	itkTDistribution.h	229
Segmentation/Watersheds	itkOneWayEquivalencyTable.h	162
Segmentation/Watersheds	itkWatershedMiniPipelineProgressCommand.h	80
Video/Core	itkTemporalProcessObject.h	156

---

The 26 Template Classes Excluded (Cannot Be Fixed Mechanically)

These were in the initial scan but use ITK_TEMPLATE_EXPORT or template <> — their destructors cannot be defined in a plain .cxx file without explicit instantiation for every type. A separate effort would be needed to address these.

Click to expand list

Module	Header
Core/Common	itkExtractImageFilter.h
Core/Common	itkFrustumSpatialFunction.h
Core/Mesh	itkTriangleMeshCurvatureCalculator.h
Core/QuadEdgeMesh	itkQuadEdgeMeshEulerOperatorFlipEdgeFunction.h
Core/SpatialObjects	itkContourSpatialObject.h
Core/TestKernel	itkTestingExtractSliceImageFilter.h
Filtering/Colormap	itkScalarToRGBColormapImageFilter.h
Filtering/Convolution	itkConvolutionImageFilterBase.h
Filtering/DiffusionTensorImage	itkDiffusionTensor3DReconstructionImageFilter.h
Filtering/FastMarching	itkFastMarchingReachedTargetNodesStoppingCriterion.h
Filtering/ImageFeature	itkMultiScaleHessianBasedMeasureImageFilter.h
Filtering/ImageIntensity	itkSymmetricEigenAnalysisImageFilter.h
Filtering/LabelMap	itkMergeLabelMapFilter.h
Filtering/Path	itkOrthogonallyCorrected2DParametricPath.h
Filtering/QuadEdgeMeshFiltering	itkBorderQuadEdgeMeshFilter.h
Filtering/QuadEdgeMeshFiltering	itkLaplacianDeformationQuadEdgeMeshFilter.h
Filtering/QuadEdgeMeshFiltering	itkNormalQuadEdgeMeshFilter.h
Filtering/Smoothing	itkFFTDiscreteGaussianImageFilter.h
Filtering/Smoothing	itkRecursiveGaussianImageFilter.h
IO/ImageBase	itkImageFileWriter.h
IO/ImageBase	itkImageSeriesWriter.h
IO/SpatialObjects	itkPolygonGroupSpatialObjectXMLFile.h
Numerics/Statistics	itkExpectationMaximizationMixtureModelEstimator.h
Numerics/Statistics	itkHistogramToRunLengthFeaturesFilter.h
Numerics/Statistics	itkHistogramToTextureFeaturesFilter.h
Segmentation/RegionGrowing	itkConnectedThresholdImageFilter.h

---

The 19 Safe Abstract Classes (No Action Required)

itkVTKImageExportBase.h, itkCommand.h, itkCreateObjectFunction.h, itkMetaDataObject.h, itkSmapsFileParser.h, itkTransformBase.h, itkFastMarchingBase.h, itkFastMarchingImageFilter.h, itkFastMarchingUpwindGradientImageFilter.h, itkMeshIOBase.h, itkXMLFile.h, itkPolygonGroupSpatialObjectXMLFile.h (reader base), itkCSVFileReaderBase.h, itkObjectToObjectMetricBase.h, itkRegistrationParameterScalesEstimator.h, itkPatchBasedDenoisingBaseImageFilter.h, itkESMDemonsRegistrationFunction.h, itkImageRegistrationMethodv4.h, itkMRFImageFilter.h, itkDTITubeSpatialObjectPoint.h

---

Fix Pattern

For each of the 30 classes, the change is mechanical:

Header:

// FROM:
~ClassName() override = default;
// TO:
~ClassName() override;

.cxx file (at the top of the namespace, near other = default definitions):

// Destructor out-of-line: keeps D1Ev/D0Ev exported in shared library builds.
// Inline = default would hide them under -fvisibility-inlines-hidden.
// See: https://github.com/InsightSoftwareConsortium/ITK/issues/6000
ClassName::~ClassName() = default;

---

Scope Clarification

This audit covers only non-template exported classes with existing .cxx files. Template classes require explicit instantiations to move code to .cxx and are a separate, more complex case. The initial scan over-counted by including 26 template classes — the true actionable count is 30 concrete non-template classes, addressed in PR #6002.

---

Audit performed by Claude Code (claude-sonnet-4-6) on 2026-04-01. Corrected 2026-04-01 after PR #6002 build revealed 26 template class false-positives.

[hjmjohnson]

Resolved by PR #6002 (merged 2026-04-02), which moved inline = default destructors out-of-line for 30 exported concrete non-template classes. The full codebase audit is documented in the comments above.