Welcome to the HPX documentation!
Contents
Welcome to the HPX documentation!#
If you’re new to HPX you can get started with the Quick start guide. Don’t forget to read the Terminology section to learn about the most important concepts in HPX. The Examples give you a feel for how it is to write real HPX applications and the Manual contains detailed information about everything from building HPX to debugging it. There are links to blog posts and videos about HPX in Additional material.
You can find a comprehensive list of contact options on Support for deploying and using HPX. Do not hesitate to contact us if you can’t find what you are looking for in the documentation!
See Citing HPX for details on how to cite HPX in publications. See HPX users for a list of institutions and projects using HPX.
There are also available a PDF version of this documentation as well as a Single HTML Page.
What is HPX?#
HPX is a C++ Standard Library for Concurrency and Parallelism. It implements all of the corresponding facilities as defined by the C++ Standard. Additionally, in HPX we implement functionalities proposed as part of the ongoing C++ standardization process. We also extend the C++ Standard APIs to the distributed case. HPX is developed by the STE||AR group (see People).
The goal of HPX is to create a high quality, freely available, open source implementation of a new programming model for conventional systems, such as classic Linux based Beowulf clusters or multi-socket highly parallel SMP nodes. At the same time, we want to have a very modular and well designed runtime system architecture which would allow us to port our implementation onto new computer system architectures. We want to use real-world applications to drive the development of the runtime system, coining out required functionalities and converging onto a stable API which will provide a smooth migration path for developers.
The API exposed by HPX is not only modeled after the interfaces defined by the C++11/14/17/20 ISO standard. It also adheres to the programming guidelines used by the Boost collection of C++ libraries. We aim to improve the scalability of today’s applications and to expose new levels of parallelism which are necessary to take advantage of the exascale systems of the future.
What’s so special about HPX?#
HPX exposes a uniform, standards-oriented API for ease of programming parallel and distributed applications.
It enables programmers to write fully asynchronous code using hundreds of millions of threads.
HPX provides unified syntax and semantics for local and remote operations.
HPX makes concurrency manageable with dataflow and future based synchronization.
It implements a rich set of runtime services supporting a broad range of use cases.
HPX exposes a uniform, flexible, and extendable performance counter framework which can enable runtime adaptivity
It is designed to solve problems conventionally considered to be scaling-impaired.
HPX has been designed and developed for systems of any scale, from hand-held devices to very large scale systems.
It is the first fully functional implementation of the ParalleX execution model.
HPX is published under a liberal open-source license and has an open, active, and thriving developer community.
Quick start#
The following steps will help you get started with HPX. Before getting started, make sure you have all the necessary prerequisites, which are listed in _prerequisites. After Installing HPX, you can check how to run a simple example Hello, World!. Writing task-based applications explains how you can get started with HPX. You can refer to our Migration guide if you use other APIs for parallelism (like OpenMP, MPI or Intel Threading Building Blocks (TBB)) and you would like to convert your code to HPX code.
Installing HPX#
The easiest way to install HPX on your system is by choosing one of the steps below:
#.* * vcpkg * *
You can download and install HPX using the vcpkg dependency manager:
$ vcpkg install hpx
#.* * Spack * *
Another way to install HPX is using Spack:
$ spack install hpx
#.* * Fedora * *
Installation can be done with Fedora as well:
$ dnf install hpx*
#.* * Arch Linux * *
HPX is available in the Arch User Repository (AUR) as
hpxtoo.
More information or alternatives regarding the installation can be found in the Building HPX, a detailed guide with thorough explanation of ways to build and use HPX.
Hello, World!#
To get started with this minimal example you need to create a new project
directory and a file CMakeLists.txt with the contents below in order to
build an executable using CMake and HPX:
cmake_minimum_required(VERSION 3.19)
project(my_hpx_project CXX)
find_package(HPX REQUIRED)
add_executable(my_hpx_program main.cpp)
target_link_libraries(my_hpx_program HPX::hpx HPX::wrap_main HPX::iostreams_component)
The next step is to create a main.cpp with the contents below:
// Including 'hpx/hpx_main.hpp' instead of the usual 'hpx/hpx_init.hpp' enables
// to use the plain C-main below as the direct main HPX entry point.
#include <hpx/hpx_main.hpp>
#include <hpx/iostream.hpp>
int main()
{
// Say hello to the world!
hpx::cout << "Hello World!\n" << std::flush;
return 0;
}
Then, in your project directory run the following:
$ mkdir build && cd build
$ cmake -DHPX_DIR=</path/to/hpx/installation> ..
$ make all
$ ./my_hpx_program
$ ./my_hpx_program
Hello World!
The program looks almost like a regular C++ hello world with the exception of
the two includes and hpx::cout.
When you include
hpx_main.hppHPX makes sure thatmainactually gets launched on the HPX runtime. So while it looks almost the same you can now use futures,async, parallel algorithms and more which make use of the HPX runtime with lightweight threads.hpx::coutis a replacement forstd::coutto make sure printing never blocks a lightweight thread. You can read more abouthpx::coutin The HPX I/O-streams component.
Note
You will most likely have more than one
main.cppfile in your project. See the section on Using HPX with CMake-based projects for more details on how to useadd_hpx_executable.HPX::wrap_mainis required if you are implicitly usingmain()as the runtime entry point. See Re-use the main() function as the main HPX entry point for more information.HPX::iostreams_componentis optional for a minimal project but lets us use the HPX equivalent ofstd::cout, i.e., the HPX The HPX I/O-streams component functionality in our application.You do not have to let HPX take over your main function like in the example. See Starting the HPX runtime for more details on how to initialize and run the HPX runtime.
Caution
Ensure that HPX is installed with HPX_WITH_DISTRIBUTED_RUNTIME=ON to
prevent encountering an error indicating that the HPX::iostreams_component
target is not found.
When including hpx_main.hpp the user-defined main gets renamed and
the real main function is defined by HPX. This means that the
user-defined main must include a return statement, unlike the real
main. If you do not include the return statement, you may end up with
confusing compile time errors mentioning user_main or even runtime
errors.
Writing task-based applications#
So far we haven’t done anything that can’t be done using the C++ standard library. In this section we will give a short overview of what you can do with HPX on a single node. The essence is to avoid global synchronization and break up your application into small, composable tasks whose dependencies control the flow of your application. Remember, however, that HPX allows you to write distributed applications similarly to how you would write applications for a single node (see Why HPX? and Writing distributed applications).
If you are already familiar with async and future from the C++ standard
library, the same functionality is available in HPX.
The following terminology is essential when talking about task-based C++ programs:
lightweight thread: Essential for good performance with task-based programs. Lightweight refers to smaller stacks and faster context switching compared to OS threads. Smaller overheads allow the program to be broken up into smaller tasks, which in turns helps the runtime fully utilize all processing units.
async: The most basic way of launching tasks asynchronously. Returns afuture<T>.future<T>: Represents a value of typeTthat will be ready in the future. The value can be retrieved withget(blocking) and one can check if the value is ready withis_ready(non-blocking).shared_future<T>: Same asfuture<T>but can be copied (similar tostd::unique_ptrvsstd::shared_ptr).continuation: A function that is to be run after a previous task has run (represented by a future).
thenis a method offuture<T>that takes a function to run next. Used to build up dataflow DAGs (directed acyclic graphs).shared_futures help you split up nodes in the DAG and functions likewhen_allhelp you join nodes in the DAG.
The following example is a collection of the most commonly used functionality in HPX:
#include <hpx/algorithm.hpp>
#include <hpx/future.hpp>
#include <hpx/init.hpp>
#include <iostream>
#include <random>
#include <vector>
void final_task(hpx::future<hpx::tuple<hpx::future<double>, hpx::future<void>>>)
{
std::cout << "in final_task" << std::endl;
}
int hpx_main()
{
// A function can be launched asynchronously. The program will not block
// here until the result is available.
hpx::future<int> f = hpx::async([]() { return 42; });
std::cout << "Just launched a task!" << std::endl;
// Use get to retrieve the value from the future. This will block this task
// until the future is ready, but the HPX runtime will schedule other tasks
// if there are tasks available.
std::cout << "f contains " << f.get() << std::endl;
// Let's launch another task.
hpx::future<double> g = hpx::async([]() { return 3.14; });
// Tasks can be chained using the then method. The continuation takes the
// future as an argument.
hpx::future<double> result = g.then([](hpx::future<double>&& gg) {
// This function will be called once g is ready. gg is g moved
// into the continuation.
return gg.get() * 42.0 * 42.0;
});
// You can check if a future is ready with the is_ready method.
std::cout << "Result is ready? " << result.is_ready() << std::endl;
// You can launch other work in the meantime. Let's sort a vector.
std::vector<int> v(1000000);
// We fill the vector synchronously and sequentially.
hpx::generate(hpx::execution::seq, std::begin(v), std::end(v), &std::rand);
// We can launch the sort in parallel and asynchronously.
hpx::future<void> done_sorting =
hpx::sort(hpx::execution::par( // In parallel.
hpx::execution::task), // Asynchronously.
std::begin(v), std::end(v));
// We launch the final task when the vector has been sorted and result is
// ready using when_all.
auto all = hpx::when_all(result, done_sorting).then(&final_task);
// We can wait for all to be ready.
all.wait();
// all must be ready at this point because we waited for it to be ready.
std::cout << (all.is_ready() ? "all is ready!" : "all is not ready...")
<< std::endl;
return hpx::local::finalize();
}
int main(int argc, char* argv[])
{
return hpx::local::init(hpx_main, argc, argv);
}
Try copying the contents to your main.cpp file and look at the output. It can
be a good idea to go through the program step by step with a debugger. You can
also try changing the types or adding new arguments to functions to make sure
you can get the types to match. The type of the then method can be especially
tricky to get right (the continuation needs to take the future as an argument).
Note
HPX programs accept command line arguments. The most important one is
--hpx:threads=N to set the number of OS threads used by
HPX. HPX uses one thread per core by default. Play around with the
example above and see what difference the number of threads makes on the
sort function. See Launching and configuring HPX applications for more details on
how and what options you can pass to HPX.
Tip
The example above used the construction hpx::when_all(...).then(...). For
convenience and performance it is a good idea to replace uses of
hpx::when_all(...).then(...) with dataflow. See
Dataflow for more details on dataflow.
Tip
If possible, try to use the provided parallel algorithms instead of writing your own implementation. This can save you time and the resulting program is often faster.
Next steps#
If you haven’t done so already, reading the Terminology section will help you get familiar with the terms used in HPX.
The Examples section contains small, self-contained walkthroughs of example HPX programs. The Local to remote example is a thorough, realistic example starting from a single node implementation and going stepwise to a distributed implementation.
The Manual contains detailed information on writing, building and running HPX applications.
Examples#
The following sections analyze some examples to help you get familiar with the HPX style of programming. We start off with simple examples that utilize basic HPX elements and then begin to expose the reader to the more complex and powerful HPX concepts. Section Building tests and examples shows how you can build the examples.
Asynchronous execution#
The Fibonacci sequence is a sequence of numbers starting with 0 and 1 where every subsequent number is the sum of the previous two numbers. In this example, we will use HPX to calculate the value of the n-th element of the Fibonacci sequence. In order to compute this problem in parallel, we will use a facility known as a future.
As shown in the Fig. 1 below, a future encapsulates a delayed computation. It acts as a proxy for a result initially not known, most of the time because the computation of the result has not completed yet. The future synchronizes the access of this value by optionally suspending any HPX-threads requesting the result until the value is available. When a future is created, it spawns a new HPX-thread (either remotely with a parcel or locally by placing it into the thread queue) which, when run, will execute the function associated with the future. The arguments of the function are bound when the future is created.
Fig. 1 Schematic of a future execution.#
Once the function has finished executing, a write operation is performed on the future. The write operation marks the future as completed, and optionally stores data returned by the function. When the result of the delayed computation is needed, a read operation is performed on the future. If the future’s function hasn’t completed when a read operation is performed on it, the reader HPX-thread is suspended until the future is ready. The future facility allows HPX to schedule work early in a program so that when the function value is needed it will already be calculated and available. We use this property in our Fibonacci example below to enable its parallel execution.
Setup#
The source code for this example can be found here:
fibonacci_local.cpp.
To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:
$ make examples.quickstart.fibonacci_local
To run the program type:
$ ./bin/fibonacci_local
This should print (time should be approximate):
fibonacci(10) == 55
elapsed time: 0.002430 [s]
This run used the default settings, which calculate the tenth element of the
Fibonacci sequence. To declare which Fibonacci value you want to calculate, use
the --n-value option. Additionally you can use the --hpx:threads
option to declare how many OS-threads you wish to use when running the program.
For instance, running:
$ ./bin/fibonacci --n-value 20 --hpx:threads 4
Will yield:
fibonacci(20) == 6765
elapsed time: 0.062854 [s]
Walkthrough#
Now that you have compiled and run the code, let’s look at how the code works.
Since this code is written in C++, we will begin with the main() function.
Here you can see that in HPX, main() is only used to initialize the
runtime system. It is important to note that application-specific command line
options are defined here. HPX uses Boost.Program_options for command line
processing. You can see that our programs --n-value option is set by calling
the add_options() method on an instance of
hpx::program_options::options_description. The default value of the
variable is set to 10. This is why when we ran the program for the first time
without using the --n-value option the program returned the 10th value of
the Fibonacci sequence. The constructor argument of the description is the text
that appears when a user uses the --hpx:help option to see what
command line options are available. HPX_APPLICATION_STRING is a macro that
expands to a string constant containing the name of the HPX application
currently being compiled.
In HPX main() is used to initialize the runtime system and pass the
command line arguments to the program. If you wish to add command line options
to your program you would add them here using the instance of the Boost class
options_description, and invoking the public member function
.add_options() (see Boost Documentation for more details). hpx::init
calls hpx_main() after setting up HPX, which is where the logic of our
program is encoded.
int main(int argc, char* argv[])
{
// Configure application-specific options
hpx::program_options::options_description desc_commandline(
"Usage: " HPX_APPLICATION_STRING " [options]");
// clang-format off
desc_commandline.add_options()
("n-value",
hpx::program_options::value<std::uint64_t>()->default_value(10),
"n value for the Fibonacci function")
;
// clang-format on
// Initialize and run HPX
hpx::local::init_params init_args;
init_args.desc_cmdline = desc_commandline;
return hpx::local::init(hpx_main, argc, argv, init_args);
}
The hpx::init function in main() starts the runtime system, and
invokes hpx_main() as the first HPX-thread. Below we can see that the
basic program is simple. The command line option --n-value is read in, a
timer (hpx::chrono::high_resolution_timer) is set up to record the
time it takes to do the computation, the fibonacci function is invoked
synchronously, and the answer is printed out.
int hpx_main(hpx::program_options::variables_map& vm)
{
hpx::threads::add_scheduler_mode(
hpx::threads::policies::scheduler_mode::fast_idle_mode);
// extract command line argument, i.e. fib(N)
std::uint64_t n = vm["n-value"].as<std::uint64_t>();
{
// Keep track of the time required to execute.
hpx::chrono::high_resolution_timer t;
std::uint64_t r = fibonacci(n);
char const* fmt = "fibonacci({1}) == {2}\nelapsed time: {3} [s]\n";
hpx::util::format_to(std::cout, fmt, n, r, t.elapsed());
}
return hpx::local::finalize(); // Handles HPX shutdown
}
The fibonacci function itself is synchronous as the work done inside is
asynchronous. To understand what is happening we have to look inside the
fibonacci function:
std::uint64_t fibonacci(std::uint64_t n)
{
if (n < 2)
return n;
hpx::future<std::uint64_t> n1 = hpx::async(fibonacci, n - 1);
std::uint64_t n2 = fibonacci(n - 2);
return n1.get() + n2; // wait for the Future to return their values
}
This block of code looks similar to regular C++ code. First, if (n < 2),
meaning n is 0 or 1, then we return 0 or 1 (recall the first element of the
Fibonacci sequence is 0 and the second is 1). If n is larger than 1 we spawn two
new tasks whose results are contained in n1 and n2. This is done using
hpx::async which takes as arguments a function (function pointer,
object or lambda) and the arguments to the function. Instead of returning a
std::uint64_t like fibonacci does, hpx::async returns a future of a
std::uint64_t, i.e. hpx::future<std::uint64_t>. Each of these futures
represents an asynchronous, recursive call to fibonacci. After we’ve created
the futures, we wait for both of them to finish computing, we add them together,
and return that value as our result. We get the values from the futures using
the get method. The recursive call tree will continue until n is equal to 0
or 1, at which point the value can be returned because it is implicitly known.
When this termination condition is reached, the futures can then be added up,
producing the n-th value of the Fibonacci sequence.
Note that calling get potentially blocks the calling HPX-thread, and lets
other HPX-threads run in the meantime. There are, however, more efficient ways
of doing this. examples/quickstart/fibonacci_futures.cpp contains many more
variations of locally computing the Fibonacci numbers, where each method makes
different tradeoffs in where asynchrony and parallelism is applied. To get
started, however, the method above is sufficient and optimizations can be
applied once you are more familiar with HPX. The example
Dataflow presents dataflow, which is a way to more
efficiently chain together multiple tasks.
Parallel algorithms#
This program will perform a matrix multiplication in parallel. The output will look something like this:
Matrix A is :
4 9 6
1 9 8
Matrix B is :
4 9
6 1
9 8
Resultant Matrix is :
124 93
130 82
Setup#
The source code for this example can be found here:
matrix_multiplication.cpp.
To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:
$ make examples.quickstart.matrix_multiplication
To run the program type:
$ ./bin/matrix_multiplication
or:
$ ./bin/matrix_multiplication --n 2 --m 3 --k 2 --s 100 --l 0 --u 10
where the first matrix is n x m and the second m x k, s is the seed for creating the random values of the matrices and the range of these values is [l,u]
This should print:
Matrix A is :
4 9 6
1 9 8
Matrix B is :
4 9
6 1
9 8
Resultant Matrix is :
124 93
130 82
Notice that the numbers may be different because of the random initialization of the matrices.
Walkthrough#
Now that you have compiled and run the code, let’s look at how the code works.
First, main() is used to initialize the runtime system and pass the command line arguments to the program.
hpx::init calls hpx_main() after setting up HPX, which is where our program is implemented.
int main(int argc, char* argv[])
{
using namespace hpx::program_options;
options_description cmdline("usage: " HPX_APPLICATION_STRING " [options]");
// clang-format off
cmdline.add_options()
("n",
hpx::program_options::value<std::size_t>()->default_value(2),
"Number of rows of first matrix")
("m",
hpx::program_options::value<std::size_t>()->default_value(3),
"Number of columns of first matrix (equal to the number of rows of "
"second matrix)")
("k",
hpx::program_options::value<std::size_t>()->default_value(2),
"Number of columns of second matrix")
("seed,s",
hpx::program_options::value<unsigned int>(),
"The random number generator seed to use for this run")
("l",
hpx::program_options::value<int>()->default_value(0),
"Lower limit of range of values")
("u",
hpx::program_options::value<int>()->default_value(10),
"Upper limit of range of values");
// clang-format on
hpx::local::init_params init_args;
init_args.desc_cmdline = cmdline;
return hpx::local::init(hpx_main, argc, argv, init_args);
}
Proceeding to the hpx_main() function, we can see that matrix multiplication can be done very easily.
int hpx_main(hpx::program_options::variables_map& vm)
{
using element_type = int;
// Define matrix sizes
std::size_t const rowsA = vm["n"].as<std::size_t>();
std::size_t const colsA = vm["m"].as<std::size_t>();
std::size_t const rowsB = colsA;
std::size_t const colsB = vm["k"].as<std::size_t>();
std::size_t const rowsR = rowsA;
std::size_t const colsR = colsB;
// Initialize matrices A and B
std::vector<int> A(rowsA * colsA);
std::vector<int> B(rowsB * colsB);
std::vector<int> R(rowsR * colsR);
// Define seed
unsigned int seed = std::random_device{}();
if (vm.count("seed"))
seed = vm["seed"].as<unsigned int>();
gen.seed(seed);
std::cout << "using seed: " << seed << std::endl;
// Define range of values
int const lower = vm["l"].as<int>();
int const upper = vm["u"].as<int>();
// Matrices have random values in the range [lower, upper]
std::uniform_int_distribution<element_type> dis(lower, upper);
auto generator = std::bind(dis, gen);
hpx::ranges::generate(A, generator);
hpx::ranges::generate(B, generator);
// Perform matrix multiplication
hpx::experimental::for_loop(hpx::execution::par, 0, rowsA, [&](auto i) {
hpx::experimental::for_loop(0, colsB, [&](auto j) {
R[i * colsR + j] = 0;
hpx::experimental::for_loop(0, rowsB, [&](auto k) {
R[i * colsR + j] += A[i * colsA + k] * B[k * colsB + j];
});
});
});
// Print all 3 matrices
print_matrix(A, rowsA, colsA, "A");
print_matrix(B, rowsB, colsB, "B");
print_matrix(R, rowsR, colsR, "R");
return hpx::local::finalize();
}
First, the dimensions of the matrices are defined. If they were not given as command-line arguments, their default values are 2 x 3 for the first matrix and 3 x 2 for the second. We use standard vectors to define the matrices to be multiplied as well as the resultant matrix.
To give some random initial values to our matrices, we use std::uniform_int_distribution. Then, std::bind() is used
along with hpx::ranges::generate() to yield two matrices A and B, which contain values in the range of [0, 10] or in
the range defined by the user at the command-line arguments. The seed to generate the values can also be defined by the user.
The next step is to perform the matrix multiplication in parallel. This can be done by just using an hpx::experimental::for_loop
combined with a parallel execution policy hpx::execution::par as the outer loop of the multiplication. Note that the execution
of hpx::experimental::for_loop without specifying an execution policy is equivalent to specifying hpx::execution::seq
as the execution policy.
Finally, the matrices A, B that are multiplied as well as the resultant matrix R are printed using the following function.
void print_matrix(std::vector<int> const& M, std::size_t rows, std::size_t cols,
char const* message)
{
std::cout << "\nMatrix " << message << " is:" << std::endl;
for (std::size_t i = 0; i < rows; i++)
{
for (std::size_t j = 0; j < cols; j++)
std::cout << M[i * cols + j] << " ";
std::cout << "\n";
}
}
Asynchronous execution with actions#
This example extends the previous example by
introducing actions: functions that can be run remotely. In this
example, however, we will still only run the action locally. The mechanism to
execute actions stays the same: hpx::async. Later
examples will demonstrate running actions on remote localities
(e.g. Remote execution with actions).
Setup#
The source code for this example can be found here:
fibonacci.cpp.
To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:
$ make examples.quickstart.fibonacci
To run the program type:
$ ./bin/fibonacci
This should print (time should be approximate):
fibonacci(10) == 55
elapsed time: 0.00186288 [s]
This run used the default settings, which calculate the tenth element of the
Fibonacci sequence. To declare which Fibonacci value you want to calculate, use
the --n-value option. Additionally you can use the --hpx:threads
option to declare how many OS-threads you wish to use when running the program.
For instance, running:
$ ./bin/fibonacci --n-value 20 --hpx:threads 4
Will yield:
fibonacci(20) == 6765
elapsed time: 0.233827 [s]
Walkthrough#
The code needed to initialize the HPX runtime is the same as in the previous example:
int main(int argc, char* argv[])
{
// Configure application-specific options
hpx::program_options::options_description desc_commandline(
"Usage: " HPX_APPLICATION_STRING " [options]");
desc_commandline.add_options()("n-value",
hpx::program_options::value<std::uint64_t>()->default_value(10),
"n value for the Fibonacci function");
// Initialize and run HPX
hpx::init_params init_args;
init_args.desc_cmdline = desc_commandline;
return hpx::init(argc, argv, init_args);
}
The hpx::init function in main() starts the runtime system, and
invokes hpx_main() as the first HPX-thread. The command line option
--n-value is read in, a timer
(hpx::chrono::high_resolution_timer) is set up to record the time it
takes to do the computation, the fibonacci action is invoked
synchronously, and the answer is printed out.
int hpx_main(hpx::program_options::variables_map& vm)
{
// extract command line argument, i.e. fib(N)
std::uint64_t n = vm["n-value"].as<std::uint64_t>();
{
// Keep track of the time required to execute.
hpx::chrono::high_resolution_timer t;
// Wait for fib() to return the value
fibonacci_action fib;
std::uint64_t r = fib(hpx::find_here(), n);
char const* fmt = "fibonacci({1}) == {2}\nelapsed time: {3} [s]\n";
hpx::util::format_to(std::cout, fmt, n, r, t.elapsed());
}
return hpx::finalize(); // Handles HPX shutdown
}
Upon a closer look we see that we’ve created a std::uint64_t to store the
result of invoking our fibonacci_action fib. This action will
launch synchronously (as the work done inside of the action will be
asynchronous itself) and return the result of the Fibonacci sequence. But wait,
what is an action? And what is this fibonacci_action? For starters,
an action is a wrapper for a function. By wrapping functions, HPX can
send packets of work to different processing units. These vehicles allow users
to calculate work now, later, or on certain nodes. The first argument to our
action is the location where the action should be run. In this
case, we just want to run the action on the machine that we are
currently on, so we use hpx::find_here. To
further understand this we turn to the code to find where fibonacci_action
was defined:
// forward declaration of the Fibonacci function
std::uint64_t fibonacci(std::uint64_t n);
// This is to generate the required boilerplate we need for the remote
// invocation to work.
HPX_PLAIN_ACTION(fibonacci, fibonacci_action)
A plain action is the most basic form of action. Plain
actions wrap simple global functions which are not associated with any
particular object (we will discuss other types of actions in
Components and actions). In this block of code the function fibonacci()
is declared. After the declaration, the function is wrapped in an action
in the declaration HPX_PLAIN_ACTION. This function takes two
arguments: the name of the function that is to be wrapped and the name of the
action that you are creating.
This picture should now start making sense. The function fibonacci() is
wrapped in an action fibonacci_action, which was run synchronously
but created asynchronous work, then returns a std::uint64_t representing the
result of the function fibonacci(). Now, let’s look at the function
fibonacci():
std::uint64_t fibonacci(std::uint64_t n)
{
if (n < 2)
return n;
// We restrict ourselves to execute the Fibonacci function locally.
hpx::id_type const locality_id = hpx::find_here();
// Invoking the Fibonacci algorithm twice is inefficient.
// However, we intentionally demonstrate it this way to create some
// heavy workload.
fibonacci_action fib;
hpx::future<std::uint64_t> n1 = hpx::async(fib, locality_id, n - 1);
hpx::future<std::uint64_t> n2 = hpx::async(fib, locality_id, n - 2);
return n1.get() +
n2.get(); // wait for the Futures to return their values
}
This block of code is much more straightforward and should look familiar from
the previous example. First, if (n < 2),
meaning n is 0 or 1, then we return 0 or 1 (recall the first element of the
Fibonacci sequence is 0 and the second is 1). If n is larger than 1 we spawn two
tasks using hpx::async. Each of these futures represents an
asynchronous, recursive call to fibonacci. As previously we wait for both
futures to finish computing, get the results, add them together, and return that
value as our result. The recursive call tree will continue until n is equal to 0
or 1, at which point the value can be returned because it is implicitly known.
When this termination condition is reached, the futures can then be added up,
producing the n-th value of the Fibonacci sequence.
Remote execution with actions#
This program will print out a hello world message on every OS-thread on every locality. The output will look something like this:
hello world from OS-thread 1 on locality 0
hello world from OS-thread 1 on locality 1
hello world from OS-thread 0 on locality 0
hello world from OS-thread 0 on locality 1
Setup#
The source code for this example can be found here:
hello_world_distributed.cpp.
To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:
$ make examples.quickstart.hello_world_distributed
To run the program type:
$ ./bin/hello_world_distributed
This should print:
hello world from OS-thread 0 on locality 0
To use more OS-threads use the command line option --hpx:threads and
type the number of threads that you wish to use. For example, typing:
$ ./bin/hello_world_distributed --hpx:threads 2
will yield:
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
Notice how the ordering of the two print statements will change with subsequent runs. To run this program on multiple localities please see the section How to use HPX applications with PBS.
Walkthrough#
Now that you have compiled and run the code, let’s look at how the code works,
beginning with main():
// Here is the main entry point. By using the include 'hpx/hpx_main.hpp' HPX
// will invoke the plain old C-main() as its first HPX thread.
int main()
{
// Get a list of all available localities.
std::vector<hpx::id_type> localities = hpx::find_all_localities();
// Reserve storage space for futures, one for each locality.
std::vector<hpx::future<void>> futures;
futures.reserve(localities.size());
for (hpx::id_type const& node : localities)
{
// Asynchronously start a new task. The task is encapsulated in a
// future, which we can query to determine if the task has
// completed.
typedef hello_world_foreman_action action_type;
futures.push_back(hpx::async<action_type>(node));
}
// The non-callback version of hpx::wait_all takes a single parameter,
// a vector of futures to wait on. hpx::wait_all only returns when
// all of the futures have finished.
hpx::wait_all(futures);
return 0;
}
In this excerpt of the code we again see the use of futures. This time the
futures are stored in a vector so that they can easily be accessed.
hpx::wait_all is a family of functions that wait on for an
std::vector<> of futures to become ready. In this piece of code, we are
using the synchronous version of hpx::wait_all, which takes one
argument (the std::vector<> of futures to wait on). This function will not
return until all the futures in the vector have been executed.
In Asynchronous execution with actions we used hpx::find_here to specify the
target of our actions. Here, we instead use
hpx::find_all_localities, which returns an std::vector<>
containing the identifiers of all the machines in the system, including the one
that we are on.
As in Asynchronous execution with actions our futures are set using
hpx::async<>. The hello_world_foreman_action is declared
here:
// Define the boilerplate code necessary for the function 'hello_world_foreman'
// to be invoked as an HPX action.
HPX_PLAIN_ACTION(hello_world_foreman, hello_world_foreman_action)
Another way of thinking about this wrapping technique is as follows: functions (the work to be done) are wrapped in actions, and actions can be executed locally or remotely (e.g. on another machine participating in the computation).
Now it is time to look at the hello_world_foreman() function which was
wrapped in the action above:
void hello_world_foreman()
{
// Get the number of worker OS-threads in use by this locality.
std::size_t const os_threads = hpx::get_os_thread_count();
// Populate a set with the OS-thread numbers of all OS-threads on this
// locality. When the hello world message has been printed on a particular
// OS-thread, we will remove it from the set.
std::set<std::size_t> attendance;
for (std::size_t os_thread = 0; os_thread < os_threads; ++os_thread)
attendance.insert(os_thread);
// As long as there are still elements in the set, we must keep scheduling
// HPX-threads. Because HPX features work-stealing task schedulers, we have
// no way of enforcing which worker OS-thread will actually execute
// each HPX-thread.
while (!attendance.empty())
{
// Each iteration, we create a task for each element in the set of
// OS-threads that have not said "Hello world". Each of these tasks
// is encapsulated in a future.
std::vector<hpx::future<std::size_t>> futures;
futures.reserve(attendance.size());
for (std::size_t worker : attendance)
{
// Asynchronously start a new task. The task is encapsulated in a
// future that we can query to determine if the task has completed.
//
// We give the task a hint to run on a particular worker thread
// (core) and suggest binding the scheduled thread to the given
// core, but no guarantees are given by the scheduler that the task
// will actually run on that worker thread. It will however try as
// hard as possible to place the new task on the given worker
// thread.
hpx::execution::parallel_executor exec(
hpx::threads::thread_priority::bound);
hpx::threads::thread_schedule_hint hint(
hpx::threads::thread_schedule_hint_mode::thread,
static_cast<std::int16_t>(worker));
futures.push_back(
hpx::async(hpx::execution::experimental::with_hint(exec, hint),
hello_world_worker, worker));
}
// Wait for all of the futures to finish. The callback version of the
// hpx::wait_each function takes two arguments: a vector of futures,
// and a binary callback. The callback takes two arguments; the first
// is the index of the future in the vector, and the second is the
// return value of the future. hpx::wait_each doesn't return until
// all the futures in the vector have returned.
hpx::spinlock mtx;
hpx::wait_each(hpx::unwrapping([&](std::size_t t) {
if (std::size_t(-1) != t)
{
std::lock_guard<hpx::spinlock> lk(mtx);
attendance.erase(t);
}
}),
futures);
}
}
Now, before we discuss hello_world_foreman(), let’s talk about the
hpx::wait_each function.
The version of hpx::wait_each invokes a callback function
provided by the user, supplying the callback function with the result of the
future.
In hello_world_foreman(), an std::set<> called attendance keeps
track of which OS-threads have printed out the hello world message. When the
OS-thread prints out the statement, the future is marked as ready, and
hpx::wait_each in hello_world_foreman(). If it is not
executing on the correct OS-thread, it returns a value of -1, which causes
hello_world_foreman() to leave the OS-thread id in attendance.
std::size_t hello_world_worker(std::size_t desired)
{
// Returns the OS-thread number of the worker that is running this
// HPX-thread.
std::size_t current = hpx::get_worker_thread_num();
if (current == desired)
{
// The HPX-thread has been run on the desired OS-thread.
char const* msg = "hello world from OS-thread {1} on locality {2}\n";
hpx::util::format_to(hpx::cout, msg, desired, hpx::get_locality_id())
<< std::flush;
return desired;
}
// This HPX-thread has been run by the wrong OS-thread, make the foreman
// try again by rescheduling it.
return std::size_t(-1);
}
Because HPX features work stealing task schedulers, there is no way to guarantee that an action will be scheduled on a particular OS-thread. This is why we must use a guess-and-check approach.
Components and actions#
The accumulator examples demonstrate the use of components. Components are C++ classes that expose methods as a type of HPX action. These actions are called component actions. There are three examples: - accumulator - template accumulator - template function accumulator
Components are globally named, meaning that a component action can be called remotely (e.g., from another machine). There are two accumulator examples in HPX.
In the Asynchronous execution with actions and the Remote execution with actions, we introduced plain actions, which wrapped global functions. The target of a plain action is an identifier which refers to a particular machine involved in the computation. For plain actions, the target is the machine where the action will be executed.
Component actions, however, do not target machines. Instead, they target component instances. The instance may live on the machine that we’ve invoked the component action from, or it may live on another machine.
The components in these examples expose three different functions:
reset()- Resets the accumulator value to 0.add(arg)- Addsargto the accumulators value.query()- Queries the value of the accumulator.
These examples create an instance of the (template or template function) accumulator, and then allow the user to enter commands at a prompt, which subsequently invoke actions on the accumulator instance.
Accumulator#
Setup#
The source code for this example can be found here:
accumulator_client.cpp.
To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:
$ make examples.accumulators.accumulator
To run the program type:
$ ./bin/accumulator_client
Once the program starts running, it will print the following prompt and then wait for input. An example session is given below:
commands: reset, add [amount], query, help, quit
> add 5
> add 10
> query
15
> add 2
> query
17
> reset
> add 1
> query
1
> quit
Walkthrough#
Now, let’s take a look at the source code of the accumulator example. This
example consists of two parts: an HPX component library (a library that
exposes an HPX component) and a client application which uses the library.
This walkthrough will cover the HPX component library. The code for the client
application can be found here: accumulator_client.cpp.
An HPX component is represented by two C++ classes:
A server class - The implementation of the component’s functionality.
A client class - A high-level interface that acts as a proxy for an instance of the component.
Typically, these two classes both have the same name, but the server class
usually lives in different sub-namespaces (server). For example, the full
names of the two classes in accumulator are:
examples::server::accumulator(server class)examples::accumulator(client class)
The following code is from server/accumulator.hpp.
All HPX component server classes must inherit publicly from the HPX
component base class: hpx::components::component_base
The accumulator component inherits from
hpx::components::locking_hook. This allows the runtime system to
ensure that all action invocations are serialized. That means that the system
ensures that no two actions are invoked at the same time on a given component
instance. This makes the component thread safe and no additional locking has to
be implemented by the user. Moreover, an accumulator component is a component
because it also inherits from hpx::components::component_base (the
template argument passed to locking_hook is used as its base class). The
following snippet shows the corresponding code:
class accumulator
: public hpx::components::locking_hook<
hpx::components::component_base<accumulator>>
Our accumulator class will need a data member to store its value in, so let’s declare a data member:
argument_type value_;
The constructor for this class simply initializes value_ to 0:
accumulator()
: value_(0)
{
}
Next, let’s look at the three methods of this component that we will be exposing as component actions:
Here are the action types. These types wrap the methods we’re exposing. The wrapping technique is very similar to the one used in the Asynchronous execution with actions and the Remote execution with actions:
HPX_DEFINE_COMPONENT_ACTION(accumulator, reset)
HPX_DEFINE_COMPONENT_ACTION(accumulator, add)
HPX_DEFINE_COMPONENT_ACTION(accumulator, query)
The last piece of code in the server class header is the declaration of the action type registration code:
HPX_REGISTER_ACTION_DECLARATION(
examples::server::accumulator::reset_action, accumulator_reset_action)
HPX_REGISTER_ACTION_DECLARATION(
examples::server::accumulator::add_action, accumulator_add_action)
HPX_REGISTER_ACTION_DECLARATION(
examples::server::accumulator::query_action, accumulator_query_action)
Note
The code above must be placed in the global namespace.
The rest of the registration code is in accumulator.cpp
///////////////////////////////////////////////////////////////////////////////
// Add factory registration functionality.
HPX_REGISTER_COMPONENT_MODULE()
///////////////////////////////////////////////////////////////////////////////
typedef hpx::components::component<examples::server::accumulator>
accumulator_type;
HPX_REGISTER_COMPONENT(accumulator_type, accumulator)
///////////////////////////////////////////////////////////////////////////////
// Serialization support for accumulator actions.
HPX_REGISTER_ACTION(
accumulator_type::wrapped_type::reset_action, accumulator_reset_action)
HPX_REGISTER_ACTION(
accumulator_type::wrapped_type::add_action, accumulator_add_action)
HPX_REGISTER_ACTION(
accumulator_type::wrapped_type::query_action, accumulator_query_action)
Note
The code above must be placed in the global namespace.
The following code is from accumulator.hpp
The client class is the primary interface to a component instance. Client classes are used to create components:
// Create a component on this locality.
examples::accumulator c = hpx::new_<examples::accumulator>(hpx::find_here());
and to invoke component actions:
c.add(hpx::launch::apply, 4);
Clients, like servers, need to inherit from a base class, this time,
hpx::components::client_base:
class accumulator
: public hpx::components::client_base<accumulator, server::accumulator>
For readability, we typedef the base class like so:
typedef hpx::components::client_base<accumulator, server::accumulator>
base_type;
Here are examples of how to expose actions through a client class:
There are a few different ways of invoking actions:
Non-blocking: For actions that don’t have return types, or when we do not care about the result of an action, we can invoke the action using fire-and-forget semantics. This means that once we have asked HPX to compute the action, we forget about it completely and continue with our computation. We use
hpx::postto invoke an action in a non-blocking fashion.
void reset(hpx::launch::apply_policy)
{
HPX_ASSERT(this->get_id());
typedef server::accumulator::reset_action action_type;
hpx::post(action_type(), this->get_id());
}
Asynchronous: Futures, as demonstrated in Asynchronous execution, Asynchronous execution with actions, and the Remote execution with actions, enable asynchronous action invocation. Here’s an example from the accumulator client class:
hpx::future<argument_type> query(hpx::launch::async_policy)
{
HPX_ASSERT(this->get_id());
typedef server::accumulator::query_action action_type;
return hpx::async(action_type(), this->get_id());
}
Synchronous: To invoke an action in a fully synchronous manner, we can simply call
hpx::syncwhich is semantically equivalent tohpx::async().get()(i.e., create a future and immediately wait on it to be ready). Here’s an example from the accumulator client class:
void add(argument_type arg)
{
HPX_ASSERT(this->get_id());
typedef server::accumulator::add_action action_type;
action_type()(this->get_id(), arg);
}
Note that this->get_id() references a data member of the
hpx::components::client_base base class which identifies the server
accumulator instance.
hpx::naming::id_type is a type which represents a global identifier
in HPX. This type specifies the target of an action. This is the type that is
returned by hpx::find_here in which case it represents the
locality the code is running on.
Template accumulator#
Walkthrough#
The following code is from server/template_accumulator.hpp.
Similarly to the accumulator example, the component server class
inherits publicly from hpx::components::component_base and from
hpx::components::locking_hook ensuring thread-safe method invocations.
template <typename T>
class template_accumulator
: public hpx::components::locking_hook<
hpx::components::component_base<template_accumulator<T>>>
The body of the template accumulator class remains mainly the same as the accumulator with the difference that it uses templates in the data types.
typedef T argument_type;
template_accumulator()
: value_(0)
{
}
///////////////////////////////////////////////////////////////////////
// Exposed functionality of this component.
/// Reset the components value to 0.
void reset()
{
// set value_ to 0.
value_ = 0;
}
/// Add the given number to the accumulator.
void add(argument_type arg)
{
// add value_ to arg, and store the result in value_.
value_ += arg;
}
/// Return the current value to the caller.
argument_type query() const
{
// Get the value of value_.
return value_;
}
///////////////////////////////////////////////////////////////////////
// Each of the exposed functions needs to be encapsulated into an
// action type, generating all required boilerplate code for threads,
// serialization, etc.
HPX_DEFINE_COMPONENT_ACTION(template_accumulator, reset)
HPX_DEFINE_COMPONENT_ACTION(template_accumulator, add)
HPX_DEFINE_COMPONENT_ACTION(template_accumulator, query)
The last piece of code in the server class header is the declaration of the action type registration code. REGISTER_TEMPLATE_ACCUMULATOR_DECLARATION(type) declares actions for the specified type, while REGISTER_TEMPLATE_ACCUMULATOR(type) registers the actions and the component for the specified type, using macros to handle boilerplate code.
#define REGISTER_TEMPLATE_ACCUMULATOR_DECLARATION(type) \
HPX_REGISTER_ACTION_DECLARATION( \
examples::server::template_accumulator<type>::reset_action, \
HPX_PP_CAT(__template_accumulator_reset_action_, type)) \
\
HPX_REGISTER_ACTION_DECLARATION( \
examples::server::template_accumulator<type>::add_action, \
HPX_PP_CAT(__template_accumulator_add_action_, type)) \
\
HPX_REGISTER_ACTION_DECLARATION( \
examples::server::template_accumulator<type>::query_action, \
HPX_PP_CAT(__template_accumulator_query_action_, type)) \
/**/
#define REGISTER_TEMPLATE_ACCUMULATOR(type) \
HPX_REGISTER_ACTION( \
examples::server::template_accumulator<type>::reset_action, \
HPX_PP_CAT(__template_accumulator_reset_action_, type)) \
\
HPX_REGISTER_ACTION( \
examples::server::template_accumulator<type>::add_action, \
HPX_PP_CAT(__template_accumulator_add_action_, type)) \
\
HPX_REGISTER_ACTION( \
examples::server::template_accumulator<type>::query_action, \
HPX_PP_CAT(__template_accumulator_query_action_, type)) \
\
typedef ::hpx::components::component< \
examples::server::template_accumulator<type>> \
HPX_PP_CAT(__template_accumulator_, type); \
HPX_REGISTER_COMPONENT(HPX_PP_CAT(__template_accumulator_, type)) \
/**/
Note
The code above must be placed in the global namespace.
Finally, HPX_REGISTER_COMPONENT_MODULE() in file server/template_accumulator.cpp adds the factory registration functionality.
The client class of the template accumulator can be found in template_accumulator.hpp and is very similar to the client class of the accumulator with the only difference that it uses templates and hence can work with different types.
Template function accumulator#
Walkthrough#
The following code is from server/template_function_accumulator.hpp.
The component server class inherits publicly from hpx::components::component_base.
class template_function_accumulator
: public hpx::components::component_base<template_function_accumulator>
typedef hpx::spinlock mutex_type defines a mutex_type as hpx::spinlock for thread safety, while the code that follows exposes the functionality of this component.
///////////////////////////////////////////////////////////////////////
// Exposed functionality of this component.
/// Reset the value to 0.
void reset()
{
// Atomically set value_ to 0.
std::lock_guard<mutex_type> l(mtx_);
value_ = 0;
}
/// Add the given number to the accumulator.
template <typename T>
void add(T arg)
{
// Atomically add value_ to arg, and store the result in value_.
std::lock_guard<mutex_type> l(mtx_);
value_ += static_cast<double>(arg);
}
/// Return the current value to the caller.
double query() const
{
// Get the value of value_.
std::lock_guard<mutex_type> l(mtx_);
return value_;
}
reset(): Resets the accumulator value to 0 in a thread-safe manner using std::lock_guard.
add(): Adds a value to the accumulator, allowing any type T that can be cast to double.
query(): Returns the current value of the accumulator in a thread-safe manner.
To define the actions for reset() and query() we can use the macro HPX_DEFINE_COMPONENT_ACTION. However, actions with template arguments require special type definitions. Therefore, we use make_action() to define add().
///////////////////////////////////////////////////////////////////////
// Each of the exposed functions needs to be encapsulated into an
// action type, generating all required boilerplate code for threads,
// serialization, etc.
HPX_DEFINE_COMPONENT_ACTION(template_function_accumulator, reset)
HPX_DEFINE_COMPONENT_ACTION(template_function_accumulator, query)
// Actions with template arguments (see add<>() above) require special
// type definitions. The simplest way to define such an action type is
// by deriving from the HPX facility make_action.
template <typename T>
struct add_action
: hpx::actions::make_action<void (template_function_accumulator::*)(
T),
&template_function_accumulator::template add<T>,
add_action<T>>::type
{
};
The last piece of code in the server class header is the action registration:
HPX_REGISTER_ACTION_DECLARATION(
examples::server::template_function_accumulator::reset_action,
managed_accumulator_reset_action)
HPX_REGISTER_ACTION_DECLARATION(
examples::server::template_function_accumulator::query_action,
managed_accumulator_query_action)
Note
The code above must be placed in the global namespace.
The rest of the registration code is in accumulator.cpp
///////////////////////////////////////////////////////////////////////////////
// Add factory registration functionality.
HPX_REGISTER_COMPONENT_MODULE()
///////////////////////////////////////////////////////////////////////////////
typedef hpx::components::component<
examples::server::template_function_accumulator>
accumulator_type;
HPX_REGISTER_COMPONENT(accumulator_type, template_function_accumulator)
///////////////////////////////////////////////////////////////////////////////
// Serialization support for managed_accumulator actions.
HPX_REGISTER_ACTION(accumulator_type::wrapped_type::reset_action,
managed_accumulator_reset_action)
HPX_REGISTER_ACTION(accumulator_type::wrapped_type::query_action,
managed_accumulator_query_action)
Note
The code above must be placed in the global namespace.
The client class of the template accumulator can be found in template_function_accumulator.hpp and is very similar to the client class of the accumulator with the only difference that it uses templates and hence can work with different types.
Dataflow#
HPX provides its users with several different tools to simply express parallel concepts. One of these tools is a local control object (LCO) called dataflow. An LCO is a type of component that can spawn a new thread when triggered. They are also distinguished from other components by a standard interface that allow users to understand and use them easily. A Dataflow, being an LCO, is triggered when the values it depends on become available. For instance, if you have a calculation X that depends on the results of three other calculations, you could set up a dataflow that would begin the calculation X as soon as the other three calculations have returned their values. Dataflows are set up to depend on other dataflows. It is this property that makes dataflow a powerful parallelization tool. If you understand the dependencies of your calculation, you can devise a simple algorithm that sets up a dependency tree to be executed. In this example, we calculate compound interest. To calculate compound interest, one must calculate the interest made in each compound period, and then add that interest back to the principal before calculating the interest made in the next period. A practical person would, of course, use the formula for compound interest:
where \(F\) is the future value, \(P\) is the principal value, \(i\) is the interest rate, and \(n\) is the number of compound periods.
However, for the sake of this example, we have chosen to manually calculate the future value by iterating:
and
Setup#
The source code for this example can be found here:
interest_calculator.cpp.
To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:
$ make examples.quickstart.interest_calculator
To run the program type:
$ ./bin/interest_calculator --principal 100 --rate 5 --cp 6 --time 36
Final amount: 134.01
Amount made: 34.0096
Walkthrough#
Let us begin with main. Here we can see that we again are using
Boost.Program_options to set our command line variables (see
Asynchronous execution with actions for more details). These options set the principal,
rate, compound period, and time. It is important to note that the units of time
for cp and time must be the same.
int main(int argc, char** argv)
{
options_description cmdline("Usage: " HPX_APPLICATION_STRING " [options]");
cmdline.add_options()("principal", value<double>()->default_value(1000),
"The principal [$]")("rate", value<double>()->default_value(7),
"The interest rate [%]")("cp", value<int>()->default_value(12),
"The compound period [months]")("time",
value<int>()->default_value(12 * 30),
"The time money is invested [months]");
hpx::init_params init_args;
init_args.desc_cmdline = cmdline;
return hpx::init(argc, argv, init_args);
}
Next we look at hpx_main.
int hpx_main(variables_map& vm)
{
{
using hpx::dataflow;
using hpx::make_ready_future;
using hpx::shared_future;
using hpx::unwrapping;
hpx::id_type here = hpx::find_here();
double init_principal =
vm["principal"].as<double>(); //Initial principal
double init_rate = vm["rate"].as<double>(); //Interest rate
int cp = vm["cp"].as<int>(); //Length of a compound period
int t = vm["time"].as<int>(); //Length of time money is invested
init_rate /= 100; //Rate is a % and must be converted
t /= cp; //Determine how many times to iterate interest calculation:
//How many full compound periods can fit in the time invested
// In non-dataflow terms the implemented algorithm would look like:
//
// int t = 5; // number of time periods to use
// double principal = init_principal;
// double rate = init_rate;
//
// for (int i = 0; i < t; ++i)
// {
// double interest = calc(principal, rate);
// principal = add(principal, interest);
// }
//
// Please note the similarity with the code below!
shared_future<double> principal = make_ready_future(init_principal);
shared_future<double> rate = make_ready_future(init_rate);
for (int i = 0; i < t; ++i)
{
shared_future<double> interest =
dataflow(unwrapping(calc), principal, rate);
principal = dataflow(unwrapping(add), principal, interest);
}
// wait for the dataflow execution graph to be finished calculating our
// overall interest
double result = principal.get();
std::cout << "Final amount: " << result << std::endl;
std::cout << "Amount made: " << result - init_principal << std::endl;
}
return hpx::finalize();
}
Here we find our command line variables read in, the rate is converted from a
percent to a decimal, the number of calculation iterations is determined, and
then our shared_futures are set up. Notice that we first place our principal and
rate into shares futures by passing the variables init_principal and
init_rate using hpx::make_ready_future.
In this way hpx::shared_future<double> principal
and rate will be initialized to init_principal and init_rate when
hpx::make_ready_future<double> returns a future containing
those initial values. These shared futures then enter the for loop and are
passed to interest. Next principal and interest are passed to the
reassignment of principal using a hpx::dataflow. A dataflow
will first wait for its arguments to be ready before launching any callbacks, so
add in this case will not begin until both principal and interest
are ready. This loop continues for each compound period that must be calculated.
To see how interest and principal are calculated in the loop, let us look
at calc_action and add_action:
// Calculate interest for one period
double calc(double principal, double rate)
{
return principal * rate;
}
///////////////////////////////////////////////////////////////////////////////
// Add the amount made to the principal
double add(double principal, double interest)
{
return principal + interest;
}
After the shared future dependencies have been defined in hpx_main, we see the following statement:
double result = principal.get();
This statement calls hpx::future::get on the shared future
principal which had its value calculated by our for loop. The program will wait
here until the entire dataflow tree has been calculated and the value assigned
to result. The program then prints out the final value of the investment and the
amount of interest made by subtracting the final value of the investment from
the initial value of the investment.
Local to remote#
When developers write code they typically begin with a simple serial code and build upon it until all of the required functionality is present. The following set of examples were developed to demonstrate this iterative process of evolving a simple serial program to an efficient, fully-distributed HPX application. For this demonstration, we implemented a 1D heat distribution problem. This calculation simulates the diffusion of heat across a ring from an initialized state to some user-defined point in the future. It does this by breaking each portion of the ring into discrete segments and using the current segment’s temperature and the temperature of the surrounding segments to calculate the temperature of the current segment in the next timestep as shown by Fig. 2 below.
Fig. 2 Heat diffusion example program flow.#
We parallelize this code over the following eight examples:
The first example is straight serial code. In this code we instantiate a vector
U that contains two vectors of doubles as seen in the structure
stepper.
struct stepper
{
// Our partition type
typedef double partition;
// Our data for one time step
typedef std::vector<partition> space;
// Our operator
static double heat(double left, double middle, double right)
{
return middle + (k * dt / (dx * dx)) * (left - 2 * middle + right);
}
// do all the work on 'nx' data points for 'nt' time steps
space do_work(std::size_t nx, std::size_t nt)
{
// U[t][i] is the state of position i at time t.
std::vector<space> U(2);
for (space& s : U)
s.resize(nx);
// Initial conditions: f(0, i) = i
for (std::size_t i = 0; i != nx; ++i)
U[0][i] = double(i);
// Actual time step loop
for (std::size_t t = 0; t != nt; ++t)
{
space const& current = U[t % 2];
space& next = U[(t + 1) % 2];
next[0] = heat(current[nx - 1], current[0], current[1]);
for (std::size_t i = 1; i != nx - 1; ++i)
next[i] = heat(current[i - 1], current[i], current[i + 1]);
next[nx - 1] = heat(current[nx - 2], current[nx - 1], current[0]);
}
// Return the solution at time-step 'nt'.
return U[nt % 2];
}
};
Each element in the vector of doubles represents a single grid point. To
calculate the change in heat distribution, the temperature of each grid point,
along with its neighbors, is passed to the function heat. In order to
improve readability, references named current and next are created
which, depending on the time step, point to the first and second vector of
doubles. The first vector of doubles is initialized with a simple heat ramp.
After calling the heat function with the data in the current vector, the
results are placed into the next vector.
In example 2 we employ a technique called futurization. Futurization is a method
by which we can easily transform a code that is serially executed into a code
that creates asynchronous threads. In the simplest case this involves replacing
a variable with a future to a variable, a function with a future to a function,
and adding a .get() at the point where a value is actually needed. The code
below shows how this technique was applied to the struct stepper.
struct stepper
{
// Our partition type
typedef hpx::shared_future<double> partition;
// Our data for one time step
typedef std::vector<partition> space;
// Our operator
static double heat(double left, double middle, double right)
{
return middle + (k * dt / (dx * dx)) * (left - 2 * middle + right);
}
// do all the work on 'nx' data points for 'nt' time steps
hpx::future<space> do_work(std::size_t nx, std::size_t nt)
{
using hpx::dataflow;
using hpx::unwrapping;
// U[t][i] is the state of position i at time t.
std::vector<space> U(2);
for (space& s : U)
s.resize(nx);
// Initial conditions: f(0, i) = i
for (std::size_t i = 0; i != nx; ++i)
U[0][i] = hpx::make_ready_future(double(i));
auto Op = unwrapping(&stepper::heat);
// Actual time step loop
for (std::size_t t = 0; t != nt; ++t)
{
space const& current = U[t % 2];
space& next = U[(t + 1) % 2];
// WHEN U[t][i-1], U[t][i], and U[t][i+1] have been computed, THEN we
// can compute U[t+1][i]
for (std::size_t i = 0; i != nx; ++i)
{
next[i] =
dataflow(hpx::launch::async, Op, current[idx(i, -1, nx)],
current[i], current[idx(i, +1, nx)]);
}
}
// Now the asynchronous computation is running; the above for-loop does not
// wait on anything. There is no implicit waiting at the end of each timestep;
// the computation of each U[t][i] will begin as soon as its dependencies
// are ready and hardware is available.
// Return the solution at time-step 'nt'.
return hpx::when_all(U[nt % 2]);
}
};
In example 2, we redefine our partition type as a shared_future and, in
main, create the object result, which is a future to a vector of
partitions. We use result to represent the last vector in a string of
vectors created for each timestep. In order to move to the next timestep, the
values of a partition and its neighbors must be passed to heat once the
futures that contain them are ready. In HPX, we have an LCO (Local Control
Object) named Dataflow that assists the programmer in expressing this
dependency. Dataflow allows us to pass the results of a set of futures to a
specified function when the futures are ready. Dataflow takes three types of
arguments, one which instructs the dataflow on how to perform the function call
(async or sync), the function to call (in this case Op), and futures to the
arguments that will be passed to the function. When called, dataflow immediately
returns a future to the result of the specified function. This allows users to
string dataflows together and construct an execution tree.
After the values of the futures in dataflow are ready, the values must be pulled
out of the future container to be passed to the function heat. In order to
do this, we use the HPX facility unwrapping, which underneath calls
.get() on each of the futures so that the function heat will be passed
doubles and not futures to doubles.
By setting up the algorithm this way, the program will be able to execute as quickly as the dependencies of each future are met. Unfortunately, this example runs terribly slow. This increase in execution time is caused by the overheads needed to create a future for each data point. Because the work done within each call to heat is very small, the overhead of creating and scheduling each of the three futures is greater than that of the actual useful work! In order to amortize the overheads of our synchronization techniques, we need to be able to control the amount of work that will be done with each future. We call this amount of work per overhead grain size.
In example 3, we return to our serial code to figure out how to control the
grain size of our program. The strategy that we employ is to create “partitions”
of data points. The user can define how many partitions are created and how many
data points are contained in each partition. This is accomplished by creating
the struct partition, which contains a member object data_, a vector of
doubles that holds the data points assigned to a particular instance of
partition.
In example 4, we take advantage of the partition setup by redefining space
to be a vector of shared_futures with each future representing a partition. In
this manner, each future represents several data points. Because the user can
define how many data points are in each partition, and, therefore, how
many data points are represented by one future, a user can control the
grainsize of the simulation. The rest of the code is then futurized in the same
manner as example 2. It should be noted how strikingly similar
example 4 is to example 2.
Example 4 finally shows good results. This code scales equivalently to the OpenMP version. While these results are promising, there are more opportunities to improve the application’s scalability. Currently, this code only runs on one locality, but to get the full benefit of HPX, we need to be able to distribute the work to other machines in a cluster. We begin to add this functionality in example 5.
In order to run on a distributed system, a large amount of boilerplate code must
be added. Fortunately, HPX provides us with the concept of a component,
which saves us from having to write quite as much code. A component is an object
that can be remotely accessed using its global address. Components are made of
two parts: a server and a client class. While the client class is not required,
abstracting the server behind a client allows us to ensure type safety instead
of having to pass around pointers to global objects. Example 5 renames example
4’s struct partition to partition_data and adds serialization support.
Next, we add the server side representation of the data in the structure
partition_server. Partition_server inherits from
hpx::components::component_base, which contains a server-side component
boilerplate. The boilerplate code allows a component’s public members to be
accessible anywhere on the machine via its Global Identifier (GID). To
encapsulate the component, we create a client side helper class. This object
allows us to create new instances of our component and access its members
without having to know its GID. In addition, we are using the client class to
assist us with managing our asynchrony. For example, our client class
partition‘s member function get_data() returns a future to
partition_data get_data(). This struct inherits its boilerplate code from
hpx::components::client_base.
In the structure stepper, we have also had to make some changes to
accommodate a distributed environment. In order to get the data from a
particular neighboring partition, which could be remote, we must retrieve the data from all
of the neighboring partitions. These retrievals are asynchronous and the function
heat_part_data, which, amongst other things, calls heat, should not be
called unless the data from the neighboring partitions have arrived. Therefore,
it should come as no surprise that we synchronize this operation with another
instance of dataflow (found in heat_part). This dataflow receives futures
to the data in the current and surrounding partitions by calling get_data()
on each respective partition. When these futures are ready, dataflow passes them
to the unwrapping function, which extracts the shared_array of doubles and
passes them to the lambda. The lambda calls heat_part_data on the
locality, which the middle partition is on.
Although this example could run distributed, it only runs on one
locality, as it always uses hpx::find_here() as the target for the
functions to run on.
In example 6, we begin to distribute the partition data on different nodes. This
is accomplished in stepper::do_work() by passing the GID of the
locality where we wish to create the partition to the partition
constructor.
for (std::size_t i = 0; i != np; ++i)
U[0][i] = partition(localities[locidx(i, np, nl)], nx, double(i));
We distribute the partitions evenly based on the number of localities used,
which is described in the function locidx. Because some of the data needed
to update the partition in heat_part could now be on a new locality,
we must devise a way of moving data to the locality of the middle
partition. We accomplished this by adding a switch in the function
get_data() that returns the end element of the buffer data_ if it is
from the left partition or the first element of the buffer if the data is from
the right partition. In this way only the necessary elements, not the whole
buffer, are exchanged between nodes. The reader should be reminded that this
exchange of end elements occurs in the function get_data() and, therefore, is
executed asynchronously.
Now that we have the code running in distributed, it is time to make some
optimizations. The function heat_part spends most of its time on two tasks:
retrieving remote data and working on the data in the middle partition. Because
we know that the data for the middle partition is local, we can overlap the work
on the middle partition with that of the possibly remote call of get_data().
This algorithmic change, which was implemented in example 7, can be seen below:
// The partitioned operator, it invokes the heat operator above on all elements
// of a partition.
static partition heat_part(
partition const& left, partition const& middle, partition const& right)
{
using hpx::dataflow;
using hpx::unwrapping;
hpx::shared_future<partition_data> middle_data =
middle.get_data(partition_server::middle_partition);
hpx::future<partition_data> next_middle = middle_data.then(
unwrapping([middle](partition_data const& m) -> partition_data {
HPX_UNUSED(middle);
// All local operations are performed once the middle data of
// the previous time step becomes available.
std::size_t size = m.size();
partition_data next(size);
for (std::size_t i = 1; i != size - 1; ++i)
next[i] = heat(m[i - 1], m[i], m[i + 1]);
return next;
}));
return dataflow(hpx::launch::async,
unwrapping([left, middle, right](partition_data next,
partition_data const& l, partition_data const& m,
partition_data const& r) -> partition {
HPX_UNUSED(left);
HPX_UNUSED(right);
// Calculate the missing boundary elements once the
// corresponding data has become available.
std::size_t size = m.size();
next[0] = heat(l[size - 1], m[0], m[1]);
next[size - 1] = heat(m[size - 2], m[size - 1], r[0]);
// The new partition_data will be allocated on the same locality
// as 'middle'.
return partition(middle.get_id(), std::move(next));
}),
std::move(next_middle),
left.get_data(partition_server::left_partition), middle_data,
right.get_data(partition_server::right_partition));
}
Example 8 completes the futurization process and utilizes the full potential of
HPX by distributing the program flow to multiple localities, usually defined as
nodes in a cluster. It accomplishes this task by running an instance of HPX main
on each locality. In order to coordinate the execution of the program,
the struct stepper is wrapped into a component. In this way, each
locality contains an instance of stepper that executes its own instance
of the function do_work(). This scheme does create an interesting
synchronization problem that must be solved. When the program flow was being
coordinated on the head node, the GID of each component was known. However, when
we distribute the program flow, each partition has no notion of the GID of its
neighbor if the next partition is on another locality. In order to make
the GIDs of neighboring partitions visible to each other, we created two buffers
to store the GIDs of the remote neighboring partitions on the left and right
respectively. These buffers are filled by sending the GID of newly created
edge partitions to the right and left buffers of the neighboring localities.
In order to finish the simulation, the solution vectors named result are then
gathered together on locality 0 and added into a vector of spaces
overall_result using the HPX functions gather_id and gather_here.
Example 8 completes this example series, which takes the serial code of example 1 and incrementally morphs it into a fully distributed parallel code. This evolution was guided by the simple principles of futurization, the knowledge of grainsize, and utilization of components. Applying these techniques easily facilitates the scalable parallelization of most applications.
Serializing user-defined types#
In order to facilitate the sending and receiving of complex datatypes HPX provides a serialization abstraction.
Just like boost, hpx allows users to serialize user-defined types by either providing the serializer as a member function or defining the serialization as a free function.
Unlike Boost HPX doesn’t acknowledge second unsigned int parameter, it is solely there to preserve API compatibility with Boost Serialization
This is tutorial was heavily inspired by Boost’s serialization concepts.
Setup#
The source code for this example can be found here:
custom_serialization.cpp.
To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:
$ make examples.quickstart.custom_serialization
To run the program type:
$ ./bin/custom_serialization
This should print:
Rectangle(Point(x=0,y=0),Point(x=0,y=5))
gravity.g = 9.81%
Serialization Requirements#
In order to serialize objects in HPX, at least one of the following criteria must be met:
In the case of default constructible objects:
The object is an empty type.
Has a serialization function as shown in this tutorial.
All members are accessible publicly and they can be used in structured binding contexts.
Otherwise:
They need to have special serialization support.
Member function serialization#
struct point_member_serialization
{
int x{0};
int y{0};
// Required when defining the serialization function as private
// In this case it isn't
// Provides serialization access to HPX
friend class hpx::serialization::access;
// Second argument exists solely for compatibility with boost serialize
// it is NOT processed by HPX in any way.
template <typename Archive>
void serialize(Archive& ar, const unsigned int)
{
// clang-format off
ar & x & y;
// clang-format on
}
};
// Allow bitwise serialization
HPX_IS_BITWISE_SERIALIZABLE(point_member_serialization)
Notice that point_member_serialization is defined as bitwise serializable
(see Bitwise serialization for bitwise copyable data for more details).
HPX is also able to recursively serialize composite classes and structs
given that its members are serializable.
struct rectangle_member_serialization
{
point_member_serialization top_left;
point_member_serialization lower_right;
template <typename Archive>
void serialize(Archive& ar, const unsigned int)
{
// clang-format off
ar & top_left & lower_right;
// clang-format on
}
};
Free function serialization#
In order to decouple your models from HPX, HPX also allows for the definition of free function serializers.
struct rectangle_free
{
point_member_serialization top_left;
point_member_serialization lower_right;
};
template <typename Archive>
void serialize(Archive& ar, rectangle_free& pt, const unsigned int)
{
// clang-format off
ar & pt.lower_right & pt.top_left;
// clang-format on
}
Even if you can’t modify a class to befriend it, you can still be able to serialize your class provided that your class is default constructable and you are able to reconstruct it yourself.
class point_class
{
public:
point_class(int x, int y)
: x(x)
, y(y)
{
}
point_class() = default;
[[nodiscard]] int get_x() const noexcept
{
return x;
}
[[nodiscard]] int get_y() const noexcept
{
return y;
}
private:
int x;
int y;
};
template <typename Archive>
void load(Archive& ar, point_class& pt, const unsigned int)
{
int x, y;
ar >> x >> y;
pt = point_class(x, y);
}
template <typename Archive>
void save(Archive& ar, point_class const& pt, const unsigned int)
{
ar << pt.get_x() << pt.get_y();
}
// This tells HPX that you have spilt your serialize function into
// load and save
HPX_SERIALIZATION_SPLIT_FREE(point_class)
Serializing non default constructable classes#
Some classes don’t provide any default constructor.
class planet_weight_calculator
{
public:
explicit planet_weight_calculator(double g)
: g(g)
{
}
template <class Archive>
friend void save_construct_data(
Archive&, planet_weight_calculator const*, unsigned int);
[[nodiscard]] double get_g() const
{
return g;
}
private:
// Provides serialization access to HPX
friend class hpx::serialization::access;
template <class Archive>
void serialize(Archive&, const unsigned int)
{
// Serialization will be done in the save_construct_data
// Still needs to be defined
}
double g;
};
In this case you have to define a save_construct_data and load_construct_data in which you
do the serialization yourself.
template <class Archive>
inline void save_construct_data(Archive& ar,
planet_weight_calculator const* weight_calc, const unsigned int)
{
ar << weight_calc->g; // Do all of your serialization here
}
template <class Archive>
inline void load_construct_data(
Archive& ar, planet_weight_calculator* weight_calc, const unsigned int)
{
double g;
ar >> g;
// ::new(ptr) construct new object at given address
hpx::construct_at(weight_calc, g);
}
Bitwise serialization for bitwise copyable data#
When sending non arithmetic types not defined by
std::is_arithmetic, HPX has to (de)serialize each object
separately. However, if the class you are trying to send classes consists only of bitwise copyable datatypes,
you may mark your class as such.
Then HPX will serialize your object bitwise instead of element wise.
This has enormous benefits, especially when sending a vector/array of your class.
To define your class as such you need to call HPX_IS_BITWISE_SERIALIZABLE(T) with your desired custom class.
struct point_member_serialization
{
int x{0};
int y{0};
// Required when defining the serialization function as private
// In this case it isn't
// Provides serialization access to HPX
friend class hpx::serialization::access;
// Second argument exists solely for compatibility with boost serialize
// it is NOT processed by HPX in any way.
template <typename Archive>
void serialize(Archive& ar, const unsigned int)
{
// clang-format off
ar & x & y;
// clang-format on
}
};
// Allow bitwise serialization
HPX_IS_BITWISE_SERIALIZABLE(point_member_serialization)
Manual#
The manual is your comprehensive guide to HPX. It contains detailed information on how to build and use HPX in different scenarios.
Prerequisites#
Supported platforms#
At this time, HPX supports the following platforms. Other platforms may work, but we do not test HPX with other platforms, so please be warned.
Name |
Minimum Version |
Architectures |
|---|---|---|
Linux |
2.6 |
x86-32, x86-64, k1om |
BlueGeneQ |
V1R2M0 |
PowerPC A2 |
Windows |
Any Windows system |
x86-32, x86-64 |
Mac OSX |
Any OSX system |
x86-64 |
ARM |
Any ARM system |
Any architecture |
RISC-V |
Any RISC-V system |
Any architecture |
Supported compilers#
The table below shows the supported compilers for HPX.
Name |
Minimum Version |
|---|---|
9.0 |
|
10.0 |
|
Visual C++ (x64) |
2019 |
Software and libraries#
The table below presents all the necessary prerequisites for building HPX.
Name |
Minimum Version |
|
|---|---|---|
Build System |
3.18 |
|
Required Libraries |
1.71.0 |
|
1.5 |
The most important dependencies are Boost and Portable Hardware Locality (HWLOC). The installation of Boost is described in detail in Boost’s Getting Started document. A recent version of hwloc is required in order to support thread pinning and NUMA awareness and can be found in Hwloc Downloads.
HPX is written in 99.99% Standard C++ (the remaining 0.01% is platform specific assembly code). As such, HPX is compilable with almost any standards compliant C++ compiler. The code base takes advantage of C++ language and standard library features when available.
Note
When building Boost using gcc, please note that it is required to specify a
cxxflags=-std=c++17 command line argument to b2 (bjam).
Note
In most configurations, HPX depends only on header-only Boost. Boost.Filesystem is required if the standard library does not support filesystem. The following are not needed by default, but are required in certain configurations: Boost.Chrono, Boost.DateTime, Boost.Log, Boost.LogSetup, Boost.Regex, and Boost.Thread.
Depending on the options you chose while building and installing HPX, you will find that HPX may depend on several other libraries such as those listed below.
Note
In order to use a high speed parcelport, we currently recommend configuring
HPX to use MPI so that MPI can be used for communication between different
localities. Please set the CMake variable MPI_CXX_COMPILER to your MPI
C++ compiler wrapper if not detected automatically.
Name |
Minimum version |
1.7.1 |
|
2.1.0 |
|
1.0.0 |
|
Performance Application Programming Interface (PAPI) |
Getting HPX#
Download a tarball of the latest release from HPX Downloads and
unpack it or clone the repository directly using git:
$ git clone https://github.com/STEllAR-GROUP/hpx.git
It is also recommended that you check out the latest stable tag:
$ cd hpx
$ git checkout v1.11.0
Building HPX#
Basic information#
The build system for HPX is based on CMake, a cross-platform build-generator tool which is not responsible for building the project but rather generates the files needed by your build tool (GNU make, Visual Studio, etc.) for building HPX. If CMake is not already installed in your system, you can download it and install it here: CMake Downloads.
Once CMake has been run, the build process can be started. The build process consists of the following parts:
The HPX core libraries (target
core): This forms the basic set of HPX libraries.HPX Examples (target
examples): This target is enabled by default and builds all HPX examples (disable by settingHPX_WITH_EXAMPLES:BOOL=Off). HPX examples are part of thealltarget and are included in the installation if enabled.HPX Tests (target
tests): This target builds the HPX test suite and is enabled by default (disable by settingHPX_WITH_TESTS:BOOL=Off). They are not built by thealltarget and have to be built separately.HPX Documentation (target
docs): This target builds the documentation, and is not enabled by default (enable by settingHPX_WITH_DOCUMENTATION:BOOL=On. For more information see Documentation.
The HPX build process is highly configurable through CMake, and various CMake variables influence the build process. A list with the most important CMake variables can be found in the section that follows, while the complete list of available CMake variables is in CMake options. These variables can be used to refine the recipes that can be found at Platform specific build recipes, a section that shows some basic steps on how to build HPX for a specific platform.
In order to use HPX, only the core libraries are required. In order to use the optional libraries, you need to specify them as link dependencies in your build (See Creating HPX projects).
Most important CMake options#
While building HPX, you are provided with multiple CMake options which correspond to different configurations. Below, there is a set of the most important and frequently used CMake options.
- HPX_WITH_MALLOC#
Use a custom allocator. Using a custom allocator tuned for multithreaded applications is very important for the performance of HPX applications. When debugging applications, it’s useful to set this to
system, as custom allocators can hide some memory-related bugs. Note that setting this to something other thansystemrequires an external dependency.
- HPX_WITH_CUDA#
Enable support for CUDA. Use
CMAKE_CUDA_COMPILERto set the CUDA compiler. This is a standard CMake variable, likeCMAKE_CXX_COMPILER.
- HPX_WITH_PARCELPORT_MPI#
Enable the MPI parcelport. This enables the use of MPI for the networking operations in the HPX runtime. The default value is
OFFbecause it’s not available on all systems and/or requires another dependency. However, it is the recommended parcelport.
- HPX_WITH_PARCELPORT_TCP#
Enable the TCP parcelport. Enables the use of TCP for networking in the runtime. The default value is
ON. However, it’s only recommended for debugging purposes, as it is slower than the MPI parcelport.
- HPX_WITH_PARCELPORT_LCI#
Enable the LCI parcelport. This enables the use of LCI for the networking operations in the HPX runtime. The default value is
OFFbecause it’s not available on all systems and/or requires another dependency. However, this experimental parcelport may provide better performance than the MPI parcelport. Please refer to Using the LCI parcelport for more information about the LCI parcelport.
- HPX_WITH_APEX#
Enable APEX integration. APEX can be used to profile HPX applications. In particular, it provides information about individual tasks in the HPX runtime.
- HPX_WITH_GENERIC_CONTEXT_COROUTINES#
Enable Boost. Context for task context switching. It must be enabled for non-x86 architectures such as ARM and Power.
- HPX_WITH_MAX_CPU_COUNT#
Set the maximum CPU count supported by HPX. The default value is 64, and should be set to a number at least as high as the number of cores on a system including virtual cores such as hyperthreads.
- HPX_WITH_CXX_STANDARD#
Set a specific C++ standard version e.g.
HPX_WITH_CXX_STANDARD=20. The default and minimum value is 17.
- HPX_WITH_EXAMPLES#
Build examples.
- HPX_WITH_TESTS#
Build tests.
For a complete list of available CMake variables that influence the build of HPX, see CMake options.
Build types#
CMake can be configured to generate project files suitable for builds that
have enabled debugging support or for an optimized build (without debugging
support). The CMake variable used to set the build type is
CMAKE_BUILD_TYPE (for more information see the CMake Documentation).
Available build types are:
Debug: Full debug symbols are available as well as additional assertions to help debugging. To enable the debug build type for the HPX API, the C++ Macro
HPX_DEBUGis defined.RelWithDebInfo: Release build with debugging symbols. This is most useful for profiling applications
Release: Release build. This disables assertions and enables default compiler optimizations.
RelMinSize: Release build with optimizations for small binary sizes.
Important
We currently don’t guarantee ABI compatibility between Debug and Release
builds. Please make sure that applications built against HPX use the same
build type as you used to build HPX. For CMake builds, this means that
the CMAKE_BUILD_TYPE variables have to match and for projects not using
CMake, the HPX_DEBUG macro has to be set in debug mode.
Platform specific build recipes#
Unix variants#
Once you have the source code and the dependencies and assuming all your dependencies are in paths known to CMake, the following gets you started:
First, set up a separate build directory to configure the project:
$ mkdir build && cd build
To configure the project you have the following options:
To build the core HPX libraries and examples, and install them to your chosen location (recommended):
$ cmake -DCMAKE_INSTALL_PREFIX=/install/path ..
Tip
If you want to change CMake variables for your build, it is usually a good idea to start with a clean build directory to avoid configuration problems. It is especially important that you use a clean build directory when changing between
ReleaseandDebugmodes.To install HPX to the default system folders, simply leave out the
CMAKE_INSTALL_PREFIXoption:
$ cmake ..If your dependencies are in custom locations, you may need to tell CMake where to find them by passing one or more options to CMake as shown below:
$ cmake -DBoost_ROOT=/path/to/boost -DHwloc_ROOT=/path/to/hwloc -DTcmalloc_ROOT=/path/to/tcmalloc -DJemalloc_ROOT=/path/to/jemalloc [other CMake variable definitions] /path/to/source/tree
For instance:
$ cmake -DBoost_ROOT=~/packages/boost -DHwloc_ROOT=/packages/hwloc -DCMAKE_INSTALL_PREFIX=~/packages/hpx ~/downloads/hpx_1.5.1
If you want to try HPX without using a custom allocator pass
-DHPX_WITH_MALLOC=systemto CMake:
$ cmake -DCMAKE_INSTALL_PREFIX=/install/path -DHPX_WITH_MALLOC=system ..
Note
Please pay special attention to the section about
HPX_WITH_MALLOC:STRINGas this is crucial for getting decent performance.Important
If you are building HPX for a system with more than 64 processing units, you must change the CMake variable
HPX_WITH_MAX_CPU_COUNT(to a value at least as big as the number of (virtual) cores on your system). Note that the default value is 64.Caution
Compiling and linking HPX needs a considerable amount of memory. It is advisable that at least 2 GB of memory per parallel process is available.
Once the configuration is complete, to build the project you run:
$ cmake --build . --target install
Windows#
Note
The following build recipes are mostly user-contributed and may be outdated. We always welcome updated and new build recipes.
To build HPX under Windows 10 x64 with Visual Studio 2015:
Download the CMake V3.18.1 installer (or latest version) from here
Download the hwloc V1.11.0 (or the latest version) from here and unpack it.
Download the latest Boost libraries from here and unpack them.
Build the Boost DLLs and LIBs by using these commands from Command Line (or PowerShell). Open CMD/PowerShell inside the Boost dir and type in:
.\bootstrap.batThis batch file will set up everything needed to create a successful build. Now execute:
.\b2.exe link=shared variant=release,debug architecture=x86 address-model=64 threading=multi --build-type=complete install
This command will start a (very long) build of all available Boost libraries. Please, be patient.
Open CMake-GUI.exe and set up your source directory (input field ‘Where is the source code’) to the base directory of the source code you downloaded from HPX’s GitHub pages. Here’s an example of CMake path settings, which point to the
Documents/GitHub/hpxfolder:
Fig. 3 Example CMake path settings.#
Inside ‘Where is the source-code’ enter the base directory of your HPX source directory (do not enter the “src” sub-directory!). Inside ‘Where to build the binaries’ you should put in the path where all the building processes will happen. This is important because the building machinery will do an “out-of-tree” build. CMake will not touch or change the original source files in any way. Instead, it will generate Visual Studio Solution Files, which will build HPX packages out of the HPX source tree.
Set new configuration variables (in CMake, not in Windows environment):
Boost_ROOT,Hwloc_ROOT,Asio_ROOT,CMAKE_INSTALL_PREFIX. The meaning of these variables is as follows:Boost_ROOTthe HPX root directory of the unpacked Boost headers/cpp files.Hwloc_ROOTthe HPX root directory of the unpacked Portable Hardware Locality files.Asio_ROOTthe HPX root directory of the unpacked ASIO files. Alternatively useHPX_WITH_FETCH_ASIOwith valueTrue.CMAKE_INSTALL_PREFIXthe HPX root directory where the future builds of HPX should be installed.Note
HPX is a very large software collection, so it is not recommended to use the default
C:\Program Files\hpx. Many users may prefer to use simpler paths without whitespace, likeC:\bin\hpxorD:\bin\hpxetc.
To insert new env-vars click on “Add Entry” and then insert the name inside “Name”, select
PATHas Type and put the path-name in the “Path” text field. Repeat this for the first three variables.This is how variable insertion will look:
Fig. 4 Example CMake adding entry.#
Alternatively, users could provide
Boost_LIBRARYDIRinstead ofBoost_ROOT; the difference is thatBoost_LIBRARYDIRshould point to the subdirectory inside Boost root where all the compiled DLLs/LIBs are. For example,Boost_LIBRARYDIRmay point to thebin.v2subdirectory under the Boost rootdir. It is important to keep the meanings of these two variables separated from each other:Boost_DIRpoints to the ROOT folder of the Boost library.Boost_LIBRARYDIRpoints to the subdir inside the Boost root folder where the compiled binaries are.Click the ‘Configure’ button of CMake-GUI. You will be immediately presented with a small window where you can select the C++ compiler to be used within Visual Studio. This has been tested using the latest v14 (a.k.a C++ 2015) but older versions should be sufficient too. Make sure to select the 64Bit compiler.
After the generate process has finished successfully, click the ‘Generate’ button. Now, CMake will put new VS Solution files into the BUILD folder you selected at the beginning.
Open Visual Studio and load the
HPX.slnfrom your build folder.Go to
CMakePredefinedTargetsand build theINSTALLproject:
Fig. 5 Visual Studio INSTALL target.#
It will take some time to compile everything, and in the end you should see an output similar to this one:
Fig. 6 Visual Studio build output.#
CMake options#
In order to configure HPX, you can set a variety of options to allow CMake to generate your specific makefiles/project files. A list of the most important CMake options can be found in Most important CMake options, while this section includes the comprehensive list.
Variables that influence how HPX is built#
The options are split into these categories:
Generic options#
- HPX_WITH_AUTOMATIC_SERIALIZATION_REGISTRATION:BOOL#
Use automatic serialization registration for actions and functions. This affects compatibility between HPX applications compiled with different compilers (default ON)
- HPX_WITH_BENCHMARK_SCRIPTS_PATH:PATH#
Directory to place batch scripts in
- HPX_WITH_BUILD_BINARY_PACKAGE:BOOL#
Build HPX on the build infrastructure on any LINUX distribution (default: OFF).
- HPX_WITH_CHECK_MODULE_DEPENDENCIES:BOOL#
Verify that no modules are cross-referenced from a different module category (default: OFF)
- HPX_WITH_COMPILER_WARNINGS:BOOL#
Enable compiler warnings (default: ON)
- HPX_WITH_COMPILER_WARNINGS_AS_ERRORS:BOOL#
Turn compiler warnings into errors (default: OFF)
- HPX_WITH_COMPRESSION_BZIP2:BOOL#
Enable bzip2 compression for parcel data (default: OFF).
- HPX_WITH_COMPRESSION_SNAPPY:BOOL#
Enable snappy compression for parcel data (default: OFF).
- HPX_WITH_COMPRESSION_ZLIB:BOOL#
Enable zlib compression for parcel data (default: OFF).
- HPX_WITH_CUDA:BOOL#
Enable support for CUDA (default: OFF)
- HPX_WITH_CXX_STANDARD:STRING#
Set the C++ standard to use when compiling HPX itself. (default: 17)
- HPX_WITH_DATAPAR:BOOL#
Enable data parallel algorithm support using Vc library (default: ON)
- HPX_WITH_DATAPAR_BACKEND:STRING#
Define which vectorization library should be used. Options are: VC, EVE, STD_EXPERIMENTAL_SIMD, SVE; NONE
- HPX_WITH_DATAPAR_VC_NO_LIBRARY:BOOL#
Don’t link with the Vc static library (default: OFF)
- HPX_WITH_DEPRECATION_WARNINGS:BOOL#
Enable warnings for deprecated facilities (default: ON).
- HPX_WITH_DISABLED_SIGNAL_EXCEPTION_HANDLERS:BOOL#
Disables the mechanism that produces debug output for caught signals and unhandled exceptions (default: OFF)
- HPX_WITH_DYNAMIC_HPX_MAIN:BOOL#
Enable dynamic overload of system
main()(Linux and Apple only, default: ON)
- HPX_WITH_FAULT_TOLERANCE:BOOL#
Build HPX to tolerate failures of nodes, i.e. ignore errors in active communication channels (default: OFF)
- HPX_WITH_FULL_RPATH:BOOL#
Build and link HPX libraries and executables with full RPATHs (default: ON)
- HPX_WITH_GCC_VERSION_CHECK:BOOL#
Don’t ignore version reported by gcc (default: ON)
- HPX_WITH_GENERIC_CONTEXT_COROUTINES:BOOL#
Use Boost.Context as the underlying coroutines context switch implementation.
- HPX_WITH_HIDDEN_VISIBILITY:BOOL#
Use -fvisibility=hidden for builds on platforms which support it (default OFF)
- HPX_WITH_HIP:BOOL#
Enable compilation with HIPCC (default: OFF)
- HPX_WITH_HIPSYCL:BOOL#
Use hipsycl cmake integration (default: OFF)
- HPX_WITH_IGNORE_COMPILER_COMPATIBILITY:BOOL#
Ignore compiler incompatibility in dependent projects (default: ON).
- HPX_WITH_LOGGING:BOOL#
Build HPX with logging enabled (default: ON).
- HPX_WITH_MALLOC:STRING#
Define which allocator should be linked in. Options are: system, tcmalloc, jemalloc, mimalloc, tbbmalloc, and custom (default is: tcmalloc)
- HPX_WITH_MODULES_AS_STATIC_LIBRARIES:BOOL#
Compile HPX modules as STATIC (whole-archive) libraries instead of OBJECT libraries (Default: ON)
- HPX_WITH_NICE_THREADLEVEL:BOOL#
Set HPX worker threads to have high NICE level (may impact performance) (default: OFF)
- HPX_WITH_PARCEL_COALESCING:BOOL#
Enable the parcel coalescing plugin (default: ON).
- HPX_WITH_PKGCONFIG:BOOL#
Enable generation of pkgconfig files (default: ON on Linux without CUDA/HIP, otherwise OFF)
- HPX_WITH_PRECOMPILED_HEADERS:BOOL#
Enable precompiled headers for certain build targets (experimental) (default OFF)
- HPX_WITH_RUN_MAIN_EVERYWHERE:BOOL#
Run hpx_main by default on all localities (default: OFF).
- HPX_WITH_STACKOVERFLOW_DETECTION:BOOL#
Enable stackoverflow detection for HPX threads/coroutines (default: OFF, debug: ON).
- HPX_WITH_STATIC_LINKING:BOOL#
Compile HPX statically linked libraries (Default: OFF)
- HPX_WITH_SUPPORT_NO_UNIQUE_ADDRESS_ATTRIBUTE:BOOL#
Enable the use of the [[no_unique_address]] attribute (default: ON)
- HPX_WITH_SYCL:BOOL#
Enable support for Sycl (default: OFF)
- HPX_WITH_SYCL_FLAGS:STRING#
Sycl compile flags for selecting specific targets (default: empty)
- HPX_WITH_UNITY_BUILD:BOOL#
Enable unity build for certain build targets (default OFF)
- HPX_WITH_VIM_YCM:BOOL#
Generate HPX completion file for VIM YouCompleteMe plugin
- HPX_WITH_ZERO_COPY_SERIALIZATION_THRESHOLD:STRING#
The threshold in bytes to when perform zero copy optimizations (default: 8192)
Build Targets options#
- HPX_WITH_ASIO_TAG:STRING#
Asio repository tag or branch
- HPX_WITH_COMPILE_ONLY_TESTS:BOOL#
Create build system support for compile time only HPX tests (default ON)
- HPX_WITH_DISTRIBUTED_RUNTIME:BOOL#
Enable the distributed runtime (default: ON). Turning off the distributed runtime completely disallows the creation and use of components and actions. Turning this option off is experimental!
- HPX_WITH_DOCUMENTATION:BOOL#
Build the HPX documentation (default OFF).
- HPX_WITH_DOCUMENTATION_OUTPUT_FORMATS:STRING#
List of documentation output formats to generate. Valid options are html;singlehtml;latexpdf;man. Multiple values can be separated with semicolons. (default html).
- HPX_WITH_EXAMPLES:BOOL#
Build the HPX examples (default ON)
- HPX_WITH_EXAMPLES_HDF5:BOOL#
Enable examples requiring HDF5 support (default: OFF).
- HPX_WITH_EXAMPLES_OPENMP:BOOL#
Enable examples requiring OpenMP support (default: OFF).
- HPX_WITH_EXAMPLES_QT4:BOOL#
Enable examples requiring Qt4 support (default: OFF).
- HPX_WITH_EXAMPLES_QTHREADS:BOOL#
Enable examples requiring QThreads support (default: OFF).
- HPX_WITH_EXAMPLES_TBB:BOOL#
Enable examples requiring TBB support (default: OFF).
- HPX_WITH_EXECUTABLE_PREFIX:STRING#
Executable prefix (default none), ‘hpx_’ useful for system install.
- HPX_WITH_FAIL_COMPILE_TESTS:BOOL#
Create build system support for fail compile HPX tests (default ON)
- HPX_WITH_FETCH_APEX:BOOL#
Use FetchContent to fetch APEX. By default an installed APEX will be used. (default: OFF)
- HPX_WITH_FETCH_ASIO:BOOL#
Use FetchContent to fetch Asio. By default an installed Asio will be used. (default: OFF)
- HPX_WITH_FETCH_BOOST:BOOL#
Use FetchContent to fetch Boost. By default an installed Boost will be used. (default: OFF)
- HPX_WITH_FETCH_GASNET:BOOL#
Use FetchContent to fetch GASNET. By default an installed GASNET will be used. (default: OFF).
- HPX_WITH_FETCH_HWLOC:BOOL#
Use FetchContent to fetch Hwloc. By default an installed Hwloc will be used. (default: OFF)
- HPX_WITH_FETCH_LCI:BOOL#
Use FetchContent to fetch LCI. By default an installed LCI will be used. (default: OFF)
- HPX_WITH_IO_COUNTERS:BOOL#
Enable IO counters (default: ON)
- HPX_WITH_LCI_TAG:STRING#
LCI repository tag or branch
- HPX_WITH_NANOBENCH:BOOL#
Use Nanobench for performance tests. Nanobench will be fetched using FetchContent (default: OFF)
- HPX_WITH_PARALLEL_LINK_JOBS:STRING#
Number of Parallel link jobs while building hpx (only for Ninja as generator) (default 2)
- HPX_WITH_TESTS:BOOL#
Build the HPX tests (default ON)
- HPX_WITH_TESTS_BENCHMARKS:BOOL#
Build HPX benchmark tests (default: ON)
- HPX_WITH_TESTS_EXAMPLES:BOOL#
Add HPX examples as tests (default: ON)
- HPX_WITH_TESTS_EXTERNAL_BUILD:BOOL#
Build external cmake build tests (default: ON)
- HPX_WITH_TESTS_HEADERS:BOOL#
Build HPX header tests (default: OFF)
- HPX_WITH_TESTS_REGRESSIONS:BOOL#
Build HPX regression tests (default: ON)
- HPX_WITH_TESTS_UNIT:BOOL#
Build HPX unit tests (default: ON)
- HPX_WITH_TOOLS:BOOL#
Build HPX tools (default: OFF)
Thread Manager options#
- HPX_COROUTINES_WITH_SWAP_CONTEXT_EMULATION:BOOL#
Emulate SwapContext API for coroutines (Windows only, default: OFF)
- HPX_COROUTINES_WITH_THREAD_SCHEDULE_HINT_RUNS_AS_CHILD:BOOL#
Futures attempt to run associated threads directly if those have not been started (default: OFF)
- HPX_WITH_COROUTINE_COUNTERS:BOOL#
Enable keeping track of coroutine creation and rebind counts (default: OFF)
- HPX_WITH_IO_POOL:BOOL#
Disable internal IO thread pool, do not change if not absolutely necessary (default: ON)
- HPX_WITH_MAX_CPU_COUNT:STRING#
HPX applications will not use more that this number of OS-Threads (empty string means dynamic) (default: “”)
- HPX_WITH_MAX_NUMA_DOMAIN_COUNT:STRING#
HPX applications will not run on machines with more NUMA domains (default: 8)
- HPX_WITH_SCHEDULER_LOCAL_STORAGE:BOOL#
Enable scheduler local storage for all HPX schedulers (default: OFF)
- HPX_WITH_SPINLOCK_DEADLOCK_DETECTION:BOOL#
Enable spinlock deadlock detection (default: OFF)
- HPX_WITH_SPINLOCK_POOL_NUM:STRING#
Number of elements a spinlock pool manages (default: 128)
- HPX_WITH_STACKTRACES:BOOL#
Attach backtraces to HPX exceptions (default: ON)
- HPX_WITH_STACKTRACES_DEMANGLE_SYMBOLS:BOOL#
Thread stack back trace symbols will be demangled (default: ON)
- HPX_WITH_STACKTRACES_STATIC_SYMBOLS:BOOL#
Thread stack back trace will resolve static symbols (default: OFF)
- HPX_WITH_THREAD_BACKTRACE_DEPTH:STRING#
Thread stack back trace depth being captured (default: 20)
- HPX_WITH_THREAD_BACKTRACE_ON_SUSPENSION:BOOL#
Enable thread stack back trace being captured on suspension (default: OFF)
- HPX_WITH_THREAD_CREATION_AND_CLEANUP_RATES:BOOL#
Enable measuring thread creation and cleanup times (default: OFF)
- HPX_WITH_THREAD_CUMULATIVE_COUNTS:BOOL#
Enable keeping track of cumulative thread counts in the schedulers (default: ON)
- HPX_WITH_THREAD_IDLE_RATES:BOOL#
Enable measuring the percentage of overhead times spent in the scheduler (default: OFF)
- HPX_WITH_THREAD_LOCAL_STORAGE:BOOL#
Enable thread local storage for all HPX threads (default: OFF)
- HPX_WITH_THREAD_MANAGER_IDLE_BACKOFF:BOOL#
HPX scheduler threads do exponential backoff on idle queues (default: ON)
- HPX_WITH_THREAD_QUEUE_WAITTIME:BOOL#
Enable collecting queue wait times for threads (default: OFF)
- HPX_WITH_THREAD_STACK_MMAP:BOOL#
Use mmap for stack allocation on appropriate platforms
- HPX_WITH_THREAD_STEALING_COUNTS:BOOL#
Enable keeping track of counts of thread stealing incidents in the schedulers (default: OFF)
- HPX_WITH_THREAD_TARGET_ADDRESS:BOOL#
Enable storing target address in thread for NUMA awareness (default: OFF)
- HPX_WITH_TIMER_POOL:BOOL#
Disable internal timer thread pool, do not change if not absolutely necessary (default: ON)
- HPX_WITH_WORK_REQUESTING_SCHEDULERS:BOOL#
Enable work requesting scheduler (default: ON)
AGAS options#
- HPX_WITH_AGAS_DUMP_REFCNT_ENTRIES:BOOL#
Enable dumps of the AGAS refcnt tables to logs (default: OFF)
Parcelport options#
- HPX_WITH_NETWORKING:BOOL#
Enable support for networking and multi-node runs (default: ON)
- HPX_WITH_PARCELPORT_ACTION_COUNTERS:BOOL#
Enable performance counters reporting parcelport statistics on a per-action basis.
- HPX_WITH_PARCELPORT_COUNTERS:BOOL#
Enable performance counters reporting parcelport statistics.
- HPX_WITH_PARCELPORT_GASNET:BOOL#
Enable the GASNET based parcelport.
- HPX_WITH_PARCELPORT_LCI:BOOL#
Enable the LCI based parcelport.
- HPX_WITH_PARCELPORT_LCI_LOG:STRING#
Enable the LCI-parcelport-specific logger
- HPX_WITH_PARCELPORT_LCI_PCOUNTER:STRING#
Enable the LCI-parcelport-specific performance counter
- HPX_WITH_PARCELPORT_LIBFABRIC:BOOL#
Enable the libfabric based parcelport. This is currently an experimental feature
- HPX_WITH_PARCELPORT_MPI:BOOL#
Enable the MPI based parcelport.
- HPX_WITH_PARCELPORT_TCP:BOOL#
Enable the TCP based parcelport.
- HPX_WITH_PARCEL_PROFILING:BOOL#
Enable profiling data for parcels
Profiling options#
- HPX_WITH_APEX:BOOL#
Enable APEX instrumentation support.
- HPX_WITH_ITTNOTIFY:BOOL#
Enable Amplifier (ITT) instrumentation support.
- HPX_WITH_PAPI:BOOL#
Enable the PAPI based performance counter.
Debugging options#
- HPX_WITH_ATTACH_DEBUGGER_ON_TEST_FAILURE:BOOL#
Break the debugger if a test has failed (default: OFF)
- HPX_WITH_PARALLEL_TESTS_BIND_NONE:BOOL#
Pass –hpx:bind=none to tests that may run in parallel (cmake -j flag) (default: OFF)
- HPX_WITH_SANITIZERS:BOOL#
Configure with sanitizer instrumentation support.
- HPX_WITH_TESTS_COMMAND_LINE:STRING#
Add given command line options to all tests run
- HPX_WITH_TESTS_DEBUG_LOG:BOOL#
Turn on debug logs (–hpx:debug-hpx-log) for tests (default: OFF)
- HPX_WITH_TESTS_DEBUG_LOG_DESTINATION:STRING#
Destination for test debug logs (default: cout)
- HPX_WITH_TESTS_MAX_THREADS_PER_LOCALITY:STRING#
Maximum number of threads to use for tests (default: 0, use the number of threads specified by the test)
- HPX_WITH_THREAD_DEBUG_INFO:BOOL#
Enable thread debugging information (default: OFF, implicitly enabled in debug builds)
- HPX_WITH_THREAD_DESCRIPTION_FULL:BOOL#
Use function address for thread description (default: OFF)
- HPX_WITH_THREAD_GUARD_PAGE:BOOL#
Enable thread guard page (default: ON)
- HPX_WITH_VALGRIND:BOOL#
Enable Valgrind instrumentation support.
- HPX_WITH_VERIFY_LOCKS:BOOL#
Enable lock verification code (default: OFF, enabled in debug builds)
- HPX_WITH_VERIFY_LOCKS_BACKTRACE:BOOL#
Enable thread stack back trace being captured on lock registration (to be used in combination with HPX_WITH_VERIFY_LOCKS=ON, default: OFF)
Modules options#
HPX_COMMAND_LINE_HANDLING_LOCAL_WITH_JSON_CONFIGURATION_FILES:BOOLHPX_ITERATOR_SUPPORT_WITH_BOOST_ITERATOR_TRAVERSAL_TAG_COMPATIBILITY:BOOLHPX_SERIALIZATION_WITH_ALL_TYPES_ARE_BITWISE_SERIALIZABLE:BOOL
- HPX_ALLOCATOR_SUPPORT_WITH_CACHING:BOOL#
Enable caching allocator. (default: ON)
- HPX_COMMAND_LINE_HANDLING_LOCAL_WITH_JSON_CONFIGURATION_FILES:BOOL#
Enable reading JSON formatted configuration files on the command line.
(default: On)
- HPX_DATASTRUCTURES_WITH_ADAPT_STD_TUPLE:BOOL#
Enable compatibility of hpx::get with std::tuple. (default: ON)
- HPX_DATASTRUCTURES_WITH_ADAPT_STD_VARIANT:BOOL#
Enable compatibility of hpx::get with std::variant.
(default: OFF)
- HPX_FILESYSTEM_WITH_BOOST_FILESYSTEM_COMPATIBILITY:BOOL#
Enable Boost.FileSystem compatibility. (default: OFF)
- HPX_ITERATOR_SUPPORT_WITH_BOOST_ITERATOR_TRAVERSAL_TAG_COMPATIBILITY:BOOL#
Enable Boost.Iterator traversal tag compatibility. (default: OFF)
- HPX_LOGGING_WITH_SEPARATE_DESTINATIONS:BOOL#
Enable separate logging channels for AGAS, timing, and parcel transport. (default: ON)
- HPX_SERIALIZATION_WITH_ALLOW_CONST_TUPLE_MEMBERS:BOOL#
Enable serializing std::tuple with const members. (default: OFF)
- HPX_SERIALIZATION_WITH_ALLOW_RAW_POINTER_SERIALIZATION:BOOL#
Enable serializing raw pointers. (default: OFF)
- HPX_SERIALIZATION_WITH_ALL_TYPES_ARE_BITWISE_SERIALIZABLE:BOOL#
Assume all types are bitwise serializable. (default: OFF)
- HPX_SERIALIZATION_WITH_BOOST_TYPES:BOOL#
Enable serialization of certain Boost types. (default: OFF)
- HPX_SERIALIZATION_WITH_SUPPORTS_ENDIANESS:BOOL#
Support endian conversion on inout and output archives. (default: OFF)
- HPX_TOPOLOGY_WITH_ADDITIONAL_HWLOC_TESTING:BOOL#
Enable HWLOC filtering that makes it report no cores, this is purely an
option supporting better testing - do not enable under normal circumstances. (default: OFF)
- HPX_WITH_POWER_COUNTER:BOOL#
Enable use of performance counters based on pwr library (default: OFF)
Additional tools and libraries used by HPX#
Here is a list of additional libraries and tools that are either optionally supported by the build system or are optionally required for certain examples or tests. These libraries and tools can be detected by the HPX build system.
Each of the tools or libraries listed here will be automatically detected if
they are installed in some standard location. If a tool or library is installed
in a different location, you can specify its base directory by appending
_ROOT to the variable name as listed below. For instance, to configure a
custom directory for Boost, specify Boost_ROOT=/custom/boost/root.
- Boost_ROOT:PATH#
Specifies where to look for the Boost installation to be used for compiling HPX. Set this if CMake is not able to locate a suitable version of Boost. The directory specified here can be either the root of an installed Boost distribution or the directory where you unpacked and built Boost without installing it (with staged libraries).
- Hwloc_ROOT:PATH#
Specifies where to look for the hwloc library. Set this if CMake is not able to locate a suitable version of hwloc. Hwloc provides platform- independent support for extracting information about the used hardware architecture (number of cores, number of NUMA domains, hyperthreading, etc.). HPX utilizes this information if available.
- Papi_ROOT:PATH#
Specifies where to look for the PAPI library. The PAPI library is needed to compile a special component exposing PAPI hardware events and counters as HPX performance counters. This is not available on the Windows platform.
- Amplifier_ROOT:PATH#
Specifies where to look for one of the tools of the Intel Parallel Studio product, either Intel Amplifier or Intel Inspector. This should be set if the CMake variable
HPX_USE_ITT_NOTIFYis set toON. Enabling ITT support in HPX will integrate any application with the mentioned Intel tools, which customizes the generated information for your application and improves the generated diagnostics.
In addition, some of the examples may need the following variables:
- Hdf5_ROOT:PATH#
Specifies where to look for the Hierarchical Data Format V5 (HDF5) include files and libraries.
Migration guide#
The Migration Guide serves as a valuable resource for developers seeking to transition their parallel computing applications from different APIs (i.e. OpenMP, Intel Threading Building Blocks (TBB), MPI) to HPX. HPX, an advanced C++ library, offers a versatile and high-performance platform for parallel and distributed computing, providing a wide range of features and capabilities. This guide aims to assist developers in understanding the key differences between different APIs and HPX, and it provides step-by-step instructions for converting code to HPX code effectively.
Some general steps that can be used to migrate code to HPX code are the following:
Install HPX using the Quick start guide.
Include the HPX header files:
Add the necessary header files for HPX at the beginning of your code, such as:
#include <hpx/init.hpp>
Replace your code with HPX code using the guide that follows.
Use HPX-specific features and APIs:
HPX provides additional features and APIs that can be used to take advantage of the library’s capabilities. For example, you can use the HPX asynchronous execution to express fine-grained tasks and dependencies, or utilize HPX’s distributed computing features for distributed memory systems.
Compile and run the HPX code:
Compile the converted code with the HPX library and run it using the appropriate HPX runtime environment.
OpenMP#
The OpenMP API supports multi-platform shared-memory parallel programming in C/C++. Typically it is used for loop-level parallelism, but it also supports function-level parallelism. Below are some examples on how to convert OpenMP to HPX code:
OpenMP parallel for loop#
OpenMP code:
#pragma omp parallel for
for (int i = 0; i < n; ++i) {
// loop body
}
HPX equivalent:
#include <hpx/algorithm.hpp>
hpx::experimental::for_loop(hpx::execution::par, 0, n, [&](int i) {
// loop body
});
In the above code, the OpenMP #pragma omp parallel for directive is replaced with
hpx::experimental::for_loop from the HPX library. The loop body within the lambda
function will be executed in parallel for each iteration.
OpenMP code:
int x = 0;
#pragma omp parallel for private(x)
for (int i = 0; i < n; ++i) {
// loop body
}
HPX equivalent:
#include <hpx/algorithm.hpp>
hpx::experimental::for_loop(hpx::execution::par, 0, n, [&](int i) {
int x = 0; // Declare 'x' as a local variable inside the loop body
// loop body
});
The variable x is declared as a local variable inside the loop body, ensuring that it is private to each thread.
OpenMP code:
#pragma omp parallel for num_threads(2)
for (int i = 0; i < n; ++i) {
// loop body
}
HPX equivalent:
#include <hpx/algorithm.hpp>
#include <hpx/execution.hpp>
hpx::execution::experimental::num_cores nc(2);
hpx::experimental::for_loop(hpx::execution::par.with(nc), 0, n, [&](int i) {
// loop body
});
To declare the number of threads to be used for the parallel region, you can use
hpx::execution::experimental::num_cores and pass the number of cores (nc) to
hpx::experimental::for_loop using hpx::execution::par.with(nc).
This example uses 2 threads for the parallel loop.
OpenMP code:
int s = 0;
#pragma omp parallel for reduction(+: s)
for (int i = 0; i < n; ++i) {
s += i;
// loop body
}
HPX equivalent:
#include <hpx/algorithm.hpp>
#include <hpx/execution.hpp>
int s = 0;
hpx::experimental::for_loop(hpx::execution::par, 0, n, reduction(s, 0, plus<>()), [&](int i, int& accum) {
accum += i;
// loop body
});
The reduction clause specifies that the variable s` should be reduced across iterations using the plus<>` operation. It initializes s to 0 at the beginning of the loop and accumulates the values of s from each iteration using the + operator. The lambda function representing the loop body takes two parameters: i, which represents the loop index, and accum, which is the reduction variable s. The lambda function is executed for each iteration of the loop. The reduction ensures that the accum value is correctly accumulated across different iterations and threads.
OpenMP code:
int s = 0;
// static scheduling with chunk size 1000
#pragma omp parallel for schedule(static, 1000)
for (int i = 0; i < n; ++i) {
// loop body
}
HPX equivalent:
#include <hpx/algorithm.hpp>
#include <hpx/execution.hpp>
hpx::execution::experimental::static_chunk_size cs(1000);
hpx::experimental::for_loop(hpx::execution::par.with(cs), 0, n, [&](int i) {
// loop body
});
To define the scheduling type, you can use the corresponding execution policy from
hpx::execution::experimental, define the chunk size (cs, here declared as 1000) and pass
it to the to hpx::experimental::for_loop using hpx::execution::par.with(cs).
Accordingly, other types of scheduling are available and can be used in a similar manner:
#include <hpx/execution.hpp>
hpx::execution::experimental::dynamic_chunk_size cs(1000);
#include <hpx/execution.hpp>
hpx::execution::experimental::guided_chunk_size cs(1000);
#include <hpx/execution.hpp>
hpx::execution::experimental::auto_chunk_size cs(1000);
OpenMP single thread#
OpenMP code:
{ // parallel code
#pragma omp single
{
// single-threaded code
}
// more parallel code
}
HPX equivalent:
#include <hpx/mutex.hpp>
hpx::mutex mtx;
{ // parallel code
{ // single-threaded code
std::scoped_lock l(mtx);
}
// more parallel code
}
To make sure that only one thread accesses a specific code within a parallel section
you can use hpx::mutex and std::scoped_lock to take ownership of the given
mutex mtx. For more information about mutexes please refer to Mutex.
OpenMP tasks#
OpenMP code:
// executed asynchronously by any available thread
#pragma omp task
{
// task code
}
HPX equivalent:
#include <hpx/future.hpp>
auto future = hpx::async([](){
// task code
});
or
#include <hpx/future.hpp>
hpx::post([](){
// task code
}); // fire and forget
The tasks in HPX can be defined simply by using the async function and passing as argument
the code you wish to run asynchronously. Another alternative is to use post which is a
fire-and-forget method.
Tip
If you think you will like to synchronize your tasks later on, we suggest you use
hpx::async which provides synchronization options, while hpx::post
explicitly states that there is no return value or way to synchronize with the function
execution. Synchronization options are listed below.
OpenMP code:
#pragma omp task
{
// task code
}
#pragma omp taskwait
// code after completion of task
HPX equivalent:
#include <hpx/future.hpp>
hpx::async([](){
// task code
}).get(); // wait for the task to complete
// code after completion of task
The get() function can be used to ensure that the task created with hpx::async
is completed before the code continues executing beyond that point.
OpenMP code:
#pragma omp task
{
// task 1 code
}
#pragma omp task
{
// task 2 code
}
#pragma omp taskwait
// code after completion of both tasks 1 and 2
HPX equivalent:
#include <hpx/future.hpp>
auto future1 = hpx::async([](){
// task 1 code
});
auto future2 = hpx::async([](){
// task 2 code
});
auto future = hpx::when_all(future1, future2).then([](auto&&){
// code after completion of both tasks 1 and 2
});
If you would like to synchronize multiple tasks, you can use the hpx::when_all function
to define which futures have to be ready and the then() function to declare what should
be executed once these futures are ready.
OpenMP code:
int a = 10;
int b = 20;
int c = 0;
#pragma omp task depend(in: a, b) depend(out: c)
{
// task code
c = 100;
}
HPX equivalent:
#include <hpx/future.hpp>
int a = 10;
int b = 20;
int c = 0;
// Create a future representing 'a'
auto future_a = hpx::make_ready_future(a);
// Create a future representing 'b'
auto future_b = hpx::make_ready_future(b);
// Create a task that depends on 'a' and 'b' and executes 'task_code'
auto future_c = hpx::dataflow(
[]() {
// task code
return 100;
},
future_a, future_b);
c = future_c.get();
If one of the arguments of hpx::dataflow is a future, then it will wait for the
future to be ready to launch the thread. Hence, to define the dependencies of tasks
you have to create futures representing the variables that create dependencies and pass
them as arguments to hpx::dataflow. get() is used to save the result of the future
to the desired variable.
OpenMP code:
#pragma omp task
{
// Outer task code
#pragma omp task
{
// Inner task code
}
}
HPX equivalent:
#include <hpx/future.hpp>
auto future_outer = hpx::async([](){
// Outer task code
hpx::async([](){
// Inner task code
});
});
or
#include <hpx/future.hpp>
auto future_outer = hpx::post([](){ // fire and forget
// Outer task code
hpx::post([](){ // fire and forget
// Inner task code
});
});
If you have nested tasks, you can simply use nested hpx::async or
hpx::post calls. The implementation is similar if you want to take
care of synchronization:
OpenMP code:
#pragma omp taskwait
{
// Outer task code
#pragma omp taskwait
{
// Inner task code
}
}
HPX equivalent:
#include <hpx/future.hpp>
auto future_outer = hpx::async([]() {
// Outer task code
hpx::async([]() {
// Inner task code
}).get(); // Wait for the inner task to complete
});
future_outer.get(); // Wait for the outer task to complete
OpenMP code:
#pragma omp task
{
// code before yielding
#pragma omp taskyield
// code after yielding
}
HPX equivalent:
#include <hpx/future.hpp>
#include <hpx/thread.hpp>
auto future = hpx::async([](){
// code before yielding
});
// yield execution to potentially allow other tasks to run
hpx::this_thread::yield();
// code after yielding
After creating a task using hpx::async, hpx::this_thread::yield
can be used to reschedule the execution of threads, allowing other threads to run.
OpenMP code:
#pragma omp taskgroup
{
#pragma omp task
{
// task 1 code
}
#pragma omp task
{
// task 2 code
}
}
HPX equivalent:
#include <hpx/task_group.hpp>
// Declare a task group
hpx::experimental::task_group tg;
// Run the tasks
tg.run([](){
// task 1 code
});
tg.run(
// task 2 code
});
// Wait for the task group
tg.wait();
To create task groups, you can use hpx::experimental::task_group. The function
run() can be used to run each task within the task group, while wait() can be used to
achieve synchronization. If you do not care about waiting for the task group to complete
its execution, you can simply remove the wait() function.
OpenMP sections#
OpenMP code:
#pragma omp sections
{
#pragma omp section
// section 1 code
#pragma omp section
// section 2 code
} // implicit synchronization
HPX equivalent:
#include <hpx/future.hpp>
auto future_section1 = hpx::async([](){
// section 1 code
});
auto future_section2 = hpx::async([](){
// section 2 code
);
// synchronization: wait for both sections to complete
hpx::wait_all(future_section1, future_section2);
Unlike tasks, there is an implicit synchronization barrier at the end of each sections`
directive in OpenMP. This synchronization is achieved using hpx::wait_all function.
Note
If the nowait clause is used in the sections directive, then you can just remove
the hpx::wait_all function while keeping the rest of the code as it is.
Intel Threading Building Blocks (TBB)#
Intel Threading Building Blocks (TBB) provides a high-level interface for parallelism and concurrent programming using standard ISO C++ code. Below are some examples on how to convert Intel Threading Building Blocks (TBB) to HPX code:
parallel_for#
Intel Threading Building Blocks (TBB) code:
auto values = std::vector<double>(10000);
tbb::parallel_for( tbb::blocked_range<int>(0,values.size()),
[&](tbb::blocked_range<int> r)
{
for (int i=r.begin(); i<r.end(); ++i)
{
// loop body
}
});
HPX equivalent:
#include <hpx/algorithm.hpp>
auto values = std::vector<double>(10000);
hpx::experimental::for_loop(hpx::execution::par, 0, values.size(), [&](int i) {
// loop body
});
In the above code, tbb::parallel_for is replaced with hpx::experimental::for_loop
from the HPX library. The loop body within the lambda function will be executed in
parallel for each iteration.
parallel_for_each#
Intel Threading Building Blocks (TBB) code:
auto values = std::vector<double>(10000);
tbb::parallel_for_each(values.begin(), values.end(), [&](){
// loop body
});
HPX equivalent:
#include <hpx/algorithm.hpp>
auto values = std::vector<double>(10000);
hpx::for_each(hpx::execution::par, values.begin(), values.end(), [&](){
// loop body
});
By utilizing hpx::for_each` and specifying a parallel execution policy with
hpx::execution::par, it is possible to transform tbb::parallel_for_each` into its
equivalent counterpart in HPX.
parallel_invoke#
Intel Threading Building Blocks (TBB) code:
tbb::parallel_invoke(task1, task2, task3);
HPX equivalent:
#include <hpx/future.hpp>
hpx::wait_all(hpx::async(task1), hpx::async(task2), hpx::async(task3));
To convert tbb::parallel_invoke to HPX, we use hpx::async to asynchronously
execute each task, which returns a future representing the result of each task.
We then pass these futures to hpx::when_all, which waits for all the futures
to complete before returning.
parallel_pipeline#
Intel Threading Building Blocks (TBB) code:
tbb::parallel_pipeline(4,
tbb::make_filter<void, int>(tbb::filter::serial_in_order,
[](tbb::flow_control& fc) -> int {
// Generate numbers from 1 to 10
static int i = 1;
if (i <= 10) {
return i++;
}
else {
fc.stop();
return 0;
}
}) &
tbb::make_filter<int, int>(tbb::filter::parallel,
[](int num) -> int {
// Multiply each number by 2
return num * 2;
}) &
tbb::make_filter<int, void>(tbb::filter::serial_in_order,
[](int num) {
// Print the results
std::cout << num << " ";
})
);
HPX equivalent:
#include <iostream>
#include <vector>
#include <ranges>
#include <hpx/algorithm.hpp>
// generate the values
auto range = std::views::iota(1) | std::views::take(10);
// materialize the output vector
std::vector<int> results(10);
// in parallel execution of pipeline and transformation
hpx::ranges::transform(
hpx::execution::par, range, result.begin(), [](int i) { return 2 * i; });
// print the modified vector
for (int i : result)
{
std::cout << i << " ";
}
std::cout << std::endl;
The line auto range = std::views::iota(1) | std::views::take(10); generates a range of values using the std::views::iota function. It starts from the value 1 and generates an infinite sequence of incrementing values. The std::views::take(10) function is then applied to limit the sequence to the first 10 values. The result is stored in the range variable.
Hint
A view is a lightweight object that represents a particular view of a sequence or range. It acts as a read-only interface to the original data, providing a way to query and traverse the elements without making any copies or modifications.
Views can be composed and chained together to form complex pipelines of operations. These operations are evaluated lazily, meaning that the actual computation is performed only when the result is needed or consumed.
Since views perform lazy evaluation, we use std::vector<int> results(10); to meterialize the vector that will store the transformed values. The hpx::ranges::transform function is then used to perform a parallel transformation on the range. The transformed values will be written to the results vector.
Hint
Ranges enable loop fusion by combining multiple operations into a single parallel loop, eliminating waiting time and reducing overhead. Using ranges, you can express these operations as a pipeline of transformations on a sequence of elements. This pipeline is evaluated in a single pass, performing all the desired operations in parallel without the need to wait between them.
In addition, HPX enhances the benefits of range fusion by offering parallel execution policies, which can be used to optimize the execution of the fused loop across multiple threads.
parallel_reduce#
Intel Threading Building Blocks (TBB) code:
auto values = std::vector<double>{1,2,3,4,5,6,7,8,9};
auto total = tbb::parallel_reduce(
tbb::blocked_range<int>(0,values.size()),
0.0,
[&](tbb::blocked_range<int> r, double running_total)
{
for (int i=r.begin(); i<r.end(); ++i)
{
running_total += values[i];
}
return running_total;
},
std::plus<double>());
HPX equivalent:
#include <hpx/numeric.hpp>
auto values = std::vector<double>{1,2,3,4,5,6,7,8,9};
auto total = hpx::reduce(
hpx::execution::par, values.begin(), values.end(), 0, std::plus{});
By utilizing hpx::reduce and specifying a parallel execution policy with
hpx::execution::par, it is possible to transform tbb::parallel_reduce` into its
equivalent counterpart in HPX. As demonstrated in the previous example, the management
of intermediate results is seamlessly handled internally by HPX, eliminating the need
for explicit consideration.
Intel Threading Building Blocks (TBB) code:
auto values = std::vector<double>{1,2,3,4,5,6,7,8,9};
auto transform_function(double current_value){
// transformation code
}
auto total = tbb::parallel_reduce(
tbb::blocked_range<int>(0,values.size()),
0.0,
[&](tbb::blocked_range<int> r, double transformed_val)
{
for (int i=r.begin(); i<r.end(); ++i)
{
transformed_val += transform_function(values[i]);
}
return transformed_val;
},
std::plus<double>());
HPX equivalent:
#include <hpx/numeric.hpp>
auto values = std::vector<double>{1,2,3,4,5,6,7,8,9};
auto transform_function(double current_value)
{
// transformation code
}
auto total = hpx::transform_reduce(hpx::execution::par, values.begin(),
values.end(), 0, std::plus{},
[&](double current_value) { return transform_function(current_value); });
In situations where certain values require transformation before the reduction process,
HPX provides a straightforward solution through hpx::transform_reduce. The
transform_function() allows for the application of the desired transformation to each value.
parallel_scan#
Intel Threading Building Blocks (TBB) code:
tbb::parallel_scan(tbb::blocked_range<size_t>(0, input.size()),
0,
[&input, &output](const tbb::blocked_range<size_t>& range, int& partial_sum, bool is_final_scan) {
for (size_t i = range.begin(); i != range.end(); ++i) {
partial_sum += input[i];
if (is_final_scan) {
output[i] = partial_sum;
}
}
return partial_sum;
},
[](int left_sum, int right_sum) {
return left_sum + right_sum;
}
);
HPX equivalent:
#include <hpx/numeric.hpp>
hpx::inclusive_scan(hpx::execution::par, input.begin(), input.end(),
output.begin(),
[](const int& left, const int& right) { return left + right; });
hpx::inclusive_scan with hpx::execution::par as execution policy
can be used to perform a prefix scan in parallel. The management of intermediate
results is seamlessly handled internally by HPX, eliminating the need
for explicit consideration. input.begin() and input.end() refer to the beginning
and end of the sequence of elements the algorithm will be applied to respectively.
output.begin() refers to the beginning of the destination, while the last argument
specifies the function which will be invoked for each of the values of the input sequence.
Apart from hpx::inclusive_scan, HPX provides its users with hpx::exclusive_scan.
The key difference between inclusive scan and exclusive scan lies in the treatment of the current element
during the scan operation. In an inclusive scan, each element in the output sequence includes the
contribution of the corresponding element in the input sequence, while in an exclusive scan, the current
element in the input sequence does not contribute to the corresponding element in the output sequence.
parallel_sort#
Intel Threading Building Blocks (TBB) code:
std::vector<int> numbers = {9, 2, 7, 1, 5, 3};
tbb::parallel_sort(numbers.begin(), numbers.end());
HPX equivalent:
#include <hpx/algorithm.hpp>
std::vector<int> numbers = {9, 2, 7, 1, 5, 3};
hpx::sort(hpx::execution::par, numbers.begin(), numbers.end());
hpx::sort provides an equivalent functionality to tbb::parallel_sort.
When given a parallel execution policy with hpx::execution::par, the algorithm employs
parallel execution, allowing for efficient sorting across available threads.
task_group#
Intel Threading Building Blocks (TBB) code:
// Declare a task group
tbb::task_group tg;
// Run the tasks
tg.run(task1);
tg.run(task2);
// Wait for the task group
tg.wait();
HPX equivalent:
#include <hpx/task_group.hpp>
// Declare a task group
hpx::experimental::task_group tg;
// Run the tasks
tg.run(task1);
tg.run(task2);
// Wait for the task group
tg.wait();
HPX drew inspiration from Intel Threading Building Blocks (TBB) to introduce the hpx::experimental::task_group
feature. Therefore, utilizing hpx::experimental::task_group provides an
equivalent functionality to tbb::task_group.
MPI#
MPI is a standardized communication protocol and library that allows multiple processes or nodes in a parallel computing system to exchange data and coordinate their execution.
List of MPI-HPX functions#
MPI function
HPX equivalent
hpx::collectives::broadcast_to()andhpx::collectives::broadcast_from()used withget()
hpx::collectives::exclusive_scan()used withget()
hpx::collectives::gather_here()andhpx::collectives::gather_there()used withget()
hpx::collectives::reduce_hereandhpx::collectives::reduce_thereused withget()
hpx::collectives::inclusive_scan()used withget()
hpx::collectives::scatter_to()andhpx::collectives::scatter_from()
hpx::collectives::get()used with a future i.e.setf.get()
MPI_Send & MPI_Recv#
Let’s assume we have the following simple message passing code where each process sends a message to the next process in a circular manner. The exchanged message is modified and printed to the console.
MPI code:
#include <cstddef>
#include <cstdint>
#include <iostream>
#include <mpi.h>
#include <vector>
constexpr int times = 2;
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
int num_localities;
MPI_Comm_size(MPI_COMM_WORLD, &num_localities);
int this_locality;
MPI_Comm_rank(MPI_COMM_WORLD, &this_locality);
int next_locality = (this_locality + 1) % num_localities;
std::vector<int> msg_vec = {0, 1};
int cnt = 0;
int msg = msg_vec[this_locality];
int recv_msg;
MPI_Request request_send, request_recv;
MPI_Status status;
while (cnt < times) {
cnt += 1;
MPI_Isend(&msg, 1, MPI_INT, next_locality, cnt, MPI_COMM_WORLD,
&request_send);
MPI_Irecv(&recv_msg, 1, MPI_INT, next_locality, cnt, MPI_COMM_WORLD,
&request_recv);
MPI_Wait(&request_send, &status);
MPI_Wait(&request_recv, &status);
std::cout << "Time: " << cnt << ", Locality " << this_locality
<< " received msg: " << recv_msg << "\n";
recv_msg += 10;
msg = recv_msg;
}
MPI_Finalize();
return 0;
}
HPX equivalent:
#include <hpx/config.hpp>
#if !defined(HPX_COMPUTE_DEVICE_CODE)
#include <hpx/algorithm.hpp>
#include <hpx/hpx_init.hpp>
#include <hpx/modules/collectives.hpp>
#include <cstddef>
#include <cstdint>
#include <iostream>
#include <utility>
#include <vector>
using namespace hpx::collectives;
constexpr char const* channel_communicator_name =
"/example/channel_communicator/";
// the number of times
constexpr int times = 2;
int hpx_main()
{
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t this_locality = hpx::get_locality_id();
// allocate channel communicator
auto comm = create_channel_communicator(hpx::launch::sync,
channel_communicator_name, num_sites_arg(num_localities),
this_site_arg(this_locality));
std::uint32_t next_locality = (this_locality + 1) % num_localities;
std::vector<int> msg_vec = {0, 1};
int cnt = 0;
int msg = msg_vec[this_locality];
// send values to another locality
auto setf = set(comm, that_site_arg(next_locality), msg, tag_arg(cnt));
auto got_msg = get<int>(comm, that_site_arg(next_locality), tag_arg(cnt));
setf.get();
while (cnt < times)
{
cnt += 1;
auto done_msg = got_msg.then([&](auto&& f) {
int rec_msg = f.get();
std::cout << "Time: " << cnt << ", Locality " << this_locality
<< " received msg: " << rec_msg << "\n";
// change msg by adding 10
rec_msg += 10;
// start next round
setf =
set(comm, that_site_arg(next_locality), rec_msg, tag_arg(cnt));
got_msg =
get<int>(comm, that_site_arg(next_locality), tag_arg(cnt));
setf.get();
});
done_msg.get();
}
return hpx::finalize();
}
#endif
int main(int argc, char* argv[])
{
#if !defined(HPX_COMPUTE_DEVICE_CODE)
hpx::init_params params;
params.cfg = {"--hpx:run-hpx-main"};
return hpx::init(argc, argv, params);
#else
(void) argc;
(void) argv;
return 0;
#endif
}
To perform message passing between different processes in HPX we can use a channel communicator. To understand this example, let’s focus on the hpx_main() function:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
create_channel_communicator function is used to create a channel to serve the communication. This function takes several arguments, including the launch policy (hpx::launch::sync), the name of the communicator (channel_communicator_name), the number of localities, and the ID of the current locality.
The communication follows a ring pattern, where each process (or locality) sends a message to its neighbor in a circular manner. This means that the messages circulate around the localities, ensuring that the communication wraps around when reaching the end of the locality sequence. To achieve this, the next_locality variable is calculated as the ID of the next locality in the ring.
The initial values for the communication are set (msg_vec, cnt, msg).
The set() function is called to send the message to the next locality in the ring. The message is sent asynchronously and is associated with a tag (cnt).
The get() function is called to receive a message from the next locality. It is also associated with the same tag as the set() operation.
The setf.get() call blocks until the message sending operation is complete.
A continuation is set up using the function then() to handle the received message. Inside the continuation:
The received message value (rec_msg) is retrieved using f.get().
The received message is printed to the console and then modified by adding 10.
The set() and get() operations are repeated to send and receive the modified message to the next locality.
The setf.get() call blocks until the new message sending operation is complete.
The done_msg.get() call blocks until the continuation is complete for the current loop iteration.
Having said that, we conclude to the following table:
MPI_Gather#
The following code gathers data from all processes to the root process and verifies the gathered data in the root process.
MPI code:
#include <iostream>
#include <mpi.h>
#include <numeric>
#include <vector>
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
int num_localities, this_locality;
MPI_Comm_size(MPI_COMM_WORLD, &num_localities);
MPI_Comm_rank(MPI_COMM_WORLD, &this_locality);
std::vector<int> local_data; // Data to be gathered
if (this_locality == 0) {
local_data.resize(num_localities); // Resize the vector on the root process
}
// Each process calculates its local data value
int my_data = 42 + this_locality;
for (std::uint32_t i = 0; i != 10; ++i) {
// Gather data from all processes to the root process (process 0)
MPI_Gather(&my_data, 1, MPI_INT, local_data.data(), 1, MPI_INT, 0,
MPI_COMM_WORLD);
// Only the root process (process 0) will print the gathered data
if (this_locality == 0) {
std::cout << "Gathered data on the root: ";
for (int i = 0; i < num_localities; ++i) {
std::cout << local_data[i] << " ";
}
std::cout << std::endl;
}
}
std::cout << std::endl;
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t this_locality = hpx::get_locality_id();
// test functionality based on immediate local result value
auto gather_direct_client = create_communicator(gather_direct_basename,
num_sites_arg(num_localities), this_site_arg(this_locality));
for (std::uint32_t i = 0; i != 10; ++i)
{
if (this_locality == 0)
{
hpx::future<std::vector<std::uint32_t>> overall_result =
gather_here(gather_direct_client, std::uint32_t(42));
std::vector<std::uint32_t> sol = overall_result.get();
std::cout << "Gathered data on the root:";
for (std::size_t j = 0; j != sol.size(); ++j)
{
HPX_TEST(j + 42 == sol[j]);
std::cout << " " << sol[j];
}
std::cout << std::endl;
}
else
{
hpx::future<void> overall_result =
gather_there(gather_direct_client, this_locality + 42);
overall_result.get();
}
}
This code will print 10 times the following message:
Gathered data on the root: 42 43
HPX uses two functions to implement the functionality of MPI_Gather: gather_here and gather_there. gather_here is gathering data from all localities to the locality with ID 0 (root locality). gather_there allows non-root localities to participate in the gather operation by sending data to the root locality. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function create_communicator() is used to create a communicator called gather_direct_client.
If the current locality is the root (its ID is equal to 0):
The gather_here function is used to perform the gather operation. It collects data from all other localities into the overall_result future object. The function arguments provide the necessary information, such as the base name for the gather operation (gather_direct_basename), the value to be gathered (value), the number of localities (num_localities), the current locality ID (this_locality), and the generation number (related to the gather operation).
The get() member function of the overall_result future is used to retrieve the gathered data.
The next for loop is used to verify the correctness of the gathered data (sol). HPX_TEST is a macro provided by the HPX testing utilities to perform similar testing with the Standard C++ macro assert.
If the current locality is not the root:
The gather_there function is used to participate in the gather operation initiated by the root locality. It sends the data (in this case, the value this_locality + 42) to the root locality, indicating that it should be included in the gathering.
The get() member function of the overall_result future is used to wait for the gather operation to complete for this locality.
MPI_Scatter#
The following code gathers data from all processes to the root process and verifies the gathered data in the root process.
MPI code:
#include <iostream>
#include <mpi.h>
#include <vector>
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
int num_localities, this_locality;
MPI_Comm_size(MPI_COMM_WORLD, &num_localities);
MPI_Comm_rank(MPI_COMM_WORLD, &this_locality);
int num_localities = num_localities;
std::vector<int> data(num_localities);
if (this_locality == 0) {
// Fill the data vector on the root locality (locality 0)
for (int i = 0; i < num_localities; ++i) {
data[i] = 42 + i;
}
}
int local_data; // Variable to store the received data
// Scatter data from the root locality to all other localities
MPI_Scatter(&data[0], 1, MPI_INT, &local_data, 1, MPI_INT, 0, MPI_COMM_WORLD);
// Now, each locality has its own local_data
// Print the local_data on each locality
std::cout << "Locality " << this_locality << " received " << local_data
<< std::endl;
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
HPX_TEST_LTE(std::uint32_t(2), num_localities);
std::uint32_t this_locality = hpx::get_locality_id();
auto scatter_direct_client =
hpx::collectives::create_communicator(scatter_direct_basename,
num_sites_arg(num_localities), this_site_arg(this_locality));
// test functionality based on immediate local result value
for (std::uint32_t i = 0; i != 10; ++i)
{
if (this_locality == 0)
{
std::vector<std::uint32_t> data(num_localities);
std::iota(data.begin(), data.end(), 42 + i);
hpx::future<std::uint32_t> result =
scatter_to(scatter_direct_client, std::move(data));
HPX_TEST_EQ(i + 42 + this_locality, result.get());
}
else
{
hpx::future<std::uint32_t> result =
scatter_from<std::uint32_t>(scatter_direct_client);
HPX_TEST_EQ(i + 42 + this_locality, result.get());
std::cout << "Locality " << this_locality << " received "
<< i + 42 + this_locality << std::endl;
}
}
For num_localities = 2 and since we run for 10 iterations this code will print the following message:
Locality 1 received 43
Locality 1 received 44
Locality 1 received 45
Locality 1 received 46
Locality 1 received 47
Locality 1 received 48
Locality 1 received 49
Locality 1 received 50
Locality 1 received 51
Locality 1 received 52
HPX uses two functions to implement the functionality of MPI_Scatter: hpx::scatter_to and hpx::scatter_from. hpx::scatter_to is distributing the data from the locality with ID 0 (root locality) to all other localities. hpx::scatter_from allows non-root localities to receive the data from the root locality. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function hpx::collectives::create_communicator() is used to create a communicator called scatter_direct_client.
If the current locality is the root (its ID is equal to 0):
The data vector is filled with values ranging from 42 + i to 42 + i + num_localities - 1.
The hpx::scatter_to function is used to perform the scatter operation using the communicator scatter_direct_client. This scatters the data vector to other localities and returns a future representing the result.
HPX_TEST_EQ is a macro provided by the HPX testing utilities to test the distributed values.
If the current locality is not the root:
The hpx::scatter_from function is used to collect the data by the root locality.
HPX_TEST_EQ is a macro provided by the HPX testing utilities to test the collected values.
MPI_Allgather#
The following code gathers data from all processes and sends the data to all processes.
MPI code:
#include <cstdint>
#include <iostream>
#include <mpi.h>
#include <vector>
int main(int argc, char **argv) {
MPI_Init(&argc, &argv);
int rank, size;
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
MPI_Comm_size(MPI_COMM_WORLD, &size);
// Get the number of MPI processes
int num_localities = size;
// Get the MPI process rank
int here = rank;
std::uint32_t value = here;
std::vector<std::uint32_t> r(num_localities);
// Perform an all-gather operation to gather values from all processes.
MPI_Allgather(&value, 1, MPI_UINT32_T, r.data(), 1, MPI_UINT32_T,
MPI_COMM_WORLD);
// Print the result.
std::cout << "Locality " << here << " has values:";
for (size_t j = 0; j < r.size(); ++j) {
std::cout << " " << r[j];
}
std::cout << std::endl;
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t here = hpx::get_locality_id();
// test functionality based on immediate local result value
auto all_gather_direct_client =
create_communicator(all_gather_direct_basename,
num_sites_arg(num_localities), this_site_arg(here));
std::uint32_t value = here;
hpx::future<std::vector<std::uint32_t>> overall_result =
all_gather(all_gather_direct_client, value);
std::vector<std::uint32_t> r = overall_result.get();
std::cout << "Locality " << here << " has values:";
for (std::size_t j = 0; j != r.size(); ++j)
{
std::cout << " " << j;
}
std::cout << std::endl;
For num_localities = 2 this code will print the following message:
Locality 0 has values: 0 1
Locality 1 has values: 0 1
HPX uses the function all_gather to implement the functionality of MPI_Allgather. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function hpx::collectives::create_communicator() is used to create a communicator called all_gather_direct_client.
The values that the localities exchange with each other are equal to each locality’s ID.
The gather operation is performed using all_gather. The result is stored in an hpx::future object called overall_result, which represents a future result that can be retrieved later when needed.
The get() function waits until the result is available and then stores it in the vector called r.
MPI_Allreduce#
The following code combines values from all processes and distributes the result back to all processes.
MPI code:
#include <cstdint>
#include <iostream>
#include <mpi.h>
int main(int argc, char **argv) {
MPI_Init(&argc, &argv);
int rank, size;
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
MPI_Comm_size(MPI_COMM_WORLD, &size);
// Get the number of MPI processes
int num_localities = size;
// Get the MPI process rank
int here = rank;
// Create a communicator for the all reduce operation.
MPI_Comm all_reduce_direct_client;
MPI_Comm_split(MPI_COMM_WORLD, 0, rank, &all_reduce_direct_client);
// Perform the all reduce operation to calculate the sum of 'here' values.
std::uint32_t value = here;
std::uint32_t res = 0;
MPI_Allreduce(&value, &res, 1, MPI_UINT32_T, MPI_SUM,
all_reduce_direct_client);
std::cout << "Locality " << rank << " has value: " << res << std::endl;
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t const num_localities =
hpx::get_num_localities(hpx::launch::sync);
std::uint32_t const here = hpx::get_locality_id();
auto const all_reduce_direct_client =
create_communicator(all_reduce_direct_basename,
num_sites_arg(num_localities), this_site_arg(here));
std::uint32_t value = here;
hpx::future<std::uint32_t> overall_result =
all_reduce(all_reduce_direct_client, value, std::plus<std::uint32_t>{});
std::uint32_t res = overall_result.get();
std::cout << "Locality " << here << " has value: " << res << std::endl;
For num_localities = 2 this code will print the following message:
Locality 0 has value: 1
Locality 1 has value: 1
HPX uses the function all_reduce to implement the functionality of MPI_Allreduce. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function hpx::collectives::create_communicator() is used to create a communicator called all_reduce_direct_client.
The value of each locality is equal to its ID.
The reduce operation is performed using all_reduce. The result is stored in an hpx::future object called overall_result, which represents a future result that can be retrieved later when needed.
The get() function waits until the result is available and then stores it in the variable res.
MPI_Alltoall#
The following code gathers data from and scatters data to all processes.
MPI code:
#include <algorithm>
#include <cstdint>
#include <iostream>
#include <mpi.h>
#include <vector>
int main(int argc, char **argv) {
MPI_Init(&argc, &argv);
int rank, size;
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
MPI_Comm_size(MPI_COMM_WORLD, &size);
// Get the number of MPI processes
int num_localities = size;
// Get the MPI process rank
int this_locality = rank;
// Create a communicator for all-to-all operation.
MPI_Comm all_to_all_direct_client;
MPI_Comm_split(MPI_COMM_WORLD, 0, rank, &all_to_all_direct_client);
std::vector<std::uint32_t> values(num_localities);
std::fill(values.begin(), values.end(), this_locality);
// Create vectors to store received values.
std::vector<std::uint32_t> r(num_localities);
// Perform an all-to-all operation to exchange values with other localities.
MPI_Alltoall(values.data(), 1, MPI_UINT32_T, r.data(), 1, MPI_UINT32_T,
all_to_all_direct_client);
// Print the results.
std::cout << "Locality " << this_locality << " has values:";
for (std::size_t j = 0; j != r.size(); ++j) {
std::cout << " " << r[j];
}
std::cout << std::endl;
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t this_locality = hpx::get_locality_id();
auto all_to_all_direct_client =
create_communicator(all_to_all_direct_basename,
num_sites_arg(num_localities), this_site_arg(this_locality));
std::vector<std::uint32_t> values(num_localities);
std::fill(values.begin(), values.end(), this_locality);
hpx::future<std::vector<std::uint32_t>> overall_result =
all_to_all(all_to_all_direct_client, std::move(values));
std::vector<std::uint32_t> r = overall_result.get();
std::cout << "Locality " << this_locality << " has values:";
for (std::size_t j = 0; j != r.size(); ++j)
{
std::cout << " " << r[j];
}
std::cout << std::endl;
For num_localities = 2 this code will print the following message:
Locality 0 has values: 0 1
Locality 1 has values: 0 1
HPX uses the function all_to_all to implement the functionality of MPI_Alltoall. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function hpx::collectives::create_communicator() is used to create a communicator called all_to_all_direct_client.
The value each locality sends is equal to its ID.
The all-to-all operation is performed using all_to_all. The result is stored in an hpx::future object called overall_result, which represents a future result that can be retrieved later when needed.
The get() function waits until the result is available and then stores it in the variable r.
MPI_Barrier#
The following code shows how barrier is used to synchronize multiple processes.
MPI code:
#include <cstdlib>
#include <iostream>
#include <mpi.h>
int main(int argc, char **argv) {
MPI_Init(&argc, &argv);
std::size_t iterations = 5;
int rank, size;
MPI_Comm_rank(MPI_COMM_WORLD, &rank);
MPI_Comm_size(MPI_COMM_WORLD, &size);
for (std::size_t i = 0; i != iterations; ++i) {
MPI_Barrier(MPI_COMM_WORLD);
if (rank == 0) {
std::cout << "Iteration " << i << " completed." << std::endl;
}
}
MPI_Finalize();
return 0;
}
HPX equivalent:
std::size_t iterations = 5;
std::uint32_t this_locality = hpx::get_locality_id();
char const* const barrier_test_name = "/test/barrier/multiple";
hpx::distributed::barrier b(barrier_test_name);
for (std::size_t i = 0; i != iterations; ++i)
{
b.wait();
if (this_locality == 0)
{
std::cout << "Iteration " << i << " completed." << std::endl;
}
}
This code will print the following message:
Iteration 0 completed.
Iteration 1 completed.
Iteration 2 completed.
Iteration 3 completed.
Iteration 4 completed.
HPX uses the function barrier to implement the functionality of MPI_Barrier. In more detail:
After defining the number of iterations, we use hpx::get_locality_id() to get the ID of the current locality.
char const* const barrier_test_name = “/test/barrier/multiple”: This line defines a constant character array as the name of the barrier. This name is used to identify the barrier across different localities. All participating threads that use this name will synchronize at this barrier.
Using hpx::distributed::barrier b(barrier_test_name), we create an instance of the distributed barrier with the previously defined name. This barrier will be used to synchronize the execution of threads across different localities.
Running for all the desired iterations, we use b.wait() to synchronize the threads. Each thread waits until all other threads also reach this point before any of them can proceed further.
MPI_Bcast#
The following code broadcasts data from one process to all other processes.
MPI code:
#include <iostream>
#include <mpi.h>
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
int num_localities;
MPI_Comm_size(MPI_COMM_WORLD, &num_localities);
int here;
MPI_Comm_rank(MPI_COMM_WORLD, &here);
int value;
for (int i = 0; i < 5; ++i) {
if (here == 0) {
value = i + 42;
}
// Broadcast the value from process 0 to all other processes
MPI_Bcast(&value, 1, MPI_INT, 0, MPI_COMM_WORLD);
if (here != 0) {
std::cout << "Locality " << here << " received " << value << std::endl;
}
}
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t here = hpx::get_locality_id();
auto broadcast_direct_client =
create_communicator(broadcast_direct_basename,
num_sites_arg(num_localities), this_site_arg(here));
// test functionality based on immediate local result value
for (std::uint32_t i = 0; i != 5; ++i)
{
if (here == 0)
{
hpx::future<std::uint32_t> result =
broadcast_to(broadcast_direct_client, i + 42);
result.get();
}
else
{
hpx::future<std::uint32_t> result =
hpx::collectives::broadcast_from<std::uint32_t>(
broadcast_direct_client);
uint32_t r = result.get();
std::cout << "Locality " << here << " received " << r << std::endl;
}
}
For num_localities = 2 this code will print the following message:
Locality 1 received 42
Locality 1 received 43
Locality 1 received 44
Locality 1 received 45
Locality 1 received 46
HPX uses two functions to implement the functionality of MPI_Bcast: broadcast_to and broadcast_from. broadcast_to is broadcasting the data from the root locality to all other localities. broadcast_from allows non-root localities to collect the data sent by the root locality. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function create_communicator() is used to create a communicator called broadcast_direct_client.
If the current locality is the root (its ID is equal to 0):
The broadcast_to function is used to perform the broadcast operation using the communicator broadcast_direct_client. This sends the data to other localities and returns a future representing the result.
The get() member function of the result future is used to wait for and retrieve the result.
If the current locality is not the root:
The broadcast_from function is used to collect the data by the root locality.
The get() member function of the result future is used to wait for the result.
MPI_Exscan#
The following code computes the exclusive scan (partial reductions) of data on a collection of processes.
MPI code:
#include <iostream>
#include <mpi.h>
#include <numeric>
#include <vector>
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
int num_localities;
MPI_Comm_size(MPI_COMM_WORLD, &num_localities);
int here;
MPI_Comm_rank(MPI_COMM_WORLD, &here);
// Calculate the value for this locality (here)
int value = here;
// Perform an exclusive scan
std::vector<int> result(num_localities);
MPI_Exscan(&value, &result[0], 1, MPI_INT, MPI_SUM, MPI_COMM_WORLD);
if (here != 0) {
int r = result[here - 1]; // Result is in the previous rank's slot
std::cout << "Locality " << here << " has value " << r << std::endl;
}
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t here = hpx::get_locality_id();
auto exclusive_scan_client = create_communicator(exclusive_scan_basename,
num_sites_arg(num_localities), this_site_arg(here));
// test functionality based on immediate local result value
std::uint32_t value = here;
hpx::future<std::uint32_t> overall_result = exclusive_scan(
exclusive_scan_client, value, std::plus<std::uint32_t>{});
uint32_t r = overall_result.get();
if (here != 0)
{
std::cout << "Locality " << here << " has value " << r << std::endl;
}
For num_localities = 2 this code will print the following message:
Locality 1 has value 0
HPX uses the function exclusive_scan to implement MPI_Exscan. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function create_communicator() is used to create a communicator called exclusive_scan_client.
The exclusive_scan function is used to perform the exclusive scan operation using the communicator exclusive_scan_client. std::plus<std::uint32_t>{} specifies the binary associative operator to use for the scan. In this case, it’s addition for summing values.
The get() member function of the overall_result future is used to wait for the result.
MPI_Scan#
The following code Computes the inclusive scan (partial reductions) of data on a collection of processes.
MPI code:
#include <iostream>
#include <mpi.h>
#include <numeric>
#include <vector>
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
int num_localities;
MPI_Comm_size(MPI_COMM_WORLD, &num_localities);
int here;
MPI_Comm_rank(MPI_COMM_WORLD, &here);
// Calculate the value for this locality (here)
int value = here;
std::vector<int> result(num_localities);
MPI_Scan(&value, &result[0], 1, MPI_INT, MPI_SUM, MPI_COMM_WORLD);
std::cout << "Locality " << here << " has value " << result[0] << std::endl;
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t here = hpx::get_locality_id();
auto inclusive_scan_client = create_communicator(inclusive_scan_basename,
num_sites_arg(num_localities), this_site_arg(here));
std::uint32_t value = here;
hpx::future<std::uint32_t> overall_result = inclusive_scan(
inclusive_scan_client, value, std::plus<std::uint32_t>{});
uint32_t r = overall_result.get();
std::cout << "Locality " << here << " has value " << r << std::endl;
For num_localities = 2 this code will print the following message:
Locality 0 has value 0
Locality 1 has value 1
HPX uses the function inclusive_scan to implement MPI_Scan. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function create_communicator() is used to create a communicator called inclusive_scan_client.
The inclusive_scan function is used to perform the exclusive scan operation using the communicator inclusive_scan_client. std::plus<std::uint32_t>{} specifies the binary associative operator to use for the scan. In this case, it’s addition for summing values.
The get() member function of the overall_result future is used to wait for the result.
MPI_Reduce#
The following code performs a global reduce operation across all processes.
MPI code:
#include <iostream>
#include <mpi.h>
int main(int argc, char *argv[]) {
MPI_Init(&argc, &argv);
int num_processes;
MPI_Comm_size(MPI_COMM_WORLD, &num_processes);
int this_rank;
MPI_Comm_rank(MPI_COMM_WORLD, &this_rank);
int value = this_rank;
int result = 0;
// Perform the reduction operation
MPI_Reduce(&value, &result, 1, MPI_INT, MPI_SUM, 0, MPI_COMM_WORLD);
// Print the result for the root process (process 0)
if (this_rank == 0) {
std::cout << "Locality " << this_rank << " has value " << result
<< std::endl;
}
MPI_Finalize();
return 0;
}
HPX equivalent:
std::uint32_t num_localities = hpx::get_num_localities(hpx::launch::sync);
std::uint32_t this_locality = hpx::get_locality_id();
auto reduce_direct_client = create_communicator(reduce_direct_basename,
num_sites_arg(num_localities), this_site_arg(this_locality));
std::uint32_t value = hpx::get_locality_id();
if (this_locality == 0)
{
hpx::future<std::uint32_t> overall_result = reduce_here(
reduce_direct_client, value, std::plus<std::uint32_t>{});
uint32_t r = overall_result.get();
std::cout << "Locality " << this_locality << " has value " << r
<< std::endl;
}
else
{
hpx::future<void> overall_result =
reduce_there(reduce_direct_client, std::move(value));
overall_result.get();
}
This code will print the following message:
Locality 0 has value 1
HPX uses two functions to implement the functionality of MPI_Reduce: reduce_here and reduce_there. reduce_here is gathering data from all localities to the locality with ID 0 (root locality) and then performs the defined reduction operation. reduce_there allows non-root localities to participate in the reduction operation by sending data to the root locality. In more detail:
hpx::get_num_localities(hpx::launch::sync) retrieves the number of localities, while hpx::get_locality_id() returns the ID of the current locality.
The function create_communicator() is used to create a communicator called reduce_direct_client.
If the current locality is the root (its ID is equal to 0):
The reduce_here function initiates a reduction operation with addition (std::plus) as the reduction operator. The result is stored in overall_result.
The get() member function of the overall_result future is used to wait for the result.
If the current locality is not the root:
The reduce_there initiates a remote reduction operation.
The get() member function of the overall_result future is used to wait for the remote reduction operation to complete. This is done to ensure synchronization among localities.
Building tests and examples#
Tests#
To build the tests:
$ cmake --build . --target tests
To control which tests to run use ctest:
To run single tests, for example a test for
for_loop:
$ ctest --output-on-failure -R tests.unit.modules.algorithms.algorithms.for_loop
To run a whole group of tests:
$ ctest --output-on-failure -R tests.unit
Examples#
To build (and install) all examples invoke:
$ cmake -DHPX_WITH_EXAMPLES=On .
$ make examples
$ make install
To build the
hello_world_1example run:
$ make hello_world_1
HPX executables end up in the bin directory in your build directory. You
can now run hello_world_1 and should see the following output:
$ ./bin/hello_world_1
Hello World!
You’ve just run an example which prints Hello World! from the HPX runtime.
The source for the example is in examples/quickstart/hello_world_1.cpp. The
hello_world_distributed example (also available in the
examples/quickstart directory) is a distributed hello world program, which is
described in Remote execution with actions. It provides a gentle introduction to
the distributed aspects of HPX.
Tip
Most build targets in HPX have two names: a simple name and
a hierarchical name corresponding to what type of example or
test the target is. If you are developing HPX it is often helpful to run
make help to get a list of available targets. For example, make help |
grep hello_world outputs the following:
... examples.quickstart.hello_world_2
... hello_world_2
... examples.quickstart.hello_world_1
... hello_world_1
... examples.quickstart.hello_world_distributed
... hello_world_distributed
It is also possible to build, for instance, all quickstart examples using make
examples.quickstart.
Creating HPX projects#
Using HPX with pkg-config#
How to build HPX applications with pkg-config#
After you are done installing HPX, you should be able to build the following
program. It prints Hello World! on the locality you run it on.
// Including 'hpx/hpx_main.hpp' instead of the usual 'hpx/hpx_init.hpp' enables
// to use the plain C-main below as the direct main HPX entry point.
#include <hpx/hpx_main.hpp>
#include <hpx/iostream.hpp>
int main()
{
// Say hello to the world!
hpx::cout << "Hello World!\n" << std::flush;
return 0;
}
Copy the text of this program into a file called hello_world.cpp.
Now, in the directory where you put hello_world.cpp, issue the following
commands (where $HPX_LOCATION is the build directory or
CMAKE_INSTALL_PREFIX you used while building HPX):
$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$HPX_LOCATION/lib/pkgconfig
$ c++ -o hello_world hello_world.cpp \
`pkg-config --cflags --libs hpx_application`\
-lhpx_iostreams -DHPX_APPLICATION_NAME=hello_world
Important
When using pkg-config with HPX, the pkg-config flags must go after the
-o flag.
Note
HPX libraries have different names in debug and release mode. If you want
to link against a debug HPX library, you need to use the _debug suffix
for the pkg-config name. That means instead of hpx_application or
hpx_component, you will have to use hpx_application_debug or
hpx_component_debug Moreover, all referenced HPX components need to
have an appended d suffix. For example, instead of -lhpx_iostreams you will
need to specify -lhpx_iostreamsd.
Important
If the HPX libraries are in a path that is not found by the dynamic
linker, you will need to add the path $HPX_LOCATION/lib to your linker search
path (for example LD_LIBRARY_PATH on Linux).
To test the program, type:
$ ./hello_world
which should print Hello World! and exit.
How to build HPX components with pkg-config#
Let’s try a more complex example involving an HPX component. An HPX component is a class that exposes HPX actions. HPX components are compiled into dynamically loaded modules called component libraries. Here’s the source code:
hello_world_component.cpp
#include <hpx/config.hpp>
#if !defined(HPX_COMPUTE_DEVICE_CODE)
#include <hpx/iostream.hpp>
#include "hello_world_component.hpp"
#include <iostream>
namespace examples { namespace server {
void hello_world::invoke()
{
hpx::cout << "Hello HPX World!" << std::endl;
}
}} // namespace examples::server
HPX_REGISTER_COMPONENT_MODULE()
typedef hpx::components::component<examples::server::hello_world>
hello_world_type;
HPX_REGISTER_COMPONENT(hello_world_type, hello_world)
HPX_REGISTER_ACTION(
examples::server::hello_world::invoke_action, hello_world_invoke_action)
#endif
hello_world_component.hpp
#pragma once
#include <hpx/config.hpp>
#if !defined(HPX_COMPUTE_DEVICE_CODE)
#include <hpx/hpx.hpp>
#include <hpx/include/actions.hpp>
#include <hpx/include/components.hpp>
#include <hpx/include/lcos.hpp>
#include <hpx/serialization.hpp>
#include <utility>
namespace examples { namespace server {
struct HPX_COMPONENT_EXPORT hello_world
: hpx::components::component_base<hello_world>
{
void invoke();
HPX_DEFINE_COMPONENT_ACTION(hello_world, invoke)
};
}} // namespace examples::server
HPX_REGISTER_ACTION_DECLARATION(
examples::server::hello_world::invoke_action, hello_world_invoke_action)
namespace examples {
struct hello_world
: hpx::components::client_base<hello_world, server::hello_world>
{
typedef hpx::components::client_base<hello_world, server::hello_world>
base_type;
hello_world(hpx::future<hpx::id_type>&& f)
: base_type(std::move(f))
{
}
hello_world(hpx::id_type&& f)
: base_type(std::move(f))
{
}
void invoke()
{
hpx::async<server::hello_world::invoke_action>(this->get_id())
.get();
}
};
} // namespace examples
#endif
hello_world_client.cpp
#include <hpx/config.hpp>
#if defined(HPX_COMPUTE_HOST_CODE)
#include <hpx/wrap_main.hpp>
#include "hello_world_component.hpp"
int main()
{
{
// Create a single instance of the component on this locality.
examples::hello_world client =
hpx::new_<examples::hello_world>(hpx::find_here());
// Invoke the component's action, which will print "Hello World!".
client.invoke();
}
return 0;
}
#endif
Copy the three source files above into three files (called
hello_world_component.cpp, hello_world_component.hpp and
hello_world_client.cpp, respectively).
Now, in the directory where you put the files, run the following command to
build the component library. (where $HPX_LOCATION is the build directory or
CMAKE_INSTALL_PREFIX you used while building HPX):
$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$HPX_LOCATION/lib/pkgconfig
$ c++ -o libhpx_hello_world.so hello_world_component.cpp \
`pkg-config --cflags --libs hpx_component` \
-lhpx_iostreams -DHPX_COMPONENT_NAME=hpx_hello_world
Now pick a directory in which to install your HPX component libraries. For
this example, we’ll choose a directory named my_hpx_libs:
$ mkdir ~/my_hpx_libs
$ mv libhpx_hello_world.so ~/my_hpx_libs
Note
HPX libraries have different names in debug and release mode. If you want
to link against a debug HPX library, you need to use the _debug suffix
for the pkg-config name. That means instead of hpx_application or
hpx_component you will have to use hpx_application_debug or
hpx_component_debug. Moreover, all referenced HPX components need to
have a appended d suffix, e.g. instead of -lhpx_iostreams you will
need to specify -lhpx_iostreamsd.
Important
If the HPX libraries are in a path that is not found by the dynamic linker.
You need to add the path $HPX_LOCATION/lib to your linker search path
(for example LD_LIBRARY_PATH on Linux).
Now, to build the application that uses this component (hello_world_client.cpp),
we do:
$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$HPX_LOCATION/lib/pkgconfig
$ c++ -o hello_world_client hello_world_client.cpp \
``pkg-config --cflags --libs hpx_application``\
-L${HOME}/my_hpx_libs -lhpx_hello_world -lhpx_iostreams
Important
When using pkg-config with HPX, the pkg-config flags must go after the
-o flag.
Finally, you’ll need to set your LD_LIBRARY_PATH before you can run the program. To run the program, type:
$ export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$HOME/my_hpx_libs"
$ ./hello_world_client
which should print Hello HPX World! and exit.
Using HPX with CMake-based projects#
In addition to the pkg-config support discussed on the previous pages, HPX comes with full CMake support. In order to integrate HPX into existing or new CMakeLists.txt, you can leverage the find_package command integrated into CMake. Following, is a Hello World component example using CMake.
Let’s revisit what we have. We have three files that compose our example application:
hello_world_component.hpphello_world_component.cpphello_world_client.hpp
The basic structure to include HPX into your CMakeLists.txt is shown here:
# Require a recent version of cmake
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
# This project is C++ based.
project(your_app CXX)
# Instruct cmake to find the HPX settings
find_package(HPX)
In order to have CMake find HPX, it needs to be told where to look for the
HPXConfig.cmake file that is generated when HPX is built or installed. It is
used by find_package(HPX) to set up all the necessary macros needed to use
HPX in your project. The ways to achieve this are:
Set the
HPX_DIRCMake variable to point to the directory containing theHPXConfig.cmakescript on the command line when you invoke CMake:$ cmake -DHPX_DIR=$HPX_LOCATION/lib/cmake/HPX ...
where
$HPX_LOCATIONis the build directory orCMAKE_INSTALL_PREFIXyou used when building/configuring HPX.Set the
CMAKE_PREFIX_PATHvariable to the root directory of your HPX build or install location on the command line when you invoke CMake:$ cmake -DCMAKE_PREFIX_PATH=$HPX_LOCATION ...
The difference between
CMAKE_PREFIX_PATHandHPX_DIRis that CMake will add common postfixes, such aslib/cmake/<project, to theCMAKE_PREFIX_PATHand search in these locations too. Note that if your project uses HPX as well as other CMake-managed projects, the paths to the locations of these multiple projects may be concatenated in theCMAKE_PREFIX_PATH.The variables above may be set in the CMake GUI or curses ccmake interface instead of the command line.
Additionally, if you wish to require HPX for your project, replace the
find_package(HPX) line with find_package(HPX REQUIRED).
You can check if HPX was successfully found with the HPX_FOUND CMake variable.
Using CMake targets#
The recommended way of setting up your targets to use HPX is to link to the
HPX::hpx CMake target:
target_link_libraries(hello_world_component PUBLIC HPX::hpx)
This requires that you have already created the target like this:
add_library(hello_world_component SHARED hello_world_component.cpp)
target_include_directories(hello_world_component PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
When you link your library to the HPX::hpx CMake target, you will be able
use HPX functionality in your library. To use main() as the implicit entry
point in your application you must additionally link your application to the
CMake target HPX::wrap_main. This target is automatically linked to
executables if you are using the macros described below
(Using macros to create new targets). See Re-use the main() function as the main HPX entry point for more information on
implicitly using main() as the entry point.
Creating a component requires setting two additional compile definitions:
target_compile_options(hello_world_component
HPX_COMPONENT_NAME=hello_world
HPX_COMPONENT_EXPORTS)
Instead of setting these definitions manually you may link to the
HPX::component target, which sets HPX_COMPONENT_NAME to
hpx_<target_name>, where <target_name> is the target name of your
library. Note that these definitions should be PRIVATE to make sure these
definitions are not propagated transitively to dependent targets.
In addition to making your library a component you can make it a plugin. To do
so link to the HPX::plugin target. Similarly to HPX::component this will
set HPX_PLUGIN_NAME to hpx_<target_name>. This definition should also be
PRIVATE. Unlike regular shared libraries, plugins are loaded at runtime from
certain directories and will not be found without additional configuration.
Plugins should be installed into a directory containing only plugins. For
example, the plugins created by HPX itself are installed into the hpx
subdirectory in the library install directory (typically lib or lib64).
When using the HPX::plugin target you need to install your plugins into an
appropriate directory. You may also want to set the location of your plugin in
the build directory with the *_OUTPUT_DIRECTORY* CMake target properties to
be able to load the plugins in the build directory. Once you’ve set the install
or output directory of your plugin you need to tell your executable where to
find it at runtime. You can do this either by setting the environment variable
HPX_COMPONENT_PATHS or the ini setting hpx.component_paths (see
--hpx:ini) to the directory containing your plugin.
Using macros to create new targets#
In addition to the targets described above, HPX provides convenience macros to hide optional boilerplate code that may be useful for your project. The link to the targets described above. We recommend that you use the targets directly whenever possible as they tend to compose better with other targets.
The macro for adding an HPX component is add_hpx_component. It can be
used in your CMakeLists.txt file like this:
# build your application using HPX
add_hpx_component(hello_world
SOURCES hello_world_component.cpp
HEADERS hello_world_component.hpp
COMPONENT_DEPENDENCIES iostreams)
Note
add_hpx_component adds a _component suffix to the target name. In the
example above, a hello_world_component target will be created.
The available options to add_hpx_component are:
SOURCES: The source files for that componentHEADERS: The header files for that componentDEPENDENCIES: Other libraries or targets this component depends onCOMPONENT_DEPENDENCIES: The components this component depends onPLUGIN: Treats this component as a plugin-able libraryCOMPILE_FLAGS: Additional compiler flagsLINK_FLAGS: Additional linker flagsFOLDER: Adds the headers and source files to this Source Group folder
EXCLUDE_FROM_ALL: Do not build this component as part of thealltarget
After adding the component, the way you add the executable is as follows:
# build your application using HPX
add_hpx_executable(hello_world
SOURCES hello_world_client.cpp
COMPONENT_DEPENDENCIES hello_world)
Note
add_hpx_executable automatically adds a _component suffix to dependencies
specified in COMPONENT_DEPENDENCIES, meaning you can directly use the name given
when adding a component using add_hpx_component.
When you configure your application, all you need to do is set the HPX_DIR
variable to point to the installation of HPX.
Note
All library targets built with HPX are exported and readily available to be
used as arguments to target_link_libraries
in your targets. The HPX include directories are available with the
HPX_INCLUDE_DIRS CMake variable.
Using the HPX compiler wrapper hpxcxx#
The hpxcxx compiler wrapper helps to compile a HPX component, application,
or object file, based on the arguments passed to it.
$ hpxcxx [--exe=<APPLICATION_NAME> | --comp=<COMPONENT_NAME> | -c] FLAGS FILES
The hpxcxx command requires that either an application or a component is
built or -c flag is specified. If the build is against a debug build, the
-g is to be specified while building.
FLAGS#-l <LIBRARY> | -l<LIBRARY>: Links<LIBRARY>to the build-g: Specifies that the application or component build is against a debug build-rd: Setsrelease-with-debug-infooption-mr: Setsminsize-releaseoption
All other flags (like -o OUTPUT_FILE) are directly passed to the underlying
C++ compiler.
Using macros to set up existing targets to use HPX#
In addition to the add_hpx_component and add_hpx_executable, you can use
the hpx_setup_target macro to have an already existing target to be used
with the HPX libraries:
hpx_setup_target(target)
Optional parameters are:
EXPORT: Adds it to the CMake export list HPXTargetsINSTALL: Generates an install rule for the targetPLUGIN: Treats this component as a plugin-able libraryTYPE: The type can be: EXECUTABLE, LIBRARY or COMPONENTDEPENDENCIES: Other libraries or targets this component depends onCOMPONENT_DEPENDENCIES: The components this component depends onCOMPILE_FLAGS: Additional compiler flagsLINK_FLAGS: Additional linker flags
If you do not use CMake, you can still build against HPX, but you should refer to the section on How to build HPX components with pkg-config.
Note
Since HPX relies on dynamic libraries, the dynamic linker needs to know
where to look for them. If HPX isn’t installed into a path that is
configured as a linker search path, external projects need to either set
RPATH or adapt LD_LIBRARY_PATH to point to where the HPX libraries
reside. In order to set RPATHs, you can include HPX_SetFullRPATH in
your project after all libraries you want to link against have been added.
Please also consult the CMake documentation here.
Using HPX with Makefile#
A basic project building with HPX is through creating makefiles. The process
of creating one can get complex depending upon the use of cmake parameter
HPX_WITH_HPX_MAIN (which defaults to ON).
How to build HPX applications with makefile#
If HPX is installed correctly, you should be able to build and run a simple
Hello World program. It prints Hello World! on the locality you
run it on.
// Including 'hpx/hpx_main.hpp' instead of the usual 'hpx/hpx_init.hpp' enables
// to use the plain C-main below as the direct main HPX entry point.
#include <hpx/hpx_main.hpp>
#include <hpx/iostream.hpp>
int main()
{
// Say hello to the world!
hpx::cout << "Hello World!\n" << std::flush;
return 0;
}
Copy the content of this program into a file called hello_world.cpp.
Now, in the directory where you put hello_world.cpp, create a Makefile. Add the following code:
CXX=(CXX) # Add your favourite compiler here or let makefile choose default.
CXXFLAGS=-O3 -std=c++17
Boost_ROOT=/path/to/boost
Hwloc_ROOT=/path/to/hwloc
Tcmalloc_ROOT=/path/to/tcmalloc
HPX_ROOT=/path/to/hpx
INCLUDE_DIRECTIVES=$(HPX_ROOT)/include $(Boost_ROOT)/include $(Hwloc_ROOT)/include
LIBRARY_DIRECTIVES=-L$(HPX_ROOT)/lib $(HPX_ROOT)/lib/libhpx_init.a $(HPX_ROOT)/lib/libhpx.so $(Boost_ROOT)/lib/libboost_atomic-mt.so $(Boost_ROOT)/lib/libboost_filesystem-mt.so $(Boost_ROOT)/lib/libboost_program_options-mt.so $(Boost_ROOT)/lib/libboost_regex-mt.so $(Boost_ROOT)/lib/libboost_system-mt.so -lpthread $(Tcmalloc_ROOT)/libtcmalloc_minimal.so $(Hwloc_ROOT)/libhwloc.so -ldl -lrt
LINK_FLAGS=$(HPX_ROOT)/lib/libhpx_wrap.a -Wl,-wrap=main # should be left empty for HPX_WITH_HPX_MAIN=OFF
hello_world: hello_world.o
$(CXX) $(CXXFLAGS) -o hello_world hello_world.o $(LIBRARY_DIRECTIVES) $(LINK_FLAGS)
hello_world.o:
$(CXX) $(CXXFLAGS) -c -o hello_world.o hello_world.cpp $(INCLUDE_DIRECTIVES)
Important
LINK_FLAGS should be left empty if HPX_WITH_HPX_MAIN is set to OFF.
Boost in the above example is build with --layout=tagged. Actual Boost
flags may vary on your build of Boost.
To build the program, type:
$ make
A successful build should result in hello_world binary. To test, type:
$ ./hello_world
How to build HPX components with makefile#
Let’s try a more complex example involving an HPX component. An HPX component is a class that exposes HPX actions. HPX components are compiled into dynamically-loaded modules called component libraries. Here’s the source code:
hello_world_component.cpp
#include <hpx/config.hpp>
#if !defined(HPX_COMPUTE_DEVICE_CODE)
#include <hpx/iostream.hpp>
#include "hello_world_component.hpp"
#include <iostream>
namespace examples { namespace server {
void hello_world::invoke()
{
hpx::cout << "Hello HPX World!" << std::endl;
}
}} // namespace examples::server
HPX_REGISTER_COMPONENT_MODULE()
typedef hpx::components::component<examples::server::hello_world>
hello_world_type;
HPX_REGISTER_COMPONENT(hello_world_type, hello_world)
HPX_REGISTER_ACTION(
examples::server::hello_world::invoke_action, hello_world_invoke_action)
#endif
hello_world_component.hpp
#pragma once
#include <hpx/config.hpp>
#if !defined(HPX_COMPUTE_DEVICE_CODE)
#include <hpx/hpx.hpp>
#include <hpx/include/actions.hpp>
#include <hpx/include/components.hpp>
#include <hpx/include/lcos.hpp>
#include <hpx/serialization.hpp>
#include <utility>
namespace examples { namespace server {
struct HPX_COMPONENT_EXPORT hello_world
: hpx::components::component_base<hello_world>
{
void invoke();
HPX_DEFINE_COMPONENT_ACTION(hello_world, invoke)
};
}} // namespace examples::server
HPX_REGISTER_ACTION_DECLARATION(
examples::server::hello_world::invoke_action, hello_world_invoke_action)
namespace examples {
struct hello_world
: hpx::components::client_base<hello_world, server::hello_world>
{
typedef hpx::components::client_base<hello_world, server::hello_world>
base_type;
hello_world(hpx::future<hpx::id_type>&& f)
: base_type(std::move(f))
{
}
hello_world(hpx::id_type&& f)
: base_type(std::move(f))
{
}
void invoke()
{
hpx::async<server::hello_world::invoke_action>(this->get_id())
.get();
}
};
} // namespace examples
#endif
hello_world_client.cpp
#include <hpx/config.hpp>
#if defined(HPX_COMPUTE_HOST_CODE)
#include <hpx/wrap_main.hpp>
#include "hello_world_component.hpp"
int main()
{
{
// Create a single instance of the component on this locality.
examples::hello_world client =
hpx::new_<examples::hello_world>(hpx::find_here());
// Invoke the component's action, which will print "Hello World!".
client.invoke();
}
return 0;
}
#endif
Now, in the directory, create a Makefile. Add the following code:
CXX=(CXX) # Add your favourite compiler here or let makefile choose default.
CXXFLAGS=-O3 -std=c++17
Boost_ROOT=/path/to/boost
Hwloc_ROOT=/path/to/hwloc
Tcmalloc_ROOT=/path/to/tcmalloc
HPX_ROOT=/path/to/hpx
INCLUDE_DIRECTIVES=$(HPX_ROOT)/include $(Boost_ROOT)/include $(Hwloc_ROOT)/include
LIBRARY_DIRECTIVES=-L$(HPX_ROOT)/lib $(HPX_ROOT)/lib/libhpx_init.a $(HPX_ROOT)/lib/libhpx.so $(Boost_ROOT)/lib/libboost_atomic-mt.so $(Boost_ROOT)/lib/libboost_filesystem-mt.so $(Boost_ROOT)/lib/libboost_program_options-mt.so $(Boost_ROOT)/lib/libboost_regex-mt.so $(Boost_ROOT)/lib/libboost_system-mt.so -lpthread $(Tcmalloc_ROOT)/libtcmalloc_minimal.so $(Hwloc_ROOT)/libhwloc.so -ldl -lrt
LINK_FLAGS=$(HPX_ROOT)/lib/libhpx_wrap.a -Wl,-wrap=main # should be left empty for HPX_WITH_HPX_MAIN=OFF
hello_world_client: libhpx_hello_world hello_world_client.o
$(CXX) $(CXXFLAGS) -o hello_world_client $(LIBRARY_DIRECTIVES) libhpx_hello_world $(LINK_FLAGS)
hello_world_client.o: hello_world_client.cpp
$(CXX) $(CXXFLAGS) -o hello_world_client.o hello_world_client.cpp $(INCLUDE_DIRECTIVES)
libhpx_hello_world: hello_world_component.o
$(CXX) $(CXXFLAGS) -o libhpx_hello_world hello_world_component.o $(LIBRARY_DIRECTIVES)
hello_world_component.o: hello_world_component.cpp
$(CXX) $(CXXFLAGS) -c -o hello_world_component.o hello_world_component.cpp $(INCLUDE_DIRECTIVES)
To build the program, type:
$ make
A successful build should result in hello_world binary. To test, type:
$ ./hello_world
Note
Due to high variations in CMake flags and library dependencies, it is recommended to build HPX applications and components with pkg-config or CMakeLists.txt. Writing Makefile may result in broken builds if due care is not taken. pkg-config files and CMake systems are configured with CMake build of HPX. Hence, they are stable when used together and provide better support overall.
Starting the HPX runtime#
In order to write an application that uses services from the HPX runtime system, you need to initialize the HPX library by inserting certain calls into the code of your application. Depending on your use case, this can be done in 3 different ways:
Minimally invasive: Re-use the
main()function as the main HPX entry point.Balanced use case: Supply your own main HPX entry point while blocking the main thread.
Most flexibility: Supply your own main HPX entry point while avoiding blocking the main thread.
Suspend and resume: As above but suspend and resume the HPX runtime to allow for other runtimes to be used.
Re-use the main() function as the main HPX entry point#
This method is the least intrusive to your code. However, it provides you with the smallest flexibility in terms of initializing the HPX runtime system. The following code snippet shows what a minimal HPX application using this technique looks like:
#include <hpx/hpx_main.hpp>
int main(int argc, char* argv[])
{
return 0;
}
The only change to your code you have to make is to include the file
hpx/hpx_main.hpp. In this case the function main() will be invoked as
the first HPX thread of the application. The runtime system will be
initialized behind the scenes before the function main() is executed and
will automatically stop after main() has returned. For this method to work
you must link your application to the CMake target HPX::wrap_main. This is
done automatically if you are using the provided macros
(Using macros to create new targets) to set up your application, but must be done
explicitly if you are using targets directly (Using CMake targets).
All HPX API functions can be used from within the main() function now.
Note
The function main() does not need to expect receiving argc and
argv as shown above, but could expose the signature int main(). This
is consistent with the usually allowed prototypes for the function main()
in C++ applications.
All command line arguments specific to HPX will still be processed by the
HPX runtime system as usual. However, those command line options will be
removed from the list of values passed to argc/argv of the function
main(). The list of values passed to main() will hold only the
commandline options that are not recognized by the HPX runtime system (see
the section HPX Command Line Options for more details on what options are recognized
by HPX).
Note
In this mode all one-letter shortcuts that are normally
available on the HPX command line are disabled (such as -t or -l see
HPX Command Line Options). This is done to minimize any possible interaction
between the command line options recognized by the HPX runtime system and
any command line options defined by the application.
The value returned from the function main() as shown above will be returned
to the operating system as usual.
Important
To achieve this seamless integration, the header file hpx/hpx_main.hpp
defines a macro:
#define main hpx_startup::user_main
which could result in unexpected behavior.
Important
To achieve this seamless integration, we use different implementations for
different operating systems. In case of Linux or macOS, the code present in
hpx_wrap.cpp is put into action. We hook into the system function in case
of Linux and provide alternate entry point in case of macOS. For other
operating systems we rely on a macro:
#define main hpx_startup::user_main
provided in the header file hpx/hpx_main.hpp. This implementation can
result in unexpected behavior.
Caution
We make use of an override variable include_libhpx_wrap in the header
file hpx/hpx_main.hpp to swiftly choose the function call stack at
runtime. Therefore, the header file should only be included in the main
executable. Including it in the components will result in multiple definition
of the variable.
Supply your own main HPX entry point while blocking the main thread#
With this method you need to provide an explicit main-thread function named
hpx_main at global scope. This function will be invoked as the main entry
point of your HPX application on the console locality only (this
function will be invoked as the first HPX thread of your application). All
HPX API functions can be used from within this function.
The thread executing the function hpx::init will block waiting for
the runtime system to exit. The value returned from hpx_main will be
returned from hpx::init after the runtime system has stopped.
The function hpx::finalize has to be called on one of the HPX
localities in order to signal that all work has been scheduled and the runtime
system should be stopped after the scheduled work has been executed.
This method of invoking HPX has the advantage of the user being able to decide
which version of hpx::init to call. This allows to pass
additional configuration parameters while initializing the HPX runtime system.
#include <hpx/hpx_init.hpp>
int hpx_main(int argc, char* argv[])
{
// Any HPX application logic goes here...
return hpx::finalize();
}
int main(int argc, char* argv[])
{
// Initialize HPX, run hpx_main as the first HPX thread, and
// wait for hpx::finalize being called.
return hpx::init(argc, argv);
}
Note
The function hpx_main does not need to expect receiving argc/argv
as shown above, but could expose one of the following signatures:
int hpx_main();
int hpx_main(int argc, char* argv[]);
int hpx_main(hpx::program_options::variables_map& vm);
This is consistent with (and extends) the usually allowed prototypes for the
function main() in C++ applications.
The header file to include for this method of using HPX is
hpx/hpx_init.hpp.
There are many additional overloads of hpx::init available, such as
the ability to provide your own entry-point function instead of hpx_main.
Please refer to the function documentation for more details (see: hpx/hpx_init.hpp).
Supply your own main HPX entry point while avoiding blocking the main thread#
With this method you need to provide an explicit main thread function named
hpx_main at global scope. This function will be invoked as the main entry
point of your HPX application on the console locality only (this
function will be invoked as the first HPX thread of your application). All
HPX API functions can be used from within this function.
The thread executing the function hpx::start will not block
waiting for the runtime system to exit, but will return immediately.
The function hpx::finalize has to be called on one of the HPX
localities in order to signal that all work has been scheduled and the runtime
system should be stopped after the scheduled work has been executed.
This method of invoking HPX is useful for applications where the main thread
is used for special operations, such a GUIs. The function hpx::stop
can be used to wait for the HPX runtime system to exit and should at least be
used as the last function called in main(). The value returned from
hpx_main will be returned from hpx::stop after the runtime
system has stopped.
#include <hpx/hpx_start.hpp>
int hpx_main(int argc, char* argv[])
{
// Any HPX application logic goes here...
return hpx::finalize();
}
int main(int argc, char* argv[])
{
// Initialize HPX, run hpx_main.
hpx::start(argc, argv);
// ...Execute other code here...
// Wait for hpx::finalize being called.
return hpx::stop();
}
Note
The function hpx_main does not need to expect receiving argc/argv
as shown above, but could expose one of the following signatures:
int hpx_main();
int hpx_main(int argc, char* argv[]);
int hpx_main(hpx::program_options::variables_map& vm);
This is consistent with (and extends) the usually allowed prototypes for the
function main() in C++ applications.
The header file to include for this method of using HPX is
hpx/hpx_start.hpp.
There are many additional overloads of hpx::start available, such as
the option for users to provide their own entry point function instead of hpx_main.
Please refer to the function documentation for more details (see:
hpx/hpx_start.hpp).
Supply your own explicit startup function as the main HPX entry point#
There is also a way to specify any function (besides hpx_main) to be used as
the main entry point for your HPX application:
#include <hpx/hpx_init.hpp>
int application_entry_point(int argc, char* argv[])
{
// Any HPX application logic goes here...
return hpx::finalize();
}
int main(int argc, char* argv[])
{
// Initialize HPX, run application_entry_point as the first HPX thread,
// and wait for hpx::finalize being called.
return hpx::init(&application_entry_point, argc, argv);
}
Note
The function supplied to hpx::init must have one of the following
prototypes:
int application_entry_point(int argc, char* argv[]); int application_entry_point(hpx::program_options::variables_map& vm);
Note
If nullptr is used as the function argument, HPX will not run any
startup function on this locality.
Suspending and resuming the HPX runtime#
In some applications it is required to combine HPX with other runtimes. To
support this use case, HPX provides two functions: hpx::suspend and
hpx::resume. hpx::suspend is a blocking call which will
wait for all scheduled tasks to finish executing and then put the thread pool OS
threads to sleep. hpx::resume simply wakes up the sleeping threads
so that they are ready to accept new work. hpx::suspend and
hpx::resume can be found in the header hpx/hpx_suspend.hpp.
#include <hpx/hpx_start.hpp>
#include <hpx/hpx_suspend.hpp>
int main(int argc, char* argv[])
{
// Initialize HPX, don't run hpx_main
hpx::start(nullptr, argc, argv);
// Schedule a function on the HPX runtime
hpx::post(&my_function, ...);
// Wait for all tasks to finish, and suspend the HPX runtime
hpx::suspend();
// Execute non-HPX code here
// Resume the HPX runtime
hpx::resume();
// Schedule more work on the HPX runtime
// hpx::finalize has to be called from the HPX runtime before hpx::stop
hpx::post([]() { hpx::finalize(); });
return hpx::stop();
}
Note
hpx::suspend does not wait for hpx::finalize to be
called. Only call hpx::finalize when you wish to fully stop the
HPX runtime.
Warning
hpx::suspendonly waits for local tasks, i.e. tasks on thecurrent locality, to finish executing. When using
hpx::suspendin a multi-locality scenario the user is responsible for ensuring that any work required from other localities has also finished.
HPX also supports suspending individual thread pools and threads. For details
on how to do that, see the documentation for hpx::threads::thread_pool_base.
Automatically suspending worker threads#
The previous method guarantees that the worker threads are suspended when you ask for it and that they stay suspended. An alternative way to achieve the same effect is to tweak how quickly HPX suspends its worker threads when they run out of work. The following configuration values make sure that HPX idles very quickly:
hpx.max_idle_backoff_time = 1000
hpx.max_idle_loop_count = 0
They can be set on the command line using
--hpx:ini=hpx.max_idle_backoff_time=1000 and
--hpx:ini=hpx.max_idle_loop_count=0. See Launching and configuring HPX applications
for more details on how to set configuration parameters.
After setting idling parameters the previous example could now be written like this instead:
#include <hpx/hpx_start.hpp>
int main(int argc, char* argv[])
{
// Initialize HPX, don't run hpx_main
hpx::start(nullptr, argc, argv);
// Schedule some functions on the HPX runtime
// NOTE: run_as_hpx_thread blocks until completion.
hpx::run_as_hpx_thread(&my_function, ...);
hpx::run_as_hpx_thread(&my_other_function, ...);
// hpx::finalize has to be called from the HPX runtime before hpx::stop
hpx::post([]() { hpx::finalize(); });
return hpx::stop();
}
In this example each call to hpx::run_as_hpx_thread acts as a
“parallel region”.
Working of hpx_main.hpp#
In order to initialize HPX from main(), we make use of linker tricks.
It is implemented differently for different operating systems. The method of implementation is as follows:
Linux: Using linker
--wrapoption.Mac OSX: Using the linker
-eoption.Windows: Using
#define main hpx_startup::user_main
Linux implementation#
We make use of the Linux linker ld‘s --wrap option to wrap the
main() function. This way any calls to main() are redirected to our own
implementation of main. It is here that we check for the existence of
hpx_main.hpp by making use of a shadow variable include_libhpx_wrap. The
value of this variable determines the function stack at runtime.
The implementation can be found in libhpx_wrap.a.
Important
It is necessary that hpx_main.hpp be not included more than once.
Multiple inclusions can result in multiple definition of
include_libhpx_wrap.
Mac OSX implementation#
Here we make use of yet another linker option -e to change the entry point
to our custom entry function initialize_main. We initialize the HPX
runtime system from this function and call main from the initialized system. We
determine the function stack at runtime by making use of the shadow variable
include_libhpx_wrap.
The implementation can be found in libhpx_wrap.a.
Important
It is necessary that hpx_main.hpp be not included more than once.
Multiple inclusions can result in multiple definition of
include_libhpx_wrap.
Windows implementation#
We make use of a macro #define main hpx_startup::user_main to take care of
the initializations.
This implementation could result in unexpected behaviors.
Launching and configuring HPX applications#
Configuring HPX applications#
All HPX applications can be configured using special command line options and/or using special configuration files. This section describes the available options, the configuration file format, and the algorithm used to locate possible predefined configuration files. Additionally, this section describes the defaults assumed if no external configuration information is supplied.
During startup any HPX application applies a predefined search pattern to locate one or more configuration files. All found files will be read and merged in the sequence they are found into one single internal database holding all configuration properties. This database is used during the execution of the application to configure different aspects of the runtime system.
In addition to the ini files, any application can supply its own configuration
files, which will be merged with the configuration database as well. Moreover,
the user can specify additional configuration parameters on the command line
when executing an application. The HPX runtime system will merge all command
line configuration options (see the description of the --hpx:ini,
--hpx:config, and --hpx:app-config command line options).
The HPX ini file format#
All HPX applications can be configured using a special file format that is
similar to the well-known Windows INI file format. This is a structured text format
that allows users to group key/value pairs (properties) into sections. The basic element
contained in an ini file is the property. Every property has a name and a
value, delimited by an equal sign '='. The name appears to the left of the
equal sign:
name=value
The value may contain equal signs as only the first '=' character
is interpreted as the delimiter between name and value. Whitespace before
the name, after the value and immediately before and after the delimiting equal
sign is ignored. Whitespace inside the value is retained.
Properties may be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets. All properties after the section declaration are associated with that section. There is no explicit “end of section” delimiter; sections end at the next section declaration or the end of the file:
[section]
In HPX sections can be nested. A nested section has a name composed of
all section names it is embedded in. The section names are concatenated using
a dot '.':
[outer_section.inner_section]
Here, inner_section is logically nested within outer_section.
It is possible to use the full section name concatenated with the property name to refer to a particular property. For example, in:
[a.b.c]
d = e
the property value of d can be referred to as a.b.c.d=e.
In HPX ini files can contain comments. Hash signs '#' at the beginning
of a line indicate a comment. All characters starting with '#' until the
end of the line are ignored.
If a property with the same name is reused inside a section, the second occurrence of this property name will override the first occurrence (discard the first value). Duplicate sections simply merge their properties together, as if they occurred contiguously.
In HPX ini files a property value ${FOO:default} will use the environmental
variable FOO to extract the actual value if it is set and default otherwise.
No default has to be specified. Therefore, ${FOO} refers to the environmental
variable FOO. If FOO is not set or empty, the overall expression will evaluate
to an empty string. A property value $[section.key:default] refers to the value
held by the property section.key if it exists and default otherwise. No
default has to be specified. Therefore $[section.key] refers to the property
section.key. If the property section.key is not set or empty, the overall
expression will evaluate to an empty string.
Note
Any property $[section.key:default] is evaluated whenever it is queried
and not when the configuration data is initialized. This allows for lazy
evaluation and relaxes initialization order of different sections. The only
exception are recursive property values, e.g., values referring to the very
key they are associated with. Those property values are evaluated at
initialization time to avoid infinite recursion.
Built-in default configuration settings#
During startup any HPX application applies a predefined search pattern to locate one or more configuration files. All found files will be read and merged in the sequence they are found into one single internal data structure holding all configuration properties.
As a first step the internal configuration database is filled with a set of default configuration properties. Those settings are described on a section by section basis below.
Note
You can print the default configuration settings used for an executable
by specifying the command line option --hpx:dump-config.
system configuration section#[system]
pid = <process-id>
prefix = <current prefix path of core HPX library>
executable = <current prefix path of executable>
Property |
Description |
|
This is initialized to store the current OS-process id of the application instance. |
|
This is initialized to the base directory HPX has been loaded from. |
|
This is initialized to the base directory the current executable has been loaded from. |
[hpx]
location = ${HPX_LOCATION:$[system.prefix]}
component_path = $[hpx.location]/lib/hpx:$[system.executable_prefix]/lib/hpx:$[system.executable_prefix]/../lib/hpx
master_ini_path = $[hpx.location]/share/hpx-<version>:$[system.executable_prefix]/share/hpx-<version>:$[system.executable_prefix]/../share/hpx-<version>
ini_path = $[hpx.master_ini_path]/ini
os_threads = 1
cores = all
localities = 1
program_name =
cmd_line =
lock_detection = ${HPX_LOCK_DETECTION:0}
throw_on_held_lock = ${HPX_THROW_ON_HELD_LOCK:1}
minimal_deadlock_detection = <debug>
spinlock_deadlock_detection = <debug>
spinlock_deadlock_detection_limit = ${HPX_SPINLOCK_DEADLOCK_DETECTION_LIMIT:1000000}
max_background_threads = ${HPX_MAX_BACKGROUND_THREADS:$[hpx.os_threads]}
max_idle_loop_count = ${HPX_MAX_IDLE_LOOP_COUNT:<hpx_idle_loop_count_max>}
max_busy_loop_count = ${HPX_MAX_BUSY_LOOP_COUNT:<hpx_busy_loop_count_max>}
max_idle_backoff_time = ${HPX_MAX_IDLE_BACKOFF_TIME:<hpx_idle_backoff_time_max>}
exception_verbosity = ${HPX_EXCEPTION_VERBOSITY:2}
trace_depth = ${HPX_TRACE_DEPTH:20}
handle_signals = ${HPX_HANDLE_SIGNALS:1}
handle_failed_new = ${HPX_HANDLE_FAILED_NEW:1}
[hpx.stacks]
small_size = ${HPX_SMALL_STACK_SIZE:<hpx_small_stack_size>}
medium_size = ${HPX_MEDIUM_STACK_SIZE:<hpx_medium_stack_size>}
large_size = ${HPX_LARGE_STACK_SIZE:<hpx_large_stack_size>}
huge_size = ${HPX_HUGE_STACK_SIZE:<hpx_huge_stack_size>}
use_guard_pages = ${HPX_THREAD_GUARD_PAGE:1}
Property |
Description |
|
This is initialized to the id of the locality this application instance is running on. |
|
Duplicates are discarded.
This property can refer to a list of directories separated by |
|
This is initialized to the list of default paths of the main hpx.ini
configuration files. This property can refer to a list of directories
separated by |
|
This is initialized to the default path where HPX will look for more
ini configuration files. This property can refer to a list of directories
separated by |
|
This setting reflects the number of OS threads used for running HPX threads. Defaults to number of detected cores (not hyperthreads/PUs). |
|
This setting reflects the number of cores used for running HPX threads. Defaults to number of detected cores (not hyperthreads/PUs). |
|
This setting reflects the number of localities the application is running
on. Defaults to |
|
This setting reflects the program name of the application instance.
Initialized from the command line |
|
This setting reflects the actual command line used to launch this application instance. |
|
This setting verifies that no locks are being held while a HPX thread
is suspended. This setting is applicable only if
|
|
This setting causes an exception if during lock detection at least one
lock is being held while a HPX thread is suspended. This setting is
applicable only if |
|
This setting enables support for minimal deadlock detection for
HPX threads. By default this is set to |
|
This setting verifies that spinlocks don’t spin longer than specified
using the |
|
This setting specifies the upper limit of the allowed number of spins that
spinlocks are allowed to perform. This setting is applicable only if
|
|
This setting defines the number of threads in the scheduler, which are used to execute background work. By default this is the same as the number of cores used for the scheduler. |
|
By default this is defined by the preprocessor constant
|
|
This setting defines the maximum value of the busy-loop counter in the
scheduler. By default this is defined by the preprocessor constant
|
|
This setting defines the maximum time (in milliseconds) for the scheduler
to sleep after being idle for |
|
This setting defines the verbosity of exceptions. Valid values are
integers. A setting of |
|
This setting defines the number of stack-levels printed in generated
stack backtraces. This defaults to |
|
This setting defines whether HPX will register signal handlers that will
print the configuration information (stack backtrace, system information,
etc.) whenever a signal is raised. The default is |
|
This setting defines whether HPX will register a handler for failed
allocationsthat will print the configuration information
(stack backtrace, system information, etc.) whenever an allocation fails.
The default is |
|
This is initialized to the small stack size to be used by HPX threads.
Set by default to the value of the compile time preprocessor constant
|
|
This is initialized to the medium stack size to be used by HPX threads.
Set by default to the value of the compile time preprocessor constant
|
|
This is initialized to the large stack size to be used by HPX threads.
Set by default to the value of the compile time preprocessor constant
|
|
This is initialized to the huge stack size to be used by HPX threads.
Set by default to the value of the compile time preprocessor constant
|
|
This entry controls whether the coroutine library will generate stack
guard pages or not. This entry is applicable on Linux only and only if
the |
hpx.threadpools configuration section#[hpx.threadpools]
io_pool_size = ${HPX_NUM_IO_POOL_SIZE:2}
parcel_pool_size = ${HPX_NUM_PARCEL_POOL_SIZE:2}
timer_pool_size = ${HPX_NUM_TIMER_POOL_SIZE:2}
Property |
Description |
|
The value of this property defines the number of OS threads created for the internal I/O thread pool. |
|
The value of this property defines the number of OS threads created for the internal parcel thread pool. |
|
The value of this property defines the number of OS threads created for the internal timer thread pool. |
hpx.thread_queue configuration section#Important
These are the setting control internal values used by the thread scheduling queues in the HPX scheduler. You should not modify these settings unless you know exactly what you are doing.
[hpx.thread_queue]
min_tasks_to_steal_pending = ${HPX_THREAD_QUEUE_MIN_TASKS_TO_STEAL_PENDING:0}
min_tasks_to_steal_staged = ${HPX_THREAD_QUEUE_MIN_TASKS_TO_STEAL_STAGED:0}
min_add_new_count = ${HPX_THREAD_QUEUE_MIN_ADD_NEW_COUNT:10}
max_add_new_count = ${HPX_THREAD_QUEUE_MAX_ADD_NEW_COUNT:10}
max_delete_count = ${HPX_THREAD_QUEUE_MAX_DELETE_COUNT:1000}
Property |
Description |
|
The value of this property defines the number of pending HPX threads that have to be available before neighboring cores are allowed to steal work. The default is to allow stealing always. |
|
The value of this property defines the number of staged HPX tasks that need to be available before neighboring cores are allowed to steal work. The default is to allow stealing always. |
|
The value of this property defines the minimal number of tasks to be converted into HPX threads whenever the thread queues for a core have run empty. |
|
The value of this property defines the maximal number of tasks to be converted into HPX threads whenever the thread queues for a core have run empty. |
|
The value of this property defines the number of terminated HPX threads to discard during each invocation of the corresponding function. |
hpx.components configuration section#[hpx.components]
load_external = ${HPX_LOAD_EXTERNAL_COMPONENTS:1}
Property |
Description |
|
This entry defines whether external components will be loaded on this
locality. This entry is normally set to |
Additionally, the section hpx.components will be populated with the
information gathered from all found components. The information loaded for each
of the components will contain at least the following properties:
[hpx.components.<component_instance_name>]
name = <component_name>
path = <full_path_of_the_component_module>
enabled = $[hpx.components.load_external]
Property |
Description |
|
This is the name of a component, usually the same as the second argument
to the macro used while registering the component with
|
|
This is either the full path file name of the component module or the
directory the component module is located in. In this case, the component
module name will be derived from the property
|
|
This setting explicitly enables or disables the component. This is an optional property. HPX assumes that the component is enabled if it is not defined. |
The value for <component_instance_name> is usually the same as for the
corresponding name property. However, generally it can be defined to any
arbitrary instance name. It is used to distinguish between different ini
sections, one for each component.
hpx.parcel configuration section#[hpx.parcel]
address = ${HPX_PARCEL_SERVER_ADDRESS:<hpx_initial_ip_address>}
port = ${HPX_PARCEL_SERVER_PORT:<hpx_initial_ip_port>}
bootstrap = ${HPX_PARCEL_BOOTSTRAP:<hpx_parcel_bootstrap>}
max_connections = ${HPX_PARCEL_MAX_CONNECTIONS:<hpx_parcel_max_connections>}
max_connections_per_locality = ${HPX_PARCEL_MAX_CONNECTIONS_PER_LOCALITY:<hpx_parcel_max_connections_per_locality>}
max_message_size = ${HPX_PARCEL_MAX_MESSAGE_SIZE:<hpx_parcel_max_message_size>}
max_outbound_message_size = ${HPX_PARCEL_MAX_OUTBOUND_MESSAGE_SIZE:<hpx_parcel_max_outbound_message_size>}
array_optimization = ${HPX_PARCEL_ARRAY_OPTIMIZATION:1}
zero_copy_optimization = ${HPX_PARCEL_ZERO_COPY_OPTIMIZATION:$[hpx.parcel.array_optimization]}
zero_copy_receive_optimization = ${HPX_PARCEL_ZERO_COPY_RECEIVE_OPTIMIZATION:$[hpx.parcel.array_optimization]}
async_serialization = ${HPX_PARCEL_ASYNC_SERIALIZATION:1}
message_handlers = ${HPX_PARCEL_MESSAGE_HANDLERS:0}
Property |
Description |
|
This property defines the default IP address to be used for the parcel
layer to listen to. This IP address will be used as long as no other
values are specified (for instance, using the |
|
This property defines the default IP port to be used for the parcel layer
to listen to. This IP port will be used as long as no other values are
specified (for instance using the |
|
This property defines which parcelport type should be used during
application bootstrap. The default depends on the compile time
preprocessor constant |
|
This property defines how many network connections between different
localities are overall kept alive by each locality. The
default depends on the compile time preprocessor constant
|
|
This property defines the maximum number of network connections that one
locality will open to another locality. The default depends
on the compile time preprocessor constant
|
|
This property defines the maximum allowed message size that will be
transferrable through the parcel layer. The default depends on the
compile time preprocessor constant |
|
This property defines the maximum allowed outbound coalesced message size
that will be transferrable through the parcel layer. The default depends
on the compile time preprocessor constant
|
|
This property defines whether this locality is allowed to utilize
array optimizations during serialization of parcel data. The default is
|
|
This property defines whether this locality is allowed to utilize
zero copy optimizations during serialization of parcel data. The default
is the same value as set for |
|
This property defines whether this locality is allowed to utilize
zero copy optimizations on the receiving end during de-serialization of
parcel data. The default is the same value as set for
|
|
This property defines the threshold value (in bytes) starting at which the
serialization layer will apply zero-copy optimizations for serialized
entities. The default value is defined by the preprocessor constant
|
|
This property defines whether this locality is allowed to spawn a
new thread for serialization (this is both for encoding and decoding
parcels). The default is |
|
This property defines whether message handlers are loaded. The default is
|
|
This property defines how many cores should be used to perform background
operations. The default is |
The following settings relate to the TCP/IP parcelport.
[hpx.parcel.tcp]
enable = ${HPX_HAVE_PARCELPORT_TCP:$[hpx.parcel.enabled]}
array_optimization = ${HPX_PARCEL_TCP_ARRAY_OPTIMIZATION:$[hpx.parcel.array_optimization]}
zero_copy_optimization = ${HPX_PARCEL_TCP_ZERO_COPY_OPTIMIZATION:$[hpx.parcel.zero_copy_optimization]}
zero_copy_receive_optimization = ${HPX_PARCEL_TCP_ZERO_COPY_RECEIVE_OPTIMIZATION:$[hpx.parcel.zero_copy_receive_optimization]}
zero_copy_serialization_threshold = ${HPX_PARCEL_TCP_ZERO_COPY_SERIALIZATION_THRESHOLD:$[hpx.parcel.zero_copy_serialization_threshold]}
async_serialization = ${HPX_PARCEL_TCP_ASYNC_SERIALIZATION:$[hpx.parcel.async_serialization]}
parcel_pool_size = ${HPX_PARCEL_TCP_PARCEL_POOL_SIZE:$[hpx.threadpools.parcel_pool_size]}
max_connections = ${HPX_PARCEL_TCP_MAX_CONNECTIONS:$[hpx.parcel.max_connections]}
max_connections_per_locality = ${HPX_PARCEL_TCP_MAX_CONNECTIONS_PER_LOCALITY:$[hpx.parcel.max_connections_per_locality]}
max_message_size = ${HPX_PARCEL_TCP_MAX_MESSAGE_SIZE:$[hpx.parcel.max_message_size]}
max_outbound_message_size = ${HPX_PARCEL_TCP_MAX_OUTBOUND_MESSAGE_SIZE:$[hpx.parcel.max_outbound_message_size]}
max_background_threads = ${HPX_PARCEL_TCP_MAX_BACKGROUND_THREADS:$[hpx.parcel.max_background_threads]}
Property |
Description |
|
Enables the use of the default TCP parcelport. Note that the initial bootstrap of the overall HPX application will be performed using the default TCP connections. This parcelport is enabled by default. This will be disabled only if MPI is enabled (see below). |
|
This property defines whether this locality is allowed to utilize
array optimizations in the TCP/IP parcelport during serialization of
parcel data. The default is the same value as set for
|
|
This property defines whether this locality is allowed to utilize
zero copy optimizations during serialization of
parcel data. The default is the same value as set for
|
|
This property defines whether this locality is allowed to utilize
zero copy optimizations on the receiving end in the TCP/IP parcelport during
de-serialization of parcel data. The default is the same value as set
for |
|
This property defines the threshold value (in bytes) starting at which the
serialization layer will apply zero-copy optimizations for serialized
entities. The default is the same value as set for
|
|
This property defines whether this locality is allowed to spawn a
new thread for serialization in the TCP/IP parcelport (this is both for
encoding and decoding parcels). The default is the same value as set for
|
|
The value of this property defines the number of OS threads created for
the internal parcel thread pool of the TCP parcel port. The default is
taken from |
|
This property defines how many network connections between different
localities are overall kept alive by each locality. The
default is taken from |
|
This property defines the maximum number of network connections that one
locality will open to another locality. The default is
taken from |
|
This property defines the maximum allowed message size that will be
transferrable through the parcel layer. The default is taken from
|
|
This property defines the maximum allowed outbound coalesced message size
that will be transferrable through the parcel layer. The default is
taken from |
|
This property defines how many cores should be used to perform background
operations. The default is taken from |
The following settings relate to the MPI parcelport. These settings take effect
only if the compile time constant HPX_HAVE_PARCELPORT_MPI is set (the
equivalent CMake variable is HPX_WITH_PARCELPORT_MPI and has to be set to
ON).
[hpx.parcel.mpi]
enable = ${HPX_HAVE_PARCELPORT_MPI:$[hpx.parcel.enabled]}
env = ${HPX_HAVE_PARCELPORT_MPI_ENV:MV2_COMM_WORLD_RANK,PMI_RANK,OMPI_COMM_WORLD_SIZE,ALPS_APP_PE,PALS_NODEID}
multithreaded = ${HPX_HAVE_PARCELPORT_MPI_MULTITHREADED:1}
rank = <MPI_rank>
processor_name = <MPI_processor_name>
array_optimization = ${HPX_HAVE_PARCEL_MPI_ARRAY_OPTIMIZATION:$[hpx.parcel.array_optimization]}
zero_copy_optimization = ${HPX_HAVE_PARCEL_MPI_ZERO_COPY_OPTIMIZATION:$[hpx.parcel.zero_copy_optimization]}
zero_copy_receive_optimization = ${HPX_HAVE_PARCEL_MPI_ZERO_COPY_RECEIVE_OPTIMIZATION:$[hpx.parcel.zero_copy_receive_optimization]}
zero_copy_serialization_threshold = ${HPX_PARCEL_MPI_ZERO_COPY_SERIALIZATION_THRESHOLD:$[hpx.parcel.zero_copy_serialization_threshold]}
use_io_pool = ${HPX_HAVE_PARCEL_MPI_USE_IO_POOL:$1}
async_serialization = ${HPX_HAVE_PARCEL_MPI_ASYNC_SERIALIZATION:$[hpx.parcel.async_serialization]}
parcel_pool_size = ${HPX_HAVE_PARCEL_MPI_PARCEL_POOL_SIZE:$[hpx.threadpools.parcel_pool_size]}
max_connections = ${HPX_HAVE_PARCEL_MPI_MAX_CONNECTIONS:$[hpx.parcel.max_connections]}
max_connections_per_locality = ${HPX_HAVE_PARCEL_MPI_MAX_CONNECTIONS_PER_LOCALITY:$[hpx.parcel.max_connections_per_locality]}
max_message_size = ${HPX_HAVE_PARCEL_MPI_MAX_MESSAGE_SIZE:$[hpx.parcel.max_message_size]}
max_outbound_message_size = ${HPX_HAVE_PARCEL_MPI_MAX_OUTBOUND_MESSAGE_SIZE:$[hpx.parcel.max_outbound_message_size]}
max_background_threads = ${HPX_PARCEL_MPI_MAX_BACKGROUND_THREADS:$[hpx.parcel.max_background_threads]}
Property |
Description |
|
Enables the use of the MPI parcelport. HPX tries to detect if the application was started within a parallel MPI environment. If the detection was successful, the MPI parcelport is enabled by default. To explicitly disable the MPI parcelport, set to 0. Note that the initial bootstrap of the overall HPX application will be performed using MPI as well. |
|
This property influences which environment variables (separated by commas) will be analyzed to find out whether the application was invoked by MPI. |
|
This property is used to determine what threading mode to use when
initializing MPI. If this setting is |
|
This property will be initialized to the MPI rank of the locality. |
|
This property will be initialized to the MPI processor name of the locality. |
|
This property defines whether this locality is allowed to utilize
array optimizations in the MPI parcelport during serialization of
parcel data. The default is the same value as set for
|
|
This property defines whether this locality is allowed to utilize
zero copy optimizations in the MPI parcelport during serialization of
parcel data. The default is the same value as set for
|
|
This property defines whether this locality is allowed to utilize
zero copy optimizations on the receiving end in the MPI parcelport during
de-serialization of parcel data. The default is the same value as
set for |
|
This property defines the threshold value (in bytes) starting at which the
serialization layer will apply zero-copy optimizations for serialized
entities. The default is the same value as set for
|
|
This property can be set to run the progress thread inside of HPX threads
instead of a separate thread pool. The default is |
|
This property defines whether this locality is allowed to spawn a
new thread for serialization in the MPI parcelport (this is both for
encoding and decoding parcels). The default is the same value as set for
|
|
The value of this property defines the number of OS threads created for
the internal parcel thread pool of the MPI parcel port. The default is
taken from |
|
This property defines how many network connections between different
localities are overall kept alive by each locality. The
default is taken from |
|
This property defines the maximum number of network connections that one
locality will open to another locality. The default is
taken from |
|
This property defines the maximum allowed message size that will be
transferrable through the parcel layer. The default is taken from
|
|
This property defines the maximum allowed outbound coalesced message size
that will be transferrable through the parcel layer. The default is
taken from |
|
This property defines how many cores should be used to perform background
operations. The default is taken from |
hpx.agas configuration section#[hpx.agas]
address = ${HPX_AGAS_SERVER_ADDRESS:<hpx_initial_ip_address>}
port = ${HPX_AGAS_SERVER_PORT:<hpx_initial_ip_port>}
service_mode = hosted
dedicated_server = 0
max_pending_refcnt_requests = ${HPX_AGAS_MAX_PENDING_REFCNT_REQUESTS:<hpx_initial_agas_max_pending_refcnt_requests>}
use_caching = ${HPX_AGAS_USE_CACHING:1}
use_range_caching = ${HPX_AGAS_USE_RANGE_CACHING:1}
local_cache_size = ${HPX_AGAS_LOCAL_CACHE_SIZE:<hpx_agas_local_cache_size>}
Property |
Description |
|
This property defines the default IP address to be used for the
AGAS root server. This IP address will be used as long as no
other values are specified (for instance, using the |
|
This property defines the default IP port to be used for the AGAS
root server. This IP port will be used as long as no other values are
specified (for instance, using the |
|
This property specifies what type of AGAS service is running on
this locality. Currently, two modes exist. The locality
that acts as the AGAS server runs in |
|
This property specifies whether the AGAS server is exclusively
running AGAS services and not hosting any application components.
It is a boolean value. Set to |
|
This property defines the number of reference counting requests
(increments or decrements) to buffer. The default depends on the compile
time preprocessor constant
|
|
This property specifies whether a software address translation cache is
used. It is a boolean value. Defaults to |
|
This property specifies whether range-based caching is used by the
software address translation cache. This property is ignored if
hpx.agas.use_caching is false. It is a boolean value. Defaults to |
|
This property defines the size of the software address translation cache
for AGAS services. This property is ignored
if |
hpx.commandline configuration section#The following table lists the definition of all pre-defined command line option shortcuts. For more information about commandline options, see the section HPX Command Line Options.
[hpx.commandline]
aliasing = ${HPX_COMMANDLINE_ALIASING:1}
allow_unknown = ${HPX_COMMANDLINE_ALLOW_UNKNOWN:0}
[hpx.commandline.aliases]
-a = --hpx:agas
-c = --hpx:console
-h = --hpx:help
-I = --hpx:ini
-l = --hpx:localities
-p = --hpx:app-config
-q = --hpx:queuing
-r = --hpx:run-agas-server
-t = --hpx:threads
-v = --hpx:version
-w = --hpx:worker
-x = --hpx:hpx
-0 = --hpx:node=0
-1 = --hpx:node=1
-2 = --hpx:node=2
-3 = --hpx:node=3
-4 = --hpx:node=4
-5 = --hpx:node=5
-6 = --hpx:node=6
-7 = --hpx:node=7
-8 = --hpx:node=8
-9 = --hpx:node=9
Note
The short options listed above are disabled by default if the application
is built using #include <hpx/hpx_main.hpp>. See Re-use the main() function as the main HPX entry point for more
information.
The rationale behind this is that in this case the user’s application may
handle its own command line options, since HPX passes all unknown options
to main(). Short options like -t are prone to create ambiguities regarding
what the application will support.
Hence, the user should instead rely on the corresponding long options like
--hpx:threads in such a case.
Property |
Description |
|
Enable command line aliases as defined in the section
|
|
Allow for unknown command line options to be passed through to
|
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
|
On the commandline |
Loading INI files#
During startup and after the internal database has been initialized as described in the section Built-in default configuration settings, HPX will try to locate and load additional ini files to be used as a source for configuration properties. This allows for a wide spectrum of additional customization possibilities by the user and system administrators. The sequence of locations where HPX will try loading the ini files is well defined and documented in this section. All ini files found are merged into the internal configuration database. The merge operation itself conforms to the rules as described in the section The HPX ini file format.
Load all component shared libraries found in the directories specified by the property
hpx.component_pathand retrieve their default configuration information (see section Loading components for more details). This property can refer to a list of directories separated by':'(Linux, Android, and MacOS) or by';'(Windows).Load all files named
hpx.iniin the directories referenced by the propertyhpx.master_ini_pathThis property can refer to a list of directories separated by':'(Linux, Android, and MacOS) or by';'(Windows).Load a file named
.hpx.iniin the current working directory, e.g., the directory the application was invoked from.Load a file referenced by the environment variable
HPX_INI. This variable is expected to provide the full path name of the ini configuration file (if any).Load a file named
/etc/hpx.ini. This lookup is done on non-Windows systems only.Load a file named
.hpx.iniin the home directory of the current user, e.g., the directory referenced by the environment variableHOME.Load a file named
.hpx.iniin the directory referenced by the environment variablePWD.Load the file specified on the command line using the option
--hpx:config.Load all properties specified on the command line using the option
--hpx:ini. The properties will be added to the database in the same sequence as they are specified on the command line. The format for those options is, for instance,--hpx:ini=hpx.default_stack_size=0x4000. In addition to the explicit command line options, this will set the following properties as implied from other settings:hpx.parcel.addressandhpx.parcel.portas set by--hpx:hpxhpx.agas.address,hpx.agas.portandhpx.agas.service_modeas set by--hpx:agashpx.program_nameandhpx.cmd_linewill be derived from the actual command linehpx.os_threadsandhpx.localitiesas set by
hpx.runtime_modewill be derived from any explicit--hpx:console,--hpx:worker, or--hpx:connect, or it will be derived from other settings, such as--hpx:node=0, which implies--hpx:console.
Load files based on the pattern
*.iniin all directories listed by the propertyhpx.ini_path. All files found during this search will be merged. The propertyhpx.ini_pathcan hold a list of directories separated by':'(on Linux or Mac) or';'(on Windows).Load the file specified on the command line using the option
--hpx:app-config. Note that this file will be merged as the content for a top level section[application].
Note
Any changes made to the configuration database caused by one of the steps
will influence the loading process for all subsequent steps. For instance, if
one of the ini files loaded changes the property hpx.ini_path, this will
influence the directories searched in step 9 as described above.
Important
The HPX core library will verify that all configuration settings specified
on the command line (using the --hpx:ini option) will be checked
for validity. That means that the library will accept only known
configuration settings. This is to protect the user from unintentional typos
while specifying those settings. This behavior can be overwritten by
appending a '!' to the configuration key, thus forcing the setting to be
entered into the configuration database. For instance: --hpx:ini=hpx.foo! = 1
If any of the environment variables or files listed above are not found, the corresponding loading step will be silently skipped.
Loading components#
HPX relies on loading application specific components during the runtime of an application. Moreover, HPX comes with a set of preinstalled components supporting basic functionalities useful for almost every application. Any component in HPX is loaded from a shared library, where any of the shared libraries can contain more than one component type. During startup, HPX tries to locate all available components (e.g., their corresponding shared libraries) and creates an internal component registry for later use. This section describes the algorithm used by HPX to locate all relevant shared libraries on a system. As described, this algorithm is customizable by the configuration properties loaded from the ini files (see section Loading INI files).
Loading components is a two-stage process. First HPX tries to locate all component shared libraries, loads those, and generates a default configuration section in the internal configuration database for each component found. For each found component the following information is generated:
[hpx.components.<component_instance_name>]
name = <name_of_shared_library>
path = $[component_path]
enabled = $[hpx.components.load_external]
default = 1
The values in this section correspond to the expected configuration information for a component as described in the section Built-in default configuration settings.
In order to locate component shared libraries, HPX will try loading all
shared libraries (files with the platform specific extension of a shared
library, Linux: *.so, Windows: *.dll, MacOS: *.dylib found in the
directory referenced by the ini property hpx.component_path).
This first step corresponds to step 1) during the process of filling the internal configuration database with default information as described in section Loading INI files.
After all of the configuration information has been loaded, HPX performs the
second step in terms of loading components. During this step, HPX scans all
existing configuration sections
[hpx.component.<some_component_instance_name>] and instantiates a special
factory object for each of the successfully located and loaded components.
During the application’s life time, these factory objects are responsible for
creating new and discarding old instances of the component they are associated with.
This step is performed after step 11) of the process of filling the internal
configuration database with default information as described in section
Loading INI files.
Application specific component example#
This section assumes there is a simple application component that exposes
one member function as a component action. The header file app_server.hpp
declares the C++ type to be exposed as a component. This type has a member
function print_greeting(), which is exposed as an action
print_greeting_action. We assume the source files for this example are
located in a directory referenced by $APP_ROOT:
// file: $APP_ROOT/app_server.hpp
#include <hpx/hpx.hpp>
#include <hpx/include/iostreams.hpp>
namespace app
{
// Define a simple component exposing one action 'print_greeting'
class HPX_COMPONENT_EXPORT server
: public hpx::components::component_base<server>
{
void print_greeting ()
{
hpx::cout << "Hey, how are you?\n" << std::flush;
}
// Component actions need to be declared, this also defines the
// type 'print_greeting_action' representing the action.
HPX_DEFINE_COMPONENT_ACTION(server, print_greeting, print_greeting_action);
};
}
// Declare boilerplate code required for each of the component actions.
HPX_REGISTER_ACTION_DECLARATION(app::server::print_greeting_action);
The corresponding source file contains mainly macro invocations that define the boilerplate code needed for HPX to function properly:
// file: $APP_ROOT/app_server.cpp
#include "app_server.hpp"
// Define boilerplate required once per component module.
HPX_REGISTER_COMPONENT_MODULE();
// Define factory object associated with our component of type 'app::server'.
HPX_REGISTER_COMPONENT(app::server, app_server);
// Define boilerplate code required for each of the component actions. Use the
// same argument as used for HPX_REGISTER_ACTION_DECLARATION above.
HPX_REGISTER_ACTION(app::server::print_greeting_action);
The following gives an example of how the component can be used. Here, one
instance of the app::server component is created on the current locality and
the exposed action print_greeting_action is invoked using the global id of the
newly created instance. Note that no special code is required to delete the
component instance after it is not needed anymore. It will be deleted
automatically when its last reference goes out of scope (shown in the example below at
the closing brace of the block surrounding the code):
// file: $APP_ROOT/use_app_server_example.cpp
#include <hpx/hpx_init.hpp>
#include "app_server.hpp"
int hpx_main()
{
{
// Create an instance of the app_server component on the current locality.
hpx::naming:id_type app_server_instance =
hpx::create_component<app::server>(hpx::find_here());
// Create an instance of the action 'print_greeting_action'.
app::server::print_greeting_action print_greeting;
// Invoke the action 'print_greeting' on the newly created component.
print_greeting(app_server_instance);
}
return hpx::finalize();
}
int main(int argc, char* argv[])
{
return hpx::init(argc, argv);
}
In order to make sure that the application will be able to use the component
app::server, special configuration information must be passed to HPX. The
simplest way to allow HPX to ‘find’ the component is to provide special ini
configuration files that add the necessary information to the internal
configuration database. The component should have a special ini file containing
the information specific to the component app_server.
# file: $APP_ROOT/app_server.ini
[hpx.components.app_server]
name = app_server
path = $APP_LOCATION/
Here, $APP_LOCATION is the directory where the (binary) component shared
library is located. HPX will attempt to load the shared library from there.
The section name hpx.components.app_server reflects the instance name of the
component (app_server is an arbitrary, but unique name). The property value
for hpx.components.app_server.name should be the same as used for the second
argument to the macro HPX_REGISTER_COMPONENT above.
Additionally, a file .hpx.ini, which could be located in the current working
directory (see step 3 as described in the section Loading INI files), can
be used to add to the ini search path for components:
# file: $PWD/.hpx.ini
[hpx]
ini_path = $[hpx.ini_path]:$APP_ROOT/
This assumes that the above ini file specific to the component is located in
the directory $APP_ROOT.
Note
It is possible to reference the defined property from inside its value. HPX
will gracefully use the previous value of hpx.ini_path for the reference
on the right hand side and assign the overall (now expanded) value to the
property.
Logging#
HPX uses a sophisticated logging framework, allowing users to follow in detail what operations have been performed inside the HPX library in what sequence. This information proves to be very useful for diagnosing problems or just for improving the understanding of what is happening in HPX as a consequence of invoking HPX API functionality.
Default logging#
Enabling default logging is a simple process. The detailed description in the remainder of this section explains different ways to customize the defaults. Default logging can be enabled by using one of the following:
A command line switch
--hpx:debug-hpx-log, which will enable logging to the console terminal.The command line switch
--hpx:debug-hpx-log=<filename>, which enables logging to a given file<filename>.Setting an environment variable
HPX_LOGLEVEL=<loglevel>while running the HPX application. In this case<loglevel>should be a number between (or equal to)1and5where1means minimal logging and5causes all available messages to be logged. When setting the environment variable, the logs will be written to a file namedhpx.<PID>.loin the current working directory, where<PID>is the process id of the console instance of the application.
Customizing logging#
Generally, logging can be customized either using environment variable settings or using by an ini configuration file. Logging is generated in several categories, each of which can be customized independently. All customizable configuration parameters have reasonable defaults, allowing for the use of logging without any additional configuration effort. The following table lists the available categories.
Category |
Category shortcut |
Information to be generated |
Environment variable |
General |
None |
Logging information generated by different subsystems of HPX, such as thread-manager, parcel layer, LCOs, etc. |
|
|
Logging output generated by the AGAS subsystem |
|
|
Application |
|
Logging generated by applications. |
|
By default, all logging output is redirected to the console instance of an application, where it is collected and written to a file, one file for each logging category.
Each logging category can be customized at two levels. The parameters for each
are stored in the ini configuration sections hpx.logging.CATEGORY and
hpx.logging.console.CATEGORY (where CATEGORY is the category shortcut as
listed in the table above). The former influences logging at the source
locality and the latter modifies the logging behaviour for each of the
categories at the console instance of an application.
Levels#
All HPX logging output has seven different logging levels. These levels can be set explicitly or through environment variables in the main HPX ini file as shown below. The logging levels and their associated integral values are shown in the table below, ordered from most verbose to least verbose. By default, all HPX logs are set to 0, e.g., all logging output is disabled by default.
Logging level |
Integral value |
|---|---|
|
|
|
|
|
|
|
|
|
|
No logging |
|
Tip
The easiest way to enable logging output is to set the environment variable
corresponding to the logging category to an integral value as described in
the table above. For instance, setting HPX_LOGLEVEL=5 will enable full
logging output for the general category. Please note that the syntax and
means of setting environment variables varies between operating systems.
Configuration#
Logs will be saved to destinations as configured by the user. By default,
logging output is saved on the console instance of an application to
hpx.<CATEGORY>.<PID>.lo (where CATEGORY and PID> are placeholders
for the category shortcut and the OS process id). The output for the general
logging category is saved to hpx.<PID>.log. The default settings for the
general logging category are shown here (the syntax is described in the section
The HPX ini file format):
[hpx.logging]
level = ${HPX_LOGLEVEL:0}
destination = ${HPX_LOGDESTINATION:console}
format = ${HPX_LOGFORMAT:(T%locality%/%hpxthread%.%hpxphase%/%hpxcomponent%) P%parentloc%/%hpxparent%.%hpxparentphase% %time%($hh:$mm.$ss.$mili) [%idx%]|\\n}
The logging level is taken from the environment variable HPX_LOGLEVEL and
defaults to zero, e.g., no logging. The default logging destination is read from
the environment variable HPX_LOGDESTINATION On any of the localities it
defaults to console, which redirects all generated logging output to the
console instance of an application. The following table lists the possible
destinations for any logging output. It is possible to specify more than one
destination separated by whitespace.
Logging destination |
Description |
file( |
Directs all output to a file with the given <filename>. |
cout |
Directs all output to the local standard output of the application instance on this locality. |
cerr |
Directs all output to the local standard error output of the application instance on this locality. |
console |
Directs all output to the console instance of the application. The console instance has its logging destinations configured separately. |
android_log |
Directs all output to the (Android) system log (available on Android systems only). |
The logging format is read from the environment variable HPX_LOGFORMAT, and
it defaults to a complex format description. This format consists of several
placeholder fields (for instance %locality%), which will be replaced by
concrete values when the logging output is generated. All other information is
transferred verbatim to the output. The table below describes the available
field placeholders. The separator character | separates the logging message
prefix formatted as shown and the actual log message which will replace the
separator.
Name |
Description |
The id of the locality on which the logging message was generated. |
|
hpxthread |
The id of the HPX thread generating this logging output. |
hpxphase |
The phase 1 of the HPX thread generating this logging output. |
hpxcomponent |
The local virtual address of the component which the current HPX thread is accessing. |
parentloc |
The id of the locality where the HPX thread was running that initiated the current HPX thread. The current HPX thread is generating this logging output. |
hpxparent |
The id of the HPX thread that initiated the current HPX thread. The current HPX thread is generating this logging output. |
hpxparentphase |
The phase of the HPX thread when it initiated the current HPX thread. The current HPX thread is generating this logging output. |
time |
The time stamp for this logging outputline as generated by the source locality. |
idx |
The sequence number of the logging output line as generated on the source locality. |
osthread |
The sequence number of the OS thread that executes the current HPX thread. |