HPX Source Code Structure and Coding Standards

General info

Coding standards used are: http://www.boost.org/development/requirements.html#Guidelines

The short version of the guidelines:

• 80-character lines.
• Absolutely no tabs (use spaces instead of tabs).
• Because we use git, UNIX line endings.
• Identifiers are C++ STL style: no CamelCase. E.g. my_class instead of MyClass.
• Use expressive identifiers.
• Exceptions for error handling instead of C-style error codes.

There is a .editorconfig file in the HPX root directory which can be used for almost any widely available editor. Please see http://editorconfig.org to download plugins for your favorite editor.

All of HPX (and we mean all of it) is released under the Boost Software License V1.0 (see: http://www.boost.org/LICENSE_1_0.txt). We insist in all contributions being released under the same license to simplify the life of our users. No sane lawyer will ever agree to use an external piece of software which does not follow a clear licensing policy. Since HPX relies on Boost we decided to keep HPX itself under the Boost license as well. Here you can find more information about the Boost Software License itself.

A few additional ones:

• Use doxygen style comments to document API functions.
• Before writing a piece of utility code, see if there is something in hpx::util, Boost or the C++ standard library that can be used to save time.

The directory structure follows the structure of the C++ namespaces, except for the runtime directory portion. Headers are in the hpx directory, and source files in the src directory (both relative to the top directory of the HPX source tree). E.g. hpx/lcos/mutex.hpp is hpx::lcos::mutex, and hpx/runtime/threads/threadmanager.hpp is hpx::threads::threadmanager.

Anything that ends in _impl is some technical details that are not part of the interface. In some places, things are called _impl_impl :p.

Likewise, anything in a namespace called detail is an implementation detail. Things in the very_detail namespace are really hacky details.

The hpx/util (hpx::util) code is utilities and implementation details.

Any directory called preprocessed contains automatically generated code. Do not touch those files. If you need to regenerate some of them, talk to us.

We tell users, whenever possible, to avoid looking at implementation details. These implementation details tend to be highly technical. This is why we try to abstract them away.

For those who are doing work on the HPX core, you may inevitably have to delve into these sections of the code, though.

General structure

HPX has a couple major subsystems. I have listed most of them, by header path (replace hpx/ with src/ to get the path to the .cpp files):

• hpx/lcos - LCOs
• hpx/lcos/local - LCOs optimized for shared memory usage
• hpx/runtime - The guts
• hpx/runtime/parcelset - The parcel transport layer. Consists of two elements: the parcel port (an object that receives parcels) and parcel handlers (objects that process parcels). There are currently two parcelhandlers in use: the early parcel handler, which handles bootstrap, and the primary parcel handler, which passes parcels on to the action manager, where they are decoded, and then scheduled with the thread manager.
• hpx/runtime/applier - The code which implements hpx::apply (its location is due to historical reasons). Previously, contained interfaces to the runtime. This directory is liable to get moved at some point.
• hpx/runtime/actions - The implementation of HPX actions (e.g. the active message; the contents of a parcel). Also contains the action_manager, which is invoked by the primary parcelhandler. Highly technical.
• hpx/runtime/components - Implementation of HPX components (e.g. globally named objects; anything that has a GID and can be acted upon remotely). Contains a good bit of allocation related code. Also contains implementations of special-case components: remote logging, remote error handling, the remotable interface to the runtime system and memory blocks. Highly technical.
• hpx/runtime/agas and hpx/runtime/naming - Implementation of AGAS, including the software cache and large chunks of the bootstrap code. Extraordinarily technical in some places. This subsystem is largely transparent to the end-user, aside from hpx::id_type.
• hpx/runtime/threads and hpx/util/coroutine - Contains the threadmanager, NUMA/CPU affinity code, scheduling code and related data structures and classes.
• hpx/config - Preprocessor configuration code (boring).
• hpx/components - Standard system components (PAPI, memory counters, factories, iostreams).
• hpx/traits - Metaprogramming code (run away).
• hpx/util - Implementation details and utilities. This contains a collection of code too diverse for me to enumerate here.
• hpx/include - Forwarding headers (boring).
• hpx/runtime.hpp, src/runtime.cpp, hpx/runtime_impl.hpp, hpx/runtime_impl.cpp - The runtime data structure. Contains a portion of startup and initialization related code. An instance of the hpx::runtime class represents an instance of the HPX runtime system.
• hpx/hpx_init.hpp, hpx_init_impl.hpp, hpx_start.hpp, hpx_start_impl.hpp, hpx/hpx_finalize.hpp - Command line handling and pre-runtime initialization code.
• src/pre_main.cpp - Post-bootstrap, pre-hpx-main initialization code.

Thread stuff

The thread schedulers are in (relative to the top directory of the tarball):

• hpx/runtime/threads/policies - location of the pluggable schedulers.

These are other places that may be of interest to you, listed from least scary to most scary.

• hpx/runtime/threads - all threadmanager related code.
• src/runtime/threads - all threadmanager related code.
• src/runtime/threads/threadmanager.cpp - main thread scheduling loop (calls into the schedulers), tfunc and tfunc_impl.
• hpx/runtime/threads/topology.hpp - NUMA/CPU affinity code.
• hpx/runtime/threads/topology.cpp - NUMA/CPU affinity code.
• hpx/hpx_fwd.hpp - new thread schedulers need to be forward declared in this file.
• src/runtime_impl.cpp - new thread schedulers currently need to be manually instantiated in this file (see the last few lines, it's self explanatory).
• src/hpx_init.cpp - new thread schedulers need to be added to the command line options here.
• CMakeLists.txt - new thread schedulers need to be added to the CMakeLists.txt file.
• hpx/util/coroutine - low-level threading implementation.
• src/util/coroutine - low-level threading implementation.

The thread scheduler subsystem isn't as pluggable as it could be - there are a few places where you will need to copy/paste boilerplate code.