Feat/local convenience header by shivansh023023 · Pull Request #7070 · TheHPXProject/hpx

shivansh023023 · 2026-03-20T09:09:09Z

Fixes # — N/A (new feature)

Proposed Changes

Add hpx/local.hpp convenience header that bundles hpx_main.hpp,
algorithm.hpp, execution.hpp, future.hpp, and numeric.hpp
into a single include for single-node HPX usage.
Register the header in include_local/CMakeLists.txt so it is
correctly installed and exported.
Add a unit test (local_header.cpp) verifying that hpx::async,
hpx::for_each, and hpx::reduce are all reachable through the
single include.

Any background context you want to provide?

This follows the existing "convenience bundle" pattern already established
in the include_local module (e.g., hpx/execution.hpp bundles four
execution modules, hpx/numeric.hpp bundles hpx/modules/algorithms.hpp).

The header directly supports the 2026 GSoC "Compiler Explorer Integration"
by providing a canonical single-header entry point for browser-based
development. On Godbolt, users currently need 4-5 separate #include
lines to write a basic parallel HPX program. With hpx/local.hpp, the
default code snippet becomes:

#include <hpx/local.hpp>
#include <iostream>
int main() {
    auto f = hpx::async([] { return 42; });
    std::cout << f.get() << std::endl;
}

The header includes hpx_main.hpp for automatic main wrapping, so
users do not need to write any HPX boilerplate.

Checklist

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.~~ — N/A
~~I have added a test using random numbers~~ — N/A

StellarBot · 2026-03-20T09:10:04Z

Can one of the admins verify this patch?

hkaiser · 2026-03-20T21:50:17Z

Also, your new test causes compilation errors: https://github.com/STEllAR-GROUP/hpx/actions/runs/23336959505/job/67885450859?pr=7070

shivansh023023 · 2026-03-20T22:12:18Z

Thank you for the detailed review, @hkaiser I see the issue, including hpx_main.hpp in the core_local module was a mistake that caused the circular dependency and the CI failures.

I am currently refactoring the PR to move the convenience header to a higher-level module (likely libs/full) and will update the copyright years and test logic accordingly. I'll push an update shortly.

hkaiser · 2026-03-20T22:16:42Z

Thank you for the detailed review, @hkaiser I see the issue, including hpx_main.hpp in the core_local module was a mistake that caused the circular dependency and the CI failures.

I am currently refactoring the PR to move the convenience header to a higher-level module (likely libs/full) and will update the copyright years and test logic accordingly. I'll push an update shortly.

Moving the header to libs/full will defat the purpose as it will not be available in that case for purely local HPX installations. Having it in include_local should make sure that nothing depends on it inside core.

shivansh023023 · 2026-03-20T22:19:35Z

Thank you for the detailed review, @hkaiser I see the issue, including hpx_main.hpp in the core_local module was a mistake that caused the circular dependency and the CI failures.
I am currently refactoring the PR to move the convenience header to a higher-level module (likely libs/full) and will update the copyright years and test logic accordingly. I'll push an update shortly.

Moving the header to libs/full will defat the purpose as it will not be available in that case for purely local HPX installations. Having it in include_local should make sure that nothing depends on it inside core.

I completely understand, @hkaiser . Moving it to libs/full would indeed defeat the purpose for local-only users.

I am refactoring the header within include_local to conditionally include hpx_main.hpp only when HPX_HAVE_NETWORKING (or the equivalent 'full' runtime flag) is defined. This should keep the core dependencies clean while still providing the convenience bundle for both local and full installations.

I am also updating the copyrights to the 2020-2026 range as suggested. Updated PR coming in a few minutes.

Add a single-include convenience header that bundles the Standard Parallel Toolkit: algorithm, execution, future, and numeric. In local-only builds (HPX_WITH_NETWORKING=OFF), hpx_main.hpp is also included for zero-boilerplate implicit main() wrapping. In full builds, the include is guarded to avoid a circular module dependency. Refs: TheHPXProject#7070

Add a single-include convenience header that bundles the Standard Parallel Toolkit: algorithm, execution, future, and numeric. In local-only builds (HPX_WITH_NETWORKING=OFF), hpx_main.hpp is also included for zero-boilerplate implicit main() wrapping. In full builds, the include is guarded to avoid a circular module dependency. Refs: TheHPXProject#7070 Signed-off-by: shivansh023023 <singhshivansh023@gmail.com>

hkaiser · 2026-03-20T23:08:36Z

Thank you for the detailed review, @hkaiser I see the issue, including hpx_main.hpp in the core_local module was a mistake that caused the circular dependency and the CI failures.
I am currently refactoring the PR to move the convenience header to a higher-level module (likely libs/full) and will update the copyright years and test logic accordingly. I'll push an update shortly.

Moving the header to libs/full will defat the purpose as it will not be available in that case for purely local HPX installations. Having it in include_local should make sure that nothing depends on it inside core.

I completely understand, @hkaiser . Moving it to libs/full would indeed defeat the purpose for local-only users.

I am refactoring the header within include_local to conditionally include hpx_main.hpp only when HPX_HAVE_NETWORKING (or the equivalent 'full' runtime flag) is defined. This should keep the core dependencies clean while still providing the convenience bundle for both local and full installations.

I am also updating the copyrights to the 2020-2026 range as suggested. Updated PR coming in a few minutes.

FWIW, the correct CMake flag is HPX_WITH_DISTRIBUTED_RUNTIME (HPX_HAVE_DISTRIBUTED_RUNTIME pp macro).

shivansh023023 · 2026-03-21T07:35:46Z

Thank you for the detailed review, @hkaiser I see the issue, including hpx_main.hpp in the core_local module was a mistake that caused the circular dependency and the CI failures.
I am currently refactoring the PR to move the convenience header to a higher-level module (likely libs/full) and will update the copyright years and test logic accordingly. I'll push an update shortly.

Moving the header to libs/full will defat the purpose as it will not be available in that case for purely local HPX installations. Having it in include_local should make sure that nothing depends on it inside core.

I completely understand, @hkaiser . Moving it to libs/full would indeed defeat the purpose for local-only users.
I am refactoring the header within include_local to conditionally include hpx_main.hpp only when HPX_HAVE_NETWORKING (or the equivalent 'full' runtime flag) is defined. This should keep the core dependencies clean while still providing the convenience bundle for both local and full installations.
I am also updating the copyrights to the 2020-2026 range as suggested. Updated PR coming in a few minutes.

FWIW, the correct CMake flag is HPX_WITH_DISTRIBUTED_RUNTIME (HPX_HAVE_DISTRIBUTED_RUNTIME pp macro).

Thank you for the tip, @hkaiser ! I've updated the code to use the canonical HPX_HAVE_DISTRIBUTED_RUNTIME macro in both the header and the unit test. This should resolve the circular dependency issues in the CI.

hkaiser · 2026-03-22T13:02:34Z

@shivansh023023 Please have a look at the CI results.There seem to be some problems with your changes.

Move the -Wl,-wrap=main compile-time diagnostic into an isolated header (hpx/config/static_linker_check.hpp) in the config module to avoid circular module dependencies. The header emits a #warning when all of these hold: - __linux__ is defined - HPX_HAVE_DYNAMIC_HPX_MAIN is defined (generated config) - HPX_HAVE_STATIC_LINKING is defined (generated config) - HPX_HAVE_WRAP_MAIN_CONFIGURED is NOT defined CMake consumers are unaffected: hpx_wrap and hpx_auto_wrap inject HPX_HAVE_WRAP_MAIN_CONFIGURED via INTERFACE compile definitions. Refs: TheHPXProject#7068, TheHPXProject#7072 Signed-off-by: shivansh023023 <singhshivansh023@gmail.com>

- local.hpp: use only source-tree headers (hpx/execution.hpp, hpx/numeric.hpp) instead of generated .hpp.in headers (algorithm.hpp, future.hpp) - local.hpp: remove all hpx_main.hpp references from comments - local_header.cpp: use hpx::local::init instead of hpx_main.hpp wrapping - tests/unit/CMakeLists.txt: remove HPX::wrap_main dependency Refs: TheHPXProject#7070 Signed-off-by: shivansh023023 <singhshivansh023@gmail.com>

hkaiser

LGTM, thanks!

hkaiser · 2026-03-24T19:49:34Z

The issues reported by the header consistency check are caused by your changes (https://github.com/STEllAR-GROUP/hpx/actions/runs/23444582618/job/68240317644?pr=7070). Please have a look.

Also, please rebase onto master to fix the other compilation issues reported.

shivansh023023 · 2026-03-24T19:52:51Z

The issues reported by the header consistency check are caused by your changes (https://github.com/STEllAR-GROUP/hpx/actions/runs/23444582618/job/68240317644?pr=7070). Please have a look.

Also, please rebase onto master to fix the other compilation issues reported.

sure , i will look into that

hkaiser · 2026-03-28T11:30:52Z

@shivansh023023 ping?

codacy-production · 2026-04-11T14:48:15Z

Not up to standards ⛔

🔴 Issues 1 medium

Alerts:
⚠ 1 issue (≤ 0 issues of at least minor severity)

Results:
1 new issue

Category Results

ErrorProne 1 medium

View in Codacy

🟢 Metrics 0 complexity · 0 duplication

Metric Results

Complexity 0

Duplication 0

View in Codacy

_{TIP This summary will be updated as you push new changes. Give us feedback}

shivansh023023 requested a review from hkaiser as a code owner March 20, 2026 09:09

shivansh023023 force-pushed the feat/local-convenience-header branch from 2540073 to be0b7cd Compare March 20, 2026 09:32

shivansh023023 mentioned this pull request Mar 20, 2026

[Build System] UX Gap: -Wl,-wrap=main does not propagate to non-CMake consumers #7071

Open

hkaiser added type: enhancement type: cleanup category: modules labels Mar 20, 2026

hkaiser reviewed Mar 20, 2026

View reviewed changes

Comment thread libs/core/include_local/include/hpx/local.hpp

Comment thread libs/core/include_local/tests/unit/CMakeLists.txt Outdated

Comment thread libs/core/include_local/tests/unit/local_header.cpp Outdated

shivansh023023 force-pushed the feat/local-convenience-header branch from be0b7cd to 265bb1c Compare March 20, 2026 22:32

shivansh023023 force-pushed the feat/local-convenience-header branch from 265bb1c to 70dea5f Compare March 20, 2026 22:33

shivansh023023 force-pushed the feat/local-convenience-header branch from 70dea5f to 478f834 Compare March 21, 2026 07:34

shivansh023023 force-pushed the feat/local-convenience-header branch from 478f834 to 023d94f Compare March 21, 2026 13:02

shivansh023023 force-pushed the feat/local-convenience-header branch from 023d94f to 15b0e7d Compare March 22, 2026 19:54

shivansh023023 force-pushed the feat/local-convenience-header branch from 15b0e7d to 9f4d518 Compare March 23, 2026 12:36

hkaiser reviewed Mar 23, 2026

View reviewed changes

Comment thread libs/core/include_local/include/hpx/local.hpp

Comment thread libs/core/include_local/tests/unit/local_header.cpp Outdated

shivansh023023 force-pushed the feat/local-convenience-header branch from 9f4d518 to 80af546 Compare March 23, 2026 15:11

hkaiser previously approved these changes Mar 23, 2026

View reviewed changes

hkaiser added this to the 2.0.0 milestone Mar 23, 2026

shivansh023023 mentioned this pull request Mar 24, 2026

[wrap] Enable hpx_main wrapping for local-only (non-distributed) builds #7099

Closed

Apply suggestion from @hkaiser

94eb202

hkaiser dismissed their stale review via 94eb202 April 11, 2026 14:46

hkaiser linked an issue Apr 11, 2026 that may be closed by this pull request

[Build System] UX Gap: -Wl,-wrap=main does not propagate to non-CMake consumers #7071

Open

Uh oh!

Conversation

shivansh023023 commented Mar 20, 2026

Proposed Changes

Any background context you want to provide?

Checklist

Uh oh!

StellarBot commented Mar 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hkaiser commented Mar 20, 2026

Uh oh!

shivansh023023 commented Mar 20, 2026

Uh oh!

hkaiser commented Mar 20, 2026

Uh oh!

shivansh023023 commented Mar 20, 2026

Uh oh!

hkaiser commented Mar 20, 2026

Uh oh!

shivansh023023 commented Mar 21, 2026

Uh oh!

hkaiser commented Mar 22, 2026

Uh oh!

Uh oh!

Uh oh!

hkaiser left a comment

Choose a reason for hiding this comment

Uh oh!

hkaiser commented Mar 24, 2026

Uh oh!

shivansh023023 commented Mar 24, 2026

Uh oh!

hkaiser commented Mar 28, 2026

Uh oh!

codacy-production bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Not up to standards ⛔

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codacy-production bot commented Apr 11, 2026 •

edited

Loading