HPX Overview

Relevant source files

• .cmake-format.py
• .gitignore
• CMakeLists.txt
• README.rst
• cmake/HPX_AddCompileTest.cmake
• cmake/HPX_AddComponent.cmake
• cmake/HPX_AddExecutable.cmake
• cmake/HPX_AddLibrary.cmake
• cmake/HPX_AddModule.cmake
• cmake/HPX_AddTest.cmake
• cmake/HPX_CXXModules.cmake
• cmake/HPX_Documentation.cmake
• cmake/HPX_GenerateDependencyReport.cmake
• cmake/HPX_GeneratePackage.cmake
• cmake/HPX_SetOutputPaths.cmake
• cmake/HPX_SetupGasnet.cmake
• cmake/HPX_SetupTarget.cmake
• cmake/HPX_UpdateGitDocs.cmake
• cmake/HPX_Utils.cmake
• cmake/packaging/rpm/CMakeLists.txt
• cmake/packaging/rpm/hpx-no-inspect
• cmake/templates/HPXConfig.cmake.in
• cmake/templates/HPXMacros.cmake.in
• cmake/templates/cmake_variables.rst.in
• cmake/templates/conf.py.in
• cmake/templates/hpx_application.pc.in
• cmake/templates/hpx_component.pc.in
• cmake/templates/hpxcxx.in
• cmake/templates/hpxrun.py.in
• docs/CMakeLists.txt
• docs/sphinx/_static/custom.css
• docs/sphinx/_static/images/emails/bhumitattarde.png
• docs/sphinx/_static/images/emails/ggonidelis.png
• docs/sphinx/_static/images/emails/rstobaugh.png
• docs/sphinx/about_hpx/people.rst
• docs/sphinx/additional_material.rst
• docs/sphinx/api.rst
• docs/sphinx/api/full_api.rst
• docs/sphinx/api/public_api.rst
• docs/sphinx/citing.rst
• docs/sphinx/contributing/documentation.rst
• docs/sphinx/extensions/sphinx-hpx.py
• docs/sphinx/index.rst
• docs/sphinx/manual/error_handling.rst
• docs/sphinx/manual/iostreams.rst
• docs/sphinx/manual/troubleshooting.rst
• docs/sphinx/manual/writing_single_node_hpx_applications.rst
• docs/sphinx/releases/whats_new_1_8_1.rst
• docs/sphinx/tutorials.rst
• docs/sphinx/users.rst
• libs/CMakeLists.txt
• libs/core/CMakeLists.txt
• libs/core/algorithms/include/hpx/parallel/algorithms/fill.hpp
• libs/core/concepts/CMakeLists.txt
• libs/core/config/CMakeLists.txt
• libs/core/config/include/hpx/config.hpp
• libs/core/config_registry/CMakeLists.txt
• libs/core/config_registry/include/hpx/modules/config_registry.hpp
• libs/core/debugging/include/hpx/debugging/print.hpp
• libs/core/hardware/CMakeLists.txt
• libs/core/hardware/include/hpx/hardware/timestamp.hpp
• libs/core/hardware/include/hpx/hardware/timestamp/bgq.hpp
• libs/core/hardware/include/hpx/hardware/timestamp/cuda.hpp
• libs/core/hardware/include/hpx/hardware/timestamp/linux_generic.hpp
• libs/core/hardware/include/hpx/hardware/timestamp/linux_x86_32.hpp
• libs/core/hardware/include/hpx/hardware/timestamp/linux_x86_64.hpp
• libs/core/hardware/include/hpx/hardware/timestamp/msvc.hpp
• libs/core/modules.rst
• libs/create_module_skeleton.py
• libs/full/CMakeLists.txt
• libs/full/async_distributed/CMakeLists.txt
• libs/full/async_distributed/tests/unit/CMakeLists.txt
• libs/full/async_distributed/tests/unit/promise_lco_dtor_policy.cpp
• libs/full/execution_distributed/CMakeLists.txt
• libs/full/execution_distributed/docs/index.rst
• libs/full/execution_distributed/examples/CMakeLists.txt
• libs/full/execution_distributed/include/hpx/execution_distributed/detail/distributed_receiver_component.hpp
• libs/full/execution_distributed/include/hpx/execution_distributed/detail/transfer_action.hpp
• libs/full/execution_distributed/include/hpx/execution_distributed/distributed_continues_on_sender.hpp
• libs/full/execution_distributed/include/hpx/execution_distributed/distributed_scheduler.hpp
• libs/full/include/include/hpx/algorithm.hpp
• libs/full/include/include/hpx/include/parallel_set_operations.hpp
• libs/full/modules.rst
• libs/overview.rst
• tests/regressions/CMakeLists.txt
• tests/regressions/util/CMakeLists.txt
• tools/hpxdep/CMakeLists.txt

This page provides a high-level introduction to HPX (High Performance ParalleX), an open-source C++ runtime system for parallel and distributed applications. It covers what HPX is, its core architecture pillars, key design principles, and how the major subsystems relate. Technical details and usage instructions are delegated to child pages for focused exploration.

---

What is HPX?

HPX is a standards-compliant C++ runtime system designed to enable highly scalable parallelism and concurrency on modern hardware architectures, from single nodes to distributed clusters. It follows a task-based parallel programming model centered on lightweight user-level threads, asynchronous programming constructs, and a global Active Global Address Space (AGAS).

The system provides:

• A distributed runtime enabling applications to transparently scale out across multiple machines.
• A local runtime managing lightweight user-level threads (tasks) efficiently on a single node.
• A rich set of parallel algorithms and concurrency primitives aligned with C++ standard interfaces.
• Modern asynchronous execution abstractions inspired by the ongoing C++ sender/receiver (P2300) standard proposal.

HPX aims to empower developers to write composable, fine-grained parallel code that can automatically scale from multicore shared memory systems up to large distributed systems without changing the programming model.

For detailed getting started instructions, visit the child page Getting Started.

Sources:

• README.rst17-37
• README.rst39-58

---

Core Architecture Pillars

HPX’s architecture is conceptually divided into four major pillars that interact to provide a unified execution platform.

1. Local Runtime

• Manages lightweight user-level threads implemented as stackful coroutines.
• Handles scheduling of tasks on OS threads arranged in thread pools.
• Supports multiple scheduling policies to optimize for various workloads.
• Offers synchronization primitives tailored for fiber-based concurrency.

Sources:

• README.rst42-43
• README.rst45
• cmake/templates/HPXConfig.cmake.in191

2. Distributed Runtime

• Implements the Active Global Address Space (AGAS) for globally unique addressing and object migration.
• Facilitates message passing with the parcel layer (parcel handlers and parcel ports) that move data and tasks between nodes.
• Supports remote execution via actions that can be dispatched to components located anywhere in the system.
• Provides distributed components and collective communication operations.

Sources:

• README.rst46
• cmake/templates/HPXConfig.cmake.in59-83
• cmake/templates/HPXConfig.cmake.in222-224

3. Parallel Algorithms

• Offers a collection of parallel algorithms compatible with C++ standard execution policies (seq, par, par_unseq).
• Supports asynchronous variants returning futures for continuation chaining.
• Implements partitioners and SIMD/vectorization-aware algorithms via the datapar layer.

Sources:

• libs/full/include/include/hpx/algorithm.hpp11
• cmake/templates/HPXConfig.cmake.in87-103

4. Sender/Receiver (P2300) Framework

• Implements the C++ asynchronous programming model proposed in P2300.
• Supports composable asynchronous operations via senders and receivers.
• Integrates with the local runtime’s lightweight tasking and standard coroutines.

Sources:

• cmake/templates/HPXConfig.cmake.in39-44

---

Key Design Principles

• Standard C++ Compliance: HPX builds on modern C++ standards. The minimum version is C++17, with extensive support for C++20, C++23, and upcoming C++26 features like contracts CMakeLists.txt104
• Asynchronous, Task-Based Execution: Fine-grained parallelism is achieved via lightweight tasks coordinated through futures and continuations.
• Unified Local and Distributed Model: The runtime abstracts away locality distinctions using AGAS and Parcelports.
• Modularity: HPX uses a modular library structure defined via add_hpx_module cmake/HPX_AddModule.cmake16-101
• Performance and Scalability: Employs advanced scheduling and custom allocators (e.g., jemalloc, tcmalloc, mimalloc) to reduce contention cmake/templates/HPXConfig.cmake.in180-189

Sources:

• README.rst17-18
• README.rst42-43
• README.rst46
• cmake/HPX_AddModule.cmake16-101
• cmake/templates/HPXConfig.cmake.in180-189

---

Relationship Between the Major Subsystems

Legend: Arrows represent data/control flow or dependency.

---

Code Entity Associations

Build System to Code Entities

HPX uses specialized CMake macros to manage its modular architecture. These macros handle dependency resolution and target configuration.

Sources:

• cmake/HPX_AddModule.cmake16-44
• cmake/HPX_AddComponent.cmake8-46
• cmake/HPX_AddExecutable.cmake8-44
• cmake/HPX_AddLibrary.cmake8-46
• cmake/HPX_SetupTarget.cmake19-48

Distributed Runtime to Code Entities

The distributed runtime relies on the parcel layer and AGAS to facilitate communication between localities.

Sources:

• cmake/templates/HPXConfig.cmake.in59-83
• cmake/templates/HPXConfig.cmake.in222-224
• cmake/HPX_SetupTarget.cmake183-185

---

Further Information and Child Pages

• Getting Started — How to obtain, build, and run HPX applications. Covers prerequisites, CMake configuration, hpx::init, and the hpx_wrap mechanism (cmake/HPX_SetupTarget.cmake183-185).
• Release History and Migration Guide — Summary of major HPX releases, version changes (CMakeLists.txt64-75), and migration guides.

---

Summary Table

Pillar	Purpose	Key Code Entities / Files
Local Runtime	Lightweight threading & scheduling	hpx::threads, hpx::thread_manager
Distributed Runtime	Global addressing & messaging	hpx::agas, hpx::parcelset
Parallel Algorithms	High-level parallel operations	hpx/algorithm.hpp, hpx::parallel::execution
Sender/Receiver	Modern async model (P2300)	hpx::execution::experimental, stdexec

Sources:

• README.rst17-58
• CMakeLists.txt64-75
• cmake/HPX_AddModule.cmake16-101
• cmake/templates/HPXConfig.cmake.in39-44
• cmake/templates/HPXConfig.cmake.in59-83
• cmake/templates/HPXConfig.cmake.in87-103
• libs/full/include/include/hpx/algorithm.hpp11