What’s the minimal HPX Program

Writing applications with HPX is not difficult. We tried to develop an API which conforms to the usual semantics of with the host language C++. This post is a first in a planned series of articles meant to introduce the concepts of writing HPX applications. As any introduction to a new programming language or programming paradigm, we will start with writing the smallest possible program (historically, this is a program which prints “Hello World!” only). Even if it’s very small it will give sufficient material to explain basic concepts.

The “Hello World!” of HPX looks like this (starting HPX V1.0):

#include <hpx/hpx_init.hpp>

int hpx_main()
{
    // Say Hello to the World!
    hpx::cout << "Hello World!\n";

    // Initiate shutdown of the runtime system.
    return hpx::finalize();
}

int main()
{
    // Initialize and run HPX, this executes hpx_main above.
    return hpx::init();
}

Please note, that before HPX V1.0 the minimal interface was looking slightly different as it still depended on the Boost.ProgramOptions library. However, this is still true as soon as you are interested in adding your own command line arguments, as shown below.

We have to include a single file #include <hpx/hpx_init.hpp> which imports all necessary declarations for our HPX program. The program itself defines two functions: main and hpx_main. As usual for any C++ program, the execution begins with the function main where all the action has to happen. In our case we use this function to initialize the HPX runtime system by calling hpx::init, which schedules and executes the function hpx_main as a HPX-thread. The function hpx::init returns only after hpx_main has returned and one of the HPX-threads has called hpx::finalize. It returns the value which has been returned by hpx_main (in our case it will return zero, as hpx::finalize() returns zero by default).

The function hpx_main is the first function in any HPX application to be scheduled and executed as a HPX-thread. It needs to be defined as it provides the main entry point for any HPX application. All further application logic is usually contained here. It is very similar to the the function main in any non-HPX program. The function hpx_main is invoked by the HPX runtime system and its only (optional) parameter is related to command line option processing as described below. We do not use that parameter in this minimal example as it does not implement its own command line handling.

If you need to add handling of your own command line arguments, the minimal program looks like this:

#include <hpx/hpx_init.hpp>

int hpx_main(boost::program_options::variables_map& vm)
{
    // was --value specified on the command line?
    bool has_value = vm.count("value");

    // Say Hello to the World!
    hpx::cout << "Hello World!\n";

    // Initiate shutdown of the runtime system.
    return hpx::finalize();
}

int main(int argc, char* argv[])
{
    using namespace boost::program_options;

    // Configure application-specific options
    options_description desc_commandline(
        "Usage: hello_world [options]");

    desc_commandline.add_options()
        ("value", "some command line flag")
        ;

    // Initialize and run HPX, this executes hpx_main above.
    return hpx::init(desc_commandline, argc, argv);
}

The code in main() is related to the processing of command line arguments. Essentially we define an object of the type options_description. This type is defined in the Boost.ProgramOptions library, one of the most excellent C++ command line processing libraries around. In addition to your command line option, HPX recognizes many command line options for various purposes, however those will be described in a later article. For now, please refer to the list of available HPX command line options in the documentation.

Generally, the released source archives (see here) contain quite a number of examples for HPX applications, where you can see different usage modes and command line handling strategies.

GD Star Rating
loading...
    This entry was posted in Applications, General by Hartmut Kaiser. Bookmark the permalink.

    About Hartmut Kaiser

    Hartmut is an Adjunct Professor of Computer Science at Louisiana State University. At the same time, he holds the position of a senior scientist at the Center for Computation and Technology (LSU). He received his doctorate from the Technical University of Chemnitz (Germany) in 1988. He is probably best known through his involvement in open source software projects, mainly as the author of several C++ libraries he has contributed to Boost, which are in use by thousands of developers worldwide. His current research is focused on leading the STE||AR group at CCT working on the practical design and implementation of the ParalleX execution model and related programming methods. In addition, he architected and developed the core library modules of SAGA for C++, a Simple API for Grid Applications.

    Leave a Reply

    Your email address will not be published. Required fields are marked *