feat: surgical header pruning for lean hpx_main (Godbolt Integration) by shivansh023023 · Pull Request #7262 · TheHPXProject/hpx

shivansh023023 · 2026-05-12T10:33:04Z

Fixes

This PR addresses the "Entry-Point Tax" and modular ergonomics required for the "Zero-Config" architecture.

Proposed Changes

Surgical Header Pruning: Replaced "fat" umbrella headers—specifically runtime_local.hpp, resource_partitioner.hpp, and runtime_configuration.hpp—with targeted forward-declaration headers (_fwd.hpp).
Implementation Decoupling: Moved the dump_config implementation out of the header into libs/core/init_runtime_local/src/init_runtime_local.cpp, leaving only a lean HPX_CORE_EXPORT declaration.
Transitive Elimination: Removed approximately 54 transitive header inclusions from the hpx_main.hpp entry-point path.
Forward Declaration Gating: Manually added forward declarations for hpx::detail::on_exit() and hpx::detail::on_abort(int) to decouple the header from intermediate fat umbrellas.
Copyright Updates: Verified BSL-1.0 license headers and updated copyright years to 2026 where applicable.

Any background context you want to provide?

The goal of this refactor is to reduce the "Complexity Wall" that hinders library adoption in lightweight, browser-based environments like Compiler Explorer (Godbolt).

Currently, the standard entry point is architecturally coupled with the distributed runtime, pulling in the network stack, AGAS, and parcelports transitively.

By gating these transitives behind forward declarations, we ensure that local-only users no longer pay the "header tax" or "binary bloat" of the distributed runtime.

Quantitative Results

Metric	Master Baseline	Post-Surgery	Total Reduction
Pre-processed Line Count	400,950	323,276	77,674 lines (~19.4%)
Transitive Headers	Monolithic Umbrellas	Targeted Forward Decls	~54 Headers Removed

Checklist

Not all points below apply to all pull requests.

I have added a new feature and have added tests to go along with it.
I have fixed a bug and have added a regression test.
I have added a test using random numbers; I have made sure it uses a seed, and that random numbers generated are valid inputs for the tests.
#Before

#After

…px_init.hpp/hpx_init_params.hpp Phase 1 of GSoC Lean Entry header surgery. hpx_init.hpp: - Remove duplicate #include <hpx/modules/resource_partitioner.hpp> (already provided by hpx_init_params.hpp transitively) - Remove duplicate #include <hpx/modules/runtime_configuration.hpp> (already provided by hpx_init_params.hpp transitively) - Replace fat #include <hpx/modules/runtime_local.hpp> (40+ headers, pulls futures/io_service/threading_base/topology) with the lean #include <hpx/runtime_local/detail/runtime_local_fwd.hpp> (only hpx/config.hpp transitive cost) hpx_init_params.hpp: - Replace #include <hpx/modules/resource_partitioner.hpp> with #include <hpx/resource_partitioner/partitioner_fwd.hpp> (sufficient for partitioner_mode enum + partitioner& reference) - Replace #include <hpx/modules/runtime_configuration.hpp> with #include <hpx/runtime_configuration/runtime_configuration_fwd.hpp> (forward decl of hpx::util::runtime_configuration is sufficient here) - Replace #include <hpx/modules/runtime_local.hpp> with #include <hpx/runtime_local/detail/runtime_local_fwd.hpp> - Add #include <hpx/runtime_configuration/runtime_mode.hpp> to satisfy hpx::runtime_mode enum used in struct init_params Estimated reduction: ~25,000-32,000 pre-processed lines (28-38%) from the hpx/hpx_main.hpp include chain.

…local umbrella Replace fat #include <hpx/modules/init_runtime_local.hpp> umbrella with direct sub-headers: - hpx/init_runtime_local/init_runtime_local.hpp (provides app_name, default_desc, dummy_argc/argv used by hpx::init_params) - hpx/init_runtime_local/macros.hpp (provides HPX_APPLICATION_STRING, only pulls config.hpp + preprocessor.hpp) This bypasses the cmake-generated umbrella re-exporter while preserving all required symbols. The direct sub-header includes are alphabetized per HPX style conventions. Also update copyright year to 2026 (Hartmut Kaiser line).

…include Phase 1 GSoC Lean Entry header surgery. Replaced #include <hpx/modules/runtime_local.hpp> with forward declarations to hit the 30-40% line reduction target. - Replaced full runtime_local header with detail/runtime_local_fwd.hpp - Moved inline dump_config::operator()() out of the header and into init_runtime_local.cpp so it doesn't require the full hpx::runtime class - Manually forward-declared on_exit and on_abort in the header to break dependency on runtime_local_fwd.hpp - Added hpx/runtime_configuration/runtime_mode.hpp to satisfy hpx::runtime_mode usage

Remove fat umbrella headers from hpx_init_impl.hpp and hpx_start_impl.hpp that were redundant — all needed symbols already flow in transitively via the include chain we slimmed in previous commits. hpx_init_impl.hpp: - Remove #include <hpx/modules/init_runtime_local.hpp> (already via hpx_init.hpp -> hpx_init_params.hpp -> lean hpx/init_runtime_local/init_runtime_local.hpp) - Remove #include <hpx/modules/runtime_configuration.hpp> (AGAS/distributed factory registry — not used here; HPX_PREFIX comes from macros.hpp pulled by init_runtime_local) - Remove #include <hpx/modules/runtime_local.hpp> (init_helper + dummy_argc/argv already in init_runtime_local.hpp) hpx_start_impl.hpp: - Same three removals for identical reasons hpx_user_main_config.hpp: - Fix copyright year typo: 2055 -> 2025 - Confirmed lean: only config.hpp + <vector> + <string> (no transitives)

codacy-production · 2026-05-12T10:34:13Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

StellarBot · 2026-05-12T10:35:04Z

Can one of the admins verify this patch?

hkaiser · 2026-05-12T18:52:38Z

+#include <hpx/runtime_configuration/runtime_mode.hpp>
+#include <hpx/runtime_local/detail/runtime_local_fwd.hpp>
+#include <hpx/runtime_local/shutdown_function.hpp>
+#include <hpx/runtime_local/startup_function.hpp>


Please do not replace the modules headers with separate one from inside the HPX modules. This will break support for C++20 modules.

Address maintainer feedback (hkaiser): internal headers from inside the HPX modules must not be used directly as this breaks support for C++20 modules. Restore hpx/modules/ umbrella paths in all three files. init_runtime_local/init_runtime_local.hpp: - Restore #include <hpx/modules/resource_partitioner.hpp> (replaces internal hpx/resource_partitioner/partitioner_fwd.hpp) - Restore #include <hpx/modules/runtime_local.hpp> (replaces 4 internal paths: runtime_local_fwd, runtime_mode, shutdown_function, startup_function) hpx_init_params.hpp: - Restore #include <hpx/modules/init_runtime_local.hpp> - Restore #include <hpx/modules/resource_partitioner.hpp> - Restore #include <hpx/modules/runtime_configuration.hpp> - Restore #include <hpx/modules/runtime_local.hpp> (replaces internal hpx/init_runtime_local/* and hpx/runtime_*/* paths) hpx_init.hpp: - Restore #include <hpx/modules/runtime_local.hpp> (replaces internal hpx/runtime_local/detail/runtime_local_fwd.hpp) Preserved savings from Phase 1 that comply with C++20 module rules: - Removed true duplicates from hpx_init.hpp (resource_partitioner, runtime_configuration which were already in hpx_init_params.hpp) - Removed redundant umbrella copies from hpx_init_impl.hpp / hpx_start_impl.hpp - dump_config::operator()() moved out of header into .cpp (no header change) - Copyright typo fixed: 2055 -> 2025 in hpx_user_main_config.hpp - Copyright year updated: 2023 -> 2026 in hpx_init_params.hpp

Implement the 'Modular Forward Re-exporter' pattern to satisfy the C++20 module boundary requirement while preserving the lean entry-point surgery. Created 3 new modular re-exporter headers in hpx/modules/ paths: [NEW] hpx/modules/runtime_local_fwd.hpp - Re-exports: detail/runtime_local_fwd.hpp, shutdown_function.hpp, startup_function.hpp - Savings vs full umbrella: 38,604 preprocessed lines (23%) [NEW] hpx/modules/resource_partitioner_fwd.hpp - Re-exports: partitioner_fwd.hpp - Marginal savings (partitioner_fwd already pulls threading_base) [NEW] hpx/modules/runtime_configuration_fwd.hpp - Re-exports: runtime_configuration_fwd.hpp, runtime_mode.hpp - Savings vs full umbrella: 139,598 preprocessed lines (84%) Updated consumers to use modular paths (hpx/modules/*_fwd.hpp): - init_runtime_local/init_runtime_local.hpp - hpx_init_params.hpp - hpx_init.hpp All includes stay within hpx/modules/ for C++20 module compatibility per maintainer (hkaiser) feedback.

hkaiser · 2026-05-12T22:07:40Z

-#include <hpx/runtime_local/shutdown_function.hpp>
-#include <hpx/runtime_local/startup_function.hpp>
+#include <hpx/modules/resource_partitioner_fwd.hpp>
+#include <hpx/modules/runtime_local_fwd.hpp>


I apologize if I was inconsise. We can't #include anything but the top-level module header files, even indirectly. The changes you made will still break C++20 module compilation. See here for the current results: https://github.com/TheHPXProject/hpx/actions/runs/25761564888/job/75663773512?pr=7262.

Address maintainer directive: no including anything but top-level module header files, even indirectly. Sub-module headers and re-exporter headers both break C++20 module compilation due to symbol redefinition. The fix: manual forward declarations for all types that were previously obtained via sub-module includes. Deleted re-exporter files (created in previous attempt): - libs/core/runtime_local/include/hpx/modules/runtime_local_fwd.hpp - libs/core/resource_partitioner/include/hpx/modules/resource_partitioner_fwd.hpp - libs/core/runtime_configuration/include/hpx/modules/runtime_configuration_fwd.hpp init_runtime_local/init_runtime_local.hpp: - Removed: modules/resource_partitioner_fwd.hpp, modules/runtime_local_fwd.hpp - Added manual forward declarations: class runtime; using startup_function_type = hpx::move_only_function<void()>; using shutdown_function_type = hpx::move_only_function<void()>; enum class partitioner_mode : std::int8_t; class partitioner; - Moved partitioner_mode default initializer to constructor via static_cast<partitioner_mode>(0) to avoid needing the full enum hpx_init_params.hpp: - Removed: modules/resource_partitioner_fwd.hpp, modules/runtime_configuration_fwd.hpp, modules/runtime_local_fwd.hpp - Added manual forward declaration: enum class runtime_mode : std::int8_t; - Moved runtime_mode and partitioner_mode default initializers to constructor via static_cast (runtime_mode::default_ = 4, partitioner_mode::default_ = 0) - Kept only top-level module headers: modules/functional.hpp, modules/init_runtime_local.hpp, modules/program_options.hpp hpx_init.hpp: - Removed: modules/runtime_local_fwd.hpp (file deleted) All .cpp files retain full umbrella includes for complete definitions.

hkaiser · 2026-05-13T23:30:46Z

+// module boundary requirements.
+namespace hpx {
+
+    enum class runtime_mode : std::int8_t;


You may have to mark this as C++ module exported:

Suggested change

enum class runtime_mode : std::int8_t;

HPX_CXX_CORE_EXPORT enum class runtime_mode : std::int8_t;

hkaiser · 2026-05-13T23:31:52Z

    {
        init_params()
+          : mode(static_cast<hpx::runtime_mode>(4))
+          , rp_mode(static_cast<hpx::resource::partitioner_mode>(0))


I'd rather separate the two enum definitions into their own header files and #include those only. Otherwise we will have to remember to change the literal values here whenever the enum is modified.

hkaiser · 2026-05-13T23:33:54Z

+  find_library(TBB_LIBRARY NAMES tbb)
+  if(TBB_LIBRARY)
+    target_link_libraries(hpx_core PUBLIC ${TBB_LIBRARY})
+  endif()


We should be able to get away without creating a hard dependency on TBB (none of our CIs requires it, BTW). Even more as this dependency is not needed on Windows, for instance. In the worst case we will have to submit an upstream patch to prevent the inclusion of TBB.

Hackathon User added 4 commits May 12, 2026 15:09

shivansh023023 requested a review from hkaiser as a code owner May 12, 2026 10:33

shivansh023023 changed the title ~~feat: surgical header pruning for lean hpx_main (Phase 1 Godbolt Integration)~~ feat: surgical header pruning for lean hpx_main (Godbolt Integration) May 12, 2026

hkaiser added type: enhancement type: compatibility issue type: cleanup labels May 12, 2026

hkaiser reviewed May 12, 2026

View reviewed changes

Hackathon User added 2 commits May 13, 2026 02:11

hkaiser reviewed May 12, 2026

View reviewed changes

Hackathon User added 2 commits May 13, 2026 14:00

build: fix TBB linkage for stdexec and finalize lean hpx_main headers

1210e5c

shivansh023023 force-pushed the feat/lean-entry-header-surgery branch from 02c46ae to 1210e5c Compare May 13, 2026 16:42

hkaiser reviewed May 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: surgical header pruning for lean hpx_main (Godbolt Integration)#7262

feat: surgical header pruning for lean hpx_main (Godbolt Integration)#7262
shivansh023023 wants to merge 8 commits into
TheHPXProject:masterfrom
shivansh023023:feat/lean-entry-header-surgery

shivansh023023 commented May 12, 2026

Uh oh!

codacy-production Bot commented May 12, 2026 •

edited

Loading

Uh oh!

StellarBot commented May 12, 2026

Uh oh!

hkaiser May 12, 2026

Uh oh!

hkaiser May 12, 2026 •

edited

Loading

Uh oh!

hkaiser May 13, 2026

Uh oh!

hkaiser May 13, 2026

Uh oh!

hkaiser May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	enum class runtime_mode : std::int8_t;
	HPX_CXX_CORE_EXPORT enum class runtime_mode : std::int8_t;

Uh oh!

Conversation

shivansh023023 commented May 12, 2026

Fixes

Proposed Changes

Any background context you want to provide?

Quantitative Results

Checklist

Uh oh!

codacy-production Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

StellarBot commented May 12, 2026

Uh oh!

hkaiser May 12, 2026

Choose a reason for hiding this comment

Uh oh!

hkaiser May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hkaiser May 13, 2026

Choose a reason for hiding this comment

Uh oh!

hkaiser May 13, 2026

Choose a reason for hiding this comment

Uh oh!

hkaiser May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codacy-production Bot commented May 12, 2026 •

edited

Loading

hkaiser May 12, 2026 •

edited

Loading