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.
If you can’t find what you’re looking for in the documentation, please:
open an issue on GitHub;
contact us on IRC, the HPX channel on the C++ Slack, or on our mailing list; or
read or ask questions tagged with HPX on StackOverflow.
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.
Why HPX?¶
Current advances in high performance computing (HPC) continue to suffer from the issues plaguing parallel computation. These issues include, but are not limited to, ease of programming, inability to handle dynamically changing workloads, scalability, and efficient utilization of system resources. Emerging technological trends such as multi-core processors further highlight limitations of existing parallel computation models. To mitigate the aforementioned problems, it is necessary to rethink the approach to parallelization models. ParalleX contains mechanisms such as multi-threading, parcels, global name space support, percolation and local control objects (LCO). By design, ParalleX overcomes limitations of current models of parallelism by alleviating contention, latency, overhead and starvation. With ParalleX, it is further possible to increase performance by at least an order of magnitude on challenging parallel algorithms, e.g., dynamic directed graph algorithms and adaptive mesh refinement methods for astrophysics. An additional benefit of ParalleX is fine-grained control of power usage, enabling reductions in power consumption.
ParalleX—a new execution model for future architectures¶
ParalleX is a new parallel execution model that offers an alternative to the conventional computation models, such as message passing. ParalleX distinguishes itself by:
Split-phase transaction model
Message-driven
Distributed shared memory (not cache coherent)
Multi-threaded
Futures synchronization
Synchronization for anonymous producer-consumer scenarios
Percolation (pre-staging of task data)
The ParalleX model is intrinsically latency hiding, delivering an abundance of variable-grained parallelism within a hierarchical namespace environment. The goal of this innovative strategy is to enable future systems delivering very high efficiency, increased scalability and ease of programming. ParalleX can contribute to significant improvements in the design of all levels of computing systems and their usage from application algorithms and their programming languages to system architecture and hardware design together with their supporting compilers and operating system software.
What is HPX?¶
High Performance ParalleX (HPX) is the first runtime system implementation of the ParalleX execution model. The HPX runtime software package is a modular, feature-complete, and performance-oriented representation of the ParalleX execution model targeted at conventional parallel computing architectures, such as SMP nodes and commodity clusters. It is academically developed and freely available under an open source license. We provide HPX to the community for experimentation and application to achieve high efficiency and scalability for dynamic adaptive and irregular computational problems. HPX is a C++ library that supports a set of critical mechanisms for dynamic adaptive resource management and lightweight task scheduling within the context of a global address space. It is solidly based on many years of experience in writing highly parallel applications for HPC systems.
The two-decade success of the communicating sequential processes (CSP) execution model and its message passing interface (MPI) programming model have been seriously eroded by challenges of power, processor core complexity, multi-core sockets, and heterogeneous structures of GPUs. Both efficiency and scalability for some current (strong scaled) applications and future Exascale applications demand new techniques to expose new sources of algorithm parallelism and exploit unused resources through adaptive use of runtime information.
The ParalleX execution model replaces CSP to provide a new computing paradigm embodying the governing principles for organizing and conducting highly efficient scalable computations greatly exceeding the capabilities of today’s problems. HPX is the first practical, reliable, and performance-oriented runtime system incorporating the principal concepts of the ParalleX model publicly provided in open source release form.
HPX is designed by the STE||AR Group (Systems Technology, Emergent Parallelism, and Algorithm Research) at Louisiana State University (LSU)’s Center for Computation and Technology (CCT) to enable developers to exploit the full processing power of many-core systems with an unprecedented degree of parallelism. STE||AR is a research group focusing on system software solutions and scientific application development for hybrid and many-core hardware architectures.
What makes our systems slow?¶
Estimates say that we currently run our computers at well below 100% efficiency. The theoretical peak performance (usually measured in FLOPS—floating point operations per second) is much higher than any practical peak performance reached by any application. This is particularly true for highly parallel hardware. The more hardware parallelism we provide to an application, the better the application must scale in order to efficiently use all the resources of the machine. Roughly speaking, we distinguish two forms of scalability: strong scaling (see Amdahl’s Law) and weak scaling (see Gustafson’s Law). Strong scaling is defined as how the solution time varies with the number of processors for a fixed total problem size. It gives an estimate of how much faster we can solve a particular problem by throwing more resources at it. Weak scaling is defined as how the solution time varies with the number of processors for a fixed problem size per processor. In other words, it defines how much more data can we process by using more hardware resources.
In order to utilize as much hardware parallelism as possible an application must exhibit excellent strong and weak scaling characteristics, which requires a high percentage of work executed in parallel, i.e., using multiple threads of execution. Optimally, if you execute an application on a hardware resource with N processors it either runs N times faster or it can handle N times more data. Both cases imply 100% of the work is executed on all available processors in parallel. However, this is just a theoretical limit. Unfortunately, there are more things that limit scalability, mostly inherent to the hardware architectures and the programming models we use. We break these limitations into four fundamental factors that make our systems SLOW:
Starvation occurs when there is insufficient concurrent work available to maintain high utilization of all resources.
Latencies are imposed by the time-distance delay intrinsic to accessing remote resources and services.
Overhead is work required for the management of parallel actions and resources on the critical execution path, which is not necessary in a sequential variant.
Waiting for contention resolution is the delay due to the lack of availability of oversubscribed shared resources.
Each of those four factors manifests itself in multiple and different ways; each of the hardware architectures and programming models expose specific forms. However, the interesting part is that all of them are limiting the scalability of applications no matter what part of the hardware jungle we look at. Hand-helds, PCs, supercomputers, or the cloud, all suffer from the reign of the 4 horsemen: Starvation, Latency, Overhead, and Contention. This realization is very important as it allows us to derive the criteria for solutions to the scalability problem from first principles, and it allows us to focus our analysis on very concrete patterns and measurable metrics. Moreover, any derived results will be applicable to a wide variety of targets.
Technology demands new response¶
Today’s computer systems are designed based on the initial ideas of John von Neumann, as published back in 1945, and later extended by the Harvard architecture. These ideas form the foundation, the execution model, of computer systems we use currently. However, a new response is required in the light of the demands created by today’s technology.
So, what are the overarching objectives for designing systems allowing for applications to scale as they should? In our opinion, the main objectives are:
Performance: as previously mentioned, scalability and efficiency are the main criteria people are interested in.
Fault tolerance: the low expected mean time between failures (MTBF) of future systems requires embracing faults, not trying to avoid them.
Power: minimizing energy consumption is a must as it is one of the major cost factors today, and will continue to rise in the future.
Generality: any system should be usable for a broad set of use cases.
Programmability: for programmer this is a very important objective, ensuring long term platform stability and portability.
What needs to be done to meet those objectives, to make applications scale better on tomorrow’s architectures? Well, the answer is almost obvious: we need to devise a new execution model—a set of governing principles for the holistic design of future systems—targeted at minimizing the effect of the outlined SLOW factors. Everything we create for future systems, every design decision we make, every criteria we apply, have to be validated against this single, uniform metric. This includes changes in the hardware architecture we prevalently use today, and it certainly involves new ways of writing software, starting from the operating system, runtime system, compilers, and at the application level. However, the key point is that all those layers have to be co-designed; they are interdependent and cannot be seen as separate facets. The systems we have today have been evolving for over 50 years now. All layers function in a certain way, relying on the other layers to do so. But we do not have the time to wait another 50 years for a new coherent system to evolve. The new paradigms are needed now—therefore, co-design is the key.
Governing principles applied while developing HPX¶
As it turn out, we do not have to start from scratch. Not everything has to be invented and designed anew. Many of the ideas needed to combat the 4 horsemen already exist, many for more than 30 years. All it takes is to gather them into a coherent approach. We’ll highlight some of the derived principles we think to be crucial for defeating SLOW. Some of those are focused on high-performance computing, others are more general.
Focus on latency hiding instead of latency avoidance¶
It is impossible to design a system exposing zero latencies. In an effort to come as close as possible to this goal many optimizations are mainly targeted towards minimizing latencies. Examples for this can be seen everywhere, such as low latency network technologies like InfiniBand, caching memory hierarchies in all modern processors, the constant optimization of existing MPI implementations to reduce related latencies, or the data transfer latencies intrinsic to the way we use GPGPUs today. It is important to note that existing latencies are often tightly related to some resource having to wait for the operation to be completed. At the same time it would be perfectly fine to do some other, unrelated work in the meantime, allowing the system to hide the latencies by filling the idle-time with useful work. Modern systems already employ similar techniques (pipelined instruction execution in the processor cores, asynchronous input/output operations, and many more). What we propose is to go beyond anything we know today and to make latency hiding an intrinsic concept of the operation of the whole system stack.
Embrace fine-grained parallelism instead of heavyweight threads¶
If we plan to hide latencies even for very short operations, such as fetching the contents of a memory cell from main memory (if it is not already cached), we need to have very lightweight threads with extremely short context switching times, optimally executable within one cycle. Granted, for mainstream architectures, this is not possible today (even if we already have special machines supporting this mode of operation, such as the Cray XMT). For conventional systems, however, the smaller the overhead of a context switch and the finer the granularity of the threading system, the better will be the overall system utilization and its efficiency. For today’s architectures we already see a flurry of libraries providing exactly this type of functionality: non-pre-emptive, task-queue based parallelization solutions, such as Intel Threading Building Blocks (TBB), Microsoft Parallel Patterns Library (PPL), Cilk++, and many others. The possibility to suspend a current task if some preconditions for its execution are not met (such as waiting for I/O or the result of a different task), seamlessly switching to any other task which can continue, and to reschedule the initial task after the required result has been calculated, which makes the implementation of latency hiding almost trivial.
Rediscover constraint-based synchronization to replace global barriers¶
The code we write today is riddled with implicit (and explicit) global barriers. By “global barriers,” we mean the synchronization of the control flow between several (very often all) threads (when using OpenMP) or processes (MPI). For instance, an implicit global barrier is inserted after each loop parallelized using OpenMP as the system synchronizes the threads used to execute the different iterations in parallel. In MPI each of the communication steps imposes an explicit barrier onto the execution flow as (often all) nodes have to be synchronized. Each of those barriers is like the eye of a needle the overall execution is forced to be squeezed through. Even minimal fluctuations in the execution times of the parallel threads (jobs) causes them to wait. Additionally, it is often only one of the executing threads that performs the actual reduce operation, which further impedes parallelism. A closer analysis of a couple of key algorithms used in science applications reveals that these global barriers are not always necessary. In many cases it is sufficient to synchronize a small subset of the threads. Any operation should proceed whenever the preconditions for its execution are met, and only those. Usually there is no need to wait for iterations of a loop to finish before you can continue calculating other things; all you need is to complete the iterations that produce the required results for the next operation. Good bye global barriers, hello constraint based synchronization! People have been trying to build this type of computing (and even computers) since the 1970s. The theory behind what they did is based on ideas around static and dynamic dataflow. There are certain attempts today to get back to those ideas and to incorporate them with modern architectures. For instance, a lot of work is being done in the area of constructing dataflow-oriented execution trees. Our results show that employing dataflow techniques in combination with the other ideas, as outlined herein, considerably improves scalability for many problems.
Adaptive locality control instead of static data distribution¶
While this principle seems to be a given for single desktop or laptop computers (the operating system is your friend), it is everything but ubiquitous on modern supercomputers, which are usually built from a large number of separate nodes (i.e., Beowulf clusters), tightly interconnected by a high-bandwidth, low-latency network. Today’s prevalent programming model for those is MPI, which does not directly help with proper data distribution, leaving it to the programmer to decompose the data to all of the nodes the application is running on. There are a couple of specialized languages and programming environments based on PGAS (Partitioned Global Address Space) designed to overcome this limitation, such as Chapel, X10, UPC, or Fortress. However, all systems based on PGAS rely on static data distribution. This works fine as long as this static data distribution does not result in heterogeneous workload distributions or other resource utilization imbalances. In a distributed system these imbalances can be mitigated by migrating part of the application data to different localities (nodes). The only framework supporting (limited) migration today is Charm++. The first attempts towards solving related problem go back decades as well, a good example is the Linda coordination language. Nevertheless, none of the other mentioned systems support data migration today, which forces the users to either rely on static data distribution and live with the related performance hits or to implement everything themselves, which is very tedious and difficult. We believe that the only viable way to flexibly support dynamic and adaptive locality control is to provide a global, uniform address space to the applications, even on distributed systems.
Prefer moving work to the data over moving data to the work¶
For the best performance it seems obvious to minimize the amount of bytes transferred from one part of the system to another. This is true on all levels. At the lowest level we try to take advantage of processor memory caches, thus, minimizing memory latencies. Similarly, we try to amortize the data transfer time to and from GPGPUs as much as possible. At high levels we try to minimize data transfer between different nodes of a cluster or between different virtual machines on the cloud. Our experience (well, it’s almost common wisdom) shows that the amount of bytes necessary to encode a certain operation is very often much smaller than the amount of bytes encoding the data the operation is performed upon. Nevertheless, we still often transfer the data to a particular place where we execute the operation just to bring the data back to where it came from afterwards. As an example let’s look at the way we usually write our applications for clusters using MPI. This programming model is all about data transfer between nodes. MPI is the prevalent programming model for clusters, and it is fairly straightforward to understand and to use. Therefore, we often write applications in a way that accommodates this model, centered around data transfer. These applications usually work well for smaller problem sizes and for regular data structures. The larger the amount of data we have to churn and the more irregular the problem domain becomes, the worse the overall machine utilization and the (strong) scaling characteristics become. While it is not impossible to implement more dynamic, data driven, and asynchronous applications using MPI, it is somewhat difficult to do so. At the same time, if we look at applications that prefer to execute the code close to the locality where the data was placed, i.e., utilizing active messages (for instance based on Charm++), we see better asynchrony, simpler application codes, and improved scaling.
Favor message driven computation over message passing¶
Today’s prevalently used programming model on parallel (multi-node) systems is MPI. It is based on message passing, as the name implies, which means that the receiver has to be aware of a message about to come in. Both codes, the sender and the receiver, have to synchronize in order to perform the communication step. Even the newer, asynchronous interfaces require explicitly coding the algorithms around the required communication scheme. As a result, everything but the most trivial MPI applications spends a considerable amount of time waiting for incoming messages, thus, causing starvation and latencies to impede full resource utilization. The more complex and more dynamic the data structures and algorithms become, the larger the adverse effects. The community discovered message-driven and data-driven methods of implementing algorithms a long time ago, and systems such as Charm++ have already integrated active messages demonstrating the validity of the concept. Message-driven computation allows for sending messages without requiring the receiver to actively wait for them. Any incoming message is handled asynchronously and triggers the encoded action by passing along arguments and—possibly—continuations. HPX combines this scheme with work-queue based scheduling as described above, which allows the system to almost completely overlap any communication with useful work, thereby minimizing latencies.
Quick start¶
This section is intended to get you to the point of running a basic HPX program as quickly as possible. To that end we skip many details but instead give you hints and links to more details along the way.
We assume that you are on a Unix system with access to reasonably recent
packages. You should have cmake and make available for the build system
(pkg-config is also supported, see Using HPX with pkg-config).
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:
git checkout 1.5.0
HPX dependencies¶
The minimum dependencies needed to use HPX are Boost and Portable Hardware Locality (HWLOC). If these
are not available through your system package manager, see
Installing Boost and Installing Hwloc for instructions on how
to build them yourself. In addition to Boost and Portable Hardware Locality (HWLOC), it is recommended
that you don’t use the system allocator, but instead use either tcmalloc
from google-perftools (default) or jemalloc for better performance. If you
would like to try HPX without a custom allocator at this point, you can
configure HPX to use the system allocator in the next step.
A full list of required and optional dependencies, including recommended versions, is available at Prerequisites.
Building HPX¶
Once you have the source code and the dependencies, set up a separate build directory and configure the project. Assuming all your dependencies are in paths known to CMake, the following gets you started:
# In the HPX source directory
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/install/path ..
make install
This will build the core HPX libraries and examples, and install them to your
chosen location. If you want to install HPX to system folders, simply leave out
the CMAKE_INSTALL_PREFIX option. This may take a while. To speed up the
process, launch more jobs by passing the -jN option to make.
Tip
Do not set only -j (i.e. -j without an explicit number of jobs)
unless you have a lot of memory available on your machine.
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 Release and Debug modes.
If your dependencies are in custom locations, you may need to tell CMake where to find them by passing one or more of the following options to CMake:
-DBOOST_ROOT=/path/to/boost
-DHWLOC_ROOT=/path/to/hwloc
-DTCMALLOC_ROOT=/path/to/tcmalloc
-DJEMALLOC_ROOT=/path/to/jemalloc
If you want to try HPX without using a custom allocator pass
-DHPX_WITH_MALLOC=system to CMake.
Important
If you are building HPX for a system with more than 64 processing units,
you must change the CMake variables HPX_WITH_MORE_THAN_64_THREADS (to
On) and HPX_WITH_MAX_CPU_COUNT (to a value at least as big as the
number of (virtual) cores on your system).
To build the tests, run make tests. To run the tests, run either make test
or use ctest for more control over which tests to run. You can run single
tests for example with ctest --output-on-failure -R
tests.unit.parallel.algorithms.for_loop or a whole group of tests with ctest
--output-on-failure -R tests.unit.
If you did not run make install earlier, do so now or build the
hello_world_1 example by running:
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: Hello world. 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.
Installing and building HPX via vcpkg¶
You can download and install HPX using the vcpkg <https://github.com/Microsoft/vcpkg> dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
vcpkg install hpx
The HPX port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request <https://github.com/Microsoft/vcpkg> on the vcpkg repository.
Hello, World!¶
The following CMakeLists.txt is a minimal example of what you need in order to
build an executable using CMake and HPX:
cmake_minimum_required(VERSION 3.13)
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)
Note
You will most likely have more than one main.cpp file in your project.
See the section on Using HPX with CMake-based projects for more details on how to use
add_hpx_executable.
Note
HPX::wrap_main is required if you are implicitly using main() as the
runtime entry point. See Re-use the main() function as the main HPX entry point for more information.
Note
HPX::iostreams_component is optional for a minimal project but lets us
use the HPX equivalent of std::cout, i.e., the HPX The HPX I/O-streams component
functionality in our application.
Create a new project directory and a CMakeLists.txt with the contents above.
Also 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" << hpx::flush;
return 0;
}
Then, in your project directory run the following:
mkdir build && cd build
cmake -DCMAKE_PREFIX_PATH=/path/to/hpx/installation ..
make all
./my_hpx_program
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.hpp some
things will be done behind the scenes to make sure that main actually 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::cout is a replacement for
std::cout to make sure printing never blocks a lightweight thread. You can
read more about hpx::cout in The HPX I/O-streams component. If you rebuild and run your
program now, you should see the familiar Hello World!:
./my_hpx_program
Hello World!
Note
You do not have to let HPX take over your main function like in the
example. You can instead keep your normal main function, and define a
separate hpx_main function which acts as the entry point to the HPX
runtime. In that case you start the HPX runtime explicitly by calling
hpx::init:
// Copyright (c) 2007-2012 Hartmut Kaiser
//
// SPDX-License-Identifier: BSL-1.0
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
///////////////////////////////////////////////////////////////////////////////
// The purpose of this example is to initialize the HPX runtime explicitly and
// execute a HPX-thread printing "Hello World!" once. That's all.
//[hello_world_2_getting_started
#include <hpx/hpx_init.hpp>
#include <hpx/iostream.hpp>
int hpx_main(int, char**)
{
// Say hello to the world!
hpx::cout << "Hello World!\n" << hpx::flush;
return hpx::finalize();
}
int main(int argc, char* argv[])
{
return hpx::init(argc, argv);
}
//]
You can also use hpx::start and hpx::stop for a
non-blocking alternative, or use hpx::resume and
hpx::suspend if you need to combine HPX with other runtimes.
See Starting the HPX runtime for more details on how to initialize and run the HPX runtime.
Caution
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 HPX applications).
If you are already familiar with async and futures 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/hpx_main.hpp>
#include <hpx/include/lcos.hpp>
#include <hpx/include/parallel_generate.hpp>
#include <hpx/include/parallel_sort.hpp>
#include <hpx/iostream.hpp>
#include <random>
#include <vector>
void final_task(
hpx::future<hpx::util::tuple<hpx::future<double>, hpx::future<void>>>)
{
hpx::cout << "in final_task" << hpx::endl;
}
// Avoid ABI incompatibilities between C++11/C++17 as std::rand has exception
// specification in libstdc++.
int rand_wrapper()
{
return std::rand();
}
int main(int, char**)
{
// 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; });
hpx::cout << "Just launched a task!" << hpx::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.
hpx::cout << "f contains " << f.get() << hpx::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.
hpx::cout << "Result is ready? " << result.is_ready() << hpx::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::parallel::execution::seq, std::begin(v), std::end(v),
&rand_wrapper);
// We can launch the sort in parallel and asynchronously.
hpx::future<void> done_sorting = hpx::parallel::sort(
hpx::parallel::execution::par( // In parallel.
hpx::parallel::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.
hpx::cout << (all.is_ready() ? "all is ready!" : "all is not ready...")
<< hpx::endl;
return hpx::finalize();
}
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: Interest calculator 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: 1D stencil 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.
Terminology¶
This section gives definitions for some of the terms used throughout the HPX documentation and source code.
- Locality
A locality in HPX describes a synchronous domain of execution, or the domain of bounded upper response time. This normally is just a single node in a cluster or a NUMA domain in a SMP machine.
- Active Global Address Space
- AGAS
HPX incorporates a global address space. Any executing thread can access any object within the domain of the parallel application with the caveat that it must have appropriate access privileges. The model does not assume that global addresses are cache coherent; all loads and stores will deal directly with the site of the target object. All global addresses within a Synchronous Domain are assumed to be cache coherent for those processor cores that incorporate transparent caches. The Active Global Address Space used by HPX differs from research PGAS models. Partitioned Global Address Space is passive in their means of address translation. Copy semantics, distributed compound operations, and affinity relationships are some of the global functionality supported by AGAS.
- Process
The concept of the “process” in HPX is extended beyond that of either sequential execution or communicating sequential processes. While the notion of process suggests action (as do “function” or “subroutine”) it has a further responsibility of context, that is, the logical container of program state. It is this aspect of operation that process is employed in HPX. Furthermore, referring to “parallel processes” in HPX designates the presence of parallelism within the context of a given process, as well as the coarse grained parallelism achieved through concurrency of multiple processes of an executing user job. HPX processes provide a hierarchical name space within the framework of the active global address space and support multiple means of internal state access from external sources.
- Parcel
The Parcel is a component in HPX that communicates data, invokes an action at a distance, and distributes flow-control through the migration of continuations. Parcels bridge the gap of asynchrony between synchronous domains while maintaining symmetry of semantics between local and global execution. Parcels enable message-driven computation and may be seen as a form of “active messages”. Other important forms of message-driven computation predating active messages include dataflow tokens, the J-machine’s support for remote method instantiation, and at the coarse grained variations of Unix remote procedure calls, among others. This enables work to be moved to the data as well as performing the more common action of bringing data to the work. A parcel can cause actions to occur remotely and asynchronously, among which are the creation of threads at different system nodes or synchronous domains.
- Local Control Object
- Lightweight Control Object
- LCO
A local control object (sometimes called a lightweight control object) is a general term for the synchronization mechanisms used in HPX. Any object implementing a certain concept can be seen as an LCO. This concepts encapsulates the ability to be triggered by one or more events which when taking the object into a predefined state will cause a thread to be executed. This could either create a new thread or resume an existing thread.
The LCO is a family of synchronization functions potentially representing many classes of synchronization constructs, each with many possible variations and multiple instances. The LCO is sufficiently general that it can subsume the functionality of conventional synchronization primitives such as spinlocks, mutexes, semaphores, and global barriers. However due to the rich concept an LCO can represent powerful synchronization and control functionality not widely employed, such as dataflow and futures (among others), which open up enormous opportunities for rich diversity of distributed control and operation.
See Using LCOs for more details on how to use LCOs in HPX.
- Action
An action is a function that can be invoked remotely. In HPX a plain function can be made into an action using a macro. See Applying actions for details on how to use actions in HPX.
- Component
A component is a C++ object which can be accessed remotely. A component can also contain member functions which can be invoked remotely. These are referred to as component actions. See Writing components for details on how to use components in HPX.
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.
Asynchronous execution with hpx::async: Fibonacci¶
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 HPX build system 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]");
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
return hpx::init(desc_commandline, argc, argv);
}
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::util::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)
{
// 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::util::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::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;
// Invoking the Fibonacci algorithm twice is inefficient.
// However, we intentionally demonstrate it this way to create some
// heavy workload.
hpx::future<std::uint64_t> n1 = hpx::async(fibonacci, n - 1);
hpx::future<std::uint64_t> n2 = hpx::async(fibonacci, n - 2);
return n1.get() + n2.get(); // wait for the Futures to return their values
}
This block of code is 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: Interest calculator presents dataflow, which is a way to more
efficiently chain together multiple tasks.
Asynchronous execution with hpx::async and actions: Fibonacci¶
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: Hello world).
Setup¶
The source code for this example can be found here:
fibonacci.cpp.
To compile this program, go to your HPX build directory (see HPX build system 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:
//[fib_main
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
return hpx::init(desc_commandline, argc, argv);
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::util::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.
//[fib_hpx_main
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::util::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:
//[fib_action
// 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.
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: Accumulator). 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():
//[fib_func
std::uint64_t fibonacci(std::uint64_t n)
{
if (n < 2)
return n;
// We restrict ourselves to execute the Fibonacci function locally.
hpx::naming::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: Hello world¶
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 HPX build system 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::naming::id_type> localities =
hpx::find_all_localities();
// Reserve storage space for futures, one for each locality.
std::vector<hpx::lcos::future<void> > futures;
futures.reserve(localities.size());
for (hpx::naming::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::lcos::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 hpx::async and actions: Fibonacci 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 hpx::async and actions: Fibonacci 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::lcos::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, which we can query to determine if the task has
// completed. We give the task a hint to run on a particular worker
// thread, but no guarantees are given by the scheduler that the
// task will actually run on that worker thread.
hpx::parallel::execution::default_executor exec(
hpx::threads::thread_schedule_hint(
hpx::threads::thread_schedule_hint_mode_thread, worker));
futures.push_back(hpx::async(exec, hello_world_worker, worker));
}
// Wait for all of the futures to finish. The callback version of the
// hpx::lcos::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::lcos::wait_each doesn't return until
// all the futures in the vector have returned.
hpx::lcos::local::spinlock mtx;
hpx::lcos::wait_each(
hpx::util::unwrapping([&](std::size_t t) {
if (std::size_t(-1) != t)
{
std::lock_guard<hpx::lcos::local::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::lcos::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::lcos::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: Accumulator¶
The accumulator example demonstrates the use of components. Components are C++ classes that expose methods as a type of HPX action. These actions are called component actions.
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 hpx::async and actions: Fibonacci and the Remote execution with actions: Hello world, 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 component in this example exposes three different functions:
reset()- Resets the accumulator value to 0.add(arg)- Addsargto the accumulators value.query()- Queries the value of the accumulator.
This example creates an instance of the accumulator, and then allows the user to enter commands at a prompt, which subsequently invoke actions on the accumulator instance.
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 HPX build system 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 server class¶
The following code is from: 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:
/// 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_;
}
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 hpx::async and actions: Fibonacci and the Remote execution with actions: Hello world:
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
//[accumulator_registration_definitions
///////////////////////////////////////////////////////////////////////////////
// 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,
Note
The code above must be placed in the global namespace.
The client class¶
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::applyto 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::apply<action_type>(this->get_id());
}
Asynchronous: Futures, as demonstrated in Asynchronous execution with hpx::async: Fibonacci, Asynchronous execution with hpx::async and actions: Fibonacci, and the Remote execution with actions: Hello world, 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>(hpx::launch::async, this->get_id());
}
Synchronous: To invoke an action in a fully synchronous manner, we can simply call
hpx::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.
Dataflow: Interest calculator¶
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 HPX build system 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
This should print:
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 hpx::async and actions: Fibonacci 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.
///////////////////////////////////////////////////////////////////////////////
//[interest_main
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]")
;
Next we look at hpx_main.
///////////////////////////////////////////////////////////////////////////////
//[interest_hpx_main
int hpx_main(variables_map & vm)
{
{
using hpx::shared_future;
using hpx::make_ready_future;
using hpx::dataflow;
using hpx::util::unwrapping;
hpx::naming::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;
}
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:
///////////////////////////////////////////////////////////////////////////////
//[interest_calc_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)
{
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: 1D stencil¶
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.
//[stepper_1
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.
//[stepper_2
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::util::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.
// Initial conditions: f(0, i) = i
//[do_work_6
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:
//[stepper_7
// 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::util::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.
Manual¶
The manual is your comprehensive guide to HPX. It contains detailed information on how to build and use HPX in different scenarios.
Getting HPX¶
There are HPX packages available for a few Linux distributions. The easiest way to get started with HPX is to use those packages. We keep an up-to-date list with instructions on the HPX Downloads page. If you use one of the available packages you can skip the next section, HPX build system, but we still recommend that you look through it as it contains useful information on how you can customize HPX at compile-time.
If there isn’t a package available for your platform you should either clone our repository:
or download a package with the source files from HPX Downloads.
HPX build system¶
The build system for HPX is based on CMake. CMake is a cross-platform build-generator tool. CMake does not build the project, it generates the files needed by your build tool (GNU make, Visual Studio, etc.) for building HPX.
This section gives an introduction on how to use our build system to build HPX and how to use HPX in your own projects.
CMake basics¶
CMake is a cross-platform build-generator tool. CMake does not build the project, it generates the files needed by your build tool (gnu make, visual studio, etc.) for building HPX.
In general, the HPX CMake scripts try to adhere to the general CMake policies on how to write CMake-based projects.
Basic CMake usage¶
This section explains basic aspects of CMake, specifically options needed for day-to-day usage.
CMake comes with extensive documentation in the form of html files and on the
CMake executable itself. Execute cmake --help for further help options.
CMake needs to know which build tool it will generate files for (GNU make,
Visual Studio, Xcode, etc.). If not specified on the command line, it will try to
guess the build tool based on you environment. Once it has identified the build tool,
CMake uses the corresponding generator to create files for your build tool. You can
explicitly specify the generator with the command line option -G "Name of the
generator". To see the available generators on your platform, execute:
cmake --help
This will list the generator names at the end of the help text. Generator names are case-sensitive. Example:
cmake -G "Visual Studio 16 2019" path/to/hpx
For a given development platform there can be more than one adequate generator.
If you use Visual Studio "NMake Makefiles" is a generator you can use for
building with NMake. By default, CMake chooses the more specific generator
supported by your development environment. If you want an alternative generator,
you must tell this to CMake with the -G option.
Quick start¶
Here, you will use the command-line, non-interactive CMake interface.
Download and install CMake here: CMake Downloads. Version 3.13 is the minimum required version for HPX.
Open a shell. Your development tools must be reachable from this shell through the
PATHenvironment variable.Create a directory for containing the build. Building HPX on the source directory is not supported. cd to this directory:
mkdir mybuilddir cd mybuilddirExecute this command on the shell replacing
path/to/hpxwith the path to the root of your HPX source tree:cmake path/to/hpx
CMake will detect your development environment, perform a series of tests and will generate the files required for building HPX. CMake will use default values for all build parameters. See the CMake variables used to configure HPX section for fine-tuning your build.
This can fail if CMake can’t detect your toolset, or if it thinks that the
environment is not sane enough. In this case make sure that the toolset that you
intend to use is the only one reachable from the shell and that the shell itself
is the correct one for you development environment. CMake will refuse to build
MinGW makefiles if you have a POSIX shell reachable through the PATH
environment variable, for instance. You can force CMake to use various compilers
and tools. Please visit CMake Useful Variables
for a detailed overview of specific CMake variables.
Options and variables¶
Variables customize how the build will be generated. Options are boolean
variables, with possible values ON/OFF. Options and variables are
defined on the CMake command line like this:
cmake -DVARIABLE=value path/to/hpx
You can set a variable after the initial CMake invocation for changing its value. You can also undefine a variable:
cmake -UVARIABLE path/to/hpx
Variables are stored on the CMake cache. This is a file named CMakeCache.txt
on the root of the build directory. Do not hand-edit it.
Variables are listed here appending its type after a colon. You should write the variable and the type on the CMake command line:
cmake -DVARIABLE:TYPE=value path/to/llvm/source
CMake supports the following variable types: BOOL (options), STRING
(arbitrary string), PATH (directory name), FILEPATH (file name).
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 |
Software and libraries¶
In the simplest case, HPX depends on Boost and Portable Hardware Locality (HWLOC). So, before you read further, please make sure you have a recent version of Boost installed on your target machine. HPX currently requires at least Boost V1.61.0 to work properly. It may build and run with older versions, but we do not test HPX with those versions, so please be warned.
The installation of Boost is described in detail in Boost’s Getting Started document. However, if you’ve never used the Boost libraries (or even if you have), here’s a quick primer: Installing Boost.
It is often possible to download the Boost libraries using the package manager of your distribution. Please refer to the corresponding documentation for your system for more information.
In addition, we require a recent version of hwloc in order to support thread pinning and NUMA awareness. See Installing Hwloc for instructions on building Portable Hardware Locality (HWLOC).
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. A compiler supporting the C++11 Standard is highly recommended. The code base takes advantage of C++11 language features when available (move semantics, rvalue references, magic statics, etc.). This may speed up the execution of your code significantly. We currently support the following C++ compilers: GCC, MSVC, ICPC and clang. For the status of your favorite compiler with HPX visit HPX Buildbot Website.
Name |
Minimum version |
Notes |
Compilers |
||
7.0 |
||
2014 |
||
5.0 |
||
Build System |
||
3.13 |
Cuda support 3.9 |
|
Required Libraries |
||
1.64.0 |
||
1.5 |
Note
When building Boost using gcc, please note that it is required to specify a
cxxflags=-std=c++14 command line argument to b2 (bjam).
Name |
Minimum version |
Notes |
Compilers |
||
Visual C++ (x64) |
2015 |
|
Build System |
||
3.13 |
||
Required Libraries |
||
1.64.0 |
||
1.5 |
Note
You need to build the following Boost libraries for HPX: Boost.Filesystem, Boost.ProgramOptions, and Boost.System. 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 |
Notes |
1.7.1 |
Used as a replacement for the system allocator, and for allocation diagnostics. |
|
0.97 |
Dependency of google-perftools on x86-64, used for stack unwinding. |
|
1.8.0 |
Can be used as a highspeed communication library backend for the parcelport. |
Note
When using OpenMPI please note that Ubuntu (notably 18.04 LTS) and older
Debian ship an OpenMPI 2.x built with --enable-heterogeneous which may
cause communication failures at runtime and should not be used.
Name |
Minimum version |
Notes |
Performance Application Programming Interface (PAPI) |
Used for accessing hardware performance data. |
|
2.1.0 |
Used as a replacement for the system allocator. |
|
1.0.0 |
Used as a replacement for the system allocator. |
|
1.6.7 |
Used for data I/O in some example applications. See important note below. |
Name |
Minimum version |
Notes |
1.6.7 |
Used for data I/O in some example applications. See important note below. |
Important
The C++ HDF5 libraries must be compiled with enabled thread safety support. This has to be explicitly specified while configuring the HDF5 libraries as it is not the default. Additionally, you must set the following environment variables before configuring the HDF5 libraries (this part only needs to be done on Linux):
export CFLAGS='-DHDatexit=""'
export CPPFLAGS='-DHDatexit=""'
Documentation¶
To build the HPX documentation, you need recent versions of the following packages:
python3sphinx(Python package)sphinx_rtd_theme(Python package)breathe 4.16.0(Python package)doxygen
If the Python dependencies are not available through your system package
manager, you can install them using the Python package manager pip:
pip install --user sphinx sphinx_rtd_theme breathe
You may need to set the following CMake variables to make sure CMake can find the required dependencies.
Installing Boost¶
Important
When building Boost using gcc, please note that it is required to specify a
cxxflags=-std=c++14 command line argument to b2 (bjam).
Important
On Windows, depending on the installed versions of Visual Studio, you might
also want to pass the correct toolset to the b2 command depending on
which version of the IDE you want to use. In addition, passing
address-model=64 is highly recommended. It might also be necessary to add
command line argument --build-type=complete to the b2 command on the
Windows platform.
The easiest way to create a working Boost installation is to compile Boost from
sources yourself. This is particularly important as many high performance
resources, even if they have Boost installed, usually only provide you with an
older version of Boost. We suggest you download the most recent release of the
Boost libraries from here: Boost Downloads. Unpack the downloaded archive
into a directory of your choosing. We will refer to this directory a $BOOST.
Building and installing the Boost binaries is simple. Regardless of what platform you are on, the basic instructions are as follows (with possible additional platform-dependent command line arguments):
cd $BOOST
bootstrap --prefix=<where to install boost>
./b2 -j<N>
./b2 install
where: <where to install boost> is the directory the built binaries will be
installed to, and <N> is the number of cores to use to build the Boost
binaries.
After the above sequence of commands has been executed (this may take a while!),
you will need to specify the directory where Boost was installed as
BOOST_ROOT (<where to install boost>) while executing CMake for HPX as
explained in detail in the sections How to install HPX on Unix variants and
How to install HPX on Windows.
Installing Hwloc¶
Note
These instructions are for everything except Windows. On Windows there is no
need to build hwloc. Instead, download the latest release, extract the files,
and set HWLOC_ROOT during CMake configuration to the directory in which
you extracted the files.
We suggest you download the most recent release of hwloc from here:
Hwloc Downloads. Unpack the downloaded archive into a directory of your
choosing. We will refer to this directory as $HWLOC.
To build hwloc run:
cd $HWLOC
./configure --prefix=<where to install hwloc>
make -j<N> install
where: <where to install hwloc> is the directory the built binaries will be
installed to, and <N> is the number of cores to use to build hwloc.
After the above sequence of commands has been executed, you will need to specify
the directory where hwloc was installed as HWLOC_ROOT (<where to install
hwloc>) while executing CMake for HPX as explained in detail in the sections
How to install HPX on Unix variants and How to install HPX on Windows.
Please see Hwloc Documentation for more information about hwloc.
Building HPX¶
Basic information¶
Once CMake has been run, the build process can be started. The HPX build process is highly configurable through CMake, and various CMake variables influence the build process. The build process consists of the following parts:
The HPX core libraries (target core): This forms the basic set of HPX libraries. The generated targets are:
hpx: The core HPX library (always enabled).hpx_init: The HPX initialization library that applications need to link against to define the HPX entry points (disabled for static builds).hpx_wrap: The HPX static library used to determine the runtime behavior of HPX code and respective entry points forhpx_main.hiostreams_component: The component used for (distributed) IO (always enabled).component_storage_component: The component needed for migration to persistent storage.unordered_component: The component needed for a distributed (partitioned) hash table.partioned_vector_component: The component needed for a distributed (partitioned) vector.memory_component: A dynamically loaded plugin that exposes memory based performance counters (only available on Linux).io_counter_component: A dynamically loaded plugin that exposes I/O performance counters (only available on Linux).papi_component: A dynamically loaded plugin that exposes PAPI performance counters (enabled withHPX_WITH_PAPI:BOOL, default isOff).
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.
For a complete list of available CMake variables that influence the build of HPX, see CMake variables used to configure HPX.
The variables can be used to refine the recipes that can be found at Platform specific build recipes which show some basic steps on how to build HPX for a specific platform.
In order to use HPX, only the core libraries are required (the ones marked as
optional above are truly optional). When building against HPX, the CMake
variable HPX_LIBRARIES will contain hpx and hpx_init (for pkgconfig,
those are added to the Libs sections). In order to use the optional
libraries, you need to specify them as link dependencies in your build (See
Creating HPX projects).
As HPX is a modern C++ library, we require a certain minimum set of features from the C++11 standard. In addition, we make use of certain C++14 features if the used compiler supports them. This means that the HPX build system will try to determine the highest support C++ standard flavor and check for availability of those features. That is, the default will be the highest C++ standard version available. If you want to force HPX to use a specific C++ standard version, you can use the following CMake variables:
HPX_WITH_CXX14: Enables C++14 support (this is the minimum requirement)HPX_WITH_CXX17: Enables C++17 supportHPX_WITH_CXX2A: Enables (experimental) C++20 support
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 notes¶
Some platforms require users to have special link and/or compiler flags specified to build HPX. This is handled via CMake’s support for different toolchains (see cmake-toolchains(7) for more information). This is also used for cross compilation.
HPX ships with a set of toolchains that can be used for compilation of HPX itself and applications depending on HPX. Please see CMake toolchains shipped with HPX for more information.
In order to enable full static linking with the libraries, the CMake variable
HPX_WITH_STATIC_LINKING:BOOL has to be set to On.
Debugging applications using core files¶
For HPX to generate useful core files, HPX has to be compiled without signal
and exception handlers
HPX_WITH_DISABLED_SIGNAL_EXCEPTION_HANDLERS:BOOL. If this option is
not specified, the signal handlers change the application state. For example,
after a segmentation fault the stack trace will show the signal handler.
Similarly, unhandled exceptions are also caught by these handlers and the
stack trace will not point to the location where the unhandled exception was
thrown.
In general, core files are a helpful tool to inspect the state of the application at the moment of the crash (post-mortem debugging), without the need of attaching a debugger beforehand. This approach to debugging is especially useful if the error cannot be reliably reproduced, as only a single crashed application run is required to gain potentially helpful information like a stacktrace.
To debug with core files, the operating system first has to be told to actually write them. On most Unix systems this can be done by calling:
ulimit -c unlimited
in the shell. Now the debugger can be started up with:
gdb <application> <core file name>
The debugger should now display the last state of the application. The default
file name for core files is core.
Platform specific build recipes¶
Note
The following build recipes are mostly user-contributed and may be outdated. We always welcome updated and new build recipes.
How to install HPX on Unix variants¶
Create a build directory. HPX requires an out-of-tree build. This means you will be unable to run CMake in the HPX source tree.
cd hpx mkdir my_hpx_build cd my_hpx_build
Invoke CMake from your build directory, pointing the CMake driver to the root of your HPX source tree.
cmake -DBOOST_ROOT=/root/of/boost/installation \ -DHWLOC_ROOT=/root/of/hwloc/installation [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.0
Invoke GNU make. If you are on a machine with multiple cores, add the -jN flag to your make invocation, where N is the number of parallel processes HPX gets compiled with.
gmake -j4
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.
Note
Many Linux distributions use
makeas an alias forgmake.To complete the build and install HPX:
gmake install
Important
These commands will build and install the essential core components of HPX only. In order to build and run the tests, please invoke:
gmake tests && gmake test
and in order to build (and install) all examples invoke:
cmake -DHPX_WITH_EXAMPLES=On . gmake examples gmake install
For more detailed information about using CMake, please refer to its documentation
and also the section Building HPX. Please pay special attention to the
section about HPX_WITH_MALLOC:STRING as this is crucial for getting
decent performance.
How to install HPX on OS X (Mac)¶
This section describes how to build HPX for OS X (Mac).
To build Boost with Clang and make it link to libc++ as standard library, you’ll
need to set up either of the following in your ~/user-config.jam file:
# user-config.jam (put this file into your home directory)
# ...
using clang
:
: "/usr/bin/clang++"
: <cxxflags>"-std=c++11 -fcolor-diagnostics"
<linkflags>"-stdlib=libc++ -L/path/to/libcxx/lib"
;
(Again, remember to replace /path/to with whatever you used earlier.)
Then, you can use one of the following for your build command:
b2 --build-dir=/tmp/build-boost --layout=versioned toolset=clang install -j4
or:
b2 --build-dir=/tmp/build-boost --layout=versioned toolset=clang install -j4
We verified this using Boost V1.53. If you use a different version, just
remember to replace /usr/local/include/boost-1_53 with whatever prefix
you used in your installation.
cd /path/to
git clone https://github.com/STEllAR-GROUP/hpx.git
mkdir build-hpx && cd build-hpx
To build with Clang, execute:
cmake ../hpx \
-DCMAKE_CXX_COMPILER=clang++ \
-DBOOST_ROOT=/path/to/boost \
-DHWLOC_ROOT=/path/to/hwloc \
-DHPX_WITH_GENERIC_CONTEXT_COROUTINES=On
make -j
For more detailed information about using CMake, please refer its documentation and to the section Building HPX.
Alternatively, you can install a recent version of gcc as well as all required libraries via MacPorts:
Install MacPorts
Install CMake, gcc, hwloc:
sudo brew install cmake sudo brew install boost sudo brew install hwloc sudo brew install make
You may also want:
sudo brew install gperftools
If you need to build Boost manually (the Boost package of MacPorts is built with Clang, and unfortunately doesn’t work with a GCC-build version of HPX):
wget https://dl.bintray.com/boostorg/release/1.69.0/source/boost_1_69_0.tar.bz2 tar xjf boost_1_69_0.tar.bz2 pushd boost_1_69_0 export BOOST_ROOT=$HOME/boost_1_69_0 ./bootstrap.sh --prefix=$BOOST_DIR ./b2 -j8 ./b2 -j8 install export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$BOOST_ROOT/lib popd
Build HPX:
git clone https://github.com/STEllAR-GROUP/hpx.git mkdir hpx-build pushd hpx-build export HPX_ROOT=$HOME/hpx cmake -DCMAKE_C_COMPILER=gcc \ -DCMAKE_CXX_COMPILER=g++ \ -DCMAKE_FORTRAN_COMPILER=gfortran \ -DCMAKE_C_FLAGS="-Wno-unused-local-typedefs" \ -DCMAKE_CXX_FLAGS="-Wno-unused-local-typedefs" \ -DBOOST_ROOT=$BOOST_ROOT \ -DHWLOC_ROOT=/opt/local \ -DCMAKE_INSTALL_PREFIX=$HOME/hpx \ -DHPX_WITH_GENERIC_CONTEXT_COROUTINES=On \ $(pwd)/../hpx make -j8 make -j8 install export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$HPX_ROOT/lib/hpx popd
Note that you need to set
BOOST_ROOT,HPX_ROOTandDYLD_LIBRARY_PATH(for bothBOOST_ROOTandHPX_ROOT) every time you configure, build, or run an HPX application.Note that you need to set
HPX_WITH_GENERIC_CONTEXT_COROUTINES=Onfor MacOS.If you want to use HPX with MPI, you need to enable the MPI parcelport, and also specify the location of the MPI wrapper scripts. This can be done using the following command:
cmake -DHPX_WITH_PARCELPORT_MPI=ON \ -DCMAKE_C_COMPILER=gcc \ -DCMAKE_CXX_COMPILER=g++ \ -DCMAKE_FORTRAN_COMPILER=gfortran \ -DMPI_C_COMPILER=openmpicc \ -DMPI_CXX_COMPILER=openmpic++ \ -DMPI_FORTRAN_COMPILER=openmpif90 \ -DCMAKE_C_FLAGS="-Wno-unused-local-typedefs" \ -DCMAKE_CXX_FLAGS="-Wno-unused-local-typedefs" \ -DBOOST_ROOT=$BOOST_DIR \ -DHWLOC_ROOT=/opt/local \ -DCMAKE_INSTALL_PREFIX=$HOME/hpx $(pwd)/../hpx
How to install HPX on Windows¶
Download the Boost c++ libraries from Boost Downloads
Install the Boost library as explained in the section Installing Boost
Install the hwloc library as explained in the section Installing Hwloc
Download the latest version of CMake binaries, which are located under the platform section of the downloads page at CMake Downloads.
Download the latest version of HPX from the STE||AR website: HPX Downloads.
Create a build folder. HPX requires an out-of-tree-build. This means that you will be unable to run CMake in the HPX source folder.
Open up the CMake GUI. In the input box labelled “Where is the source code:”, enter the full path to the source folder. The source directory is the one where the sources were checked out. CMakeLists.txt files in the source directory as well as the subdirectories describe the build to CMake. In addition to this, there are CMake scripts (usually ending in .cmake) stored in a special CMake directory. CMake does not alter any file in the source directory and doesn’t add new ones either. In the input box labelled “Where to build the binaries:”, enter the full path to the build folder you created before. The build directory is one where all compiler outputs are stored, which includes object files and final executables.
Add CMake variable definitions (if any) by clicking the “Add Entry” button. There are two required variables you need to define:
BOOST_ROOTandHWLOC_ROOTThese (PATH) variables need to be set to point to the root folder of your Boost and hwloc installations. It is recommended to set the variableCMAKE_INSTALL_PREFIXas well. This determines where the HPX libraries will be built and installed. If this (PATH) variable is set, it has to refer to the directory where the built HPX files should be installed to.Press the “Configure” button. A window will pop up asking you which compilers to use. Select the Visual Studio 10 (64Bit) compiler (it usually is the default if available). The Visual Studio 2012 (64Bit) and Visual Studio 2013 (64Bit) compilers are supported as well. Note that while it is possible to build HPX for x86, we don’t recommend doing so as 32 bit runs are severely restricted by a 32 bit Windows system limitation affecting the number of HPX threads you can create.
Press “Configure” again. Repeat this step until the “Generate” button becomes clickable (and until no variable definitions are marked in red anymore).
Press “Generate”.
Open up the build folder, and double-click hpx.sln.
Build the INSTALL target.
For more detailed information about using CMake please refer its documentation and also the section Building HPX.
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.bat
This 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 three new environment variables (in CMake, not in Windows environment):
BOOST_ROOT,HWLOC_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.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.¶
How to install HPX on Fedora distributions¶
Important
There are official HPX packages for Fedora. Unless you want to customize your, build you may want to start off with the official packages. Instructions can be found on the HPX Downloads page.
Note
This section of the manual is based off of our collaborator Patrick Diehl’s blog post Installing |hpx| on Fedora 22.
Install all packages for minimal installation:
sudo dnf install gcc-c++ cmake boost-build boost boost-devel hwloc-devel \ hwloc gcc-gfortran papi-devel gperftools-devel docbook-dtds \ docbook-style-xsl libsodium-devel doxygen boost-doc hdf5-devel \ fop boost-devel boost-openmpi-devel boost-mpich-devel
Get the development branch of HPX:
git clone https://github.com/STEllAR-GROUP/hpx.git
Configure it with CMake:
cd hpx mkdir build cd build cmake -DCMAKE_INSTALL_PREFIX=/opt/hpx .. make -j make install
Note
To build HPX without examples use:
cmake -DCMAKE_INSTALL_PREFIX=/opt/hpx -DHPX_WITH_EXAMPLES=Off ..
Add the library path of HPX to ldconfig:
sudo echo /opt/hpx/lib > /etc/ld.so.conf.d/hpx.conf sudo ldconfig
How to install HPX on Arch distributions¶
Important
There are HPX packages for Arch in the AUR. Unless you want to customize your build, you may want to start off with those. Instructions can be found on the HPX Downloads page.
Install all packages for a minimal installation:
sudo pacman -S gcc clang cmake boost hwloc gperftools
For building the documentation, you will need to further install the following:
sudo pacman -S doxygen python-pip pip install --user sphinx sphinx_rtd_theme breathe
The rest of the installation steps are the same as those for the Fedora or Unix variants.
How to install HPX on Debian-based distributions¶
Install all packages for a minimal installation:
sudo apt install cmake libboost-all-dev hwloc libgoogle-perftools-dev
To build the documentation you will need to further install the following:
sudo apt install doxygen python-pip pip install --user sphinx sphinx_rtd_theme breathe
or the following if you prefer to get Python packages from the Debian repositories:
sudo apt install doxygen python-sphinx python-sphinx-rtd-theme python-breathe
The rest of the installation steps are same as those for the Fedora or Unix variants.
CMake toolchains shipped with HPX¶
In order to compile HPX for various platforms, we provide a variety of toolchain
files that take care of setting up various CMake variables like compilers, etc.
They are located in the cmake/toolchains directory:
To use them, pass the -DCMAKE_TOOLCHAIN_FILE=<toolchain> argument to the
CMake invocation.
ARM-gcc¶
# Copyright (c) 2015 Thomas Heller
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_CROSSCOMPILING ON)
# Set the gcc Compiler
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++-4.8)
set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc-4.8)
set(HPX_WITH_GENERIC_CONTEXT_COROUTINES
ON
CACHE BOOL "enable generic coroutines"
)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
BGION-gcc¶
# Copyright (c) 2014 John Biddiscombe
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
# This is the default toolchain file to be used with CNK on a BlueGene/Q. It
# sets the appropriate compile flags and compiler such that HPX will compile.
# Note that you still need to provide Boost, hwloc and other utility libraries
# like a custom allocator yourself.
#
# Usage : cmake
# -DCMAKE_TOOLCHAIN_FILE=~/src/hpx/cmake/toolchains/BGION-gcc.cmake ~/src/hpx
#
set(CMAKE_SYSTEM_NAME Linux)
# Set the gcc Compiler
set(CMAKE_CXX_COMPILER g++)
set(CMAKE_C_COMPILER gcc)
# set(CMAKE_Fortran_COMPILER)
# Add flags we need for BGAS compilation
set(CMAKE_CXX_FLAGS_INIT
"-D__powerpc__ -D__bgion__ -I/gpfs/bbp.cscs.ch/home/biddisco/src/bgas/rdmahelper "
CACHE STRING "Initial compiler flags used to compile for BGAS"
)
# cmake-format: off
# the V1R2M2 includes are necessary for some hardware specific features
# -DHPX_SMALL_STACK_SIZE=0x200000
# -DHPX_MEDIUM_STACK_SIZE=0x200000
# -DHPX_LARGE_STACK_SIZE=0x200000
# -DHPX_HUGE_STACK_SIZE=0x200000
# cmake-format: on
set(CMAKE_EXE_LINKER_FLAGS_INIT
"-L/gpfs/bbp.cscs.ch/apps/bgas/tools/gcc/gcc-4.8.2/install/lib64 -latomic -lrt"
CACHE STRING "BGAS flags"
)
set(CMAKE_C_FLAGS_INIT
"-D__powerpc__ -I/gpfs/bbp.cscs.ch/home/biddisco/src/bgas/rdmahelper"
CACHE STRING "BGAS flags"
)
# We do not perform cross compilation here ...
set(CMAKE_CROSSCOMPILING OFF)
# Set our platform name
set(HPX_PLATFORM "native")
# Disable generic coroutines (and use posix version)
set(HPX_WITH_GENERIC_CONTEXT_COROUTINES
OFF
CACHE BOOL "disable generic coroutines"
)
# BGAS nodes support ibverbs, but it is deprecated
set(HPX_WITH_PARCELPORT_VERBS
OFF
CACHE BOOL ""
)
# Always disable the tcp parcelport as it is non-functional on the BGQ.
set(HPX_WITH_PARCELPORT_TCP
ON
CACHE BOOL ""
)
# Always enable the tcp parcelport as it is currently the only way to
# communicate on the BGQ.
set(HPX_WITH_PARCELPORT_MPI
ON
CACHE BOOL ""
)
# We have a bunch of cores on the A2 processor ...
set(HPX_WITH_MAX_CPU_COUNT
"64"
CACHE STRING ""
)
# We have no custom malloc yet
if(NOT DEFINED HPX_WITH_MALLOC)
set(HPX_WITH_MALLOC
"system"
CACHE STRING ""
)
endif()
set(HPX_HIDDEN_VISIBILITY
OFF
CACHE BOOL ""
)
#
# Convenience setup for jb @ bbpbg2.cscs.ch
#
set(BOOST_ROOT "/gpfs/bbp.cscs.ch/home/biddisco/apps/gcc-4.8.2/boost_1_56_0")
set(HWLOC_ROOT "/gpfs/bbp.cscs.ch/home/biddisco/apps/gcc-4.8.2/hwloc-1.8.1")
set(CMAKE_BUILD_TYPE
"Debug"
CACHE STRING "Default build"
)
#
# Testing flags
#
set(BUILD_TESTING
ON
CACHE BOOL "Testing enabled by default"
)
set(HPX_WITH_TESTS
ON
CACHE BOOL "Testing enabled by default"
)
set(HPX_WITH_TESTS_BENCHMARKS
ON
CACHE BOOL "Testing enabled by default"
)
set(HPX_WITH_TESTS_REGRESSIONS
ON
CACHE BOOL "Testing enabled by default"
)
set(HPX_WITH_TESTS_UNIT
ON
CACHE BOOL "Testing enabled by default"
)
set(HPX_WITH_TESTS_EXAMPLES
ON
CACHE BOOL "Testing enabled by default"
)
set(HPX_WITH_TESTS_EXTERNAL_BUILD
OFF
CACHE BOOL "Turn off build of cmake build tests"
)
set(DART_TESTING_TIMEOUT
45
CACHE STRING "Life is too short"
)
# HPX_WITH_STATIC_LINKING
BGQ¶
# Copyright (c) 2014 Thomas Heller
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#
# This is the default toolchain file to be used with CNK on a BlueGene/Q. It sets
# the appropriate compile flags and compiler such that HPX will compile.
# Note that you still need to provide Boost, hwloc and other utility libraries
# like a custom allocator yourself.
#
set(CMAKE_SYSTEM_NAME Linux)
# Set the Intel Compiler
set(CMAKE_CXX_COMPILER bgclang++11)
set(CMAKE_C_COMPILER bgclang)
# set(CMAKE_Fortran_COMPILER)
set(MPI_CXX_COMPILER mpiclang++11)
set(MPI_C_COMPILER mpiclang)
# set(MPI_Fortran_COMPILER)
set(CMAKE_C_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_C_COMPILE_OBJECT
"<CMAKE_C_COMPILER> -fPIC <DEFINES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_C_LINK_EXECUTABLE
"<CMAKE_C_COMPILER> -fPIC -dynamic <FLAGS> <CMAKE_C_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_C_CREATE_SHARED_LIBRARY
"<CMAKE_C_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_CXX_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES> "
CACHE STRING ""
)
set(CMAKE_CXX_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_CXX_COMPILE_OBJECT
"<CMAKE_CXX_COMPILER> -fPIC <DEFINES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_CXX_LINK_EXECUTABLE
"<CMAKE_CXX_COMPILER> -fPIC -dynamic <FLAGS> <CMAKE_CXX_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_CXX_CREATE_SHARED_LIBRARY
"<CMAKE_CXX_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_CXX_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_Fortran_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_Fortran_COMPILE_OBJECT
"<CMAKE_Fortran_COMPILER> -fPIC <DEFINES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_Fortran_LINK_EXECUTABLE
"<CMAKE_Fortran_COMPILER> -fPIC -dynamic <FLAGS> <CMAKE_Fortran_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
)
set(CMAKE_Fortran_CREATE_SHARED_LIBRARY
"<CMAKE_Fortran_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_Fortran_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_Fortran_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES> "
CACHE STRING ""
)
# Disable searches in the default system paths. We are cross compiling after all
# and cmake might pick up wrong libraries that way
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
# We do a cross compilation here ...
set(CMAKE_CROSSCOMPILING ON)
# Set our platform name
set(HPX_PLATFORM "BlueGeneQ")
# Always disable the ibverbs parcelport as it is non-functional on the BGQ.
set(HPX_WITH_PARCELPORT_VERBS OFF)
# Always disable the tcp parcelport as it is non-functional on the BGQ.
set(HPX_WITH_PARCELPORT_TCP OFF)
# Always enable the mpi parcelport as it is currently the only way to
# communicate on the BGQ.
set(HPX_WITH_PARCELPORT_MPI ON)
# We have a bunch of cores on the BGQ ...
set(HPX_WITH_MAX_CPU_COUNT "64")
# We default to tbbmalloc as our allocator on the MIC
if(NOT DEFINED HPX_WITH_MALLOC)
set(HPX_WITH_MALLOC
"system"
CACHE STRING ""
)
endif()
Cray¶
# Copyright (c) 2014 Thomas Heller
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#
# This is the default toolchain file to be used with Intel Xeon PHIs. It sets
# the appropriate compile flags and compiler such that HPX will compile.
# Note that you still need to provide Boost, hwloc and other utility libraries
# like a custom allocator yourself.
#
# set(CMAKE_SYSTEM_NAME Cray-CNK-Intel)
if(HPX_WITH_STATIC_LINKING)
set_property(GLOBAL PROPERTY TARGET_SUPPORTS_SHARED_LIBS FALSE)
else()
endif()
# Set the Cray Compiler Wrapper
set(CMAKE_CXX_COMPILER CC)
set(CMAKE_C_COMPILER cc)
set(CMAKE_Fortran_COMPILER ftn)
set(CMAKE_C_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_C_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_C_COMPILE_OBJECT
"<CMAKE_C_COMPILER> -shared -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_C_LINK_EXECUTABLE
"<CMAKE_C_COMPILER> -fPIC -dynamic <FLAGS> <CMAKE_C_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_C_CREATE_SHARED_LIBRARY
"<CMAKE_C_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_CXX_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES> "
CACHE STRING ""
)
set(CMAKE_CXX_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CXX_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_CXX_COMPILE_OBJECT
"<CMAKE_CXX_COMPILER> -shared -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_CXX_LINK_EXECUTABLE
"<CMAKE_CXX_COMPILER> -fPIC -dynamic <FLAGS> <CMAKE_CXX_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_CXX_CREATE_SHARED_LIBRARY
"<CMAKE_CXX_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_CXX_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_Fortran_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_Fortran_FLAGS
"-fPIC"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_Fortran_FLAGS
"-shared"
CACHE STRING ""
)
set(CMAKE_Fortran_COMPILE_OBJECT
"<CMAKE_Fortran_COMPILER> -shared -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_Fortran_LINK_EXECUTABLE
"<CMAKE_Fortran_COMPILER> -fPIC -dynamic <FLAGS> <CMAKE_Fortran_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
)
set(CMAKE_Fortran_CREATE_SHARED_LIBRARY
"<CMAKE_Fortran_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_Fortran_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_Fortran_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES> "
CACHE STRING ""
)
# Disable searches in the default system paths. We are cross compiling after all
# and cmake might pick up wrong libraries that way
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
set(HPX_WITH_PARCELPORT_TCP
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI_MULTITHREADED
OFF
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_LIBFABRIC
ON
CACHE BOOL ""
)
set(HPX_PARCELPORT_LIBFABRIC_PROVIDER
"gni"
CACHE STRING "See libfabric docs for details, gni,verbs,psm2 etc etc"
)
set(HPX_PARCELPORT_LIBFABRIC_THROTTLE_SENDS
"256"
CACHE STRING "Max number of messages in flight at once"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_DEV_MODE
OFF
CACHE BOOL "Custom libfabric logging flag"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_LOGGING
OFF
CACHE BOOL "Libfabric parcelport logging on/off flag"
)
set(HPX_WITH_ZERO_COPY_SERIALIZATION_THRESHOLD
"4096"
CACHE
STRING
"The threshold in bytes to when perform zero copy optimizations (default: 128)"
)
# We do a cross compilation here ...
set(CMAKE_CROSSCOMPILING
ON
CACHE BOOL ""
)
CrayKNL¶
# Copyright (c) 2014 Thomas Heller
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#
# This is the default toolchain file to be used with Intel Xeon PHIs. It sets
# the appropriate compile flags and compiler such that HPX will compile.
# Note that you still need to provide Boost, hwloc and other utility libraries
# like a custom allocator yourself.
#
if(HPX_WITH_STATIC_LINKING)
set_property(GLOBAL PROPERTY TARGET_SUPPORTS_SHARED_LIBS FALSE)
else()
endif()
# Set the Cray Compiler Wrapper
set(CMAKE_CXX_COMPILER CC)
set(CMAKE_C_COMPILER cc)
set(CMAKE_Fortran_COMPILER ftn)
set(CMAKE_C_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_C_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_C_COMPILE_OBJECT
"<CMAKE_C_COMPILER> -shared -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_C_LINK_EXECUTABLE
"<CMAKE_C_COMPILER> -fPIC <FLAGS> <CMAKE_C_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_C_CREATE_SHARED_LIBRARY
"<CMAKE_C_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_CXX_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES> "
CACHE STRING ""
)
#
set(CMAKE_CXX_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CXX_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS
"-fPIC -shared"
CACHE STRING ""
)
set(CMAKE_CXX_COMPILE_OBJECT
"<CMAKE_CXX_COMPILER> -shared -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_CXX_LINK_EXECUTABLE
"<CMAKE_CXX_COMPILER> -fPIC -dynamic <FLAGS> <CMAKE_CXX_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_CXX_CREATE_SHARED_LIBRARY
"<CMAKE_CXX_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_CXX_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES>"
CACHE STRING ""
)
#
set(CMAKE_Fortran_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_Fortran_FLAGS
"-fPIC"
CACHE STRING ""
)
set(CMAKE_SHARED_LIBRARY_CREATE_Fortran_FLAGS
"-shared"
CACHE STRING ""
)
set(CMAKE_Fortran_COMPILE_OBJECT
"<CMAKE_Fortran_COMPILER> -shared -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_Fortran_LINK_EXECUTABLE
"<CMAKE_Fortran_COMPILER> -fPIC <FLAGS> <CMAKE_Fortran_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
)
set(CMAKE_Fortran_CREATE_SHARED_LIBRARY
"<CMAKE_Fortran_COMPILER> -fPIC -shared <CMAKE_SHARED_LIBRARY_Fortran_FLAGS> <LANGUAGE_COMPILE_FLAGS> <LINK_FLAGS> <CMAKE_SHARED_LIBRARY_CREATE_Fortran_FLAGS> <SONAME_FLAG><TARGET_SONAME> -o <TARGET> <OBJECTS> <LINK_LIBRARIES> "
CACHE STRING ""
)
#
# Disable searches in the default system paths. We are cross compiling after all
# and cmake might pick up wrong libraries that way
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
set(HPX_WITH_PARCELPORT_TCP
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI_MULTITHREADED
OFF
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_LIBFABRIC
ON
CACHE BOOL ""
)
set(HPX_PARCELPORT_LIBFABRIC_PROVIDER
"gni"
CACHE STRING "See libfabric docs for details, gni,verbs,psm2 etc etc"
)
set(HPX_PARCELPORT_LIBFABRIC_THROTTLE_SENDS
"256"
CACHE STRING "Max number of messages in flight at once"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_DEV_MODE
OFF
CACHE BOOL "Custom libfabric logging flag"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_LOGGING
OFF
CACHE BOOL "Libfabric parcelport logging on/off flag"
)
set(HPX_WITH_ZERO_COPY_SERIALIZATION_THRESHOLD
"4096"
CACHE
STRING
"The threshold in bytes to when perform zero copy optimizations (default: 128)"
)
# Set the TBBMALLOC_PLATFORM correctly so that find_package(TBBMalloc) sets the
# right hints
set(TBBMALLOC_PLATFORM
"mic-knl"
CACHE STRING ""
)
# We have a bunch of cores on the MIC ... increase the default
set(HPX_WITH_MAX_CPU_COUNT
"512"
CACHE STRING ""
)
# We do a cross compilation here ...
set(CMAKE_CROSSCOMPILING
ON
CACHE BOOL ""
)
# RDTSCP is available on Xeon/Phis
set(HPX_WITH_RDTSCP
ON
CACHE BOOL ""
)
CrayKNLStatic¶
# Copyright (c) 2014-2017 Thomas Heller
# Copyright (c) 2017 Bryce Adelstein Lelbach
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
set(HPX_WITH_STATIC_LINKING
ON
CACHE BOOL ""
)
set(HPX_WITH_STATIC_EXE_LINKING
ON
CACHE BOOL ""
)
set_property(GLOBAL PROPERTY TARGET_SUPPORTS_SHARED_LIBS FALSE)
# Set the Cray Compiler Wrapper
set(CMAKE_CXX_COMPILER CC)
set(CMAKE_C_COMPILER cc)
set(CMAKE_Fortran_COMPILER ftn)
set(CMAKE_C_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_C_COMPILE_OBJECT
"<CMAKE_C_COMPILER> -static -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_C_LINK_EXECUTABLE
"<CMAKE_C_COMPILER> -fPIC <FLAGS> <CMAKE_C_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_CXX_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_CXX_COMPILE_OBJECT
"<CMAKE_CXX_COMPILER> -static -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_CXX_LINK_EXECUTABLE
"<CMAKE_CXX_COMPILER> -fPIC <FLAGS> <CMAKE_CXX_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_Fortran_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_Fortran_COMPILE_OBJECT
"<CMAKE_Fortran_COMPILER> -static -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_Fortran_LINK_EXECUTABLE
"<CMAKE_Fortran_COMPILER> -fPIC <FLAGS> <CMAKE_Fortran_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
)
# Disable searches in the default system paths. We are cross compiling after all
# and cmake might pick up wrong libraries that way
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
set(HPX_WITH_PARCELPORT_TCP
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI_MULTITHREADED
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_LIBFABRIC
ON
CACHE BOOL ""
)
set(HPX_PARCELPORT_LIBFABRIC_PROVIDER
"gni"
CACHE STRING "See libfabric docs for details, gni,verbs,psm2 etc etc"
)
set(HPX_PARCELPORT_LIBFABRIC_THROTTLE_SENDS
"256"
CACHE STRING "Max number of messages in flight at once"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_DEV_MODE
OFF
CACHE BOOL "Custom libfabric logging flag"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_LOGGING
OFF
CACHE BOOL "Libfabric parcelport logging on/off flag"
)
set(HPX_WITH_ZERO_COPY_SERIALIZATION_THRESHOLD
"4096"
CACHE
STRING
"The threshold in bytes to when perform zero copy optimizations (default: 128)"
)
# Set the TBBMALLOC_PLATFORM correctly so that find_package(TBBMalloc) sets the
# right hints
set(TBBMALLOC_PLATFORM
"mic-knl"
CACHE STRING ""
)
# We have a bunch of cores on the MIC ... increase the default
set(HPX_WITH_MAX_CPU_COUNT
"512"
CACHE STRING ""
)
# We do a cross compilation here ...
set(CMAKE_CROSSCOMPILING
ON
CACHE BOOL ""
)
# RDTSCP is available on Xeon/Phis
set(HPX_WITH_RDTSCP
ON
CACHE BOOL ""
)
CrayStatic¶
# Copyright (c) 2014-2017 Thomas Heller
# Copyright (c) 2017 Bryce Adelstein Lelbach
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
set(HPX_WITH_STATIC_LINKING
ON
CACHE BOOL ""
)
set(HPX_WITH_STATIC_EXE_LINKING
ON
CACHE BOOL ""
)
set_property(GLOBAL PROPERTY TARGET_SUPPORTS_SHARED_LIBS FALSE)
# Set the Cray Compiler Wrapper
set(CMAKE_CXX_COMPILER CC)
set(CMAKE_C_COMPILER cc)
set(CMAKE_Fortran_COMPILER ftn)
set(CMAKE_C_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_C_COMPILE_OBJECT
"<CMAKE_C_COMPILER> -static -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_C_LINK_EXECUTABLE
"<CMAKE_C_COMPILER> -fPIC <FLAGS> <CMAKE_C_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_CXX_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_CXX_COMPILE_OBJECT
"<CMAKE_CXX_COMPILER> -static -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_CXX_LINK_EXECUTABLE
"<CMAKE_CXX_COMPILER> -fPIC <FLAGS> <CMAKE_CXX_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
CACHE STRING ""
)
set(CMAKE_Fortran_FLAGS_INIT
""
CACHE STRING ""
)
set(CMAKE_Fortran_COMPILE_OBJECT
"<CMAKE_Fortran_COMPILER> -static -fPIC <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> -c <SOURCE>"
CACHE STRING ""
)
set(CMAKE_Fortran_LINK_EXECUTABLE
"<CMAKE_Fortran_COMPILER> -fPIC <FLAGS> <CMAKE_Fortran_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>"
)
# Disable searches in the default system paths. We are cross compiling after all
# and cmake might pick up wrong libraries that way
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
# We do a cross compilation here ...
set(CMAKE_CROSSCOMPILING
ON
CACHE BOOL ""
)
# RDTSCP is available on Xeon/Phis
set(HPX_WITH_RDTSCP
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_TCP
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_MPI_MULTITHREADED
ON
CACHE BOOL ""
)
set(HPX_WITH_PARCELPORT_LIBFABRIC
ON
CACHE BOOL ""
)
set(HPX_PARCELPORT_LIBFABRIC_PROVIDER
"gni"
CACHE STRING "See libfabric docs for details, gni,verbs,psm2 etc etc"
)
set(HPX_PARCELPORT_LIBFABRIC_THROTTLE_SENDS
"256"
CACHE STRING "Max number of messages in flight at once"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_DEV_MODE
OFF
CACHE BOOL "Custom libfabric logging flag"
)
set(HPX_PARCELPORT_LIBFABRIC_WITH_LOGGING
OFF
CACHE BOOL "Libfabric parcelport logging on/off flag"
)
set(HPX_WITH_ZERO_COPY_SERIALIZATION_THRESHOLD
"4096"
CACHE
STRING
"The threshold in bytes to when perform zero copy optimizations (default: 128)"
)
XeonPhi¶
# Copyright (c) 2014 Thomas Heller
#
# SPDX-License-Identifier: BSL-1.0
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#
# This is the default toolchain file to be used with Intel Xeon PHIs. It sets
# the appropriate compile flags and compiler such that HPX will compile.
# Note that you still need to provide Boost, hwloc and other utility libraries
# like a custom allocator yourself.
#
set(CMAKE_SYSTEM_NAME Linux)
# Set the Intel Compiler
set(CMAKE_CXX_COMPILER icpc)
set(CMAKE_C_COMPILER icc)
set(CMAKE_Fortran_COMPILER ifort)
# Add the -mmic compile flag such that everything will be compiled for the
# correct platform
set(CMAKE_CXX_FLAGS_INIT
"-mmic"
CACHE STRING "Initial compiler flags used to compile for the Xeon Phi"
)
set(CMAKE_C_FLAGS_INIT
"-mmic"
CACHE STRING "Initial compiler flags used to compile for the Xeon Phi"
)
set(CMAKE_Fortran_FLAGS_INIT
"-mmic"
CACHE STRING "Initial compiler flags used to compile for the Xeon Phi"
)
# Disable searches in the default system paths. We are cross compiling after all
# and cmake might pick up wrong libraries that way
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM BOTH)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
# We do a cross compilation here ...
set(CMAKE_CROSSCOMPILING ON)
# Set our platform name
set(HPX_PLATFORM "XeonPhi")
# Always disable the ibverbs parcelport as it is non-functional on the BGQ.
set(HPX_WITH_PARCELPORT_VERBS
OFF
CACHE
BOOL
"Enable the ibverbs based parcelport. This is currently an experimental feature"
)
set(HPX_WITH_PARCELPORT_MPI
ON
CACHE BOOL "Enable the MPI based parcelport."
)
# We have a bunch of cores on the MIC ... increase the default
set(HPX_WITH_MAX_CPU_COUNT
"256"
CACHE STRING ""
)
# We default to tbbmalloc as our allocator on the MIC
if(NOT DEFINED HPX_WITH_MALLOC)
set(HPX_WITH_MALLOC
"tbbmalloc"
CACHE STRING ""
)
endif()
# Set the TBBMALLOC_PLATFORM correctly so that find_package(TBBMalloc) sets the
# right hints
set(TBBMALLOC_PLATFORM
"mic"
CACHE STRING ""
)
set(HPX_HIDDEN_VISIBILITY
OFF
CACHE BOOL
"Use -fvisibility=hidden for builds on platforms which support it"
)
# RDTSC is available on Xeon/Phis
set(HPX_WITH_RDTSC
ON
CACHE BOOL ""
)
CMake variables used to configure HPX¶
In order to configure HPX, you can set a variety of options to allow CMake to generate your specific makefiles/project files.
Variables that influence how HPX is built¶
The options are split into these categories:
Generic options¶
-
HPX_WITH_ACTION_BASE_COMPATIBILITY:BOOL¶ Enable deprecated action bases (default: ON)
-
HPX_WITH_ASYNC_CUDA:BOOL¶ Enable HPX CUDA compute capability (parallel algorithms) module (default: OFF) - note: CUDA futures may be used without CUDA Compute
-
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_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 HPX_WITH_ASYNC_CUDA (CUDA futures) and HPX_WITH_CUDA_COMPUTE (CUDA enabled parallel algorithms) (default: OFF)
-
HPX_WITH_CUDA_CLANG:BOOL¶ Use clang to compile CUDA code (default: OFF)
-
HPX_WITH_CUDA_COMPUTE:BOOL¶ Enable HPX CUDA compute capability (parallel algorithms) module (default: OFF) - note: enabling this also enables CUDA futures via HPX_WITH_ASYNC_CUDA
-
HPX_WITH_DATAPAR_VC:BOOL¶ Enable data parallel algorithm support using the external Vc 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_EMBEDDED_THREAD_POOLS_COMPATIBILITY:BOOL¶ Enable deprecated embedded thread pools (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_FORTRAN:BOOL¶ Enable or disable the compilation of Fortran examples using HPX
-
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_INIT_START_OVERLOADS_COMPATIBILITY:BOOL¶ Enable deprecated init() and start() overloads functions (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_NATIVE_TLS:BOOL¶ Use native TLS support if available (default: )
-
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_POOL_EXECUTOR_COMPATIBILITY:BOOL¶ Enable deprecated pool executor (default: ON)
-
HPX_WITH_PROMISE_ALIAS_COMPATIBILITY:BOOL¶ Enable deprecated alias of hpx::promise to hpx::lcos::promise (default: ON)
-
HPX_WITH_REGISTER_THREAD_COMPATIBILITY:BOOL¶ Enable deprecated register_thread/work functions in the hpx::applier namespace (default: ON)
-
HPX_WITH_REGISTER_THREAD_OVERLOADS_COMPATIBILITY:BOOL¶ Enable deprecated register_thread/work overloads (default: ON)
-
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_THREAD_AWARE_TIMER_COMPATIBILITY:BOOL¶ Enable deprecated thread_aware_timer (default: ON)
-
HPX_WITH_THREAD_EXECUTORS_COMPATIBILITY:BOOL¶ Enable deprecated thread executors (default: ON)
-
HPX_WITH_THREAD_POOL_OS_EXECUTOR_COMPATIBILITY:BOOL¶ Enable deprecated thread pool executors (default: ON)
-
HPX_WITH_UNITY_BUILD:BOOL¶ Enable unity build for certain build targets (experimental, requires CMake 3.16 or newer) (default OFF)
-
HPX_WITH_UNSCOPED_ENUM_COMPATIBILITY:BOOL¶ Enable deprecated unscoped enums (default: ON)
-
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: 128)
Build Targets options¶
-
HPX_WITH_COMPILE_ONLY_TESTS:BOOL¶ Create build system support for compile time only HPX tests (default ON)
-
HPX_WITH_DEFAULT_TARGETS:BOOL¶ Associate the core HPX library with the default build target (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_IO_COUNTERS:BOOL¶ Enable IO counters (default: ON)
-
HPX_WITH_PSEUDO_DEPENDENCIES:BOOL¶ Force creating pseudo targets and pseudo dependencies (default ON).
-
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_SCHEDULER_MAX_TERMINATED_THREADS:STRING¶ [Deprecated] Maximum number of terminated threads collected before those are cleaned up (default: 100)
-
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: 64)
-
HPX_WITH_MAX_NUMA_DOMAIN_COUNT:STRING¶ HPX applications will not run on machines with more NUMA domains (default: 8)
-
HPX_WITH_MORE_THAN_64_THREADS:BOOL¶ HPX applications will be able to run on more than 64 cores (This variable is deprecated. The value is derived from HPX_WITH_MAX_CPU_COUNT instead.)
-
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_SWAP_CONTEXT_EMULATION:BOOL¶ Emulate SwapContext API for coroutines (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_SCHEDULERS:STRING¶ Which thread schedulers are built. Options are: all, abp-priority, local, static-priority, static, shared-priority. For multiple enabled schedulers, separate with a semicolon (default: all)
-
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)
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_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_PARCELPORT_VERBS:BOOL¶ Enable the ibverbs based parcelport. This is currently an experimental feature
-
HPX_WITH_PARCEL_PROFILING:BOOL¶ Enable profiling data for parcels
Profiling options¶
-
HPX_WITH_APEX:BOOL¶ Enable APEX instrumentation support.
-
HPX_WITH_GOOGLE_PERFTOOLS:BOOL¶ Enable Google Perftools 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_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, implicitly 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)
-
HPX_WITH_VERIFY_LOCKS_GLOBALLY:BOOL¶ Enable global lock verification code (default: OFF, implicitly enabled in debug builds)
Modules options¶
-
HPX_ACTIONS_BASE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ACTIONS_BASE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ACTIONS_BASE_WITH_TESTS:BOOL¶ Build HPX actions_base module tests. (default: ON)
-
HPX_ACTIONS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ACTIONS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ACTIONS_WITH_TESTS:BOOL¶ Build HPX actions module tests. (default: ON)
-
HPX_AFFINITY_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_AFFINITY_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_AFFINITY_WITH_TESTS:BOOL¶ Build HPX affinity module tests. (default: ON)
-
HPX_ALGORITHMS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ALGORITHMS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ALGORITHMS_WITH_TESTS:BOOL¶ Build HPX algorithms module tests. (default: ON)
-
HPX_ALLOCATOR_SUPPORT_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ALLOCATOR_SUPPORT_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ALLOCATOR_SUPPORT_WITH_TESTS:BOOL¶ Build HPX allocator_support module tests. (default: ON)
-
HPX_ASIO_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ASIO_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ASIO_WITH_TESTS:BOOL¶ Build HPX asio module tests. (default: ON)
-
HPX_ASSERTION_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ASSERTION_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ASSERTION_WITH_TESTS:BOOL¶ Build HPX assertion module tests. (default: ON)
-
HPX_ASYNC_BASE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ASYNC_BASE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ASYNC_BASE_WITH_TESTS:BOOL¶ Build HPX async_base module tests. (default: ON)
-
HPX_ASYNC_COMBINATORS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ASYNC_COMBINATORS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ASYNC_COMBINATORS_WITH_TESTS:BOOL¶ Build HPX async_combinators module tests. (default: ON)
-
HPX_ASYNC_DISTRIBUTED_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ASYNC_DISTRIBUTED_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ASYNC_DISTRIBUTED_WITH_TESTS:BOOL¶ Build HPX async_distributed module tests. (default: ON)
-
HPX_ASYNC_LOCAL_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ASYNC_LOCAL_WITH_TESTS:BOOL¶ Build HPX async_local module tests. (default: ON)
-
HPX_BATCH_ENVIRONMENTS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_BATCH_ENVIRONMENTS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_BATCH_ENVIRONMENTS_WITH_TESTS:BOOL¶ Build HPX batch_environments module tests. (default: ON)
-
HPX_CACHE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_CACHE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_CACHE_WITH_TESTS:BOOL¶ Build HPX cache module tests. (default: ON)
-
HPX_CHECKPOINT_BASE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: OFF)
-
HPX_CHECKPOINT_BASE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_CHECKPOINT_BASE_WITH_TESTS:BOOL¶ Build HPX checkpoint_base module tests. (default: ON)
-
HPX_CHECKPOINT_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_CHECKPOINT_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_CHECKPOINT_WITH_TESTS:BOOL¶ Build HPX checkpoint module tests. (default: ON)
-
HPX_COLLECTIVES_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_COLLECTIVES_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_COLLECTIVES_WITH_TESTS:BOOL¶ Build HPX collectives module tests. (default: ON)
-
HPX_COMMAND_LINE_HANDLING_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_COMMAND_LINE_HANDLING_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_COMMAND_LINE_HANDLING_WITH_TESTS:BOOL¶ Build HPX command_line_handling module tests. (default: ON)
-
HPX_COMPONENTS_BASE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_COMPONENTS_BASE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_COMPONENTS_BASE_WITH_TESTS:BOOL¶ Build HPX components_base module tests. (default: ON)
-
HPX_COMPUTE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_COMPUTE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_COMPUTE_WITH_TESTS:BOOL¶ Build HPX compute module tests. (default: ON)
-
HPX_CONCEPTS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_CONCEPTS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_CONCEPTS_WITH_TESTS:BOOL¶ Build HPX concepts module tests. (default: ON)
-
HPX_CONCURRENCY_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_CONCURRENCY_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_CONCURRENCY_WITH_TESTS:BOOL¶ Build HPX concurrency module tests. (default: ON)
-
HPX_CONFIG_REGISTRY_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_CONFIG_REGISTRY_WITH_TESTS:BOOL¶ Build HPX config_registry module tests. (default: ON)
-
HPX_CONFIG_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: OFF)
-
HPX_CONFIG_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_CONFIG_WITH_TESTS:BOOL¶ Build HPX config module tests. (default: ON)
-
HPX_COROUTINES_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_COROUTINES_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_COROUTINES_WITH_TESTS:BOOL¶ Build HPX coroutines module tests. (default: ON)
-
HPX_DATASTRUCTURES_WITH_ADAPT_STD_TUPLE:BOOL¶ Enable compatibility of hpx::util::tuple with std::tuple. (default: ON)
-
HPX_DATASTRUCTURES_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_DATASTRUCTURES_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_DATASTRUCTURES_WITH_TESTS:BOOL¶ Build HPX datastructures module tests. (default: ON)
-
HPX_DEBUGGING_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_DEBUGGING_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_DEBUGGING_WITH_TESTS:BOOL¶ Build HPX debugging module tests. (default: ON)
-
HPX_ERRORS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ERRORS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ERRORS_WITH_TESTS:BOOL¶ Build HPX errors module tests. (default: ON)
-
HPX_EXECUTION_BASE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_EXECUTION_BASE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_EXECUTION_BASE_WITH_TESTS:BOOL¶ Build HPX execution_base module tests. (default: ON)
-
HPX_EXECUTION_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_EXECUTION_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_EXECUTION_WITH_TESTS:BOOL¶ Build HPX execution module tests. (default: ON)
-
HPX_EXECUTORS_DISTRIBUTED_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_EXECUTORS_DISTRIBUTED_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_EXECUTORS_DISTRIBUTED_WITH_TESTS:BOOL¶ Build HPX executors_distributed module tests. (default: ON)
-
HPX_EXECUTORS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_EXECUTORS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_EXECUTORS_WITH_TESTS:BOOL¶ Build HPX executors module tests. (default: ON)
-
HPX_FILESYSTEM_WITH_BOOST_FILESYSTEM_COMPATIBILITY:BOOL¶ Enable Boost.FileSystem compatibility. (default: ON)
-
HPX_FILESYSTEM_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_FILESYSTEM_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_FILESYSTEM_WITH_TESTS:BOOL¶ Build HPX filesystem module tests. (default: ON)
-
HPX_FORMAT_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_FORMAT_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_FORMAT_WITH_TESTS:BOOL¶ Build HPX format module tests. (default: ON)
-
HPX_FUNCTIONAL_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_FUNCTIONAL_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_FUNCTIONAL_WITH_TESTS:BOOL¶ Build HPX functional module tests. (default: ON)
-
HPX_FUTURES_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_FUTURES_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_FUTURES_WITH_TESTS:BOOL¶ Build HPX futures module tests. (default: ON)
-
HPX_HARDWARE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_HARDWARE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_HARDWARE_WITH_TESTS:BOOL¶ Build HPX hardware module tests. (default: ON)
-
HPX_HASHING_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_HASHING_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_HASHING_WITH_TESTS:BOOL¶ Build HPX hashing module tests. (default: ON)
-
HPX_INCLUDE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_INCLUDE_WITH_TESTS:BOOL¶ Build HPX include module tests. (default: ON)
-
HPX_INIT_RUNTIME_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_INIT_RUNTIME_WITH_TESTS:BOOL¶ Build HPX init_runtime module tests. (default: ON)
-
HPX_IO_SERVICE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_IO_SERVICE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_IO_SERVICE_WITH_TESTS:BOOL¶ Build HPX io_service module tests. (default: ON)
-
HPX_ITERATOR_SUPPORT_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ITERATOR_SUPPORT_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ITERATOR_SUPPORT_WITH_TESTS:BOOL¶ Build HPX iterator_support module tests. (default: ON)
-
HPX_ITT_NOTIFY_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_ITT_NOTIFY_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_ITT_NOTIFY_WITH_TESTS:BOOL¶ Build HPX itt_notify module tests. (default: ON)
-
HPX_LCOS_DISTRIBUTED_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_LCOS_DISTRIBUTED_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_LCOS_DISTRIBUTED_WITH_TESTS:BOOL¶ Build HPX lcos_distributed module tests. (default: ON)
-
HPX_LCOS_LOCAL_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_LCOS_LOCAL_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_LCOS_LOCAL_WITH_TESTS:BOOL¶ Build HPX lcos_local module tests. (default: ON)
-
HPX_LOGGING_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_LOGGING_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_LOGGING_WITH_TESTS:BOOL¶ Build HPX logging module tests. (default: ON)
-
HPX_MEMORY_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_MEMORY_WITH_TESTS:BOOL¶ Build HPX memory module tests. (default: ON)
-
HPX_NAMING_BASE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: OFF)
-
HPX_NAMING_BASE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_NAMING_BASE_WITH_TESTS:BOOL¶ Build HPX naming_base module tests. (default: ON)
-
HPX_PACK_TRAVERSAL_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_PACK_TRAVERSAL_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_PACK_TRAVERSAL_WITH_TESTS:BOOL¶ Build HPX pack_traversal module tests. (default: ON)
-
HPX_PERFORMANCE_COUNTERS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_PERFORMANCE_COUNTERS_WITH_TESTS:BOOL¶ Build HPX performance_counters module tests. (default: ON)
-
HPX_PLUGIN_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_PLUGIN_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_PLUGIN_WITH_TESTS:BOOL¶ Build HPX plugin module tests. (default: ON)
-
HPX_PREFIX_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_PREFIX_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_PREFIX_WITH_TESTS:BOOL¶ Build HPX prefix module tests. (default: ON)
-
HPX_PREPROCESSOR_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_PREPROCESSOR_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_PREPROCESSOR_WITH_TESTS:BOOL¶ Build HPX preprocessor module tests. (default: ON)
-
HPX_PROGRAM_OPTIONS_WITH_BOOST_PROGRAM_OPTIONS_COMPATIBILITY:BOOL¶ Enable Boost.ProgramOptions compatibility. (default: ON)
-
HPX_PROGRAM_OPTIONS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_PROGRAM_OPTIONS_WITH_TESTS:BOOL¶ Build HPX program_options module tests. (default: ON)
-
HPX_RESILIENCY_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_RESILIENCY_WITH_TESTS:BOOL¶ Build HPX resiliency module tests. (default: ON)
-
HPX_RESOURCE_PARTITIONER_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_RESOURCE_PARTITIONER_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_RESOURCE_PARTITIONER_WITH_TESTS:BOOL¶ Build HPX resource_partitioner module tests. (default: ON)
-
HPX_RUNTIME_CONFIGURATION_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_RUNTIME_CONFIGURATION_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_RUNTIME_CONFIGURATION_WITH_TESTS:BOOL¶ Build HPX runtime_configuration module tests. (default: ON)
-
HPX_RUNTIME_LOCAL_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_RUNTIME_LOCAL_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_RUNTIME_LOCAL_WITH_TESTS:BOOL¶ Build HPX runtime_local module tests. (default: ON)
-
HPX_SCHEDULERS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_SCHEDULERS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_SCHEDULERS_WITH_TESTS:BOOL¶ Build HPX schedulers module tests. (default: ON)
-
HPX_SEGMENTED_ALGORITHMS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_SEGMENTED_ALGORITHMS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_SEGMENTED_ALGORITHMS_WITH_TESTS:BOOL¶ Build HPX segmented_algorithms module tests. (default: ON)
-
HPX_SERIALIZATION_WITH_BOOST_TYPES:BOOL¶ Enable serialization of certain Boost types. (default: ON)
-
HPX_SERIALIZATION_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_SERIALIZATION_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_SERIALIZATION_WITH_TESTS:BOOL¶ Build HPX serialization module tests. (default: ON)
-
HPX_STATIC_REINIT_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_STATIC_REINIT_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_STATIC_REINIT_WITH_TESTS:BOOL¶ Build HPX static_reinit module tests. (default: ON)
-
HPX_STATISTICS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_STATISTICS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_STATISTICS_WITH_TESTS:BOOL¶ Build HPX statistics module tests. (default: ON)
-
HPX_STRING_UTIL_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_STRING_UTIL_WITH_TESTS:BOOL¶ Build HPX string_util module tests. (default: ON)
-
HPX_SYNCHRONIZATION_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_SYNCHRONIZATION_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_SYNCHRONIZATION_WITH_TESTS:BOOL¶ Build HPX synchronization module tests. (default: ON)
-
HPX_TESTING_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_TESTING_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_TESTING_WITH_TESTS:BOOL¶ Build HPX testing module tests. (default: ON)
-
HPX_THREADING_BASE_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_THREADING_BASE_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_THREADING_BASE_WITH_TESTS:BOOL¶ Build HPX threading_base module tests. (default: ON)
-
HPX_THREADING_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_THREADING_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_THREADING_WITH_TESTS:BOOL¶ Build HPX threading module tests. (default: ON)
-
HPX_THREADMANAGER_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_THREADMANAGER_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_THREADMANAGER_WITH_TESTS:BOOL¶ Build HPX threadmanager module tests. (default: ON)
-
HPX_THREAD_EXECUTORS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_THREAD_EXECUTORS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_THREAD_EXECUTORS_WITH_TESTS:BOOL¶ Build HPX thread_executors module tests. (default: ON)
-
HPX_THREAD_POOLS_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_THREAD_POOLS_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_THREAD_POOLS_WITH_TESTS:BOOL¶ Build HPX thread_pools module tests. (default: ON)
-
HPX_THREAD_SUPPORT_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_THREAD_SUPPORT_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_THREAD_SUPPORT_WITH_TESTS:BOOL¶ Build HPX thread_support module tests. (default: ON)
-
HPX_TIMED_EXECUTION_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_TIMED_EXECUTION_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_TIMED_EXECUTION_WITH_TESTS:BOOL¶ Build HPX timed_execution module tests. (default: ON)
-
HPX_TIMING_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_TIMING_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_TIMING_WITH_TESTS:BOOL¶ Build HPX timing module tests. (default: ON)
-
HPX_TOPOLOGY_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_TOPOLOGY_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_TOPOLOGY_WITH_TESTS:BOOL¶ Build HPX topology module tests. (default: ON)
-
HPX_TYPE_SUPPORT_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_TYPE_SUPPORT_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_TYPE_SUPPORT_WITH_TESTS:BOOL¶ Build HPX type_support module tests. (default: ON)
-
HPX_UTIL_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: ON)
-
HPX_UTIL_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_UTIL_WITH_TESTS:BOOL¶ Build HPX util module tests. (default: ON)
-
HPX_VERSION_WITH_COMPATIBILITY_HEADERS:BOOL¶ Enable compatibility headers for old headers. (default: OFF)
-
HPX_VERSION_WITH_DEPRECATION_WARNINGS:BOOL¶ Enable warnings for deprecated facilities. (default: On)
-
HPX_VERSION_WITH_TESTS:BOOL¶ Build HPX version module tests. (default: ON)
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.
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" << hpx::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 "hello_world_component.hpp"
#include <hpx/iostream.hpp>
#include <iostream>
namespace examples { namespace server
{
void hello_world::invoke()
{
hpx::cout << "Hello HPX World!" << std::endl;
}
}}
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);
hello_world_component.hpp
#pragma once
#include <hpx/hpx.hpp>
#include <hpx/include/actions.hpp>
#include <hpx/include/lcos.hpp>
#include <hpx/include/components.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);
};
}}
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::naming::id_type> && f)
: base_type(std::move(f))
{}
hello_world(hpx::naming::id_type && f)
: base_type(std::move(f))
{}
void invoke()
{
hpx::async<server::hello_world::invoke_action>(this->get_id()).get();
}
};
}
hello_world_client.cpp
#include "hello_world_component.hpp"
#include <hpx/hpx_main.hpp>
int main(int argc, char* argv[])
{
{
// 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;
}
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.13 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
ESSENTIAL
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" << hpx::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 "hello_world_component.hpp"
#include <hpx/iostream.hpp>
#include <iostream>
namespace examples { namespace server
{
void hello_world::invoke()
{
hpx::cout << "Hello HPX World!" << std::endl;
}
}}
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);
hello_world_component.hpp
#pragma once
#include <hpx/hpx.hpp>
#include <hpx/include/actions.hpp>
#include <hpx/include/lcos.hpp>
#include <hpx/include/components.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);
};
}}
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::naming::id_type> && f)
: base_type(std::move(f))
{}
hello_world(hpx::naming::id_type && f)
: base_type(std::move(f))
{}
void invoke()
{
hpx::async<server::hello_world::invoke_action>(this->get_id()).get();
}
};
}
hello_world_client.cpp
#include "hello_world_component.hpp"
#include <hpx/hpx_main.hpp>
int main(int argc, char* argv[])
{
{
// 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;
}
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 which 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 to block 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. It however 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 which 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 are disabled which are normally
available on the HPX command line (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 you 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
for instance 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 to block 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 be at least
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
for instance to provide your own entry point function instead of hpx_main.
Please refer to the function documentation for more details (see:
hpx/hpx_start.hpp).
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::apply(&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::apply([]() { 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.
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::apply([]() { 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. 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 call 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 which is
similar to the well-known Windows INI file format. This is a structured text format
allowing 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 equals sign '='. The name appears to the left of the
equals 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 [ and ]. 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 the '#' until the
end of 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 configuration section¶[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
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}
[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 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 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 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 setting control internal values used by the thread scheduling queues in the HPX scheduler. You should not modify these settings except if 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:10}
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 which 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 have which to be available before neighboring cores are allowed to steal work. The default is to allow stealing only if there are more tan 10 tasks available. |
|
The value of this property defines the minimal number 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 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 normally is 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 assumed 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]}
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 of 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 which 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
which 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 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
|
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]}
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]}
Property |
Description |
|
Enable 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 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 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 of 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 which will be
transferrable through the parcel layer. The default is taken from
|
|
This property defines the maximum allowed outbound coalesced message size
which will be transferrable through the parcel layer. 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}
multithreaded = ${HPX_HAVE_PARCELPORT_MPI_MULTITHREADED:0}
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]}
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]}
Property |
Description |
|
Enable 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 (comma separated) 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 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 of 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 which will be
transferrable through the parcel layer. The default is taken from
|
|
This property defines the maximum allowed outbound coalesced message size
which will be transferrable through the parcel layer. 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
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 using';'(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 using';'(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=0which 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 is 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 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 will be responsible to
create new and discard 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¶
In this section we assume to have a simple application component which 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" << hpx::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 which define 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. We create one
instance of the app::server component on the current locality and
invoke the exposed action print_greeting_action 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, here 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
simples way to allow HPX to ‘find’ the component is to provide special ini
configuration files, which 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 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 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 terminalthe command line switch
--hpx:debug-hpx-log=<filename>, which enables logging to a given file<filename>, orsetting 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 to log all available messages. 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 to use 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 environmental 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( |
Direct all output to a file with the given <filename>. |
cout |
Direct all output to the local standard output of the application instance on this locality. |
cerr |
Direct all output to the local standard error output of the application instance on this locality. |
console |
Direct all output to the console instance of the application. The console instance has its logging destinations configured separately. |
android_log |
Direct 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 which initiated the current HPX-thread. The current HPX-thread is generating this logging output. |
hpxparent |
The id of the HPX-thread which 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 which executes the current HPX-thread. |
Note
Not all of the field placeholder may be expanded for all generated logging
output. If no value is available for a particular field it is replaced with a
sequence of '-' characters.]
Here is an example line from a logging output generated by one of the HPX examples (please note that this is generated on a single line, without line break):
(T00000000/0000000002d46f90.01/00000000009ebc10) P--------/0000000002d46f80.02 17:49.37.320 [000000000000004d]
<info> [RT] successfully created component {0000000100ff0001, 0000000000030002} of type: component_barrier[7(3)]
The default settings for the general logging category on the console is shown here:
[hpx.logging.console]
level = ${HPX_LOGLEVEL:$[hpx.logging.level]}
destination = ${HPX_CONSOLE_LOGDESTINATION:file(hpx.$[system.pid].log)}
format = ${HPX_CONSOLE_LOGFORMAT:|}
These settings define how the logging is customized once the logging output is
received by the console instance of an application. The logging level is read
from the environment variable HPX_LOGLEVEL (as set for the console instance
of the application). The level defaults to the same values as the corresponding
settings in the general logging configuration shown before. The destination on
the console instance is set to be a file which name is generated based from its
OS process id. Setting the environment variable HPX_CONSOLE_LOGDESTINATION
allows customization of the naming scheme for the output file. The logging
format is set to leave the original logging output unchanged, as received from
one of the localities the application runs on.
HPX Command Line Options¶
The predefined command line options for any application using
hpx::init are described in the following subsections.
HPX options (allowed on command line only)¶
-
--hpx:help¶ print out program usage (default: this message), possible values:
full(additionally prints options from components)
-
--hpx:version¶ print out HPX version and copyright information
-
--hpx:info¶ print out HPX configuration information
-
--hpx:options-filearg¶ specify a file containing command line options (alternatively: @filepath)
HPX options (additionally allowed in an options file)¶
-
--hpx:worker¶ run this instance in worker mode
-
--hpx:console¶ run this instance in console mode
-
--hpx:connect¶ run this instance in worker mode, but connecting late
-
--hpx:hpxarg¶ the IP address the HPX parcelport is listening on, expected format:
address:port(default:127.0.0.1:7910)
-
--hpx:agasarg¶ the IP address the AGAS root server is running on, expected format:
address:port(default:127.0.0.1:7910)
-
--hpx:nodefilearg¶ the file name of a node file to use (list of nodes, one node name per line and core)
-
--hpx:nodesarg¶ the (space separated) list of the nodes to use (usually this is extracted from a node file)
-
--hpx:endnodes¶ this can be used to end the list of nodes specified using the option
--hpx:nodes
-
--hpx:ifsuffixarg¶ suffix to append to host names in order to resolve them to the proper network interconnect
-
--hpx:ifprefixarg¶ prefix to prepend to host names in order to resolve them to the proper network interconnect
-
--hpx:iftransformarg¶ sed-style search and replace (
s/search/replace/) used to transform host names to the proper network interconnect
-
--hpx:localitiesarg¶ the number of localities to wait for at application startup (default:
1)
-
--hpx:ignore-batch-env¶ ignore batch environment variables
-
--hpx:expect-connecting-localities¶ this locality expects other localities to dynamically connect (this is implied if the number of initial localities is larger than 1)
-
--hpx:pu-offset¶ the first processing unit this instance of HPX should be run on (default:
0)
-
--hpx:pu-step¶ the step between used processing unit numbers for this instance of HPX (default:
1)
-
--hpx:threadsarg¶ the number of operating system threads to spawn for this HPX locality. Possible values are: numeric values
1,2,3and so on,all(which spawns one thread per processing unit, includes hyperthreads), orcores(which spawns one thread per core) (default:cores).
-
--hpx:coresarg¶ the number of cores to utilize for this HPX locality (default:
all, i.e. the number of cores is based on the number of threads--hpx:threadsassuming--hpx:bind=compact
-
--hpx:affinityarg¶ the affinity domain the OS threads will be confined to, possible values:
pu,core,numa,machine(default:pu)
-
--hpx:bindarg¶ the detailed affinity description for the OS threads, see More details about HPX command line options for a detailed description of possible values. Do not use with
--hpx:pu-step,--hpx:pu-offsetor--hpx:affinityoptions. Implies--hpx:numa-sensitive(--hpx:bind=none) disables defining thread affinities).
-
--hpx:use-process-mask¶ use the process mask to restrict available hardware resources (implies
--hpx:ignore-batch-env)
-
--hpx:print-bind¶ print to the console the bit masks calculated from the arguments specified to all
--hpx:bindoptions.
-
--hpx:queuingarg¶ the queue scheduling policy to use, options are
local,local-priority-fifo,local-priority-lifo,static,static-priority,abp-priority-fifoandabp-priority-lifo(default:local-priority-fifo)
-
--hpx:high-priority-threadsarg¶ the number of operating system threads maintaining a high priority queue (default: number of OS threads), valid for
--hpx:queuing=abp-priority,--hpx:queuing=static-priorityand--hpx:queuing=local-priorityonly
-
--hpx:numa-sensitive¶ makes the scheduler NUMA sensitive
HPX configuration options¶
-
--hpx:app-configarg¶ load the specified application configuration (ini) file
-
--hpx:configarg¶ load the specified hpx configuration (ini) file
-
--hpx:iniarg¶ add a configuration definition to the default runtime configuration
-
--hpx:exit¶ exit after configuring the runtime
HPX debugging options¶
-
--hpx:list-symbolic-names¶ list all registered symbolic names after startup
-
--hpx:list-component-types¶ list all dynamic component types after startup
-
--hpx:dump-config-initial¶ print the initial runtime configuration
-
--hpx:dump-config¶ print the final runtime configuration
-
--hpx:debug-hpx-log[arg]¶ enable all messages on the HPX log channel and send all HPX logs to the target destination (default:
cout)
-
--hpx:debug-agas-log[arg]¶ enable all messages on the AGAS log channel and send all AGAS logs to the target destination (default:
cout)
-
--hpx:debug-parcel-log[arg]¶ enable all messages on the parcel transport log channel and send all parcel transport logs to the target destination (default:
cout)
-
--hpx:debug-timing-log[arg]¶ enable all messages on the timing log channel and send all timing logs to the target destination (default:
cout)
-
--hpx:debug-app-log[arg]¶ enable all messages on the application log channel and send all application logs to the target destination (default:
cout)
-
--hpx:debug-clp¶ debug command line processing
-
--hpx:attach-debuggerarg¶ wait for a debugger to be attached, possible arg values:
startuporexception(default:startup)
Command line argument shortcuts¶
Additionally, the following shortcuts are available from every HPX application.
Shortcut option |
Equivalent long option |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It is possible to define your own shortcut options. In fact, all of the shortcuts listed above are pre-defined using the technique described here. Also, it is possible to redefine any of the pre-defined shortcuts to expand differently as well.
Shortcut options are obtained from the internal configuration database. They are
stored as key-value properties in a special properties section named
hpx.commandline. You can define your own shortcuts by adding the
corresponding definitions to one of the ini configuration files as described
in the section Configuring HPX applications. For instance, in order to define a command
line shortcut --p which should expand to -hpx:print-counter, the
following configuration information needs to be added to one of the ini
configuration files:
[hpx.commandline.aliases]
--pc = --hpx:print-counter
Note
Any arguments for shortcut options passed on the command line are retained and passed as arguments to the corresponding expanded option. For instance, given the definition above, the command line option:
--pc=/threads{locality#0/total}/count/cumulative
would be expanded to:
--hpx:print-counter=/threads{locality#0/total}/count/cumulative
Important
Any shortcut option should either start with a single '-' or with two
'--' characters. Shortcuts starting with a single '-' are interpreted
as short options (i.e. everything after the first character following the
'-' is treated as the argument). Shortcuts starting with '--' are
interpreted as long options. No other shortcut formats are supported.
Specifying options for single localities only¶
For runs involving more than one locality it is sometimes desirable to
supply specific command line options to single localities only. When the HPX
application is launched using a scheduler (like PBS, for more details see
section How to use HPX applications with PBS), specifying dedicated command line options for single
localities may be desirable. For this reason all of the command line options
which have the general format --hpx:<some_key> can be used in a more general
form: --hpx:<N>:<some_key>, where <N> is the number of the locality
this command line options will be applied to, all other localities will simply
ignore the option. For instance, the following PBS script passes the option
--hpx:pu-offset=4 to the locality '1' only.
#!/bin/bash
#
#PBS -l nodes=2:ppn=4
APP_PATH=~/packages/hpx/bin/hello_world_distributed
APP_OPTIONS=
pbsdsh -u $APP_PATH $APP_OPTIONS --hpx:1:pu-offset=4 --hpx:nodes=`cat $PBS_NODEFILE`
Caution
If the first application specific argument (inside $APP_OPTIONS is a
non-option (i.e. does not start with a - or a --, then it must be
placed before the option --hpx:nodes, which, in this case,
should be the last option on the command line.
Alternatively, use the option --hpx:endnodes to explicitly
mark the end of the list of node names:
pbsdsh -u $APP_PATH --hpx:1:pu-offset=4 --hpx:nodes=`cat $PBS_NODEFILE` --hpx:endnodes $APP_OPTIONS
More details about HPX command line options¶
This section documents the following list of the command line options in more detail:
--hpx:bind¶This command line option allows one to specify the required affinity of the
HPX worker threads to the underlying processing units. As a result the worker
threads will run only on the processing units identified by the corresponding
bind specification. The affinity settings are to be specified using
--hpx:bind=<BINDINGS>, where <BINDINGS> have to be formatted as
described below.
In addition to the syntax described below one can use --hpx:bind=none to disable all binding of any threads to a particular core. This is
mostly supported for debugging purposes.
The specified affinities refer to specific regions within a machine hardware topology. In order to understand the hardware topology of a particular machine it may be useful to run the lstopo tool which is part of Portable Hardware Locality (HWLOC) to see the reported topology tree. Seeing and understanding a topology tree will definitely help in understanding the concepts that are discussed below.
Affinities can be specified using HWLOC (Portable Hardware Locality (HWLOC)) tuples. Tuples of HWLOC
objects and associated indexes can be specified in the form
object:index, object:index-index or object:index,...,index. HWLOC
objects represent types of mapped items in a topology tree. Possible values for
objects are socket, numanode, core and pu (processing unit).
Indexes are non-negative integers that specify a unique physical object in a
topology tree using its logical sequence number.
Chaining multiple tuples together in the more general form
object1:index1[.object2:index2[...]] is permissible. While the first tuple’s
object may appear anywhere in the topology, the Nth tuple’s object must have a
shallower topology depth than the (N+1)th tuple’s object. Put simply: as you
move right in a tuple chain, objects must go deeper in the topology tree.
Indexes specified in chained tuples are relative to the scope of the parent
object. For example, socket:0.core:1 refers to the second core in the first
socket (all indices are zero based).
Multiple affinities can be specified using several --hpx:bind command
line options or by appending several affinities separated by a ';' By
default, if multiple affinities are specified, they are added.
"all" is a special affinity consisting in the entire current topology.
Note
All ‘names’ in an affinity specification, such as thread, socket,
numanode, pu or all can be abbreviated. Thus the affinity
specification threads:0-3=socket:0.core:1.pu:1 is fully equivalent to its
shortened form t:0-3=s:0.c:1.p:1.
Here is a full grammar describing the possible format of mappings:
mappings ::=distribution|mapping(";"mapping)* distribution ::= "compact" | "scatter" | "balanced" | "numa-balanced" mapping ::=thread_spec"="pu_specsthread_spec ::= "thread:"range_specspu_specs ::=pu_spec("."pu_spec)* pu_spec ::=type":"range_specs| "~"pu_specrange_specs ::=range_spec(","range_spec)* range_spec ::= int | int "-" int | "all" type ::= "socket" | "numanode" | "core" | "pu"
The following example assumes a system with at least 4 cores, where each core
has more than 1 processing unit (hardware threads). Running
hello_world_distributed with 4 OS-threads (on 4 processing units), where
each of those threads is bound to the first processing unit of each of the
cores, can be achieved by invoking:
hello_world_distributed -t4 --hpx:bind=thread:0-3=core:0-3.pu:0
Here thread:0-3 specifies the OS threads for which to define affinity
bindings, and core:0-3.pu: defines that for each of the cores (core:0-3)
only their first processing unit pu:0 should be used.
Note
The command line option --hpx:print-bind can be used to print the
bitmasks generated from the affinity mappings as specified with
--hpx:bind. For instance, on a system with hyperthreading enabled
(i.e. 2 processing units per core), the command line:
hello_world_distributed -t4 --hpx:bind=thread:0-3=core:0-3.pu:0 --hpx:print-bind
will cause this output to be printed:
0: PU L#0(P#0), Core L#0, Socket L#0, Node L#0(P#0)
1: PU L#2(P#2), Core L#1, Socket L#0, Node L#0(P#0)
2: PU L#4(P#4), Core L#2, Socket L#0, Node L#0(P#0)
3: PU L#6(P#6), Core L#3, Socket L#0, Node L#0(P#0)
where each bit in the bitmasks corresponds to a processing unit the listed worker thread will be bound to run on.
The difference between the four possible predefined distribution schemes
(compact, scatter, balanced and numa-balanced) is best explained
with an example. Imagine that we have a system with 4 cores and 4 hardware
threads per core on 2 sockets. If we place 8 threads the assignments produced by
the compact, scatter, balanced and numa-balanced types are shown
in the figure below. Notice that compact does not fully utilize all the
cores in the system. For this reason it is recommended that applications are run
using the scatter or balanced/numa-balanced options in most cases.
Fig. 7 Schematic of thread affinity type distributions.¶
In addition to the predefined distributions it is possible to restrict the
resources used by HPX to the process CPU mask. The CPU mask is typically set
by e.g. MPI and batch environments. Using the command line option
--hpx:use-process-mask makes HPX act as if only the processing units
in the CPU mask are available for use by HPX. The number of threads is
automatically determined from the CPU mask. The number of threads can still be
changed manually using this option, but only to a number less than or equal to
the number of processing units in the CPU mask. The option
--hpx:print-bind is useful in conjunction with
--hpx:use-process-mask to make sure threads are placed as expected.
- 1
The phase of a HPX-thread counts how often this thread has been activated.
Writing single-node HPX applications¶
HPX is a C++ Standard Library for Concurrency and Parallelism. This means that it implements all of the corresponding facilities as defined by the C++ Standard. Additionally, HPX implements functionalities proposed as part of the ongoing C++ standardization process. This section focuses on the features available in HPX for parallel and concurrent computation on a single node, although many of the features presented here are also implemented to work in the distributed case.
Using LCOs¶
Lightweight Control Objects (LCOs) provide synchronization for HPX applications. Most of them are familiar from other frameworks, but a few of them work in slightly different ways adapted to HPX. The following synchronization objects are available in HPX:
futurequeueobject_semaphorebarrier
Channels¶
Channels combine communication (the exchange of a value) with synchronization (guaranteeing that two calculations (tasks) are in a known state). A channel can transport any number of values of a given type from a sender to a receiver:
hpx::lcos::local::channel<int> c;
hpx::future<int> f = c.get();
HPX_ASSERT(!f.is_ready());
c.set(42);
HPX_ASSERT(f.is_ready());
hpx::cout << f.get() << hpx::endl;
Channels can be handed to another thread (or in case of channel components, to other localities), thus establishing a communication channel between two independent places in the program:
void do_something(hpx::lcos::local::receive_channel<int> c,
hpx::lcos::local::send_channel<> done)
{
// prints 43
hpx::cout << c.get(hpx::launch::sync) << hpx::endl;
// signal back
done.set();
}
void send_receive_channel()
{
hpx::lcos::local::channel<int> c;
hpx::lcos::local::channel<> done;
hpx::apply(&do_something, c, done);
// send some value
c.set(43);
// wait for thread to be done
done.get().wait();
}
Note how hpx::lcos::local::channel::get without any arguments
returns a future which is ready when a value has been set on the channel. The
launch policy hpx::launch::sync can be used to make
hpx::lcos::local::channel::get block until a value is set and
return the value directly.
A channel component is created on one locality and can be sent to another locality using an action. This example also demonstrates how a channel can be used as a range of values:
// channel components need to be registered for each used type (not needed
// for hpx::lcos::local::channel)
HPX_REGISTER_CHANNEL(double);
void channel_sender(hpx::lcos::channel<double> c)
{
for (double d : c)
hpx::cout << d << std::endl;
}
HPX_PLAIN_ACTION(channel_sender);
void channel()
{
// create the channel on this locality
hpx::lcos::channel<double> c(hpx::find_here());
// pass the channel to a (possibly remote invoked) action
hpx::apply(channel_sender_action(), hpx::find_here(), c);
// send some values to the receiver
std::vector<double> v = {1.2, 3.4, 5.0};
for (double d : v)
c.set(d);
// explicitly close the communication channel (implicit at destruction)
c.close();
}
Composable guards¶
Composable guards operate in a manner similar to locks, but are applied only to asynchronous functions. The guard (or guards) is automatically locked at the beginning of a specified task and automatically unlocked at the end. Because guards are never added to an existing task’s execution context, the calling of guards is freely composable and can never deadlock.
To call an application with a single guard, simply declare the guard and call run_guarded() with a function (task):
hpx::lcos::local::guard gu;
run_guarded(gu,task);
If a single method needs to run with multiple guards, use a guard set:
boost::shared<hpx::lcos::local::guard> gu1(new hpx::lcos::local::guard());
boost::shared<hpx::lcos::local::guard> gu2(new hpx::lcos::local::guard());
gs.add(*gu1);
gs.add(*gu2);
run_guarded(gs,task);
Guards use two atomic operations (which are not called repeatedly) to manage what they do, so overhead should be extremely low. The following guards are available in HPX:
conditional_triggercounting_semaphoredatafloweventmutexoncerecursive_mutexspinlockspinlock_no_backofftrigger
Extended facilities for futures¶
Concurrency is about both decomposing and composing the program from the parts that work well individually and together. It is in the composition of connected and multicore components where today’s C++ libraries are still lacking.
The functionality of std::future offers a partial solution. It allows for
the separation of the initiation of an operation and the act of waiting for its
result; however, the act of waiting is synchronous. In communication-intensive
code this act of waiting can be unpredictable, inefficient and simply
frustrating. The example below illustrates a possible synchronous wait using
futures:
#include <future>
using namespace std;
int main()
{
future<int> f = async([]() { return 123; });
int result = f.get(); // might block
}
For this reason, HPX implements a set of extensions to std::future (as
proposed by __cpp11_n4107__). This proposal introduces the following key
asynchronous operations to hpx::future, hpx::shared_future and
hpx::async, which enhance and enrich these facilities.
Facility |
Description |
|
In asynchronous programming, it is very common for one asynchronous
operation, on completion, to invoke a second operation and pass data to
it. The current C++ standard does not allow one to register a
continuation to a future. With |
unwrapping constructor for |
In some scenarios, you might want to create a future that returns another future, resulting in nested futures. Although it is possible to write code to unwrap the outer future and retrieve the nested future and its result, such code is not easy to write because users must handle exceptions and it may cause a blocking call. Unwrapping can allow users to mitigate this problem by doing an asynchronous call to unwrap the outermost future. |
|
There are often situations where a |
|
Some functions may know the value at the point of construction. In these
cases the value is immediately available, but needs to be returned as a
future. By using |
The standard also omits the ability to compose multiple futures. This is a common pattern that is ubiquitous in other asynchronous frameworks and is absolutely necessary in order to make C++ a powerful asynchronous programming language. Not including these functions is synonymous to Boolean algebra without AND/OR.
In addition to the extensions proposed by N4313, HPX adds functions allowing users to compose several futures in a more flexible way.
Facility |
Description |
Comment |
Asynchronously wait for at least one of multiple future or shared_future objects to finish. |
N4313, |
|
Synchronously wait for at least one of multiple future or shared_future objects to finish. |
HPX only |
|
Asynchronously wait for all future and shared_future objects to finish. |
N4313, |
|
Synchronously wait for all future and shared_future objects to finish. |
HPX only |
|
Asynchronously wait for multiple future and shared_future objects to finish. |
HPX only |
|
Synchronously wait for multiple future and shared_future objects to finish. |
HPX only |
|
Asynchronously wait for multiple future and shared_future objects to finish and call a function for each of the future objects as soon as it becomes ready. |
HPX only |
|
Synchronously wait for multiple future and shared_future objects to finish and call a function for each of the future objects as soon as it becomes ready. |
HPX only |
High level parallel facilities¶
In preparation for the upcoming C++ Standards, there are currently several proposals targeting different facilities supporting parallel programming. HPX implements (and extends) some of those proposals. This is well aligned with our strategy to align the APIs exposed from HPX with current and future C++ Standards.
At this point, HPX implements several of the C++ Standardization working papers, most notably N4409 (Working Draft, Technical Specification for C++ Extensions for Parallelism), N4411 (Task Blocks), and N4406 (Parallel Algorithms Need Executors).
Using parallel algorithms¶
A parallel algorithm is a function template described by this document
which is declared in the (inline) namespace hpx::parallel::v1.
Note
For compilers that do not support inline namespaces, all of the namespace
v1 is imported into the namespace hpx::parallel. The effect is similar
to what inline namespaces would do, namely all names defined in
hpx::parallel::v1 are accessible from the namespace hpx::parallel as
well.
All parallel algorithms are very similar in semantics to their sequential
counterparts (as defined in the namespace std) with an additional formal
template parameter named ExecutionPolicy. The execution policy is generally
passed as the first argument to any of the parallel algorithms and describes the
manner in which the execution of these algorithms may be parallelized and the
manner in which they apply user-provided function objects.
The applications of function objects in parallel algorithms invoked with an
execution policy object of type hpx::parallel::execution::sequenced_policy or
hpx::parallel::execution::sequenced_task_policy execute in sequential order. For
hpx::parallel::execution::sequenced_policy the execution happens in the calling thread.
The applications of function objects in parallel algorithms invoked with an
execution policy object of type hpx::parallel::execution::parallel_policy or
hpx::parallel::execution::parallel_task_policy are permitted to execute in an unordered
fashion in unspecified threads, and are indeterminately sequenced within each
thread.
Important
It is the caller’s responsibility to ensure correctness, such as making sure that the invocation does not introduce data races or deadlocks.
The applications of function objects in parallel algorithms invoked with an
execution policy of type hpx::parallel::execution::parallel_unsequenced_policy is, in HPX,
equivalent to the use of the execution policy hpx::parallel::execution::parallel_policy.
Algorithms invoked with an execution policy object of type hpx::parallel::v1::execution_policy
execute internally as if invoked with the contained execution policy object. No
exception is thrown when an hpx::parallel::v1::execution_policy contains an execution policy of
type hpx::parallel::execution::sequenced_task_policy or hpx::parallel::execution::parallel_task_policy
(which normally turn the algorithm into its asynchronous version). In this case
the execution is semantically equivalent to the case of passing a
hpx::parallel::execution::sequenced_policy or hpx::parallel::execution::parallel_policy contained in the
hpx::parallel::v1::execution_policy object respectively.
Parallel exceptions¶
During the execution of a standard parallel algorithm, if temporary memory
resources are required by any of the algorithms and no memory is available, the
algorithm throws a std::bad_alloc exception.
During the execution of any of the parallel algorithms, if the application of a function object terminates with an uncaught exception, the behavior of the program is determined by the type of execution policy used to invoke the algorithm:
If the execution policy object is of type
hpx::parallel::execution::parallel_unsequenced_policy,hpx::terminateshall be called.If the execution policy object is of type
hpx::parallel::execution::sequenced_policy,hpx::parallel::execution::sequenced_task_policy,hpx::parallel::execution::parallel_policy, orhpx::parallel::execution::parallel_task_policy, the execution of the algorithm terminates with anhpx::exception_listexception. All uncaught exceptions thrown during the application of user-provided function objects shall be contained in thehpx::exception_list.
For example, the number of invocations of the user-provided function object in
for_each is unspecified. When hpx::parallel::v1::for_each is executed sequentially, only one
exception will be contained in the hpx::exception_list object.
These guarantees imply that, unless the algorithm has failed to allocate memory
and terminated with std::bad_alloc, all exceptions thrown during the
execution of the algorithm are communicated to the caller. It is unspecified
whether an algorithm implementation will “forge ahead” after encountering and
capturing a user exception.
The algorithm may terminate with the std::bad_alloc exception even if one or
more user-provided function objects have terminated with an exception. For
example, this can happen when an algorithm fails to allocate memory while
creating or adding elements to the hpx::exception_list object.
Parallel algorithms¶
HPX provides implementations of the following parallel algorithms:
Name |
Description |
In header |
Algorithm page at cppreference.com |
Computes the differences between adjacent elements in a range. |
|
||
Checks if a predicate is |
|
||
Checks if a predicate is |
|
||
Returns the number of elements equal to a given value. |
|
||
Returns the number of elements satisfying a specific criteria. |
|
||
Determines if two sets of elements are the same. |
|
||
Finds the first element equal to a given value. |
|
||
Finds the last sequence of elements in a certain range. |
|
||
Searches for any one of a set of elements. |
|
||
Finds the first element satisfying a specific criteria. |
|
||
Finds the first element not satisfying a specific criteria. |
|
||
Applies a function to a range of elements. |
|
||
Applies a function to a number of elements. |
|
||
Checks if a range of values is lexicographically less than another range of values. |
|
||
|
Finds the first position where two ranges differ. |
|
|
Checks if a predicate is |
|
||
Searches for a range of elements. |
|
||
Searches for a number consecutive copies of an element in a range. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Copies a range of elements to a new location. |
|
||
Copies a number of elements to a new location. |
|
||
Copies the elements from a range to a new location for which the given predicate is |
|
||
Moves a range of elements to a new location. |
|
||
Assigns a range of elements a certain value. |
|
||
Assigns a value to a number of elements. |
|
||
Saves the result of a function in a range. |
|
||
Saves the result of N applications of a function. |
|
||
Removes the elements from a range that are equal to the given value. |
|
||
Removes the elements from a range that are equal to the given predicate is |
|
||
Copies the elements from a range to a new location that are not equal to the given value. |
|
||
Copies the elements from a range to a new location for which the given predicate is |
|
||
Replaces all values satisfying specific criteria with another value. |
|
||
Replaces all values satisfying specific criteria with another value. |
|
||
Copies a range, replacing elements satisfying specific criteria with another value. |
|
||
Copies a range, replacing elements satisfying specific criteria with another value. |
|
||
Reverses the order elements in a range. |
|
||
Creates a copy of a range that is reversed. |
|
||
Rotates the order of elements in a range. |
|
||
Copies and rotates a range of elements. |
|
||
Swaps two ranges of elements. |
|
||
Applies a function to a range of elements. |
|
||
Eliminates all but the first element from every consecutive group of equivalent elements from a range. |
|
||
Eliminates all but the first element from every consecutive group of equivalent elements from a range. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Merges two sorted ranges. |
|
||
Merges two ordered ranges in-place. |
|
||
Returns true if one set is a subset of another. |
|
||
Computes the difference between two sets. |
|
||
Computes the intersection of two sets. |
|
||
Computes the symmetric difference between two sets. |
|
||
Computes the union of two sets. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Returns |
|
||
Returns the first element that breaks a max heap. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Returns the largest element in a range. |
|
||
Returns the smallest element in a range. |
|
||
Returns the smallest and the largest element in a range. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Returns |
|
||
Divides elements into two groups without preserving their relative order. |
|
||
Copies a range dividing the elements into two groups. |
|
||
Divides elements into two groups while preserving their relative order. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Returns |
|
||
Returns the first unsorted element. |
|
||
Sorts the elements in a range. |
|
||
Sorts the elements in a range, maintain sequence of equal elements. |
|
||
Sorts one range of data using keys supplied in another range. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Calculates the difference between each element in an input range and the preceding element. |
|
||
Does an exclusive parallel scan over a range of elements. |
|
||
Sums up a range of elements. |
|
||
Does an inclusive parallel scan over a range of elements. |
|
||
Performs an inclusive scan on consecutive elements with matching keys,
with a reduction to output only the final sum for each key. The key
sequence |
|
||
Sums up a range of elements after applying a function. Also, accumulates the inner products of two input ranges. |
|
||
Does an inclusive parallel scan over a range of elements after applying a function. |
|
||
Does an exclusive parallel scan over a range of elements after applying a function. |
|
Name |
Description |
In header |
Algorithm page at cppreference.com |
Destroys a range of objects. |
|
||
Destroys a range of objects. |
|
||
Copies a range of objects to an uninitialized area of memory. |
|
||
Copies a number of objects to an uninitialized area of memory. |
|
||
Copies a range of objects to an uninitialized area of memory. |
|
||
Copies a number of objects to an uninitialized area of memory. |
|
||
Copies an object to an uninitialized area of memory. |
|
||
Copies an object to an uninitialized area of memory. |
|
||
Moves a range of objects to an uninitialized area of memory. |
|
||
Moves a number of objects to an uninitialized area of memory. |
|
||
Constructs objects in an uninitialized area of memory. |
|
||
Constructs objects in an uninitialized area of memory. |
|
Name |
Description |
In header |
Implements loop functionality over a range specified by integral or iterator bounds. |
|
|
Implements loop functionality over a range specified by integral or iterator bounds. |
|
|
Implements loop functionality over a range specified by integral or iterator bounds. |
|
|
Implements loop functionality over a range specified by integral or iterator bounds. |
|
Executor parameters and executor parameter traits¶
HPX introduces the notion of execution parameters and execution parameter traits. At this point, the only parameter that can be customized is the size of the chunks of work executed on a single HPX thread (such as the number of loop iterations combined to run as a single task).
An executor parameter object is responsible for exposing the calculation of the size of the chunks scheduled. It abstracts the (potentially platform-specific) algorithms of determining those chunk sizes.
The way executor parameters are implemented is aligned with the way executors
are implemented. All functionalities of concrete executor parameter types are
exposed and accessible through a corresponding
hpx::parallel::executor_parameter_traits type.
With executor_parameter_traits, clients access all types of executor
parameters uniformly:
std::size_t chunk_size =
executor_parameter_traits<my_parameter_t>::get_chunk_size(my_parameter,
my_executor, [](){ return 0; }, num_tasks);
This call synchronously retrieves the size of a single chunk of loop iterations
(or similar) to combine for execution on a single HPX thread if the overall
number of tasks to schedule is given by num_tasks. The lambda function
exposes a means of test-probing the execution of a single iteration for
performance measurement purposes. The execution parameter type might dynamically
determine the execution time of one or more tasks in order to calculate the
chunk size; see hpx::parallel::execution::auto_chunk_size for an
example of this executor parameter type.
Other functions in the interface exist to discover whether an executor parameter
type should be invoked once (i.e., it returns a static chunk size; see
hpx::parallel::execution::static_chunk_size) or whether it should
be invoked for each scheduled chunk of work (i.e., it returns a variable chunk
size; for an example, see
hpx::parallel::execution::guided_chunk_size).
Although this interface appears to require executor parameter type authors to implement all different basic operations, none are required. In practice, all operations have sensible defaults. However, some executor parameter types will naturally specialize all operations for maximum efficiency.
HPX implements the following executor parameter types:
hpx::parallel::execution::auto_chunk_size: Loop iterations are divided into pieces and then assigned to threads. The number of loop iterations combined is determined based on measurements of how long the execution of 1% of the overall number of iterations takes. This executor parameter type makes sure that as many loop iterations are combined as necessary to run for the amount of time specified.hpx::parallel::execution::static_chunk_size: Loop iterations are divided into pieces of a given size and then assigned to threads. If the size is not specified, the iterations are, if possible, evenly divided contiguously among the threads. This executor parameters type is equivalent to OpenMP’s STATIC scheduling directive.hpx::parallel::execution::dynamic_chunk_size: Loop iterations are divided into pieces of a given size and then dynamically scheduled among the cores; when a core finishes one chunk, it is dynamically assigned another. If the size is not specified, the default chunk size is 1. This executor parameter type is equivalent to OpenMP’s DYNAMIC scheduling directive.hpx::parallel::execution::guided_chunk_size: Iterations are dynamically assigned to cores in blocks as cores request them until no blocks remain to be assigned. This is similar todynamic_chunk_sizeexcept that the block size decreases each time a number of loop iterations is given to a thread. The size of the initial block is proportional tonumber_of_iterations / number_of_cores. Subsequent blocks are proportional tonumber_of_iterations_remaining / number_of_cores. The optional chunk size parameter defines the minimum block size. The default minimal chunk size is 1. This executor parameter type is equivalent to OpenMP’s GUIDED scheduling directive.
Using task blocks¶
The define_task_block, run and the wait functions implemented based
on N4411 are based on the task_block concept that is a part of the
common subset of the Microsoft Parallel Patterns Library (PPL) and the Intel Threading Building Blocks (TBB) libraries.
These implementations adopt a simpler syntax than exposed by those libraries— one that is influenced by language-based concepts, such as spawn and sync from Cilk++ and async and finish from X10. They improve on existing practice in the following ways:
The exception handling model is simplified and more consistent with normal C++ exceptions.
Most violations of strict fork-join parallelism can be enforced at compile time (with compiler assistance, in some cases).
The syntax allows scheduling approaches other than child stealing.
Consider an example of a parallel traversal of a tree, where a user-provided function compute is applied to each node of the tree, returning the sum of the results:
template <typename Func>
int traverse(node& n, Func && compute)
{
int left = 0, right = 0;
define_task_block(
[&](task_block<>& tr) {
if (n.left)
tr.run([&] { left = traverse(*n.left, compute); });
if (n.right)
tr.run([&] { right = traverse(*n.right, compute); });
});
return compute(n) + left + right;
}
The example above demonstrates the use of two of the functions,
hpx::parallel::define_task_block and the
hpx::parallel::task_block::run member function of a
hpx::parallel::task_block.
The task_block function delineates a region in a program code potentially
containing invocations of threads spawned by the run member function of the
task_block class. The run function spawns an HPX thread, a unit of
work that is allowed to execute in parallel with respect to the caller. Any
parallel tasks spawned by run within the task block are joined back to a
single thread of execution at the end of the define_task_block. run
takes a user-provided function object f and starts it asynchronously—i.e.,
it may return before the execution of f completes. The HPX scheduler may
choose to run f immediately or delay running f until compute resources
become available.
A task_block can be constructed only by define_task_block because it has
no public constructors. Thus, run can be invoked directly or indirectly
only from a user-provided function passed to define_task_block:
void g();
void f(task_block<>& tr)
{
tr.run(g); // OK, invoked from within task_block in h
}
void h()
{
define_task_block(f);
}
int main()
{
task_block<> tr; // Error: no public constructor
tr.run(g); // No way to call run outside of a define_task_block
return 0;
}
Extensions for task blocks¶
HPX implements some extensions for task_block beyond the actual
standards proposal N4411. The main addition is that a task_block
can be invoked with an execution policy as its first argument, very similar to
the parallel algorithms.
An execution policy is an object that expresses the requirements on the
ordering of functions invoked as a consequence of the invocation of a
task block. Enabling passing an execution policy to define_task_block
gives the user control over the amount of parallelism employed by the
created task_block. In the following example the use of an explicit
par execution policy makes the user’s intent explicit:
template <typename Func>
int traverse(node *n, Func&& compute)
{
int left = 0, right = 0;
define_task_block(
execution::par, // execution::parallel_policy
[&](task_block<>& tb) {
if (n->left)
tb.run([&] { left = traverse(n->left, compute); });
if (n->right)
tb.run([&] { right = traverse(n->right, compute); });
});
return compute(n) + left + right;
}
This also causes the hpx::parallel::v2::task_block object to be a
template in our implementation. The template argument is the type of the
execution policy used to create the task block. The template argument defaults
to hpx::parallel::execution::parallel_policy.
HPX still supports calling hpx::parallel::v2::define_task_block
without an explicit execution policy. In this case the task block will run using
the hpx::parallel::execution::parallel_policy.
HPX also adds the ability to access the execution policy that was used to
create a given task_block.
Often, users want to be able to not only define an execution policy to use by
default for all spawned tasks inside the task block, but also to
customize the execution context for one of the tasks executed by
task_block::run. Adding an optionally passed executor instance to that
function enables this use case:
template <typename Func>
int traverse(node *n, Func&& compute)
{
int left = 0, right = 0;
define_task_block(
execution::par, // execution::parallel_policy
[&](auto& tb) {
if (n->left)
{
// use explicitly specified executor to run this task
tb.run(my_executor(), [&] { left = traverse(n->left, compute); });
}
if (n->right)
{
// use the executor associated with the par execution policy
tb.run([&] { right = traverse(n->right, compute); });
}
});
return compute(n) + left + right;
}
HPX still supports calling hpx::parallel::v2::task_block::run
without an explicit executor object. In this case the task will be run using the
executor associated with the execution policy that was used to call
hpx::parallel::v2::define_task_block.
Writing distributed HPX applications¶
This section focuses on the features of HPX needed to write distributed applications, namely the Active Global Address Space (AGAS), remotely executable functions (i.e. actions), and distributed objects (i.e. components).
Global names¶
HPX implements an Active Global Address Space (AGAS) which is exposing a single uniform address space spanning all localities an application runs on. AGAS is a fundamental component of the ParalleX execution model. Conceptually, there is no rigid demarcation of local or global memory in AGAS; all available memory is a part of the same address space. AGAS enables named objects to be moved (migrated) across localities without having to change the object’s name, i.e., no references to migrated objects have to be ever updated. This feature has significance for dynamic load balancing and in applications where the workflow is highly dynamic, allowing work to be migrated from heavily loaded nodes to less loaded nodes. In addition, immutability of names ensures that AGAS does not have to keep extra indirections (“bread crumbs”) when objects move, hence minimizing complexity of code management for system developers as well as minimizing overheads in maintaining and managing aliases.
The AGAS implementation in HPX does not automatically expose every local address to the global address space. It is the responsibility of the programmer to explicitly define which of the objects have to be globally visible and which of the objects are purely local.
In HPX global addresses (global names) are represented using the
hpx::id_type data type. This data type is conceptually very similar to
void* pointers as it does not expose any type information of the object it
is referring to.
The only predefined global addresses are assigned to all localities. The following HPX API functions allow one to retrieve the global addresses of localities:
hpx::find_here: retrieve the global address of the locality this function is called on.hpx::find_all_localities: retrieve the global addresses of all localities available to this application (including the locality the function is being called on).hpx::find_remote_localities: retrieve the global addresses of all remote localities available to this application (not including the locality the function is being called on)hpx::get_num_localities: retrieve the number of localities available to this application.hpx::find_locality: retrieve the global address of any locality supporting the given component type.hpx::get_colocation_id: retrieve the global address of the locality currently hosting the object with the given global address.
Additionally, the global addresses of localities can be used to create new instances of components using the following HPX API function:
hpx::components::new_: Create a new instance of the givenComponenttype on the specified locality.
Note
HPX does not expose any functionality to delete component instances. All
global addresses (as represented using hpx::id_type) are automatically
garbage collected. When the last (global) reference to a particular component
instance goes out of scope the corresponding component instance is
automatically deleted.
Applying actions¶
Action type definition¶
Actions are special types we use to describe possibly remote operations. For
every global function and every member function which has to be invoked
distantly, a special type must be defined. For any global function the special
macro HPX_PLAIN_ACTION can be used to define the
action type. Here is an example demonstrating this:
namespace app
{
void some_global_function(double d)
{
cout << d;
}
}
// This will define the action type 'some_global_action' which represents
// the function 'app::some_global_function'.
HPX_PLAIN_ACTION(app::some_global_function, some_global_action);
Important
The macro HPX_PLAIN_ACTION has to be placed in
global namespace, even if the wrapped function is located in some other
namespace. The newly defined action type is placed in the global namespace as
well.
If the action type should be defined somewhere not in global namespace, the
action type definition has to be split into two macro invocations
(HPX_DEFINE_PLAIN_ACTION and HPX_REGISTER_ACTION) as shown
in the next example:
namespace app
{
void some_global_function(double d)
{
cout << d;
}
// On conforming compilers the following macro expands to:
//
// typedef hpx::actions::make_action<
// decltype(&some_global_function), &some_global_function
// >::type some_global_action;
//
// This will define the action type 'some_global_action' which represents
// the function 'some_global_function'.
HPX_DEFINE_PLAIN_ACTION(some_global_function, some_global_action);
}
// The following macro expands to a series of definitions of global objects
// which are needed for proper serialization and initialization support
// enabling the remote invocation of the function``some_global_function``
HPX_REGISTER_ACTION(app::some_global_action, app_some_global_action);
The shown code defines an action type some_global_action inside the namespace
app.
Important
If the action type definition is split between two macros as shown above, the
name of the action type to create has to be the same for both macro
invocations (here some_global_action).
Important
The second argument passed to HPX_REGISTER_ACTION (app_some_global_action) has
to comprise a globally unique C++ identifier representing the action. This is
used for serialization purposes.
For member functions of objects which have been registered with AGAS
(e.g. ‘components’) a different registration macro
HPX_DEFINE_COMPONENT_ACTION has to be utilized. Any component needs
to be declared in a header file and have some special support macros defined in
a source file. Here is an example demonstrating this. The first snippet has to
go into the header file:
namespace app
{
struct some_component
: hpx::components::component_base<some_component>
{
int some_member_function(std::string s)
{
return boost::lexical_cast<int>(s);
}
// This will define the action type 'some_member_action' which
// represents the member function 'some_member_function' of the
// object type 'some_component'.
HPX_DEFINE_COMPONENT_ACTION(some_component, some_member_function,
some_member_action);
};
}
// Note: The second argument to the macro below has to be systemwide-unique
// C++ identifiers
HPX_REGISTER_ACTION_DECLARATION(app::some_component::some_member_action, some_component_some_action);
The next snippet belongs into a source file (e.g. the main application source file) in the simplest case:
typedef hpx::components::component<app::some_component> component_type;
typedef app::some_component some_component;
HPX_REGISTER_COMPONENT(component_type, some_component);
// The parameters for this macro have to be the same as used in the corresponding
// HPX_REGISTER_ACTION_DECLARATION() macro invocation above
typedef some_component::some_member_action some_component_some_action;
HPX_REGISTER_ACTION(some_component_some_action);
Granted, these macro invocations are a bit more complex than for simple global functions, however we believe they are still manageable.
The most important macro invocation is the HPX_DEFINE_COMPONENT_ACTION in the header file
as this defines the action type we need to invoke the member function. For a
complete example of a simple component action see [hpx_link
examples/quickstart/component_in_executable.cpp..component_in_executable.cpp]
Action invocation¶
The process of invoking a global function (or a member function of an object) with the help of the associated action is called ‘applying the action’. Actions can have arguments, which will be supplied while the action is applied. At the minimum, one parameter is required to apply any action - the id of the locality the associated function should be invoked on (for global functions), or the id of the component instance (for member functions). Generally, HPX provides several ways to apply an action, all of which are described in the following sections.
Generally, HPX actions are very similar to ‘normal’ C++ functions except that actions can be invoked remotely. Fig. 8 below shows an overview of the main API exposed by HPX. This shows the function invocation syntax as defined by the C++ language (dark gray), the additional invocation syntax as provided through C++ Standard Library features (medium gray), and the extensions added by HPX (light gray) where:
ffunction to invoke,p..: (optional) arguments,R: return type off,action: action type defined by,HPX_DEFINE_PLAIN_ACTIONorHPX_DEFINE_COMPONENT_ACTIONencapsulatingf,a: an instance of the type`action,id: the global address the action is applied to.
Fig. 8 Overview of the main API exposed by HPX.¶
This figure shows that HPX allows the user to apply actions with a syntax
similar to the C++ standard. In fact, all action types have an overloaded
function operator allowing to synchronously apply the action. Further, HPX
implements hpx::async which semantically works similar to the
way std::async works for plain C++ function.
Note
The similarity of applying an action to conventional function invocations
extends even further. HPX implements hpx::bind and hpx::function
two facilities which are semantically equivalent to the std::bind and
std::function types as defined by the C++11 Standard. While
hpx::async extends beyond the conventional semantics by supporting
actions and conventional C++ functions, the HPX facilities hpx::bind
and hpx::function extend beyond the conventional standard facilities too.
The HPX facilities not only support conventional functions, but can be used
for actions as well.
Additionally, HPX exposes hpx::apply and hpx::async_continue both of
which refine and extend the standard C++ facilities.
The different ways to invoke a function in HPX will be explained in more detail in the following sections.
Applying an action asynchronously without any synchronization¶
This method (‘fire and forget’) will make sure the function associated with the action is scheduled to run on the target locality. Applying the action does not wait for the function to start running, instead it is a fully asynchronous operation. The following example shows how to apply the action as defined in the previous section on the local locality (the locality this code runs on):
some_global_action act; // define an instance of some_global_action
hpx::apply(act, hpx::find_here(), 2.0);
(the function hpx::find_here() returns the id of the local locality,
i.e. the locality this code executes on).
Any component member function can be invoked using the same syntactic construct.
Given that id is the global address for a component instance created
earlier, this invocation looks like:
some_component_action act; // define an instance of some_component_action
hpx::apply(act, id, "42");
In this case any value returned from this action (e.g. in this case the integer
42 is ignored. Please look at Action type definition for the code
defining the component action some_component_action used.
Applying an action asynchronously with synchronization¶
This method will make sure the action is scheduled to run on the target
locality. Applying the action itself does not wait for the function to
start running or to complete, instead this is a fully asynchronous operation
similar to using hpx::apply as described above. The difference is that this
method will return an instance of a hpx::future<> encapsulating the result
of the (possibly remote) execution. The future can be used to synchronize with
the asynchronous operation. The following example shows how to apply the action
from above on the local locality:
some_global_action act; // define an instance of some_global_action
hpx::future<void> f = hpx::async(act, hpx::find_here(), 2.0);
//
// ... other code can be executed here
//
f.get(); // this will possibly wait for the asynchronous operation to 'return'
(as before, the function hpx::find_here() returns the id of the local
locality (the locality this code is executed on).
Note
The use of a hpx::future<void> allows the current thread to synchronize
with any remote operation not returning any value.
Note
Any std::future<> returned from std::async() is required to block in
its destructor if the value has not been set for this future yet. This is not
true for hpx::future<> which will never block in its destructor, even if
the value has not been returned to the future yet. We believe that
consistency in the behavior of futures is more important than standards
conformance in this case.
Any component member function can be invoked using the same syntactic construct.
Given that id is the global address for a component instance created
earlier, this invocation looks like:
some_component_action act; // define an instance of some_component_action
hpx::future<int> f = hpx::async(act, id, "42");
//
// ... other code can be executed here
//
cout << f.get(); // this will possibly wait for the asynchronous operation to 'return' 42
Note
The invocation of f.get() will return the result immediately (without
suspending the calling thread) if the result from the asynchronous operation
has already been returned. Otherwise, the invocation of f.get() will
suspend the execution of the calling thread until the asynchronous operation
returns its result.
Applying an action synchronously¶
This method will schedule the function wrapped in the specified action on the target locality. While the invocation appears to be synchronous (as we will see), the calling thread will be suspended while waiting for the function to return. Invoking a plain action (e.g. a global function) synchronously is straightforward:
some_global_action act; // define an instance of some_global_action
act(hpx::find_here(), 2.0);
While this call looks just like a normal synchronous function invocation, the function wrapped by the action will be scheduled to run on a new thread and the calling thread will be suspended. After the new thread has executed the wrapped global function, the waiting thread will resume and return from the synchronous call.
Equivalently, any action wrapping a component member function can be invoked synchronously as follows:
some_component_action act; // define an instance of some_component_action
int result = act(id, "42");
The action invocation will either schedule a new thread locally to execute the
wrapped member function (as before, id is the global address of the
component instance the member function should be invoked on), or it will send a
parcel to the remote locality of the component causing a new thread to
be scheduled there. The calling thread will be suspended until the function
returns its result. This result will be returned from the synchronous action
invocation.
It is very important to understand that this ‘synchronous’ invocation syntax in fact conceals an asynchronous function call. This is beneficial as the calling thread is suspended while waiting for the outcome of a potentially remote operation. The HPX thread scheduler will schedule other work in the meantime, allowing the application to make further progress while the remote result is computed. This helps overlapping computation with communication and hiding communication latencies.
Note
The syntax of applying an action is always the same, regardless whether the target locality is remote to the invocation locality or not. This is a very important feature of HPX as it frees the user from the task of keeping track what actions have to be applied locally and which actions are remote. If the target for applying an action is local, a new thread is automatically created and scheduled. Once this thread is scheduled and run, it will execute the function encapsulated by that action. If the target is remote, HPX will send a parcel to the remote locality which encapsulates the action and its parameters. Once the parcel is received on the remote locality HPX will create and schedule a new thread there. Once this thread runs on the remote locality, it will execute the function encapsulated by the action.
Applying an action with a continuation but without any synchronization¶
This method is very similar to the method described in section Applying an action asynchronously without any synchronization. The
difference is that it allows the user to chain a sequence of asynchronous
operations, while handing the (intermediate) results from one step to the next
step in the chain. Where hpx::apply invokes a single function using ‘fire
and forget’ semantics, hpx::apply_continue asynchronously triggers a chain
of functions without the need for the execution flow ‘to come back’ to the
invocation site. Each of the asynchronous functions can be executed on a
different locality.
Applying an action with a continuation and with synchronization¶
This method is very similar to the method described in section Applying an action asynchronously with synchronization. In
addition to what hpx::async can do, the functions hpx::async_continue
takes an additional function argument. This function will be called as the
continuation of the executed action. It is expected to perform additional
operations and to make sure that a result is returned to the original invocation
site. This method chains operations asynchronously by providing a continuation
operation which is automatically executed once the first action has finished
executing.
As an example we chain two actions, where the result of the first action is forwarded to the second action and the result of the second action is sent back to the original invocation site:
// first action
std::int32_t action1(std::int32_t i)
{
return i+1;
}
HPX_PLAIN_ACTION(action1); // defines action1_type
// second action
std::int32_t action2(std::int32_t i)
{
return i*2;
}
HPX_PLAIN_ACTION(action2); // defines action2_type
// this code invokes 'action1' above and passes along a continuation
// function which will forward the result returned from 'action1' to
// 'action2'.
action1_type act1; // define an instance of 'action1_type'
action2_type act2; // define an instance of 'action2_type'
hpx::future<int> f =
hpx::async_continue(act1, hpx::make_continuation(act2),
hpx::find_here(), 42);
hpx::cout << f.get() << "\n"; // will print: 86 ((42 + 1) * 2)
By default, the continuation is executed on the same locality as
hpx::async_continue is invoked from. If you want to specify the
locality where the continuation should be executed, the code above has
to be written as:
// this code invokes 'action1' above and passes along a continuation
// function which will forward the result returned from 'action1' to
// 'action2'.
action1_type act1; // define an instance of 'action1_type'
action2_type act2; // define an instance of 'action2_type'
hpx::future<int> f =
hpx::async_continue(act1, hpx::make_continuation(act2, hpx::find_here()),
hpx::find_here(), 42);
hpx::cout << f.get() << "\n"; // will print: 86 ((42 + 1) * 2)
Similarly, it is possible to chain more than 2 operations:
action1_type act1; // define an instance of 'action1_type'
action2_type act2; // define an instance of 'action2_type'
hpx::future<int> f =
hpx::async_continue(act1,
hpx::make_continuation(act2, hpx::make_continuation(act1)),
hpx::find_here(), 42);
hpx::cout << f.get() << "\n"; // will print: 87 ((42 + 1) * 2 + 1)
The function hpx::make_continuation creates a special function object
which exposes the following prototype:
struct continuation
{
template <typename Result>
void operator()(hpx::id_type id, Result&& result) const
{
...
}
};
where the parameters passed to the overloaded function operator operator()()
are:
the
idis the global id where the final result of the asynchronous chain of operations should be sent to (in most cases this is the id of thehpx::futurereturned from the initial call tohpx::async_continue. Any custom continuation function should make sure thisidis forwarded to the last operation in the chain.the
resultis the result value of the current operation in the asynchronous execution chain. This value needs to be forwarded to the next operation.
Note
All of those operations are implemented by the predefined continuation
function object which is returned from hpx::make_continuation. Any (custom)
function object used as a continuation should conform to the same interface.
Action error handling¶
Like in any other asynchronous invocation scheme it is important to be able to handle error conditions occurring while the asynchronous (and possibly remote) operation is executed. In HPX all error handling is based on standard C++ exception handling. Any exception thrown during the execution of an asynchronous operation will be transferred back to the original invocation locality, where it is rethrown during synchronization with the calling thread.
Important
Exceptions thrown during asynchronous execution can be transferred back to
the invoking thread only for the synchronous and the asynchronous case with
synchronization. Like with any other unhandled exception, any exception
thrown during the execution of an asynchronous action without
synchronization will result in calling hpx::terminate causing the running
application to exit immediately.
Note
Even if error handling internally relies on exceptions, most of the API functions exposed by HPX can be used without throwing an exception. Please see Working with exceptions for more information.
As an example, we will assume that the following remote function will be executed:
namespace app
{
void some_function_with_error(int arg)
{
if (arg < 0) {
HPX_THROW_EXCEPTION(bad_parameter, "some_function_with_error",
"some really bad error happened");
}
// do something else...
}
}
// This will define the action type 'some_error_action' which represents
// the function 'app::some_function_with_error'.
HPX_PLAIN_ACTION(app::some_function_with_error, some_error_action);
The use of HPX_THROW_EXCEPTION to report the error encapsulates the
creation of a hpx::exception which is initialized with the error
code hpx::bad_parameter. Additionally it carries the passed strings, the
information about the file name, line number, and call stack of the point the
exception was thrown from.
We invoke this action using the synchronous syntax as described before:
// note: wrapped function will throw hpx::exception
some_error_action act; // define an instance of some_error_action
try {
act(hpx::find_here(), -3); // exception will be rethrown from here
}
catch (hpx::exception const& e) {
// prints: 'some really bad error happened: HPX(bad parameter)'
cout << e.what();
}
If this action is invoked asynchronously with synchronization, the exception is
propagated to the waiting thread as well and is re-thrown from the future’s
function get():
// note: wrapped function will throw hpx::exception
some_error_action act; // define an instance of some_error_action
hpx::future<void> f = hpx::async(act, hpx::find_here(), -3);
try {
f.get(); // exception will be rethrown from here
}
catch (hpx::exception const& e) {
// prints: 'some really bad error happened: HPX(bad parameter)'
cout << e.what();
}
For more information about error handling please refer to the section Working with exceptions. There we also explain how to handle error conditions without having to rely on exception.
Writing components¶
A component in HPX is a C++ class which can be created remotely and for which its member functions can be invoked remotely as well. The following sections highlight how components can be defined, created, and used.
Defining components¶
In order for a C++ class type to be managed remotely in HPX, the type must be
derived from the hpx::components::component_base template type. We
call such C++ class types ‘components’.
Note that the component type itself is passed as a template argument to the base class:
// header file some_component.hpp
#include <hpx/include/components.hpp>
namespace app
{
// Define a new component type 'some_component'
struct some_component
: hpx::components::component_base<some_component>
{
// This member function is has to be invoked remotely
int some_member_function(std::string const& s)
{
return boost::lexical_cast<int>(s);
}
// This will define the action type 'some_member_action' which
// represents the member function 'some_member_function' of the
// object type 'some_component'.
HPX_DEFINE_COMPONENT_ACTION(some_component, some_member_function, some_member_action);
};
}
// This will generate the necessary boiler-plate code for the action allowing
// it to be invoked remotely. This declaration macro has to be placed in the
// header file defining the component itself.
//
// Note: The second argument to the macro below has to be systemwide-unique
// C++ identifiers
//
HPX_REGISTER_ACTION_DECLARATION(app::some_component::some_member_action, some_component_some_action);
There is more boiler plate code which has to be placed into a source file in order for the component to be usable. Every component type is required to have macros placed into its source file, one for each component type and one macro for each of the actions defined by the component type.
For instance:
// source file some_component.cpp
#include "some_component.hpp"
// The following code generates all necessary boiler plate to enable the
// remote creation of 'app::some_component' instances with 'hpx::new_<>()'
//
using some_component = app::some_component;
using some_component_type = hpx::components::component<some_component>;
// Please note that the second argument to this macro must be a
// (system-wide) unique C++-style identifier (without any namespaces)
//
HPX_REGISTER_COMPONENT(some_component_type, some_component);
// The parameters for this macro have to be the same as used in the corresponding
// HPX_REGISTER_ACTION_DECLARATION() macro invocation in the corresponding
// header file.
//
// Please note that the second argument to this macro must be a
// (system-wide) unique C++-style identifier (without any namespaces)
//
HPX_REGISTER_ACTION(app::some_component::some_member_action, some_component_some_action);
Defining client side representation classes¶
Often it is very convenient to define a separate type for a component which can be used on the client side (from where the component is instantiated and used). This step might seem as unnecessary duplicating code, however it significantly increases the type safety of the code.
A possible implementation of such a client side representation for the component described in the previous section could look like:
#include <hpx/include/components.hpp>
namespace app
{
// Define a client side representation type for the component type
// 'some_component' defined in the previous section.
//
struct some_component_client
: hpx::components::client_base<some_component_client, some_component>
{
using base_type = hpx::components::client_base<
some_component_client, some_component>;
some_component_client(hpx::future<hpx::id_type> && id)
: base_type(std::move(id))
{}
hpx::future<int> some_member_function(std::string const& s)
{
some_component::some_member_action act;
return hpx::async(act, get_id(), s);
}
};
}
A client side object stores the global id of the component instance it
represents. This global id is accessible by calling the function
client_base<>::get_id(). The special constructor which is provided in the
example allows to create this client side object directly using the API function
hpx::new_.
Creating component instances¶
Instances of defined component types can be created in two different ways. If the component to create has a defined client side representation type, then this can be used, otherwise use the server type.
The following examples assume that some_component_type is the type of the
server side implementation of the component to create. All additional arguments
(see , ... notation below) are passed through to the corresponding
constructor calls of those objects:
// create one instance on the given locality
hpx::id_type here = hpx::find_here();
hpx::future<hpx::id_type> f =
hpx::new_<some_component_type>(here, ...);
// create one instance using the given distribution
// policy (here: hpx::colocating_distribution_policy)
hpx::id_type here = hpx::find_here();
hpx::future<hpx::id_type> f =
hpx::new_<some_component_type>(hpx::colocated(here), ...);
// create multiple instances on the given locality
hpx::id_type here = find_here();
hpx::future<std::vector<hpx::id_type>> f =
hpx::new_<some_component_type[]>(here, num, ...);
// create multiple instances using the given distribution
// policy (here: hpx::binpacking_distribution_policy)
hpx::future<std::vector<hpx::id_type>> f = hpx::new_<some_component_type[]>(
hpx::binpacking(hpx::find_all_localities()), num, ...);
The examples below demonstrate the use of the same API functions for creating
client side representation objects (instead of just plain ids). These examples
assume that client_type is the type of the client side representation of the
component type to create. As above, all additional arguments
(see , ... notation below) are passed through to the corresponding constructor
calls of the server side implementation objects corresponding to the
client_type:
// create one instance on the given locality
hpx::id_type here = hpx::find_here();
client_type c = hpx::new_<client_type>(here, ...);
// create one instance using the given distribution
// policy (here: hpx::colocating_distribution_policy)
hpx::id_type here = hpx::find_here();
client_type c = hpx::new_<client_type>(hpx::colocated(here), ...);
// create multiple instances on the given locality
hpx::id_type here = hpx::find_here();
hpx::future<std::vector<client_type>> f =
hpx::new_<client_type[]>(here, num, ...);
// create multiple instances using the given distribution
// policy (here: hpx::binpacking_distribution_policy)
hpx::future<std::vector<client_type>> f = hpx::new_<client_type[]>(
hpx::binpacking(hpx::find_all_localities()), num, ...);
Using component instances¶
Segmented containers¶
In parallel programming, there is now a plethora of solutions aimed at implementing “partially contiguous” or segmented data structures, whether on shared memory systems or distributed memory systems. HPX implements such structures by drawing inspiration from Standard C++ containers.
Using segmented containers¶
A segmented container is a template class that is described in the namespace
hpx. All segmented containers are very similar semantically to their
sequential counterpart (defined in namespace std but with an additional
template parameter named DistPolicy). The distribution policy is an optional
parameter that is passed last to the segmented container constructor (after the
container size when no default value is given, after the default value if not).
The distribution policy describes the manner in which a container is segmented
and the placement of each segment among the available runtime localities.
However, only a part of the std container member functions were
reimplemented:
(constructor),(destructor),operator=operator[]begin,cbegin,end,cendsize
An example of how to use the partitioned_vector container would be:
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(double);
// By default, the number of segments is equal to the current number of
// localities
//
hpx::partitioned_vector<double> va(50);
hpx::partitioned_vector<double> vb(50, 0.0);
An example of how to use the partitioned_vector container
with distribution policies would be:
#include <hpx/include/partitioned_vector.hpp>
#include <hpx/runtime/find_localities.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(double);
std::size_t num_segments = 10;
std::vector<hpx::id_type> locs = hpx::find_all_localities()
auto layout =
hpx::container_layout( num_segments, locs );
// The number of segments is 10 and those segments are spread across the
// localities collected in the variable locs in a Round-Robin manner
//
hpx::partitioned_vector<double> va(50, layout);
hpx::partitioned_vector<double> vb(50, 0.0, layout);
By definition, a segmented container must be accessible from any thread although its construction is synchronous only for the thread who has called its constructor. To overcome this problem, it is possible to assign a symbolic name to the segmented container:
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(double);
hpx::future<void> fserver = hpx::async(
[](){
hpx::partitioned_vector<double> v(50);
// Register the 'partitioned_vector' with the name "some_name"
//
v.register_as("some_name");
/* Do some code */
});
hpx::future<void> fclient =
hpx::async(
[](){
// Naked 'partitioned_vector'
//
hpx::partitioned_vector<double> v;
// Now the variable v points to the same 'partitioned_vector' that has
// been registered with the name "some_name"
//
v.connect_to("some_name");
/* Do some code */
});
HPX provides the following segmented containers:
Name |
Description |
In header |
Class page at cppreference.com |
|
Dynamic segmented contiguous array. |
|
Name |
Description |
In header |
Class page at cppreference.com |
|
Segmented collection of key-value pairs, hashed by keys, keys are unique. |
|
Segmented iterators and segmented iterator traits¶
The basic iterator used in the STL library is only suitable for one-dimensional
structures. The iterators we use in HPX must adapt to the segmented format of
our containers. Our iterators are then able to know when incrementing themselves
if the next element of type T is in the same data segment or in another
segment. In this second case, the iterator will automatically point to the
beginning of the next segment.
Note
Note that the dereference operation operator * does not directly return a
reference of type T& but an intermediate object wrapping this reference.
When this object is used as an l-value, a remote write operation is
performed; When this object is used as an r-value, implicit conversion to
T type will take care of performing remote read operation.
It is sometimes useful not only to iterate element by element, but also segment
by segment, or simply get a local iterator in order to avoid additional
construction costs at each deferencing operations. To mitigate this need, the
hpx::traits::segmented_iterator_traits are used.
With segmented_iterator_traits users can uniformly get the iterators
which specifically iterates over segments (by providing a segmented iterator
as a parameter), or get the local begin/end iterators of the nearest
local segment (by providing a per-segment iterator as a parameter):
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(double);
using iterator = hpx::partitioned_vector<T>::iterator;
using traits = hpx::traits::segmented_iterator_traits<iterator>;
hpx::partitioned_vector<T> v;
std::size_t count = 0;
auto seg_begin = traits::segment(v.begin());
auto seg_end = traits::segment(v.end());
// Iterate over segments
for (auto seg_it = seg_begin; seg_it != seg_end; ++seg_it)
{
auto loc_begin = traits::begin(seg_it);
auto loc_end = traits::end(seg_it);
// Iterate over elements inside segments
for (auto lit = loc_begin; lit != loc_end; ++lit, ++count)
{
*lit = count;
}
}
Which is equivalent to:
hpx::partitioned_vector<T> v;
std::size_t count = 0;
auto begin = v.begin();
auto end = v.end();
for (auto it = begin; it != end; ++it, ++count)
{
*it = count;
}
Using views¶
The use of multidimensional arrays is quite common in the numerical field
whether to perform dense matrix operations or to process images. It exist many
libraries which implement such object classes overloading their basic operators
(e.g.``+``, -, *, (), etc.). However, such operation becomes more
delicate when the underlying data layout is segmented or when it is mandatory to
use optimized linear algebra subroutines (i.e. BLAS subroutines).
Our solution is thus to relax the level of abstraction by allowing the user to work not directly on n-dimensionnal data, but on “n-dimensionnal collections of 1-D arrays”. The use of well-accepted techniques on contiguous data is thus preserved at the segment level, and the composability of the segments is made possible thanks to multidimensional array-inspired access mode.
Although HPX refutes by design this programming model, the locality plays a dominant role when it comes to implement vectorized code. To maximize local computations and avoid unneeded data transfers, a parallel section (or Single Programming Multiple Data section) is required. Because the use of global variables is prohibited, this parallel section is created via the RAII idiom.
To define a parallel section, simply write an action taking a spmd_block
variable as a first parameter:
#include <hpx/collectives/spmd_block.hpp>
void bulk_function(hpx::lcos::spmd_block block /* , arg0, arg1, ... */)
{
// Parallel section
/* Do some code */
}
HPX_PLAIN_ACTION(bulk_function, bulk_action);
Note
In the following paragraphs, we will use the term “image” several times. An image is defined as a lightweight process whose entry point is a function provided by the user. It’s an “image of the function”.
The spmd_block class contains the following methods:
[def Team information]
get_num_images,this_image,images_per_locality[def Control statements]
sync_all,sync_images
Here is a sample code summarizing the features offered by the spmd_block
class:
#include <hpx/collectives/spmd_block.hpp>
void bulk_function(hpx::lcos::spmd_block block /* , arg0, arg1, ... */)
{
std::size_t num_images = block.get_num_images();
std::size_t this_image = block.this_image();
std::size_t images_per_locality = block.images_per_locality();
/* Do some code */
// Synchronize all images in the team
block.sync_all();
/* Do some code */
// Synchronize image 0 and image 1
block.sync_images(0,1);
/* Do some code */
std::vector<std::size_t> vec_images = {2,3,4};
// Synchronize images 2, 3 and 4
block.sync_images(vec_images);
// Alternative call to synchronize images 2, 3 and 4
block.sync_images(vec_images.begin(), vec_images.end());
/* Do some code */
// Non-blocking version of sync_all()
hpx::future<void> event =
block.sync_all(hpx::launch::async);
// Callback waiting for 'event' to be ready before being scheduled
hpx::future<void> cb =
event.then(
[](hpx::future<void>)
{
/* Do some code */
});
// Finally wait for the execution tree to be finished
cb.get();
}
HPX_PLAIN_ACTION(bulk_test_function, bulk_test_action);
Then, in order to invoke the parallel section, call the function
define_spmd_block specifying an arbitrary symbolic name and indicating the
number of images per locality to create:
void bulk_function(hpx::lcos::spmd_block block, /* , arg0, arg1, ... */)
{
}
HPX_PLAIN_ACTION(bulk_test_function, bulk_test_action);
int main()
{
/* std::size_t arg0, arg1, ...; */
bulk_action act;
std::size_t images_per_locality = 4;
// Instantiate the parallel section
hpx::lcos::define_spmd_block(
"some_name", images_per_locality, std::move(act) /*, arg0, arg1, ... */);
return 0;
}
Note
In principle, the user should never call the spmd_block constructor. The
define_spmd_block function is responsible of instantiating spmd_block
objects and broadcasting them to each created image.
Some classes are defined as “container views” when the purpose is to observe
and/or modify the values of a container using another perspective than the one
that characterizes the container. For example, the values of an std::vector
object can be accessed via the expression [i]. Container views can be used,
for example, when it is desired for those values to be “viewed” as a 2D matrix
that would have been flattened in a std::vector. The values would be
possibly accessible via the expression vv(i,j) which would call internally
the expression v[k].
By default, the partitioned_vector class integrates 1-D views of its segments:
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(double);
using iterator = hpx::partitioned_vector<double>::iterator;
using traits = hpx::traits::segmented_iterator_traits<iterator>;
hpx::partitioned_vector<double> v;
// Create a 1-D view of the vector of segments
auto vv = traits::segment(v.begin());
// Access segment i
std::vector<double> v = vv[i];
Our views are called “multidimensional” in the sense that they generalize to N
dimensions the purpose of segmented_iterator_traits::segment() in the 1-D
case. Note that in a parallel section, the 2-D expression a(i,j) = b(i,j) is
quite confusing because without convention, each of the images invoked will race
to execute the statement. For this reason, our views are not only
multidimensional but also “spmd-aware”.
Note
SPMD-awareness: The convention is simple. If an assignment statement contains a view subscript as an l-value, it is only and only the image holding the r-value who is evaluating the statement. (In MPI sense, it is called a Put operation).
Here are some examples of using subscripts in the 2-D view case:
#include <hpx/components/containers/partitioned_vector/partitioned_vector_view.hpp>
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(double);
using Vec = hpx::partitioned_vector<double>;
using View_2D = hpx::partitioned_vector_view<double,2>;
/* Do some code */
Vec v;
// Parallel section (suppose 'block' an spmd_block instance)
{
std::size_t height, width;
// Instantiate the view
View_2D vv(block, v.begin(), v.end(), {height,width});
// The l-value is a view subscript, the image that owns vv(1,0)
// evaluates the assignment.
vv(0,1) = vv(1,0);
// The l-value is a view subscript, the image that owns the r-value
// (result of expression 'std::vector<double>(4,1.0)') evaluates the
// assignment : oops! race between all participating images.
vv(2,3) = std::vector<double>(4,1.0);
}
Here are some examples of using iterators in the 3-D view case:
#include <hpx/components/containers/partitioned_vector/partitioned_vector_view.hpp>
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(int);
using Vec = hpx::partitioned_vector<int>;
using View_3D = hpx::partitioned_vector_view<int,3>;
/* Do some code */
Vec v1, v2;
// Parallel section (suppose 'block' an spmd_block instance)
{
std::size_t sixe_x, size_y, size_z;
// Instantiate the views
View_3D vv1(block, v1.begin(), v1.end(), {sixe_x,size_y,size_z});
View_3D vv2(block, v2.begin(), v2.end(), {sixe_x,size_y,size_z});
// Save previous segments covered by vv1 into segments covered by vv2
auto vv2_it = vv2.begin();
auto vv1_it = vv1.cbegin();
for(; vv2_it != vv2.end(); vv2_it++, vv1_it++)
{
// It's a Put operation
*vv2_it = *vv1_it;
}
// Ensure that all images have performed their Put operations
block.sync_all();
// Ensure that only one image is putting updated data into the different
// segments covered by vv1
if(block.this_image() == 0)
{
int idx = 0;
// Update all the segments covered by vv1
for(auto i = vv1.begin(); i != vv1.end(); i++)
{
// It's a Put operation
*i = std::vector<float>(elt_size,idx++);
}
}
}
Here is an example that shows how to iterate only over segments owned by the current image:
#include <hpx/components/containers/partitioned_vector/partitioned_vector_view.hpp>
#include <hpx/components/containers/partitioned_vector/partitioned_vector_local_view.hpp>
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(float);
using Vec = hpx::partitioned_vector<float>;
using View_1D = hpx::partitioned_vector_view<float,1>;
/* Do some code */
Vec v;
// Parallel section (suppose 'block' an spmd_block instance)
{
std::size_t num_segments;
// Instantiate the view
View_1D vv(block, v.begin(), v.end(), {num_segments});
// Instantiate the local view from the view
auto local_vv = hpx::local_view(vv);
for ( auto i = local_vv.begin(); i != local_vv.end(); i++ )
{
std::vector<float> & segment = *i;
/* Do some code */
}
}
It is possible to construct views from other views: we call it sub-views. The constraint nevertheless for the subviews is to retain the dimension and the value type of the input view. Here is an example showing how to create a sub-view:
#include <hpx/components/containers/partitioned_vector/partitioned_vector_view.hpp>
#include <hpx/include/partitioned_vector.hpp>
// The following code generates all necessary boiler plate to enable the
// remote creation of 'partitioned_vector' segments
//
HPX_REGISTER_PARTITIONED_VECTOR(float);
using Vec = hpx::partitioned_vector<float>;
using View_2D = hpx::partitioned_vector_view<float,2>;
/* Do some code */
Vec v;
// Parallel section (suppose 'block' an spmd_block instance)
{
std::size_t N = 20;
std::size_t tilesize = 5;
// Instantiate the view
View_2D vv(block, v.begin(), v.end(), {N,N});
// Instantiate the subview
View_2D svv(
block,&vv(tilesize,0),&vv(2*tilesize-1,tilesize-1),{tilesize,tilesize},{N,N});
if(block.this_image() == 0)
{
// Equivalent to 'vv(tilesize,0) = 2.0f'
svv(0,0) = 2.0f;
// Equivalent to 'vv(2*tilesize-1,tilesize-1) = 3.0f'
svv(tilesize-1,tilesize-1) = 3.0f;
}
}
Note
The last parameter of the subview constructor is the size of the original
view. If one would like to create a subview of the subview and so on, this
parameter should stay unchanged. {N,N} for the above example).
C++ co-arrays¶
Fortran has extended its scalar element indexing approach to reference each segment of a distributed array. In this extension, a segment is attributed a ?co-index? and lives in a specific locality. A co-index provides the application with enough information to retrieve the corresponding data reference. In C++, containers present themselves as a ?smarter? alternative of Fortran arrays but there are still no corresponding standardized features similar to the Fortran co-indexing approach. We present here an implementation of such features in HPX.
As mentioned before, a co-array is a distributed array whose segments are accessible through an array-inspired access mode. We have previously seen that it is possible to reproduce such access mode using the concept of views. Nevertheless, the user must pre-create a segmented container to instantiate this view. We illustrate below how a single constructor call can perform those two operations:
#include <hpx/components/containers/coarray/coarray.hpp>
#include <hpx/collectives/spmd_block.hpp>
// The following code generates all necessary boiler plate to enable the
// co-creation of 'coarray'
//
HPX_REGISTER_COARRAY(double);
// Parallel section (suppose 'block' an spmd_block instance)
{
using hpx::container::placeholders::_;
std::size_t height=32, width=4, segment_size=10;
hpx::coarray<double,3> a(block, "a", {height,width,_}, segment_size);
/* Do some code */
}
Unlike segmented containers, a co-array object can only be instantiated within a parallel section. Here is the description of the parameters to provide to the coarray constructor:
Parameter |
Description |
|
Reference to a |
|
Symbolic name of type |
|
Dimensions of the |
|
Size of a co-indexed element (i.e. size of the object referenced by the
expression |
Note that the “last dimension size” cannot be set by the user. It only accepts
the constexpr variable hpx::container::placeholders::_. This size, which is
considered private, is equal to the number of current images (value returned by
block.get_num_images()).
Note
An important constraint to remember about coarray objects is that all segments sharing the same “last dimension index” are located in the same image.
The member functions owned by the coarray objects are exactly the same as
those of spmd multidimensional views. These are:
* Subscript-based operations
* Iterator-based operations
However, one additional functionality is provided. Knowing that the element
a(i,j,k) is in the memory of the kth image, the use of local subscripts
is possible.
Note
For spmd multidimensional views, subscripts are only global as it still involves potential remote data transfers.
Here is an example of using local subscripts:
#include <hpx/components/containers/coarray/coarray.hpp>
#include <hpx/collectives/spmd_block.hpp>
// The following code generates all necessary boiler plate to enable the
// co-creation of 'coarray'
//
HPX_REGISTER_COARRAY(double);
// Parallel section (suppose 'block' an spmd_block instance)
{
using hpx::container::placeholders::_;
std::size_t height=32, width=4, segment_size=10;
hpx::coarray<double,3> a(block, "a", {height,width,_}, segment_size);
double idx = block.this_image()*height*width;
for (std::size_t j = 0; j<width; j++)
for (std::size_t i = 0; i<height; i++)
{
// Local write operation performed via the use of local subscript
a(i,j,_) = std::vector<double>(elt_size,idx);
idx++;
}
block.sync_all();
}
Note
When the “last dimension index” of a subscript is equal to
hpx::container::placeholders::_, local subscript (and not global
subscript) is used. It is equivalent to a global subscript used with a “last
dimension index” equal to the value returned by block.this_image().
Running on batch systems¶
This section walks you through launching HPX applications on various batch systems.
How to use HPX applications with PBS¶
Most HPX applications are executed on parallel computers. These platforms typically provide integrated job management services that facilitate the allocation of computing resources for each parallel program. HPX includes support for one of the most common job management systems, the Portable Batch System (PBS).
All PBS jobs require a script to specify the resource requirements and other
parameters associated with a parallel job. The PBS script is basically a shell
script with PBS directives placed within commented sections at the beginning of
the file. The remaining (not commented-out) portions of the file executes just
like any other regular shell script. While the description of all available PBS
options is outside the scope of this tutorial (the interested reader may refer
to in-depth documentation for
more information), below is a minimal example to illustrate the approach. The following
test application will use the multithreaded hello_world_distributed
program, explained in the section Remote execution with actions: Hello world.
#!/bin/bash
#
#PBS -l nodes=2:ppn=4
APP_PATH=~/packages/hpx/bin/hello_world_distributed
APP_OPTIONS=
pbsdsh -u $APP_PATH $APP_OPTIONS --hpx:nodes=`cat $PBS_NODEFILE`
Caution
If the first application specific argument (inside $APP_OPTIONS) is a
non-option (i.e., does not start with a - or a --), then the argument has to
be placed before the option --hpx:nodes, which, in this case, should
be the last option on the command line.
Alternatively, use the option --hpx:endnodes to explicitly mark the
end of the list of node names:
pbsdsh -u $APP_PATH --hpx:nodes`cat $PBS_NODEFILE` --hpx:endnodes $APP_OPTIONS
The #PBS -l nodes=2:ppn=4 directive will cause two compute nodes to be
allocated for the application, as specified in the option nodes. Each of the
nodes will dedicate four cores to the program, as per the option ppn, short
for “processors per node” (PBS does not distinguish between processors and
cores). Note that requesting more cores per node than physically available is
pointless and may prevent PBS from accepting the script.
On newer PBS versions the PBS command syntax might be different. For instance, the PBS script above would look like:
#!/bin/bash
#
#PBS -l select=2:ncpus=4
APP_PATH=~/packages/hpx/bin/hello_world_distributed
APP_OPTIONS=
pbsdsh -u $APP_PATH $APP_OPTIONS --hpx:nodes=`cat $PBS_NODEFILE`
APP_PATH and APP_OPTIONS are shell variables that respectively specify
the correct path to the executable (hello_world_distributed in this case)
and the command line options. Since the hello_world_distributed application
doesn’t need any command line options, APP_OPTIONS has been left empty.
Unlike in other execution environments, there is no need to use the
--hpx:threads option to indicate the required number of OS threads per
node; the HPX library will derive this parameter automatically from PBS.
Finally, pbsdsh is a PBS command that starts tasks to the resources allocated to the current job. It is recommended to leave this line as shown and modify only the PBS options and shell variables as needed for a specific application.
Important
A script invoked by pbsdsh starts in a very basic environment: the user’s
$HOME directory is defined and is the current directory, the LANG
variable is set to C and the PATH is set to the basic
/usr/local/bin:/usr/bin:/bin as defined in a system-wide file
pbs_environment. Nothing that would normally be set up by a system shell
profile or user shell profile is defined, unlike the environment for the main
job script.
Another choice is for the pbsdsh command in your main job script to invoke
your program via a shell, like sh or bash, so that it gives an initialized
environment for each instance. Users can create a small script runme.sh, which is used
to invoke the program:
#!/bin/bash
# Small script which invokes the program based on what was passed on its
# command line.
#
# This script is executed by the bash shell which will initialize all
# environment variables as usual.
$@
Now, the script is invoked using the pbsdsh tool:
#!/bin/bash
#
#PBS -l nodes=2:ppn=4
APP_PATH=~/packages/hpx/bin/hello_world_distributed
APP_OPTIONS=
pbsdsh -u runme.sh $APP_PATH $APP_OPTIONS --hpx:nodes=`cat $PBS_NODEFILE`
All that remains now is submitting the job to the queuing system. Assuming that
the contents of the PBS script were saved in the file pbs_hello_world.sh in the
current directory, this is accomplished by typing:
qsub ./pbs_hello_world_pbs.sh
If the job is accepted, qsub will print out the assigned job ID, which may look like:
$ 42.supercomputer.some.university.edu
To check the status of your job, issue the following command:
qstat 42.supercomputer.some.university.edu
and look for a single-letter job status symbol. The common cases include:
Q - signifies that the job is queued and awaiting its turn to be executed.
R - indicates that the job is currently running.
C - means that the job has completed.
The example qstat output below shows a job waiting for execution resources to become available:
Job id Name User Time Use S Queue
------------------------- ---------------- --------------- -------- - -----
42.supercomputer ...ello_world.sh joe_user 0 Q batch
After the job completes, PBS will place two files, pbs_hello_world.sh.o42 and
pbs_hello_world.sh.e42, in the directory where the job was submitted. The
first contains the standard output and the second contains the standard error
from all the nodes on which the application executed. In our example, the error
output file should be empty and the standard output file should contain something
similar to:
hello world from OS-thread 3 on locality 0
hello world from OS-thread 2 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 3 on locality 1
hello world from OS-thread 2 on locality 1
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 1
Congratulations! You have just run your first distributed HPX application!
How to use HPX applications with SLURM¶
Just like PBS (described in section How to use HPX applications with PBS), SLURM is a job management system which is widely used on large supercomputing systems. Any HPX application can easily be run using SLURM. This section describes how this can be done.
The easiest way to run an HPX application using SLURM is to utilize the command line tool srun, which interacts with the SLURM batch scheduling system:
srun -p <partition> -N <number-of-nodes> hpx-application <application-arguments>
Here, <partition> is one of the node partitions existing on the target
machine (consult the machine’s documentation to get a list of existing
partitions) and <number-of-nodes> is the number of compute nodes that should
be used. By default, the HPX application is started with one locality per
node and uses all available cores on a node. You can change the number of
localities started per node (for example, to account for NUMA effects) by
specifying the -n option of srun. The number of cores per locality
can be set by -c. The <application-arguments> are any application
specific arguments that need to be passed on to the application.
Note
There is no need to use any of the HPX command line options related to the number of localities, number of threads, or related to networking ports. All of this information is automatically extracted from the SLURM environment by the HPX startup code.
Important
The srun documentation explicitly states: “If -c is specified without
-n, as many tasks will be allocated per node as possible while satisfying
the -c restriction. For instance on a cluster with 8 CPUs per node, a job
request for 4 nodes and 3 CPUs per task may be allocated 3 or 6 CPUs per node
(1 or 2 tasks per node) depending upon resource consumption by other jobs.”
For this reason, it’s recommended to always specify -n <number-of-instances>,
even if <number-of-instances> is equal to one (1).
Interactive shells¶
To get an interactive development shell on one of the nodes, users can issue the following command:
srun -p <node-type> -N <number-of-nodes> --pty /bin/bash -l
After the shell has been opened, users can run their HPX application. By default,
it uses all available cores. Note that if you requested one node, you don’t need
to do srun again. However, if you requested more than one node, and want to
run your distributed application, you can use srun again to start up the
distributed HPX application. It will use the resources that have been requested
for the interactive shell.
Scheduling batch jobs¶
The above mentioned method of running HPX applications is fine for development
purposes. The disadvantage that comes with srun is that it only returns once
the application is finished. This might not be appropriate for longer-running
applications (for example, benchmarks or larger scale simulations). In order to
cope with that limitation, users can use the sbatch command.
The sbatch command expects a script that it can run once the requested
resources are available. In order to request resources, users need to add
#SBATCH comments in their script or provide the necessary parameters to
sbatch directly. The parameters are the same as with run. The commands
you need to execute are the same you would need to start your application as if
you were in an interactive shell.
Debugging HPX applications¶
Using a debugger with HPX applications¶
Using a debugger such as gdb with HPX applications is no problem. However,
there are some things to keep in mind to make the experience somewhat more
productive.
Call stacks in HPX can often be quite unwieldy as the library is heavily
templated and the call stacks can be very deep. For this reason it is sometimes
a good idea compile HPX in RelWithDebInfo mode, which applies some
optimizations but keeps debugging symbols. This can often compress call stacks
significantly. On the other hand, stepping through the code can also be more
difficult because of statements being reordered and variables being optimized
away. Also, note that because HPX implements user-space threads and context
switching, call stacks may not always be complete in a debugger.
HPX launches not only worker threads but also a few helper threads. The first thread is the main thread, which typically does no work in an HPX application, except at startup and shutdown. If using the default settings, HPX will spawn six additional threads (used for service thread pools). The first worker thread is usually the eighth thread, and most user codes will be run on these worker threads. The last thread is a helper thread used for HPX shutdown.
Finally, since HPX is a multi-threaded runtime, the following gdb options
can be helpful:
set pagination off
set non-stop on
Non-stop mode allows users to have a single thread stop on a breakpoint without stopping all other threads as well.
Using sanitizers with HPX applications¶
Warning
Not all parts of HPX are sanitizer clean. This means that users may end up with false positives from HPX itself when using sanitizers for their applications.
To use sanitizers with HPX, turn on HPX_WITH_SANITIZERS and turn
off HPX_WITH_STACKOVERFLOW_DETECTION during CMake configuration. It’s
recommended to also build Boost with the same sanitizers that will be
used for HPX. The appropriate sanitizers can then be enabled using CMake by
appending -fsanitize=address -fno-omit-frame-pointer to CMAKE_CXX_FLAGS
and -fsanitize=address to CMAKE_EXE_LINKER_FLAGS. Replace address
with the sanitizer that you want to use.
Optimizing HPX applications¶
Performance counters¶
Performance counters in HPX are used to provide information as to how well the runtime system or an application is performing. The counter data can help determine system bottlenecks, and fine-tune system and application performance. The HPX runtime system, its networking, and other layers provide counter data that an application can consume to provide users with information about how well the application is performing.
Applications can also use counter data to determine how much system resources to consume. For example, an application that transfers data over the network could consume counter data from a network switch to determine how much data to transfer without competing for network bandwidth with other network traffic. The application could use the counter data to adjust its transfer rate as the bandwidth usage from other network traffic increases or decreases.
Performance counters are HPX parallel processes that expose a predefined interface. HPX exposes special API functions that allow one to create, manage, and read the counter data, and release instances of performance counters. Performance Counter instances are accessed by name, and these names have a predefined structure which is described in the section Performance counter names. The advantage of this is that any Performance Counter can be accessed remotely (from a different locality) or locally (from the same locality). Moreover, since all counters expose their data using the same API, any code consuming counter data can be utilized to access arbitrary system information with minimal effort.
Counter data may be accessed in real time. More information about how to consume counter data can be found in the section Consuming performance counter data.
All HPX applications provide command line options related to performance counters, such as the ability to list available counter types, or periodically query specific counters to be printed to the screen or save them in a file. For more information, please refer to the section HPX Command Line Options.
Performance counter names¶
All Performance Counter instances have a name uniquely identifying each instance. This name can be used to access the counter, retrieve all related meta data, and to query the counter data (as described in the section Consuming performance counter data). Counter names are strings with a predefined structure. The general form of a countername is:
/objectname{full_instancename}/countername@parameters
where full_instancename could be either another (full) counter name or a
string formatted as:
parentinstancename#parentindex/instancename#instanceindex
Each separate part of a countername (e.g., objectname, countername
parentinstancename, instancename, and parameters) should start with
a letter ('a'…'z', 'A'…'Z') or an underscore
character ('_'), optionally followed by letters, digits ('0'…'9'), hyphen ('-'), or underscore characters. Whitespace is not allowed
inside a counter name. The characters '/', '{', '}', '#' and
'@' have a special meaning and are used to delimit the different parts of
the counter name.
The parts parentinstanceindex and instanceindex are integers. If an
index is not specified, HPX will assume a default of -1.
Two counter name examples¶
This section gives examples of both simple counter names and aggregate counter names. For more information on simple and aggregate counter names, please see Performance counter instances.
An example of a well-formed (and meaningful) simple counter name would be:
/threads{locality#0/total}/count/cumulative
This counter returns the current cumulative number of executed (retired)
HPX threads for the locality 0. The counter type of this counter
is /threads/count/cumulative and the full instance name is
locality#0/total. This counter type does not require an instanceindex or
parameters to be specified.
In this case, the parentindex (the '0') designates the locality
for which the counter instance is created. The counter will return the number of
HPX threads retired on that particular locality.
Another example for a well formed (aggregate) counter name is:
/statistics{/threads{locality#0/total}/count/cumulative}/average@500
This counter takes the simple counter from the first example, samples its values
every 500 milliseconds, and returns the average of the value samples
whenever it is queried. The counter type of this counter is
/statistics/average and the instance name is the full name of the counter
for which the values have to be averaged. In this case, the parameters (the
'500') specify the sampling interval for the averaging to take place (in
milliseconds).
Performance counter types¶
Every performance counter belongs to a specific performance counter type which
classifies the counters into groups of common semantics. The type of a counter
is identified by the objectname and the countername parts of the name.
/objectname/countername
When an application starts HPX will register all available counter types on each of the localities. These counter types are held in a special performance counter registration database, which can be used to retrieve the meta data related to a counter type and to create counter instances based on a given counter instance name.
Performance counter instances¶
The full_instancename distinguishes different counter instances of the same
counter type. The formatting of the full_instancename depends on the counter
type. There are two types of counters: simple counters, which usually generate
the counter values based on direct measurements, and aggregate counters, which
take another counter and transform its values before generating their own
counter values. An example for a simple counter is given above:
counting retired HPX threads. An aggregate counter is shown as an example
above as well: calculating the average of the underlying
counter values sampled at constant time intervals.
While simple counters use instance names formatted as
parentinstancename#parentindex/instancename#instanceindex, most aggregate
counters have the full counter name of the embedded counter as their instance
name.
Not all simple counter types require specifying all four elements of a full counter
instance name; some of the parts (parentinstancename, parentindex,
instancename, and instanceindex) are optional for specific counters.
Please refer to the documentation of a particular counter for more information
about the formatting requirements for the name of this counter (see
Existing HPX performance counters).
The parameters are used to pass additional information to a counter at
creation time. They are optional, and they fully depend on the concrete counter.
Even if a specific counter type allows additional parameters to be given, those
usually are not required as sensible defaults will be chosen. Please refer to
the documentation of a particular counter for more information about what
parameters are supported, how to specify them, and what default values are
assumed (see also Existing HPX performance counters).
Every locality of an application exposes its own set of performance counter types and performance counter instances. The set of exposed counters is determined dynamically at application start based on the execution environment of the application. For instance, this set is influenced by the current hardware environment for the locality (such as whether the locality has access to accelerators), and the software environment of the application (such as the number of OS threads used to execute HPX threads).
Using wildcards in performance counter names¶
It is possible to use wildcard characters when specifying performance counter names. Performance counter names can contain two types of wildcard characters:
Wildcard characters in the performance counter type
Wildcard characters in the performance counter instance name
A wildcard character has a meaning which is very close to usual file name wildcard matching rules implemented by common shells (like bash).
Wildcard |
Description |
|
This wildcard character matches any number (zero or more) of arbitrary characters. |
|
This wildcard character matches any single arbitrary character. |
|
This wildcard character matches any single character from the list of specified within the square brackets. |
Wildcard |
Description |
|
This wildcard character matches any locality or any thread,
depending on whether it is used for |
Consuming performance counter data¶
You can consume performance data using either the command line interface, the HPX application or the HPX API. The command line interface is easier to use, but it is less flexible and does not allow one to adjust the behaviour of your application at runtime. The command line interface provides a convenience abstraction but simplified abstraction for querying and logging performance counter data for a set of performance counters.
Consuming performance counter data from the command line¶
HPX provides a set of predefined command line options for every application
that uses hpx::init for its initialization. While there are many more
command line options available (see HPX Command Line Options), the set of options related
to performance counters allows one to list existing counters, and query existing
counters once at application termination or repeatedly after a constant time
interval.
The following table summarizes the available command line options:
Command line option |
Description |
|
Prints the specified performance counter either repeatedly and/or at the
times specified by |
|
Prints the specified performance counter either repeatedly and/or at the
times specified by |
|
Prints the performance counter(s) specified with |
|
Prints the performance counter(s) specified with |
|
Lists the names of all registered performance counters. |
|
Lists the description of all registered performance counters. |
|
Prints the performance counter(s) specified with |
|
Prints the performance counter(s) specified with |
|
Prints the performance counter(s) specified with |
|
Resets all performance counter(s) specified with |
|
Appends counter type description to generated output. |
|
Each locality prints only its own local counters. |
While the options --hpx:list-counters and --hpx:list-counter-infos give
a short list of all available counters, the full documentation for those can
be found in the section Existing HPX performance counters.
A simple example¶
All of the commandline options mentioned above can be tested using
the hello_world_distributed example.
Listing all available counters hello_world_distributed --hpx:list-counters
yields:
List of available counter instances (replace * below with the appropriate
sequence number)
-------------------------------------------------------------------------
/agas/count/allocate /agas/count/bind /agas/count/bind_gid
/agas/count/bind_name ... /threads{locality#*/allocator#*}/count/objects
/threads{locality#*/total}/count/stack-recycles
/threads{locality#*/total}/idle-rate
/threads{locality#*/worker-thread#*}/idle-rate
Providing more information about all available counters,
hello_world_distributed --hpx:list-counter-infos yields:
Information about available counter instances (replace * below with the
appropriate sequence number)
------------------------------------------------------------------------------
fullname: /agas/count/allocate helptext: returns the number of invocations of
the AGAS service 'allocate' type: counter_raw version: 1.0.0
------------------------------------------------------------------------------
------------------------------------------------------------------------------
fullname: /agas/count/bind helptext: returns the number of invocations of the
AGAS service 'bind' type: counter_raw version: 1.0.0
------------------------------------------------------------------------------
------------------------------------------------------------------------------
fullname: /agas/count/bind_gid helptext: returns the number of invocations of
the AGAS service 'bind_gid' type: counter_raw version: 1.0.0
------------------------------------------------------------------------------
...
This command will not only list the counter names but also a short description of the data exposed by this counter.
Note
The list of available counters may differ depending on the concrete execution environment (hardware or software) of your application.
Requesting the counter data for one or more performance counters can be achieved
by invoking hello_world_distributed with a list of counter names:
hello_world_distributed \
--hpx:print-counter=/threads{locality#0/total}/count/cumulative \
--hpx:print-counter=/agas{locality#0/total}/count/bind
which yields for instance:
hello world from OS-thread 0 on locality 0
/threads{locality#0/total}/count/cumulative,1,0.212527,[s],33
/agas{locality#0/total}/count/bind,1,0.212790,[s],11
The first line is the normal output generated by hello_world_distributed and
has no relation to the counter data listed. The last two lines contain the
counter data as gathered at application shutdown. These lines have six fields, the
counter name, the sequence number of the counter invocation, the time stamp at
which this information has been sampled, the unit of measure for the time stamp,
the actual counter value and an optional unit of measure for the counter value.
Note
The command line option --hpx:print-counter-types will append a seventh
field to the generated output. This field will hold an abbreviated counter
type.
The actual counter value can be represented by a single number (for counters
returning singular values) or a list of numbers separated by ':' (for
counters returning an array of values, like for instance a histogram).
Note
The name of the performance counter will be enclosed in double quotes '"'
if it contains one or more commas ','.
Requesting to query the counter data once after a constant time interval with this command line:
hello_world_distributed \
--hpx:print-counter=/threads{locality#0/total}/count/cumulative \
--hpx:print-counter=/agas{locality#0/total}/count/bind \
--hpx:print-counter-interval=20
yields for instance (leaving off the actual console output of the
hello_world_distributed example for brevity):
threads{locality#0/total}/count/cumulative,1,0.002409,[s],22
agas{locality#0/total}/count/bind,1,0.002542,[s],9
threads{locality#0/total}/count/cumulative,2,0.023002,[s],41
agas{locality#0/total}/count/bind,2,0.023557,[s],10
threads{locality#0/total}/count/cumulative,3,0.037514,[s],46
agas{locality#0/total}/count/bind,3,0.038679,[s],10
The command --hpx:print-counter-destination=<file> will redirect all counter
data gathered to the specified file name, which avoids cluttering the console
output of your application.
The command line option --hpx:print-counter supports using a limited set of
wildcards for a (very limited) set of use cases. In particular, all occurrences
of #* as in locality#* and in worker-thread#* will be automatically
expanded to the proper set of performance counter names representing the actual
environment for the executed program. For instance, if your program is utilizing
four worker threads for the execution of HPX threads (see command line option
--hpx:threads) the following command line
hello_world_distributed \
--hpx:threads=4 \
--hpx:print-counter=/threads{locality#0/worker-thread#*}/count/cumulative
will print the value of the performance counters monitoring each of the worker threads:
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
hello world from OS-thread 3 on locality 0
hello world from OS-thread 2 on locality 0
/threads{locality#0/worker-thread#0}/count/cumulative,1,0.0025214,[s],27
/threads{locality#0/worker-thread#1}/count/cumulative,1,0.0025453,[s],33
/threads{locality#0/worker-thread#2}/count/cumulative,1,0.0025683,[s],29
/threads{locality#0/worker-thread#3}/count/cumulative,1,0.0025904,[s],33
The command --hpx:print-counter-format takes values csv and
csv-short to generate CSV formatted counter values with a header.
With format as csv:
hello_world_distributed \
--hpx:threads=2 \
--hpx:print-counter-format csv \
--hpx:print-counter /threads{locality#*/total}/count/cumulative \
--hpx:print-counter /threads{locality#*/total}/count/cumulative-phases
will print the values of performance counters in CSV format with the full countername as a header:
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
/threads{locality#*/total}/count/cumulative,/threads{locality#*/total}/count/cumulative-phases
39,93
With format csv-short:
hello_world_distributed \
--hpx:threads 2 \
--hpx:print-counter-format csv-short \
--hpx:print-counter cumulative,/threads{locality#*/total}/count/cumulative \
--hpx:print-counter phases,/threads{locality#*/total}/count/cumulative-phases
will print the values of performance counters in CSV format with the short countername as a header:
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
cumulative,phases
39,93
With format csv and csv-short when used with --hpx:print-counter-interval:
hello_world_distributed \
--hpx:threads 2 \
--hpx:print-counter-format csv-short \
--hpx:print-counter cumulative,/threads{locality#*/total}/count/cumulative \
--hpx:print-counter phases,/threads{locality#*/total}/count/cumulative-phases \
--hpx:print-counter-interval 5
will print the header only once repeating the performance counter value(s) repeatedly:
cum,phases
25,42
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
44,95
The command --hpx:no-csv-header can be used with
--hpx:print-counter-format to print performance counter values in CSV format
without any header:
hello_world_distributed \
--hpx:threads 2 \
--hpx:print-counter-format csv-short \
--hpx:print-counter cumulative,/threads{locality#*/total}/count/cumulative \
--hpx:print-counter phases,/threads{locality#*/total}/count/cumulative-phases \
--hpx:no-csv-header
will print:
hello world from OS-thread 1 on locality 0
hello world from OS-thread 0 on locality 0
37,91
Consuming performance counter data using the HPX API¶
HPX provides an API that allows users to discover performance counters and to retrieve the current value of any existing performance counter from any application.
Discover existing performance counters¶
Retrieve the current value of any performance counter¶
Performance counters are specialized HPX components. In order to retrieve a counter value, the performance counter needs to be instantiated. HPX exposes a client component object for this purpose:
hpx::performance_counters::performance_counter counter(std::string const& name);
Instantiating an instance of this type will create the performance counter
identified by the given name. Only the first invocation for any given counter
name will create a new instance of that counter. All following invocations for a
given counter name will reference the initially created instance. This ensures
that at any point in time there is never more than one active instance of
any of the existing performance counters.
In order to access the counter value (or to invoke any of the other functionality
related to a performance counter, like start, stop or reset) member
functions of the created client component instance should be called:
// print the current number of threads created on locality 0
hpx::performance_counters::performance_counter count(
"/threads{locality#0/total}/count/cumulative");
hpx::cout << count.get_value<int>().get() << hpx::endl;
For more information about the client component type, see
hpx::performance_counters::performance_counter
Note
In the above example count.get_value() returns a future. In order to print
the result we must append .get() to retrieve the value. You could write the
above example like this for more clarity:
// print the current number of threads created on locality 0
hpx::performance_counters::performance_counter count(
"/threads{locality#0/total}/count/cumulative");
hpx::future<int> result = count.get_value<int>();
hpx::cout << result.get() << hpx::endl;
Providing performance counter data¶
HPX offers several ways by which you may provide your own data as a performance counter. This has the benefit of exposing additional, possibly application-specific information using the existing Performance Counter framework, unifying the process of gathering data about your application.
An application that wants to provide counter data can implement a performance counter to provide the data. When a consumer queries performance data, the HPX runtime system calls the provider to collect the data. The runtime system uses an internal registry to determine which provider to call.
Generally, there are two ways of exposing your own performance counter data: a simple, function-based way and a more complex, but more powerful way of implementing a full performance counter. Both alternatives are described in the following sections.
Exposing performance counter data using a simple function¶
The simplest way to expose arbitrary numeric data is to write a function which will then be called whenever a consumer queries this counter. Currently, this type of performance counter can only be used to expose integer values. The expected signature of this function is:
std::int64_t some_performance_data(bool reset);
The argument bool reset (which is supplied by the runtime system when the
function is invoked) specifies whether the counter value should be reset after
evaluating the current value (if applicable).
For instance, here is such a function returning how often it was invoked:
// The atomic variable 'counter' ensures the thread safety of the counter.
boost::atomic<std::int64_t> counter(0);
std::int64_t some_performance_data(bool reset)
{
std::int64_t result = ++counter;
if (reset)
counter = 0;
return result;
}
This example function exposes a linearly-increasing value as our performance data. The value is incremented on each invocation, i.e., each time a consumer requests the counter data of this performance counter.
The next step in exposing this counter to the runtime system is to register the
function as a new raw counter type using the HPX API function
hpx::performance_counters::install_counter_type. A counter type
represents certain common characteristics of counters, like their counter type
name and any associated description information. The following snippet shows an
example of how to register the function some_performance_data, which is shown
above, for a counter type named "/test/data". This registration has to be
executed before any consumer instantiates, and queries an instance of this
counter type:
#include <hpx/include/performance_counters.hpp>
void register_counter_type()
{
// Call the HPX API function to register the counter type.
hpx::performance_counters::install_counter_type(
"/test/data", // counter type name
&some_performance_data, // function providing counter data
"returns a linearly increasing counter value" // description text (optional)
"" // unit of measure (optional)
);
}
Now it is possible to instantiate a new counter instance based on the naming
scheme "/test{locality#*/total}/data" where * is a zero-based integer
index identifying the locality for which the counter instance should be
accessed. The function
hpx::performance_counters::install_counter_type enables users to
instantiate exactly one counter instance for each locality. Repeated
requests to instantiate such a counter will return the same instance, i.e., the
instance created for the first request.
If this counter needs to be accessed using the standard HPX command line
options, the registration has to be performed during application startup, before
hpx_main is executed. The best way to achieve this is to register an HPX
startup function using the API function
hpx::register_startup_function before calling hpx::init to
initialize the runtime system:
int main(int argc, char* argv[])
{
// By registering the counter type we make it available to any consumer
// who creates and queries an instance of the type "/test/data".
//
// This registration should be performed during startup. The
// function 'register_counter_type' should be executed as an HPX thread right
// before hpx_main is executed.
hpx::register_startup_function(®ister_counter_type);
// Initialize and run HPX.
return hpx::init(argc, argv);
}
Please see the code in simplest_performance_counter.cpp
for a full example demonstrating this functionality.
Implementing a full performance counter¶
Sometimes, the simple way of exposing a single value as a performance counter is not sufficient. For that reason, HPX provides a means of implementing full performance counters which support:
Retrieving the descriptive information about the performance counter
Retrieving the current counter value
Resetting the performance counter (value)
Starting the performance counter
Stopping the performance counter
Setting the (initial) value of the performance counter
Every full performance counter will implement a predefined interface:
// Copyright (c) 2007-2020 Hartmut Kaiser
//
// SPDX-License-Identifier: BSL-1.0
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#pragma once
#include <hpx/config.hpp>
#include <hpx/async_base/launch_policy.hpp>
#include <hpx/functional/bind_front.hpp>
#include <hpx/futures/future.hpp>
#include <hpx/modules/execution.hpp>
#include <hpx/runtime/components/client_base.hpp>
#include <hpx/performance_counters/counters_fwd.hpp>
#include <hpx/performance_counters/server/base_performance_counter.hpp>
#include <string>
#include <utility>
#include <vector>
///////////////////////////////////////////////////////////////////////////////
namespace hpx { namespace performance_counters {
///////////////////////////////////////////////////////////////////////////
struct HPX_EXPORT performance_counter
: components::client_base<performance_counter,
server::base_performance_counter>
{
using base_type = components::client_base<performance_counter,
server::base_performance_counter>;
performance_counter() = default;
performance_counter(std::string const& name);
performance_counter(
std::string const& name, hpx::id_type const& locality);
performance_counter(id_type const& id)
: base_type(id)
{
}
performance_counter(future<id_type>&& id)
: base_type(std::move(id))
{
}
performance_counter(hpx::future<performance_counter>&& c)
: base_type(std::move(c))
{
}
///////////////////////////////////////////////////////////////////////
future<counter_info> get_info() const;
counter_info get_info(
launch::sync_policy, error_code& ec = throws) const;
future<counter_value> get_counter_value(bool reset = false);
counter_value get_counter_value(
launch::sync_policy, bool reset = false, error_code& ec = throws);
future<counter_value> get_counter_value() const;
counter_value get_counter_value(
launch::sync_policy, error_code& ec = throws) const;
future<counter_values_array> get_counter_values_array(
bool reset = false);
counter_values_array get_counter_values_array(
launch::sync_policy, bool reset = false, error_code& ec = throws);
future<counter_values_array> get_counter_values_array() const;
counter_values_array get_counter_values_array(
launch::sync_policy, error_code& ec = throws) const;
///////////////////////////////////////////////////////////////////////
future<bool> start();
bool start(launch::sync_policy, error_code& ec = throws);
future<bool> stop();
bool stop(launch::sync_policy, error_code& ec = throws);
future<void> reset();
void reset(launch::sync_policy, error_code& ec = throws);
future<void> reinit(bool reset = true);
void reinit(
launch::sync_policy, bool reset = true, error_code& ec = throws);
///////////////////////////////////////////////////////////////////////
future<std::string> get_name() const;
std::string get_name(
launch::sync_policy, error_code& ec = throws) const;
private:
template <typename T>
static T extract_value(future<counter_value>&& value)
{
return value.get().get_value<T>();
}
public:
template <typename T>
future<T> get_value(bool reset = false)
{
return get_counter_value(reset).then(hpx::launch::sync,
util::bind_front(&performance_counter::extract_value<T>));
}
template <typename T>
T get_value(
launch::sync_policy, bool reset = false, error_code& ec = throws)
{
return get_counter_value(launch::sync, reset).get_value<T>(ec);
}
template <typename T>
future<T> get_value() const
{
return get_counter_value().then(hpx::launch::sync,
util::bind_front(&performance_counter::extract_value<T>));
}
template <typename T>
T get_value(launch::sync_policy, error_code& ec = throws) const
{
return get_counter_value(launch::sync).get_value<T>(ec);
}
};
// Return all counters matching the given name (with optional wild cards).
HPX_EXPORT std::vector<performance_counter> discover_counters(
std::string const& name, error_code& ec = throws);
}} // namespace hpx::performance_counters
In order to implement a full performance counter, you have to create an HPX
component exposing this interface. To simplify this task, HPX provides a
ready-made base class which handles all the boiler plate of creating
a component for you. The remainder of this section will explain the process of creating a full
performance counter based on the Sine example, which you can find in the
directory examples/performance_counters/sine/.
The base class is defined in the header file [hpx_link hpx/performance_counters/base_performance_counter.hpp..hpx/performance_counters/base_performance_counter.hpp] as:
// Copyright (c) 2007-2018 Hartmut Kaiser
//
// SPDX-License-Identifier: BSL-1.0
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#pragma once
#include <hpx/config.hpp>
#include <hpx/actions_base/component_action.hpp>
#include <hpx/performance_counters/counters.hpp>
#include <hpx/performance_counters/server/base_performance_counter.hpp>
#include <hpx/runtime/components/component_type.hpp>
#include <hpx/runtime/components/server/component_base.hpp>
///////////////////////////////////////////////////////////////////////////////
//[performance_counter_base_class
namespace hpx { namespace performance_counters {
template <typename Derived>
class base_performance_counter;
}} // namespace hpx::performance_counters
//]
///////////////////////////////////////////////////////////////////////////////
namespace hpx { namespace performance_counters {
template <typename Derived>
class base_performance_counter
: public hpx::performance_counters::server::base_performance_counter
, public hpx::components::component_base<Derived>
{
private:
typedef hpx::components::component_base<Derived> base_type;
public:
typedef Derived type_holder;
typedef hpx::performance_counters::server::base_performance_counter
base_type_holder;
base_performance_counter() {}
base_performance_counter(
hpx::performance_counters::counter_info const& info)
: base_type_holder(info)
{
}
// Disambiguate finalize() which is implemented in both base classes
void finalize()
{
base_type_holder::finalize();
base_type::finalize();
}
};
}} // namespace hpx::performance_counters
The single template parameter is expected to receive the type of the derived class implementing the performance counter. In the Sine example this looks like:
// Copyright (c) 2007-2012 Hartmut Kaiser
//
// SPDX-License-Identifier: BSL-1.0
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
#pragma once
#include <hpx/hpx.hpp>
#include <hpx/include/lcos_local.hpp>
#include <hpx/include/performance_counters.hpp>
#include <hpx/include/util.hpp>
#include <cstdint>
namespace performance_counters { namespace sine { namespace server
{
///////////////////////////////////////////////////////////////////////////
//[sine_counter_definition
class sine_counter
: public hpx::performance_counters::base_performance_counter<sine_counter>
//]
{
public:
sine_counter() : current_value_(0), evaluated_at_(0) {}
explicit sine_counter(
hpx::performance_counters::counter_info const& info);
/// This function will be called in order to query the current value of
/// this performance counter
hpx::performance_counters::counter_value get_counter_value(bool reset);
/// The functions below will be called to start and stop collecting
/// counter values from this counter.
bool start();
bool stop();
/// finalize() will be called just before the instance gets destructed
void finalize();
protected:
bool evaluate();
private:
typedef hpx::lcos::local::spinlock mutex_type;
mutable mutex_type mtx_;
double current_value_;
std::uint64_t evaluated_at_;
hpx::util::interval_timer timer_;
};
}}}
i.e., the type sine_counter is derived from the base class passing the type
as a template argument (please see simplest_performance_counter.cpp
for the full source code of the counter definition). For more information about this
technique (called Curiously Recurring Template Pattern - CRTP), please see for
instance the corresponding Wikipedia article. This base
class itself is derived from the performance_counter interface described
above.
Additionally, a full performance counter implementation not only exposes the actual value but also provides information about:
The point in time a particular value was retrieved.
A (sequential) invocation count.
The actual counter value.
An optional scaling coefficient.
Information about the counter status.
Existing HPX performance counters¶
The HPX runtime system exposes a wide variety of predefined performance counters. These counters expose critical information about different modules of the runtime system. They can help determine system bottlenecks and fine-tune system and application performance.
Counter type |
Counter instance formatting |
Description |
Parameters |
where:
primary namespace services: component namespace services: locality namespace services: symbol namespace services: |
where:
The value for |
None |
Returns the total number of invocations of the specified AGAS service since its creation. |
where:
|
where:
|
None |
Returns the overall total number of invocations of all AGAS services provided by the given AGAS service category since its creation. |
where:
primary namespace services: component namespace services: locality namespace services: symbol namespace services: |
where:
The value for |
None |
Returns the overall execution time of the specified AGAS service since its creation (in nanoseconds). |
where:
|
where:
|
None |
Returns the overall execution time of all AGAS services provided by the given AGAS service category since its creation (in nanoseconds). |
|
where:
|
None |
Returns the number of cache entries resident in the AGAS cache of
the specified locality (see |
where:
|
where:
|
None |
Returns the number of cache events (evictions, hits, inserts, and misses)
in the AGAS cache of the specified locality (see
|
where:
|
where:
|
None |
Returns the number of invocations of the specified cache API function of the AGAS cache. |
where:
|
where:
|
None |
Returns the overall time spent executing of the specified API function of the AGAS cache. |
Counter type |
Counter instance formatting |
Description |
Parameters |
where:
|
where:
|
Returns the overall number of raw (uncompressed) bytes sent or received
(see The performance counters for the connection type Please see CMake variables used to configure HPX for more details. |
None |
where:
|
where:
|
Returns the total time (in nanoseconds) between the start of each
asynchronous transmission operation and the end of the corresponding
operation for the specified The performance counters for the connection type Please see CMake variables used to configure HPX for more details. |
None |
where:
|
where:
|
Returns the overall number of bytes transferred (see The performance counters for the connection type Please see CMake variables used to configure HPX for more details. |
If the configure-time option |
where:
|
where:
|
Returns the overall time spent performing outgoing data serialization for
the specified The performance counters for the connection type Please see CMake variables used to configure HPX for more details. |
If the configure-time option |
|
where:
|
Returns the overall number of routed (outbound) parcels transferred by the given locality. Routed parcels are those which cannot directly be delivered to its destination as the local AGAS is not able to resolve the destination address. In this case a parcel is sent to the AGAS service component which is responsible for creating the destination GID (and is responsible for resolving the destination address). This AGAS service component will deliver the parcel to its final target. |
If the configure-time option |
where:
|
where:
|
Returns the overall number of parcels transferred using the specified
The performance counters for the connection type Please see CMake variables used to configure HPX for more details. |
None |
where:
|
where:
|
Returns the overall number of messages 1 transferred using the
specified The performance counters for the connection type Please see CMake variables used to configure HPX for more details. |
None |
where:
<connection_type` is one of the following: |
where:
|
Returns the overall number cache events (evictions, hits, inserts,
misses, and reclaims) for the connection cache of the given connection
type on the given locality (see The performance counters for the connection type Please see CMake variables used to configure HPX for more details. |
None |
where:
|
where:
|
Returns the current number of parcels stored in the parcel queue (see
|
None |
Counter type |
Counter instance formatting |
Description |
Parameters |
|
where:
|
Returns the overall number of executed (retired) HPX-threads on the
given locality since application start. If the instance name is
|
None |
|
where:
|
Returns the average time spent executing one HPX-thread on the given
locality since application start. If the instance name is |
None |
|
where:
|
Returns the average time spent on overhead while executing one
HPX-thread on the given locality since application start. If
the instance name is |
None |
|
where:
|
Returns the overall number of executed HPX-thread phases (invocations)
on the given locality since application start. If the instance
name is |
None |
|
where:
|
Returns the average time spent executing one HPX-thread phase
(invocation) on the given locality since application start. If
the instance name is |
None |
|
where:
|
Returns the average time spent on overhead executing one HPX-thread
phase (invocation) on the given locality since application start.
If the instance name is |
None |
|
where:
|
Returns the overall time spent running the scheduler on the given
locality since application start. If the instance name is |
None |
|
where:
|
Returns the overall time spent executing all HPX-threads on the given
locality since application start. If the instance name is |
None |
|
where:
|
Returns the overall overhead time incurred executing all HPX-threads on
the given locality since application start. If the instance name
is |
None |
where:
|
where:
The |
Returns the current number of HPX-threads having the given thread state
on the given locality. If the instance name is |
None |
where:
|
where:
The |
Returns the average wait time of HPX-threads (if the thread state is
These counters are available only if the compile time constant
|
None |
|
where:
|
Returns the average idle rate for the given worker thread(s) on the given
locality. The idle rate is defined as the ratio of the time spent
on scheduling and management tasks and the overall time spent executing
work since the application started. This counter is available only if the
configuration time constant |
None |
|
where:
|
Returns the average idle rate for the given worker thread(s) on the given
locality which is caused by creating new threads. The creation idle
rate is defined as the ratio of the time spent on creating new threads and
the overall time spent executing work since the application started. This
counter is available only if the configuration time constants
|
None |
|
where:
|
Returns the average idle rate for the given worker thread(s) on the given
locality which is caused by cleaning up terminated threads. The
cleanup idle rate is defined as the ratio of the time spent on cleaning up
terminated thread objects and the overall time spent executing work since
the application started. This counter is available only if the
configuration time constants |
None |
|
where:
|
Returns the overall length of all queues for the given worker thread(s) on the given locality. |
None |
|
where:
|
Returns the total number of HPX-thread unbind (madvise) operations performed for the referenced locality. Note that this counter is not available on Windows based platforms. |
None |
|
where:
|
Returns the total number of HPX-thread recycling operations performed. |
None |
|
|
Returns the total number of HPX-threads ‘stolen’ from the pending
thread queue by a neighboring thread worker thread (these threads are
executed by a different worker thread than they were initially scheduled
on). This counter is available only if the configuration time constant
|
None |
|
where:
|
Returns the total number of times that the referenced worker-thread on
the referenced locality failed to find pending HPX-threads in
its associated queue. This counter is available only if the configuration
time constant |
None |
|
where:
|
Returns the total number of times that the referenced worker-thread on
the referenced locality looked for pending HPX-threads in its
associated queue. This counter is available only if the configuration
time constant |
None |
|
where:
|
Returns the total number of HPX-threads ‘stolen’ from the staged thread
queue by a neighboring worker thread (these threads are executed by a
different worker thread than they were initially scheduled on). This
counter is available only if the configuration time constant
|
None |
|
where:
|
Returns the total number of HPX-threads ‘stolen’ to the pending thread
queue of the worker thread (these threads are executed by a different
worker thread than they were initially scheduled on). This counter is
available only if the configuration time constant
|
None |
|
where:
|
Returns the total number of HPX-threads ‘stolen’ to the staged thread
queue of a neighboring worker thread (these threads are executed by a
different worker thread than they were initially scheduled on). This
counter is available only if the configuration time constant
|
None |
|
where:
|
Returns the total number of HPX-thread objects created. Note that thread objects are reused to improve system performance, thus this number does not reflect the number of actually executed (retired) HPX-threads. |
None |
|
where:
|
|
Percent |
|
where:
|
Returns the current (instantaneous) idle-loop count for the given HPX- worker thread or the accumulated value for all worker threads. |
None |
|
where:
|
Returns the current (instantaneous) busy-loop count for the given HPX- worker thread or the accumulated value for all worker threads. |
None |
|
where:
|
Returns the overall time spent performing background work on the given
locality since application start. If the instance name is |
None |
|
where:
|
Returns the background overhead on the given locality since application
start. If the instance name is |
None |
|
where:
|
Returns the overall time spent performing background work related to
sending parcels on the given locality since application start. If the
instance name is This counter will currently return meaningful values for the MPI parcelport only. |
None |
|
where:
|
Returns the background overhead related to sending parcels on the given
locality since application start. If the instance name is This counter will currently return meaningful values for the MPI parcelport only. |
None |
|
where:
|
Returns the overall time spent performing background work related to
receiving parcels on the given locality since application start. If the
instance name is This counter will currently return meaningful values for the MPI parcelport only. |
None |
|
where:
|
Returns the background overhead related to receiving parcels on the given
locality since application start. If the instance name is This counter will currently return meaningful values for the MPI parcelport only. |
None |
Counter type |
Counter instance formatting |
Description |
Parameters |
|
where:
|
Returns the overall number of currently active components of the specified type on the given locality. |
The type of the component. This is the string which has been used while
registering the component with HPX, e.g. which has been passed as the
second parameter to the macro |
|
|
Returns the overall (local) invocation count of the specified action type on the given locality. |
The action type. This is the string which has been used while registering
the action with HPX, e.g. which has been passed as the second parameter
to the macro |
|
where:
|
Returns the overall (remote) invocation count of the specified action type on the given locality. |
The action type. This is the string which has been used while registering
the action with HPX, e.g. which has been passed as the second parameter
to the macro |
|
where:
|
Returns the overall time since application start on the given locality in nanoseconds. |
None |
|
where:
|
Returns the amount of virtual memory currently allocated by the referenced locality (in bytes). |
None |
|
where:
|
Returns the amount of resident memory currently allocated by the referenced locality (in bytes). |
None |
|
where:
|
|
None |
|
where:
|
Returns the number of bytes read by the process (aggregate of count arguments passed to read() call or its analogues). This performance counter is available only on systems which expose the related data through the /proc file system. |
None |
|
where:
|
Returns the number of bytes written by the process (aggregate of count arguments passed to write() call or its analogues). This performance counter is available only on systems which expose the related data through the /proc file system. |
None |
|
where:
|
Returns the number of system calls that perform I/O reads. This performance counter is available only on systems which expose the related data through the /proc file system. |
None |
|
where:
|
Returns the number of system calls that perform I/O writes. This performance counter is available only on systems which expose the related data through the /proc file system. |
None |
|
where:
|
Returns the number of bytes retrieved from storage by I/O operations. This performance counter is available only on systems which expose the related data through the /proc file system. |
None |
|
where:
|
Returns the number of bytes retrieved from storage by I/O operations. This performance counter is available only on systems which expose the related data through the /proc file system. |
None |
|
where:
|
Returns the number of bytes accounted by write_bytes_transferred that has not been ultimately stored due to truncation or deletion. This performance counter is available only on systems which expose the related data through the /proc file system. |
None |
Counter type |
Counter instance formatting |
Description |
Parameters |
where:
For a full list of available PAPI events and their (short) description
use the |
where:
|
This counter returns the current count of occurrences of the specified
PAPI event. This counter is available only if the configuration time
constant |
None |
Counter type |
Counter instance formatting |
Description |
Parameters |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current average (mean) value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to two comma separated
(integer) values, where the first is the time interval (in milliseconds)
at which the underlying counter should be queried. If no value is
specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current rolling average (mean) value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to three comma
separated (integer) values, where the first is the time interval (in
milliseconds) at which the underlying counter should be queried. If no
value is specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current standard deviation (stddev) value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to two comma separated
(integer) values, where the first is the time interval (in milliseconds)
at which the underlying counter should be queried. If no value is
specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current rolling variance (stddev) value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to three comma
separated (integer) values, where the first is the time interval (in
milliseconds) at which the underlying counter should be queried. If no
value is specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current (statistically estimated) median value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to two comma separated
(integer) values, where the first is the time interval (in milliseconds)
at which the underlying counter should be queried. If no value is
specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current maximum value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to two comma separated
(integer) values, where the first is the time interval (in milliseconds)
at which the underlying counter should be queried. If no value is
specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current rolling maximum value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to three comma
separated (integer) values, where the first is the time interval (in
milliseconds) at which the underlying counter should be queried. If no
value is specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current minimum value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to two comma separated
(integer) values, where the first is the time interval (in milliseconds)
at which the underlying counter should be queried. If no value is
specified, the counter will assume |
|
Any full performance counter name. The referenced performance counter is queried at fixed time intervals as specified by the first parameter. |
Returns the current rolling minimum value calculated based on the values queried from the underlying counter (the one specified as the instance name). |
Any parameter will be interpreted as a list of up to three comma
separated (integer) values, where the first is the time interval (in
milliseconds) at which the underlying counter should be queried. If no
value is specified, the counter will assume |
Counter type |
Counter instance formatting |
Description |
Parameters |
|
None |
Returns the sum calculated based on the values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the difference calculated based on the values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the product calculated based on the values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the result of division of the values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the average value of all values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the standard deviation of all values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the median value of all values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the minimum value of all values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the maximum value of all values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
|
None |
Returns the count value of all values queried from the underlying counters (the ones specified as the parameters). |
The parameter will be interpreted as a comma separated list of full performance counter names which are queried whenever this counter is accessed. Any wildcards in the counter names will be expanded. |
Note
The /arithmetics counters can consume an arbitrary number of other
counters. For this reason those have to be specified as parameters (a comma
separated list of counters appended after a '@'). For instance:
./bin/hello_world_distributed -t2 \
--hpx:print-counter=/threads{locality#0/worker-thread#*}/count/cumulative \
--hpx:print-counter=/arithmetics/add@/threads{locality#0/worker-thread#*}/count/cumulative
hello world from OS-thread 0 on locality 0
hello world from OS-thread 1 on locality 0
/threads{locality#0/worker-thread#0}/count/cumulative,1,0.515640,[s],25
/threads{locality#0/worker-thread#1}/count/cumulative,1,0.515520,[s],36
/arithmetics/add@/threads{locality#0/worker-thread#*}/count/cumulative,1,0.516445,[s],64
Since all wildcards in the parameters are expanded, this example is fully
equivalent to specifying both counters separately to /arithmetics/add:
./bin/hello_world_distributed -t2 \
--hpx:print-counter=/threads{locality#0/worker-thread#*}/count/cumulative \
--hpx:print-counter=/arithmetics/add@\
/threads{locality#0/worker-thread#0}/count/cumulative,\
/threads{locality#0/worker-thread#1}/count/cumulative
Counter type |
Counter instance formatting |
Description |
Parameters |
|
where:
|
Returns the number of parcels handled by the message handler associated with the action which is given by the counter parameter. |
The action type. This is the string which has been used while registering
the action with HPX, e.g. which has been passed as the second parameter
to the macro |
|
where:
|
Returns the number of messages generated by the message handler associated with the action which is given by the counter parameter. |
The action type. This is the string which has been used while registering
the action with HPX, e.g. which has been passed as the second parameter
to the macro |
|
where:
|
Returns the average number of parcels sent in a message generated by the message handler associated with the action which is given by the counter parameter. |
The action type. This is the string which has been used while registering
the action with HPX, e.g. which has been passed as the second parameter
to the macro |
|
where:
|
Returns the average time between arriving parcels for the action which is given by the counter parameter. |
The action type. This is the string which has been used while registering
the action with HPX, e.g. which has been passed as the second parameter
to the macro |
|
where:
|
Returns a histogram representing the times between arriving parcels for the action which is given by the counter parameter. This counter returns an array of values, where the first three values represent the three parameters used for the histogram followed by one value for each of the histogram buckets. The first unit of measure displayed for this counter For each bucket the counter shows a value between |
The action type and optional histogram parameters. The action type is
the string which has been used while registering the action with HPX,
e.g. which has been passed as the second parameter to the macro
The action type may be followed by a comma separated list of up-to three
numbers: the lower and upper boundaries for the collected histogram, and
the number of buckets for the histogram to generate. By default these
three numbers will be assumed to be |
Note
The performance counters related to parcel coalescing are available only if
the configuration time constant HPX_WITH_PARCEL_COALESCING is set to
ON (default: ON). However, even in this case it will be available
only for actions that are enabled for parcel coalescing (see the
macros HPX_ACTION_USES_MESSAGE_COALESCING and
HPX_ACTION_USES_MESSAGE_COALESCING_NOTHROW).
APEX integration¶
HPX provides integration with APEX, which is a framework for application
profiling using task timers and various performance counters. It can be added as
a git submodule by turning on the option HPX_WITH_APEX:BOOL during
CMake configuration. TAU is an optional dependency when using APEX.
To build HPX with APEX, add HPX_WITH_APEX=ON, and,
optionally, TAU_ROOT=$PATH_TO_TAU to your CMake configuration. In
addition, you can override the tag used for APEX with the
HPX_WITH_APEX_TAG option. Please see the APEX HPX documentation for detailed
instructions on using APEX with HPX.
HPX runtime and resources¶
HPX thread scheduling policies¶
The HPX runtime has five thread scheduling policies: local-priority,
static-priority, local, static and abp-priority. These policies can be specified
from the command line using the command line option --hpx:queuing. In
order to use a particular scheduling policy, the runtime system must be built
with the appropriate scheduler flag turned on (e.g. cmake
-DHPX_THREAD_SCHEDULERS=local, see CMake variables used to configure HPX for more
information).
Priority local scheduling policy (default policy)¶
default or invoke using:
--hpx:queuinglocal-priority-fifo
The priority local scheduling policy maintains one queue per operating system
(OS) thread. The OS thread pulls its work from this queue. By default the number
of high priority queues is equal to the number of OS threads; the number of high
priority queues can be specified on the command line using
--hpx:high-priority-threads. High priority threads are executed by any
of the OS threads before any other work is executed. When a queue is empty work
will be taken from high priority queues first. There is one low priority queue
from which threads will be scheduled only when there is no other work.
For this scheduling policy there is an option to turn on NUMA sensitivity using
the command line option --hpx:numa-sensitive. When NUMA sensitivity is
turned on work stealing is done from queues associated with the same NUMA domain
first, only after that work is stolen from other NUMA domains.
This scheduler is enabled at build time by default and will be available always.
This scheduler can be used with two underlying queuing policies (FIFO:
first-in-first-out, and LIFO: last-in-first-out). The default is FIFO. In order
to use the LIFO policy use the command line option --hpx:queuing=local-priority-lifo.
Static priority scheduling policy¶
invoke using:
--hpx:queuing=static-priority(or-qs)flag to turn on for build:
HPX_THREAD_SCHEDULERS=allorHPX_THREAD_SCHEDULERS=static-priority
The static scheduling policy maintains one queue per OS thread from which each OS thread pulls its tasks (user threads). Threads are distributed in a round robin fashion. There is no thread stealing in this policy.
Local scheduling policy¶
invoke using:
--hpx:queuing=local(or-ql)flag to turn on for build:
HPX_THREAD_SCHEDULERS=allorHPX_THREAD_SCHEDULERS=local
The local scheduling policy maintains one queue per OS thread from which each OS thread pulls its tasks (user threads).
Static scheduling policy¶
invoke using:
--hpx:queuing=staticflag to turn on for build:
HPX_THREAD_SCHEDULERS=allorHPX_THREAD_SCHEDULERS=static
The static scheduling policy maintains one queue per OS thread from which each OS thread pulls its tasks (user threads). Threads are distributed in a round robin fashion. There is no thread stealing in this policy.
Priority ABP scheduling policy¶
invoke using:
--hpx:queuing=abp-priority-fifoflag to turn on for build:
HPX_THREAD_SCHEDULERS=allorHPX_THREAD_SCHEDULERS=abp-priority
Priority ABP policy maintains a double ended lock free queue for each OS thread.
By default the number of high priority queues is equal to the number of OS
threads; the number of high priority queues can be specified on the command line
using --hpx:high-priority-threads. High priority threads are executed
by the first OS threads before any other work is executed. When a queue is empty
work will be taken from high priority queues first. There is one low priority
queue from which threads will be scheduled only when there is no other work. For
this scheduling policy there is an option to turn on NUMA sensitivity using the
command line option --hpx:numa-sensitive. When NUMA sensitivity
is turned on work stealing is done from queues associated with the same NUMA
domain first, only after that work is stolen from other NUMA domains.
This scheduler can be used with two underlying queuing policies (FIFO:
first-in-first-out, and LIFO: last-in-first-out). In order to use the LIFO
policy use the command line option --hpx:queuing=abp-priority-lifo.
The HPX resource partitioner¶
The HPX resource partitioner lets you take the execution resources available
on a system—processing units, cores, and numa domains—and assign them to
thread pools. By default HPX creates a single thread pool name default.
While this is good for most use cases, the resource partitioner lets you create
multiple thread pools with custom resources and options.
Creating custom thread pools is useful for cases where you have tasks which absolutely need to run without interference from other tasks. An example of this is when using MPI for distribution instead of the built-in mechanisms in HPX (useful in legacy applications). In this case one can create a thread pool containing a single thread for MPI communication. MPI tasks will then always run on the same thread, instead of potentially being stuck in a queue behind other threads.
Note that HPX thread pools are completely independent from each other in the sense that task stealing will never happen between different thread pools. However, tasks running on a particular thread pool can schedule tasks on another thread pool.
Note
It is simpler in some situations to schedule important tasks with high priority instead of using a separate thread pool.
Using the resource partitioner¶
The hpx::resource::partitioner is now created during HPX runtime
initialization without explicit action needed from the user. To specify some of
the initialization parameters you can use the hpx::init_params.
#include <hpx/hpx_init.hpp>
#include <hpx/resource_partitioner/partitioner.hpp>
int hpx_main(int argc, char* argv[])
{
return hpx::finalize();
}
int main(int argc, char** argv)
{
// Setup the init parameters
hpx::init_params init_args;
hpx::init(argc, argv, init_args);
}
The resource partitioner callback is the interface to add thread pools to the
HPX runtime and to assign resources to the thread pools. In order to create
custom thread pools you can specify the resource partitioner callback
hpx::init_params::rp_callback which will be called once the
resource partitioner will be created , see the example below. You can also
specify other parameters, see hpx::init_params.
To add a thread pool use the
hpx::resource::partitioner::create_thread_pool method. If you
simply want to use the default scheduler and scheduler options it is enough to
call rp.create_thread_pool("my-thread-pool").
Then, to add resources to the thread pool you can use the
hpx::resource::partitioner::add_resource method. The resource
partitioner exposes the hardware topology retrieved using Portable Hardware Locality (HWLOC) and lets you
iterate through the topology to add the wanted processing units to the thread
pool. Below is an example of adding all processing units from the first NUMA
domain to a custom thread pool, unless there is only one NUMA domain in which
case we leave the first processing unit for the default thread pool:
#include <hpx/hpx_init.hpp>
#include <hpx/resource_partitioner/partitioner.hpp>
#include <iostream>
int hpx_main(int argc, char* argv[])
{
return hpx::finalize();
}
void init_resource_partitioner_handler(hpx::resource::partitioner& rp)
{
rp.create_thread_pool("my-thread-pool");
bool one_numa_domain = rp.numa_domains().size() == 1;
bool skipped_first_pu = false;
hpx::resource::numa_domain const& d = rp.numa_domains()[0];
for (const hpx::resource::core& c : d.cores())
{
for (const hpx::resource::pu& p : c.pus())
{
if (one_numa_domain && !skipped_first_pu)
{
skipped_first_pu = true;
continue;
}
rp.add_resource(p, "my-thread-pool");
}
}
}
int main(int argc, char* argv[])
{
// Set the callback to init the thread_pools
hpx::init_params init_args;
init_args.rp_callback = &init_resource_partitioner_handler;
hpx::init(argc, argv, init_args);
}
Note
Whatever processing units not assigned to a thread pool by the time
hpx::init is called will be added to the default thread pool. It
is also possible to explicitly add processing units to the default thread
pool, and to create the default thread pool manually (in order to e.g. set
the scheduler type).
Tip
The command line option --hpx:print-bind is useful for checking
that the thread pools have been set up the way you expect.
Difference between the old and new version¶
In the old version, you had to create an instance of the
resource_partitioner with argc and argv.
int main(int argc, char** argv)
{
hpx::resource::partitioner rp(argc, argv);
hpx::init();
}
From HPX 1.5.0 onwards, you just pass argc and argv to hpx::init()
or hpx::start() for the binding options to be parsed by the resource
partitioner.
int main(int argc, char** argv)
{
hpx::init_params init_args;
hpx::init(argc, argv, init_args);
}
In the old version, when creating a custom thread pool, you just called the utilities on the resource partitioner instantiated previously.
int main(int argc, char** argv)
{
hpx::resource::partitioner rp(argc, argv);
rp.create_thread_pool("my-thread-pool");
bool one_numa_domain = rp.numa_domains().size() == 1;
bool skipped_first_pu = false;
hpx::resource::numa_domain const& d = rp.numa_domains()[0];
for (const hpx::resource::core& c : d.cores())
{
for (const hpx::resource::pu& p : c.pus())
{
if (one_numa_domain && !skipped_first_pu)
{
skipped_first_pu = true;
continue;
}
rp.add_resource(p, "my-thread-pool");
}
}
hpx::init();
}
You now specify the resource partitioner callback which will tie the resources to the resource partitioner created during runtime initialization.
void init_resource_partitioner_handler(hpx::resource::partitioner& rp)
{
rp.create_thread_pool("my-thread-pool");
bool one_numa_domain = rp.numa_domains().size() == 1;
bool skipped_first_pu = false;
hpx::resource::numa_domain const& d = rp.numa_domains()[0];
for (const hpx::resource::core& c : d.cores())
{
for (const hpx::resource::pu& p : c.pus())
{
if (one_numa_domain && !skipped_first_pu)
{
skipped_first_pu = true;
continue;
}
rp.add_resource(p, "my-thread-pool");
}
}
}
int main(int argc, char* argv[])
{
hpx::init_params init_args;
init_args.rp_callback = &init_resource_partitioner_handler;
hpx::init(argc, argv, init_args);
}
Advanced usage¶
It is possible to customize the built in schedulers by passing scheduler options
to hpx::resource::partitioner::create_thread_pool. It is also possible
to create and use custom schedulers.
Note
It is not recommended to create your own scheduler. The HPX developers use
this to experiment with new scheduler designs before making them available to
users via the standard mechanisms of choosing a scheduler (command line
options). If you would like to experiment with a custom scheduler the
resource partitioner example shared_priority_queue_scheduler.cpp contains
a fully implemented scheduler with logging etc. to make exploration easier.
To choose a scheduler and custom mode for a thread pool, pass additional options when creating the thread pool like this:
rp.create_thread_pool("my-thread-pool",
hpx::resource::policies::local_priority_lifo,
hpx::policies::scheduler_mode(
hpx::policies::scheduler_mode::default |
hpx::policies::scheduler_mode::enable_elasticity));
The available schedulers are documented here:
hpx::resource::scheduling_policy, and the available scheduler modes
here: hpx::threads::policies::scheduler_mode. Also see the examples
folder for examples of advanced resource partitioner usage:
simple_resource_partitioner.cpp and
oversubscribing_resource_partitioner.cpp.
Miscellaneous¶
Error handling¶
Like in any other asynchronous invocation scheme, it is important to be able to handle error conditions occurring while the asynchronous (and possibly remote) operation is executed. In HPX all error handling is based on standard C++ exception handling. Any exception thrown during the execution of an asynchronous operation will be transferred back to the original invocation locality, where it will be rethrown during synchronization with the calling thread.
The source code for this example can be found here:
error_handling.cpp.
Working with exceptions¶
For the following description assume that the function raise_exception()
is executed by invoking the plain action raise_exception_type.
#include <hpx/modules/runtime_local.hpp>
//[error_handling_raise_exception
void raise_exception()
{
The exception is thrown using the macro HPX_THROW_EXCEPTION. The type
of the thrown exception is hpx::exception. This associates
additional diagnostic information with the exception, such as file name and line
number, locality id and thread id, and stack backtrace from the point
where the exception was thrown.
Any exception thrown during the execution of an action is transferred back to
the (asynchronous) invocation site. It will be rethrown in this context when the
calling thread tries to wait for the result of the action by invoking either
future<>::get() or the synchronous action invocation wrapper as shown here:
///////////////////////////////////////////////////////////////////////
// Error reporting using exceptions
//[exception_diagnostic_information
hpx::cout << "Error reporting using exceptions\n";
try {
// invoke raise_exception() which throws an exception
raise_exception_action do_it;
do_it(hpx::find_here());
}
catch (hpx::exception const& e) {
// Print just the essential error information.
hpx::cout << "caught exception: " << e.what() << "\n\n";
// Print all of the available diagnostic information as stored with
// the exception.
hpx::cout << "diagnostic information:"
Note
The exception is transferred back to the invocation site even if it is executed on a different locality.
Additionally, this example demonstrates how an exception thrown by an (possibly
remote) action can be handled. It shows the use of
hpx::diagnostic_information, which retrieves all available diagnostic
information from the exception as a formatted string. This includes, for
instance, the name of the source file and line number, the sequence number of
the OS thread and the HPX thread id, the locality id and the stack
backtrace of the point where the original exception was thrown.
Under certain circumstances it is desirable to output only some of the diagnostics, or to output those using different formatting. For this case, HPX exposes a set of lower-level functions as demonstrated in the following code snippet:
// Detailed error reporting using exceptions
//[exception_diagnostic_elements
hpx::cout << "Detailed error reporting using exceptions\n";
try {
// Invoke raise_exception() which throws an exception.
raise_exception_action do_it;
do_it(hpx::find_here());
}
catch (hpx::exception const& e) {
// Print the elements of the diagnostic information separately.
hpx::cout << "{what}: " << hpx::get_error_what(e) << "\n";
hpx::cout << "{locality-id}: " << hpx::get_error_locality_id(e) << "\n";
hpx::cout << "{hostname}: " << hpx::get_error_host_name(e) << "\n";
hpx::cout << "{pid}: " << hpx::get_error_process_id(e) << "\n";
hpx::cout << "{function}: " << hpx::get_error_function_name(e) << "\n";
hpx::cout << "{file}: " << hpx::get_error_file_name(e) << "\n";
hpx::cout << "{line}: " << hpx::get_error_line_number(e) << "\n";
hpx::cout << "{os-thread}: " << hpx::get_error_os_thread(e) << "\n";
hpx::cout << "{thread-id}: " << std::hex << hpx::get_error_thread_id(e)
<< "\n";
hpx::cout << "{thread-description}: "
<< hpx::get_error_thread_description(e) << "\n";
hpx::cout << "{state}: " << std::hex << hpx::get_error_state(e)
<< "\n";
hpx::cout << "{stack-trace}: " << hpx::get_error_backtrace(e) << "\n";
Working with error codes¶
Most of the API functions exposed by HPX can be invoked in two different
modes. By default those will throw an exception on error as described above.
However, sometimes it is desirable not to throw an exception in case of an error
condition. In this case an object instance of the hpx::error_code
type can be passed as the last argument to the API function. In case of an error,
the error condition will be returned in that hpx::error_code
instance. The following example demonstrates extracting the full diagnostic
information without exception handling:
// Error reporting using error code
{
//[error_handling_diagnostic_information
hpx::cout << "Error reporting using error code\n";
// Create a new error_code instance.
hpx::error_code ec;
// If an instance of an error_code is passed as the last argument while
// invoking the action, the function will not throw in case of an error
// but store the error information in this error_code instance instead.
raise_exception_action do_it;
do_it(hpx::find_here(), ec);
if (ec) {
// Print just the essential error information.
hpx::cout << "returned error: " << ec.get_message() << "\n";
// Print all of the available diagnostic information as stored with
// the exception.
hpx::cout << "diagnostic information:"
<< hpx::diagnostic_information(ec) << "\n";
Note
The error information is transferred back to the invocation site even if it is executed on a different locality.
This example show how an error can be handled without having to resolve to
exceptions and that the returned hpx::error_code instance can be
used in a very similar way as the hpx::exception type above. Simply
pass it to the hpx::diagnostic_information, which retrieves all
available diagnostic information from the error code instance as a formatted
string.
As for handling exceptions, when working with error codes, under certain circumstances it is desirable to output only some of the diagnostics, or to output those using different formatting. For this case, HPX exposes a set of lower-level functions usable with error codes as demonstrated in the following code snippet:
// Detailed error reporting using error code
{
//[error_handling_diagnostic_elements
hpx::cout << "Detailed error reporting using error code\n";
// Create a new error_code instance.
hpx::error_code ec;
// If an instance of an error_code is passed as the last argument while
// invoking the action, the function will not throw in case of an error
// but store the error information in this error_code instance instead.
raise_exception_action do_it;
do_it(hpx::find_here(), ec);
if (ec) {
// Print the elements of the diagnostic information separately.
hpx::cout << "{what}: " << hpx::get_error_what(ec) << "\n";
hpx::cout << "{locality-id}: " << hpx::get_error_locality_id(ec) << "\n";
hpx::cout << "{hostname}: " << hpx::get_error_host_name(ec) << "\n";
hpx::cout << "{pid}: " << hpx::get_error_process_id(ec) << "\n";
hpx::cout << "{function}: " << hpx::get_error_function_name(ec)
<< "\n";
hpx::cout << "{file}: " << hpx::get_error_file_name(ec) << "\n";
hpx::cout << "{line}: " << hpx::get_error_line_number(ec) << "\n";
hpx::cout << "{os-thread}: " << hpx::get_error_os_thread(ec) << "\n";
hpx::cout << "{thread-id}: " << std::hex
<< hpx::get_error_thread_id(ec) << "\n";
hpx::cout << "{thread-description}: "
<< hpx::get_error_thread_description(ec) << "\n\n";
hpx::cout << "{state}: " << std::hex << hpx::get_error_state(ec)
<< "\n";
hpx::cout << "{stack-trace}: " << hpx::get_error_backtrace(ec) << "\n";
hpx::cout << "{env}: " << hpx::get_error_env(ec) << "\n";
For more information please refer to the documentation of
hpx::get_error_what, hpx::get_error_locality_id,
hpx::get_error_host_name, hpx::get_error_process_id,
hpx::get_error_function_name, hpx::get_error_file_name,
hpx::get_error_line_number, hpx::get_error_os_thread,
hpx::get_error_thread_id,
hpx::get_error_thread_description,
hpx::get_error_backtrace, hpx::get_error_env, and
hpx::get_error_state.
Lightweight error codes¶
Sometimes it is not desirable to collect all the ambient information about the error at the point where it happened as this might impose too much overhead for simple scenarios. In this case, HPX provides a lightweight error code facility that will hold the error code only. The following snippet demonstrates its use:
// Error reporting using lightweight error code
{
//[lightweight_error_handling_diagnostic_information
hpx::cout << "Error reporting using an lightweight error code\n";
// Create a new error_code instance.
hpx::error_code ec(hpx::lightweight);
// If an instance of an error_code is passed as the last argument while
// invoking the action, the function will not throw in case of an error
// but store the error information in this error_code instance instead.
raise_exception_action do_it;
do_it(hpx::find_here(), ec);
if (ec) {
// Print just the essential error information.
hpx::cout << "returned error: " << ec.get_message() << "\n";
// Print all of the available diagnostic information as stored with
// the exception.
hpx::cout << "error code:" << ec.value() << "\n";
All functions that retrieve other diagnostic elements from the
hpx::error_code will fail if called with a lightweight error_code
instance.
Utilities in HPX¶
In order to ease the burden of programming, HPX provides several utilities to users. The following section documents those facilies.
Checkpoint¶
See checkpoint.
The HPX I/O-streams component¶
The HPX I/O-streams subsystem extends the standard C++ output streams
std::cout and std::cerr to work in the distributed setting of an HPX
application. All of the output streamed to hpx::cout will be dispatched to
std::cout on the console locality. Likewise, all output generated
from hpx::cerr will be dispatched to std::cerr on the console
locality.
Note
All existing standard manipulators can be used in conjunction with
hpx::cout and hpx::cerr Historically, HPX also defines
hpx::endl and hpx::flush but those are just aliases for the
corresponding standard manipulators.
In order to use either hpx::cout or hpx::cerr, application codes need to
#include <hpx/include/iostreams.hpp>. For an example, please see the
following ‘Hello world’ program:
// Copyright (c) 2007-2012 Hartmut Kaiser
//
// SPDX-License-Identifier: BSL-1.0
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
///////////////////////////////////////////////////////////////////////////////
// The purpose of this example is to execute a HPX-thread printing
// "Hello World!" once. That's all.
//[hello_world_1_getting_started
// 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" << hpx::flush;
return 0;
}
//]
Additionally, those applications need to link with the iostreams component. When
using CMake this can be achieved by using the COMPONENT_DEPENDENCIES
parameter; for instance:
include(HPX_AddExecutable)
add_hpx_executable(
hello_world
SOURCES hello_world.cpp
COMPONENT_DEPENDENCIES iostreams
)
Note
The hpx::cout and hpx::cerr streams buffer all output locally until a
std::endl or std::flush is encountered. That means that no output
will appear on the console as long as either of these is explicitly used.
Troubleshooting¶
This section contains commonly encountered problems when compiling or using HPX.
Undefined reference to boost::program_options¶
Boost.ProgramOptions is not ABI compatible between all C++ versions and compilers. Because of this you may see linker errors similar to this:
...: undefined reference to `boost::program_options::operator<<(std::ostream&, boost::program_options::options_description const&)'
if you are not linking to a compatible version of Boost.ProgramOptions. We
recommend that you use hpx::program_options, which is part of HPX, as a
replacement for boost::program_options (see program_options).
Until you have migrated to use hpx::program_options we recommend that you
always build Boost libraries and HPX with the same compiler and C++
standard.
Undefined reference to hpx::cout¶
You may see an linker error message that looks a bit like this:
hello_world.cpp:(.text+0x5aa): undefined reference to `hpx::cout'
hello_world.cpp:(.text+0x5c3): undefined reference to `hpx::iostreams::flush'
This usually happens if you are trying to use HPX iostreams functionality such
as hpx::cout but are not linking against it. The iostreams functionality is
not part of the core HPX library, and must be linked to explicitly. Typically
this can be solved by adding COMPONENT_DEPENDENCIES iostreams to a call to
add_hpx_library/add_hpx_executable/hpx_setup_target if using CMake. See
Creating HPX projects for more details.
Additional material¶
2-day workshop held at CSCS in 2016
Overview¶
HPX is organized into different sub-libraries. Those libraries can be seen as
independent modules, with clear dependencies and no cycles. As an end-user, the
use of these modules is completely transparent. If you use e.g.
add_hpx_executable to create a target in your project you will automatically
get all modules as dependencies. See All modules for a list of the
available modules.
All modules¶
actions¶
TODO: High-level description of the library.
See the API reference of this module for more details.
actions_base¶
TODO: High-level description of the library.
See the API reference of this module for more details.
affinity¶
The affinity module contains helper functionality for mapping worker threads to hardware resources.
See the API reference of the module for more details.
algorithms¶
The algorithms module exposes the full set of algorithms defined by the C++ standard. There is also partial support for C++ ranges.
See the API reference of the module for more details.
allocator_support¶
This module provides utilities for allocators. It contains
hpx::util::internal_allocator which directly forwards allocation
calls to jemalloc. This utility is is mainly useful on Windows.
See the API reference of the module for more details.
asio¶
The asio module is a thin wrapper around the Boost.ASIO library, providing a few additional helper functions.
See the API reference of the module for more details.
assertion¶
The assertion library implements the macros HPX_ASSERT and
HPX_ASSERT_MSG. Those two macros can be used to implement assertions
which are turned of during a release build.
By default, the location and function where the assert has been called from are
displayed when the assertion fires. This behavior can be modified by using
hpx::assertion::set_assertion_handler. When HPX initializes, it uses
this function to specify a more elaborate assertion handler. If your application
needs to customize this, it needs to do so before calling
hpx::hpx_init, hpx::hpx_main or using the C-main
wrappers.
See the API reference of the module for more details.
async_base¶
The async_base module defines the basic functionality for spawning tasks on thread pools. This module does not implement any functionality on its own, but is extended by async_local and libs_async_distributed with implementations for the local and distributed cases.
See the API reference of this module for more details.
async_combinators¶
This module contains combinators for futures. The when_* functions allow you
to turn multiple futures into a single future which is ready when all, any,
some, or each of the given futures are ready. The wait_* combinators are
equivalent to the when_* functions except that they do not return a future.
The split_future combinator takes a single future of a container (e.g.
tuple) and turns it into a container of futures.
See lcos_local, synchronization, and async for other synchronization facilities.
See the API reference of this module for more details.
async_cuda¶
This library adds a simple API that enables the user to retrieve a future from a cuda stream. Typically, a user may launch one or more kernels and then get a future from the stream that will become ready when those kernels have completed. The act of getting a future from the cuda_stream_helper object in this library hides the creation of a cuda stream event and the attachment of this event to the promise that is backing the future returned.
The usage is best illustrated by looking at an example
// create a cuda target using device number 0,1,2...
hpx::cuda::experimental::target target(device);
// create a stream helper object
hpx::cuda::experimental::cuda_future_helper helper(device);
// launch a kernel and return a future
auto fn = &cuda_trivial_kernel<double>;
double d = 3.1415;
auto f = helper.async(fn, d);
// attach a continuation to the future
f.then([](hpx::future<void>&& f) {
std::cout << "trivial kernel completed \n";
}).get();
Kernels and CPU work may be freely intermixed/overlapped and synchronized with futures.
It is important to note that multiple kernels may be launched without fetching a future, and multiple futures may be obtained from the helper. Please refer to the unit tests and examples for further examples.
CMake variables¶
HPX_WITH_CUDA - this is a general option that will enable both HPX_WITH_ASYNC_CUDA
and HPX_WITH_CUDA_COMPUTE when turned ON.
HPX_WITH_ASYNC_CUDA=ON enables the building of this module which requires
only the presence of CUDA on the system and only exposes cuda+fuures support
(HPX_WITH_ASYNC_CUDA may be used when HPX_WITH_CUDA_COMPUTE=OFF).
HPX_WITH_CUDA_COMPUTE=ON enables building HPX compute features that allow parallel
algorithms to be passed through to the GPU/CUDA backend.
See the API reference of this module for more details.
async¶
This module contains functionality for asynchronously launching work on remote
localities: hpx::async, hpx::apply. This module extends
the local-only functions in async_local.
See the API reference of this module for more details.
async_local¶
This module extends async_base to provide local implementations of
hpx::async, hpx::apply, hpx::sync, and
hpx::dataflow.
See the API reference of this module for more details.
async_mpi¶
The MPI library is intended to simplify the process of integrating MPI based codes with the HPX runtime. Any MPI function that is asynchronous and uses an MPI_Request may be converted into an hpx::future. The syntax is designed to allow a simple replacement of the MPI call with a futurized async version that accepts an executor instead of a communicator, and returns a future instead of assigning a request. Typically, an MPI call of the form
int MPI_Isend(buf, count, datatype, rank, tag, comm, request);
becomes
hpx::future<int> f = hpx::async(executor, MPI_Isend, buf, count, datatype, rank, tag);
When the MPI operation is complete, the future will become ready. This allows communication to integrated cleanly with the rest of HPX, in particular the continuation style of programming may be used to build up more complex code. Consider the following example, that chains user processing, sends and receives using continuations…
// create an executor for MPI dispatch
hpx::mpi::experimental::executor exec(MPI_COMM_WORLD);
// post an asynchronous receive using MPI_Irecv
hpx::future<int> f_recv = hpx::async(
exec, MPI_Irecv, &data, rank, MPI_INT, rank_from, i);
// attach a continuation to run when the recv completes,
f_recv.then([=, &tokens, &counter](auto&&)
{
// call an application specific function
msg_recv(rank, size, rank_to, rank_from, tokens[i], i);
// send a new message
hpx::future<int> f_send = hpx::async(
exec, MPI_Isend, &tokens[i], 1, MPI_INT, rank_to, i);
// when that send completes
f_send.then([=, &tokens, &counter](auto&&)
{
// call an application specific function
msg_send(rank, size, rank_to, rank_from, tokens[i], i);
});
}
The example above makes use of MPI_Isend and MPI_Irecv, but any MPI function
that uses requests may be futurized in this manner.
The following is a (non exhaustive) list of MPI functions that should be supported,
though not all have been tested at the time of writing
(please report any problems to the issue tracker).
int MPI_Isend(...);
int MPI_Ibsend(...);
int MPI_Issend(...);
int MPI_Irsend(...);
int MPI_Irecv(...);
int MPI_Imrecv(...);
int MPI_Ibarrier(...);
int MPI_Ibcast(...);
int MPI_Igather(...);
int MPI_Igatherv(...);
int MPI_Iscatter(...);
int MPI_Iscatterv(...);
int MPI_Iallgather(...);
int MPI_Iallgatherv(...);
int MPI_Ialltoall(...);
int MPI_Ialltoallv(...);
int MPI_Ialltoallw(...);
int MPI_Ireduce(...);
int MPI_Iallreduce(...);
int MPI_Ireduce_scatter(...);
int MPI_Ireduce_scatter_block(...);
int MPI_Iscan(...);
int MPI_Iexscan(...);
int MPI_Ineighbor_allgather(...);
int MPI_Ineighbor_allgatherv(...);
int MPI_Ineighbor_alltoall(...);
int MPI_Ineighbor_alltoallv(...);
int MPI_Ineighbor_alltoallw(...);
Note that the HPX mpi futurization wrapper should work with any asynchronous MPI call, as long as the function signature has the last two arguments MPI_xxx(…, MPI_Comm comm, MPI_Request *request) - internally these two parameters will be substituted by the executor and future data parameters that are supplied by template instantiations inside the hpx::mpi code.
See the API reference of this module for more details.
batch_environments¶
This module allows for the detection of execution as batch jobs, a series of programs executed without user intervention. All data is preselected and will be executed according to preset parameters, such as date or completion of another task. Batch environments are especially useful for executing repetitive tasks.
HPX supports the creation of batch jobs through the Portable Batch System (PBS) and SLURM.
For more information on batch environments, see Running on batch systems and the API reference for the module.
cache¶
This module provides two cache data structures:
hpx::util::cache::local_cachehpx::util::cache::lru_cache
See the API reference of the module for more details.
checkpoint¶
A common need of users is to periodically backup an application. This practice
provides resiliency and potential restart points in code. HPX utilizes the
concept of a checkpoint to support this use case.
Found in hpx/util/checkpoint.hpp, checkpoints are defined as objects
that hold a serialized version of an object or set of objects at a particular
moment in time. This representation can be stored in memory for later use or it
can be written to disk for storage and/or recovery at a later point. In order to
create and fill this object with data, users must use a function called
save_checkpoint. In code the function looks like this:
hpx::future<hpx::util::checkpoint> hpx::util::save_checkpoint(a, b, c, ...);
save_checkpoint takes arbitrary data containers, such as int,
double, float, vector, and future, and serializes them into a
newly created checkpoint object. This function returns a future to a
checkpoint containing the data. Here’s an example of a simple use case:
using hpx::util::checkpoint;
using hpx::util::save_checkpoint;
std::vector<int> vec{1,2,3,4,5};
hpx::future<checkpoint> save_checkpoint(vec);
Once the future is ready, the checkpoint object will contain the vector
vec and its five elements.
prepare_checkpoint takes arbitrary data containers (same as for
save_checkpoint), , such as int,
double, float, vector, and future, and calculates the necessary
buffer space for the checkpoint that would be created if save_checkpoint
was called with the same arguments. This function returns a future to a
checkpoint that is appropriately initialized. Here’s an example of a
simple use case:
using hpx::util::checkpoint;
using hpx::util::prepare_checkpoint;
std::vector<int> vec{1,2,3,4,5};
hpx::future<checkpoint> prepare_checkpoint(vec);
Once the future is ready, the checkpoint object will be initialized with an appropriately sized internal buffer.
It is also possible to modify the launch policy used by save_checkpoint.
This is accomplished by passing a launch policy as the first argument. It is
important to note that passing hpx::launch::sync will cause
save_checkpoint to return a checkpoint instead of a future to a
checkpoint. All other policies passed to save_checkpoint will return a
future to a checkpoint.
Sometimes checkpoint s must be declared before they are used.
save_checkpoint allows users to move pre-created checkpoint s into the
function as long as they are the first container passing into the function (In
the case where a launch policy is used, the checkpoint will immediately
follow the launch policy). An example of these features can be found below:
char character = 'd';
int integer = 10;
float flt = 10.01f;
bool boolean = true;
std::string str = "I am a string of characters";
std::vector<char> vec(str.begin(), str.end());
checkpoint archive;
// Test 1
// test basic functionality
hpx::shared_future<checkpoint> f_archive = save_checkpoint(
std::move(archive), character, integer, flt, boolean, str, vec);
Once users can create checkpoints they must now be able to restore the
objects they contain into memory. This is accomplished by the function
restore_checkpoint. This function takes a checkpoint and fills its data
into the containers it is provided. It is important to remember that the
containers must be ordered in the same way they were placed into the
checkpoint. For clarity see the example below:
char character2;
int integer2;
float flt2;
bool boolean2;
std::string str2;
std::vector<char> vec2;
restore_checkpoint(data, character2, integer2, flt2, boolean2, str2, vec2);
The core utility of checkpoint is in its ability to make certain data
persistent. Often, this means that the data needs to be stored in an object,
such as a file, for later use. HPX has two solutions for these issues: stream
operator overloads and access iterators.
HPX contains two stream overloads, operator<< and operator>>, to stream
data out of and into checkpoint. Here is an example of the overloads in
use below:
double a9 = 1.0, b9 = 1.1, c9 = 1.2;
std::ofstream test_file_9("test_file_9.txt");
hpx::future<checkpoint> f_9 = save_checkpoint(a9, b9, c9);
test_file_9 << f_9.get();
test_file_9.close();
double a9_1, b9_1, c9_1;
std::ifstream test_file_9_1("test_file_9.txt");
checkpoint archive9;
test_file_9_1 >> archive9;
restore_checkpoint(archive9, a9_1, b9_1, c9_1);
This is the primary way to move data into and out of a checkpoint. It is
important to note, however, that users should be cautious when using a stream
operator to load data and another function to remove it (or vice versa). Both
operator<< and operator>> rely on a .write() and a .read()
function respectively. In order to know how much data to read from the
std::istream, the operator<< will write the size of the checkpoint
before writing the checkpoint data. Correspondingly, the operator>> will
read the size of the stored data before reading the data into a new instance of
checkpoint. As long as the user employs the operator<< and
operator>> to stream the data, this detail can be ignored.
Important
Be careful when mixing operator<< and operator>> with other
facilities to read and write to a checkpoint. operator<< writes an
extra variable, and operator>> reads this variable back separately. Used
together the user will not encounter any issues and can safely ignore this
detail.
Users may also move the data into and out of a checkpoint using the exposed
.begin() and .end() iterators. An example of this use case is
illustrated below.
std::ofstream test_file_7("checkpoint_test_file.txt");
std::vector<float> vec7{1.02f, 1.03f, 1.04f, 1.05f};
hpx::future<checkpoint> fut_7 = save_checkpoint(vec7);
checkpoint archive7 = fut_7.get();
std::copy(archive7.begin(), // Write data to ofstream
archive7.end(), // ie. the file
std::ostream_iterator<char>(test_file_7));
test_file_7.close();
std::vector<float> vec7_1;
std::vector<char> char_vec;
std::ifstream test_file_7_1("checkpoint_test_file.txt");
if (test_file_7_1)
{
test_file_7_1.seekg(0, test_file_7_1.end);
auto length = test_file_7_1.tellg();
test_file_7_1.seekg(0, test_file_7_1.beg);
char_vec.resize(length);
test_file_7_1.read(char_vec.data(), length);
}
checkpoint archive7_1(std::move(char_vec)); // Write data to checkpoint
restore_checkpoint(archive7_1, vec7_1);
Checkpointing components¶
save_checkpoint and restore_checkpoint are also able to store components
inside checkpoints. This can be done in one of two ways. First a client of
the component can be passed to save_checkpoint. When the user wishes to
resurrect the component she can pass a client instance to
restore_checkpoint.
This technique is demonstrated below:
// Try to checkpoint and restore a component with a client
std::vector<int> vec3{10, 10, 10, 10, 10};
// Create a component instance through client constructor
data_client D(hpx::find_here(), std::move(vec3));
hpx::future<checkpoint> f3 = save_checkpoint(D);
// Create a new client
data_client E;
// Restore server inside client instance
restore_checkpoint(f3.get(), E);
The second way a user can save a component is by passing a shared_ptr to the
component to save_checkpoint. This component can be resurrected by creating
a new instance of the component type and passing a shared_ptr to the new
instance to restore_checkpoint.
This technique is demonstrated below:
// test checkpoint a component using a shared_ptr
std::vector<int> vec{1, 2, 3, 4, 5};
data_client A(hpx::find_here(), std::move(vec));
// Checkpoint Server
hpx::id_type old_id = A.get_id();
hpx::future<std::shared_ptr<data_server>> f_a_ptr =
hpx::get_ptr<data_server>(A.get_id());
std::shared_ptr<data_server> a_ptr = f_a_ptr.get();
hpx::future<checkpoint> f = save_checkpoint(a_ptr);
auto&& data = f.get();
// test prepare_checkpoint API
checkpoint c = prepare_checkpoint(hpx::launch::sync, a_ptr);
HPX_TEST(c.size() == data.size());
// Restore Server
// Create a new server instance
std::shared_ptr<data_server> b_server;
restore_checkpoint(data, b_server);
checkpoint_base¶
The checkpoint_base module contains lower level facilities that wrap simple check-pointing capabilities. This module does not implement special handling for futures or components, but simply serializes all arguments to or from a given container.
This module exposes the hpx::util::save_checkpoint_data,
hpx::util::restore_checkpoint_data, and hpx::util::prepare_checkpoint_data
APIs. These functions encapsulate the basic serialization functionalities
necessary to save/resore a variadic list of arguments to/from a given data
container.
See the API reference of this module for more details.
collectives¶
The collectives module exposes a set of distributed collective operations. Those can be used to exchange data between participating sites in a coordinated way. At this point the module exposes the following collective primitives:
hpx::collectives::all_reduce: performs a reduction on data from each participating site to each participating site.hpx::collectives::all_to_all: each participating site provides its element of the data to collect while all participating sites receive the data from every other site.hpx::lcos::barrier: distributed barrier.hpx::lcos::broadcast: performs a given action on all given global identifiers.hpx::lcos::fold: performs a fold with a given action on all given global identifiers.hpx::lcos::gather: gathers values from all participating sites.hpx::lcos::latch: distributed latch.hpx::lcos::reduce: performs a reduction on data from each participating site to a root site.hpx::lcos::spmd_block: performs the same operation on a local image while providing handles to the other images.
See the API reference of the module for more details.
command_line_handling¶
The command_line_handling module defines and handles the command-line options required by the HPX runtime, combining them with configuration options defined by the runtime_configuration module. The actual parsing of command line options is handled by the program_options module.
See the API reference of the module for more details.
components_base¶
TODO: High-level description of the library.
See the API reference of this module for more details.
compute¶
The compute module provides utilities for handling task and memory affinity on host systems. The compute_cuda for extensions to CUDA programmable GPU devices.
See the API reference of the module for more details.
compute_cuda¶
This module extends the compute module to handle CUDA programmable GPU devices.
See the API reference of the module for more details.
concepts¶
This module provides helpers for emulating concepts. It provides the following macros:
See the API reference of the module for more details.
concurrency¶
This module provides concurrency primitives useful for multi-threaded programming such as:
hpx::util::cache_line_dataandhpx::util::cache_aligned_data: wrappers for aligning and padding data to cache lines.various lockfree queue data structures
See the API reference of the module for more details.
config¶
The config module contains various configuration options, typically hidden behind macros that choose the correct implementation based on the compiler and other available options.
See the API reference of the module for more details.
config_registry¶
The config_registry module is a low level module providing helper functionality
for registering configuration entries to a global registry from other modules.
The hpx::config_registry::add_module_config function is used to add
configuration options, and hpx::config_registry::get_module_configs
can be used to retrieve configuration entries registered so far.
add_module_config_helper can be used to register configuration
entries through static global options.
See the API reference of this module for more details.
coroutines¶
The coroutines module provides coroutine (user-space thread) implementations for different platforms.
See the API reference of the module for more details.
datastructures¶
The datastructures module provides basic data structures (typically provided for compatibility with older C++ standards):
hpx::util::basic_anyhpx::util::optionalhpx::util::tuple
See the API reference of the module for more details.
debugging¶
This module provides helpers for demangling symbol names.
See the API reference of the module for more details.
errors¶
This module provides support for exceptions and error codes:
hpx::error
See the API reference of the module for more details.
execution¶
This library implements executors and execution policies for use with parallel algorithms and other facilities related to managing the execution of tasks.
See the API reference of the module for more details.
execution_base¶
The basic execution module is the main entry point to implement parallel and concurrent operations. It is modeled after P0443 with some additions and implementations for the described concepts. Most notably, it provides an abstraction for execution resources, execution contexts and execution agents in such a way, that it provides customization points that those aforementioned concepts can be replaced and combined with ease.
For that purpose, three virtual base classes are provided to be able to provide implementations with different properties:
resource_base: This is the abstraction for execution resources, that isfor example CPU cores or an accelerator.
context_base: An execution context uses execution resources and is ableto spawn new execution agents, as new threads of executions on the available resources.
agent_base: The execution agent represents the thread of execution, andcan be used to yield, suspend, resume or abort a thread of execution.
executors¶
The executors module exposes executors and execution policies. Most importantly, it exposes the following classes and constants:
hpx::parallel::execution::seqhpx::parallel::execution::parhpx::parallel::execution::par_unseqhpx::parallel::execution::task
See the API reference of this module for more details.
executors_distributed¶
This module provides the executor
hpx::parallel::execution::disribution_policy_executor. It allows
one to create work that is implicitly distributed over multiple localities.
See the API reference of this module for more details.
filesystem¶
This module provides a compatibility layer for the C++17 filesystem library. If
the filesystem library is available this module will simply forward its contents
into the hpx::filesystem namespace. If the library is not available it will
fall back to Boost.Filesystem instead.
See the API reference of the module for more details.
format¶
The format module exposes the format and format_to
functions for formatting strings.
See the API reference of the module for more details.
functional¶
This module provides function wrappers and helpers for managing functions and their arguments.
hpx::util::functionhpx::util::function_refhpx::util::unique_functionhpx::util::result_of
See the API reference of the module for more details.
futures¶
This module defines the hpx::lcos::future and
hpx:lcos::shared_future classes corresponding to the C++ standard
library classes std::future and std::shared_future. Note that the
specializations of hpx::lcos::future::then for executors and
execution policies are defined in the execution module.
See the API reference of this module for more details.
hardware¶
The hardware module abstracts away hardware specific details of timestamps and CPU features.
See the API reference of the module for more details.
hashing¶
The hashing module provides two hashing implementations:
See the API reference of the module for more details.
include¶
This module provides no functionality in itself. Instead it provides headers that group together other headers that often appear together. The grouping is similar to that provided by modules. We intend to deprecate these headers in favor of hpx/<modulename>.hpp headers.
See the API reference of this module for more details.
init_runtime¶
TODO: High-level description of the library.
See the API reference of this module for more details.
io_service¶
This module provides an abstraction over Boost.ASIO, combining multiple
boost::asio::io_services into a single pool.
hpx::util::io_service_pool provides a simple pool of
boost::asio::io_services with an API similar to
boost::asio::io_service.
hpx::threads::detail::io_service_thread_pool` wraps
hpx::util::io_service_pool into an interface derived from
hpx::threads::detail::thread_pool_base.
See the API reference of this module for more details.
iterator_support¶
This module provides helpers for iterators. It provides
hpx::util::iterator_facade and
hpx::util::iterator_adaptor for creating new iterators, and the
trait hpx::util::is_iterator along with more specific iterator
traits.
See the API reference of the module for more details.
itt_notify¶
This module provides support for profiling with Intel VTune.
See the API reference of this module for more details.
lcos_distributed¶
This module contains distributed LCOs. Currently the only LCO provided is :cpp:class::hpx::lcos::channel, a construct for sending values from one locality to another. See lcos_local for local LCOs.
See the API reference of this module for more details.
lcos_local¶
This module provides the following local LCOs:
hpx::lcos::local::channelhpx::lcos::local::one_element_channelhpx::lcos::local::receive_channelhpx::lcos::local::send_channelhpx::lcos::local::packaged_taskhpx::lcos::local::promisehpx::lcos::local::receive_buffer
See lcos_distributed for distributed LCOs. Basic synchronization primitives for use in HPX threads can be found in synchronization. async_combinators contains useful utility functions for combining futures.
See the API reference of this module for more details.
logging¶
This module provides useful macros for logging information.
See the API reference of the module for more details.
memory¶
Part of this module is a forked version of boost::intrusive_ptr from Boost.SmartPtr.
See the API reference of the module for more details.
mpi_base¶
This module provides helper functionality for detecting MPI environments.
See the API reference of this module for more details.
naming_base¶
This module provides a forward declaration of address_type, component_type and invalid_locality_id.
See the API reference of this module for more details.
pack_traversal¶
This module exposes the basic functionality for traversing various packs, both
synchronously and asynchronously: hpx::util::traverse_pack and
hpx::util::traverse_pack_async. It also exposes the higher level
functionality of unwrapping nested futures: hpx::util::unwrap and
its function object form hpx::util::functional::unwrap.
See the API reference of this module for more details.
performance_counters¶
This module provides the basic functionality required for defining performance counters. See Performance counters for more information about performance counters.
See the API reference of this module for more details.
plugin¶
This module provides base utilities for creating plugins.
See the API reference of the module for more details.
prefix¶
This module provides utilities for handling the prefix of an HPX application, i.e. the paths used for searching components and plugins.
See the API reference of this module for more details.
preprocessor¶
This library contains useful preprocessor macros:
See the API reference of the module for more details.
program_options¶
The module program_options is a direct fork of the Boost.ProgramOptions library
(Boost V1.70.0). For more information about this library please see here.
In order to be included as an HPX module, the Boost.ProgramOptions library has
been moved to the namespace hpx::program_options. We have also replaced all
Boost facilities the library depends on with either the equivalent facilities
from the standard library or from HPX. As a result, the HPX program_options module
is fully interface compatible with Boost.ProgramOptions (sans the hpx
namespace and the #include <hpx/modules/program_options.hpp> changes that need to be
applied to all code relying on this library).
All credit goes to Vladimir Prus, the author of the excellent Boost.ProgramOptions library. All bugs have been introduced by us.
See the API reference of the module for more details.
resiliency¶
In HPX, a program failure is a manifestation of a failing task. This module exposes several APIs that allow users to manage failing tasks in a convenient way by either replaying a failed task or by replicating a specific task.
Task replay is analogous to the Checkpoint/Restart mechanism found in conventional execution models. The key difference being localized fault detection. When the runtime detects an error, it replays the failing task as opposed to completely rolling back the entire program to the previous checkpoint.
Task replication is designed to provide reliability enhancements by replicating a set of tasks and evaluating their results to determine a consensus among them. This technique is most effective in situations where there are few tasks in the critical path of the DAG which leaves the system underutilized or where hardware or software failures may result in an incorrect result instead of an error. However, the drawback of this method is the additional computational cost incurred by repeating a task multiple times.
The following API functions are exposed:
hpx::resiliency::experimental::async_replay: This version of task replay will catch user-defined exceptions and automatically reschedule the task N times before throwing anhpx::resiliency::experimental::abort_replay_exceptionif no task is able to complete execution without an exception.hpx::resiliency::experimental::async_replay_validate: This version of replay adds an argument to async replay which receives a user-provided validation function to test the result of the task against. If the task’s output is validated, the result is returned. If the output fails the check or an exception is thrown, the task is replayed until no errors are encountered or the number of specified retries has been exceeded.hpx::resiliency::experimental::async_replicate: This is the most basic implementation of the task replication. The API returns the first result that runs without detecting any errors.hpx::resiliency::experimental::async_replicate_validate: This API additionally takes a validation function which evaluates the return values produced by the threads. The first task to compute a valid result is returned.hpx::resiliency::experimental::async_replicate_vote: This API adds a vote function to the basic replicate function. Many hardware or software failures are silent errors which do not interrupt program flow. In order to detect errors of this kind, it is necessary to run the task several times and compare the values returned by every version of the task. In order to determine which return value is “correct”, the API allows the user to provide a custom consensus function to properly form a consensus. This voting function then returns the “correct”” answer.hpx::resiliency::experimental::async_replicate_vote_validate: This combines the features of the previously discussed replicate set. Replicate vote validate allows a user to provide a validation function to filter results. Additionally, as described in replicate vote, the user can provide a “voting function” which returns the consensus formed by the voting logic.hpx::resiliency::experimental::dataflow_replay: This version of dataflow replay will catch user-defined exceptions and automatically reschedules the task N times before throwing anhpx::resiliency::experimental::abort_replay_exceptionif no task is able to complete execution without an exception. Any arguments for the executed task that are futures will cause the task invocation to be delayed until all of those futures have become ready.hpx::resiliency::experimental::dataflow_replay_validate: This version of replay adds an argument to dataflow replay which receives a user-provided validation function to test the result of the task against. If the task’s output is validated, the result is returned. If the output fails the check or an exception is thrown, the task is replayed until no errors are encountered or the number of specified retries have been exceeded. Any arguments for the executed task that are futures will cause the task invocation to be delayed until all of those futures have become ready.hpx::resiliency::experimental::dataflow_replicate: This is the most basic implementation of the task replication. The API returns the first result that runs without detecting any errors. Any arguments for the executed task that are futures will cause the task invocation to be delayed until all of those futures have become ready.hpx::resiliency::experimental::dataflow_replicate_validate: This API additionally takes a validation function which evaluates the return values produced by the threads. The first task to compute a valid result is returned. Any arguments for the executed task that are futures will cause the task invocation to be delayed until all of those futures have become ready.hpx::resiliency::experimental::dataflow_replicate_vote: This API adds a vote function to the basic replicate function. Many hardware or software failures are silent errors which do not interrupt program flow. In order to detect errors of this kind, it is necessary to run the task several times and compare the values returned by every version of the task. In order to determine which return value is “correct”, the API allows the user to provide a custom consensus function to properly form a consensus. This voting function then returns the “correct” answer. Any arguments for the executed task that are futures will cause the task invocation to be delayed until all of those futures have become ready.hpx::resiliency::experimental::dataflow_replicate_vote_validate: This combines the features of the previously discussed replicate set. Replicate vote validate allows a user to provide a validation function to filter results. Additionally, as described in replicate vote, the user can provide a “voting function” which returns the consensus formed by the voting logic. Any arguments for the executed task that are futures will cause the task invocation to be delayed until all of those futures have become ready.
See the API reference of the module for more details.
resource_partitioner¶
The resource_partitioner module defines hpx::resource::partitioner,
the class used by the runtime and users to partition available hardware
resources into thread pools. See Using the resource partitioner for more
details on using the resource partitioner in applications.
See the API reference of this module for more details.
runtime_configuration¶
This module handles the configuration options required by the runtime.
See the API reference of this module for more details.
runtime_local¶
TODO: High-level description of the library.
See the API reference of this module for more details.
schedulers¶
This module provides schedulers used by thread pools in the thread_pools module. There are currently three main schedulers:
hpx::threads::policies::local_priority_queue_schedulerhpx::threads::policies::static_priority_queue_schedulerhpx::threads::policies::shared_priority_queue_scheduler
Other schedulers are specializations or variations of the above schedulers. See the examples of the resource_partitioner module for examples of specifying a custom scheduler for a thread pool.
See the API reference of this module for more details.
segmented_algorithms¶
Segmented algorithms extend the usual parallel algorithms by providing overloads that work with distributed containers, such as partitioned vectors.
See the API reference of the module for more details.
serialization¶
This module provides serialization primitives and support for all built-in types as well as all C++ Standard Library collection and utility types. This list is extended by HPX vocabulary types with proper support for global reference counting. HPX’s mode of serialization is dervied from Boost’s serialization model and, as such, is mostly interface compatible with its Boost counterpart.
The purest form of serializing data is to copy the content of the payload bit by bit; however, this method is impractical for generic C++ types, which might be composed of more than just regular built-in types. Instead, HPX’s approach to serialization is derived from the Boost Serialization library, and is geared towards allowing the programmer of a given class explicit control and syntax of what to serialize. It is based on operator overloading of two special archive types that hold a buffer or stream to store the serialized data and is responsible for dispatching the serialization mechanism to the intrusive or non-intrusive version. The serialization process is recursive. Each member that needs to be serialized must be specified explicitly. The advantage of this approach is that the serialization code is written in C++ and leverages all necessary programming techniques. The generic, user-facing interface allows for effective application of the serialization process without obstructing the algorithms that need special code for packing and unpacking. It also allows for optimizations in the implementation of the archives.
See the API reference of the module for more details.
static_reinit¶
This module provides a simple wrapper around static variables that can be reinitialized.
See the API reference of this module for more details.
statistics¶
This module provide some statistics utilities like rolling min/max and histogram.
See the API reference of the module for more details.
string_util¶
This module contains string utilities inspired by the Boost string algorithms library.
See the API reference of this module for more details.
synchronization¶
This module provides synchronization primitives which should be used rather than the C++ standard ones in HPX threads:
hpx::lcos::local::spinlock(std::mutex compatible spinlock)hpx::lcos::local::spinlock_no_backoff(boost::mutex compatible spinlock)hpx::lcos::local::spinlock_pool
See lcos_local, async_combinators, and async for higher level synchronization facilities.
See the API reference of this module for more details.
testing¶
The testing module contains useful macros for testing. The results of tests can
be printed with hpx::util::report_errors. The following macros are
provided:
See the API reference of the module for more details.
thread_executors¶
This module provides executors implementing the executor interface proposed in N3562. These executors are deprecated.
See the API reference of this module for more details.
thread_pools¶
This module defines the thread pools and utilities used by the HPX runtime.
The only thread pool implementation provided by this module is
hpx::threads::detail::scheduled_thread_pool, which is derived from
hpx::threads::detail::thread_pool_base defined in the
threading_base module.
See the API reference of this module for more details.
thread_support¶
This module provides miscellaneous utilities for threading and concurrency.
See the API reference of the module for more details.
threading¶
This module provides the equivalents of std::thread and std::jthread
for lightweight HPX threads:
See the API reference of this module for more details.
threading_base¶
This module contains the base class definition required for threads. The base
class hpx::threads::thread_data is inherited by two specializations
for stackful and stackless threads:
hpx::threads::thread_data_stackful and
hpx::threads::thread_data_stackless. In addition, the module
defines the base classes for schedulers and thread pools:
hpx::threads::policies::scheduler_base and
hpx::threads::thread_pool_base.
See the API reference of this module for more details.
thread_manager¶
This module defines the hpx::threads::threadmanager class. This is
used by the runtime to manage the creation and destruction of thread pools. The
resource_partitioner module handles the partitioning of resources
into thread pools, but not the creation of thread pools.
See the API reference of this module for more details.
timed_execution¶
This module provides extensions to the executor interfaces defined in the execution module that allow timed submission of tasks on thread pools (at or after a specified time).
See the API reference of this module for more details.
timing¶
This module provides the timing utilities (clocks and timers).
See the API reference of the module for more details.
topology¶
This module provides the class hpx::threads::topology which
represents the hardware resources available on a node. The class is a light
wrapper around the Portable Hardware Locality (HWLOC) library. The hpx::threads::cpu_mask is
a small companion class that represents a set of resources on a node.
See the API reference of the module for more details.
type_support¶
This module provides helper facilities related to types.
See the API reference of the module for more details.
util¶
The util module provides miscellaneous standalone utilities.
See the API reference of the module for more details.
version¶
This module macros and functions for accessing version information about HPX and its dependencies.
See the API reference of this module for more details.
API reference¶
HPX follows a versioning scheme with three numbers: major.minor.patch. We
guarantee no breaking changes in the API for patch releases. Minor releases may
remove or break existing APIs, but only after a deprecation period of at least
two minor releases. In rare cases do we outright remove old and unused
functionality without a deprecation period.
We do not provide any ABI compatibility guarantees between any versions, debug and release builds, and builds with different C++ standards.
The public API of HPX is presented below. Clicking on a name brings you to the full documentation for the class or function. Including the header specified in a heading brings in the features listed under that heading.
Note
Names listed here are guaranteed stable with respect to semantic versioning. However, at the moment the list is incomplete and certain unlisted features are intended to be in the public API. While we work on completing the list, if you’re unsure about whether a particular unlisted name is part of the public API you can get into contact with us or open an issue and we’ll clarify the situation.
Public API¶
All names below are also available in the top-level hpx namespace unless
otherwise noted. The names in hpx should be preferred. The names in
sub-namespaces will eventually be removed.
Header hpx/algorithm.hpp¶
Corresponds to the C++ standard library header algorithm. See Using parallel algorithms for more information about the parallel algorithms.
Functions¶
hpx::parallel::v1::mismatchhpx::ranges::fillhpx::ranges::fill_nhpx::ranges::find_ifhpx::ranges::find_if_nothpx::ranges::move
Header hpx/any.hpp¶
Corresponds to the C++ standard library header any.
hpx::util::any is compatible with std::any.
Header hpx/assert.hpp¶
Corresponds to the C++ standard library header cassert.
HPX_ASSERT is the HPX equivalent to assert in cassert.
HPX_ASSERT can also be used in CUDA device code.
Macros¶
Header hpx/barrier.hpp¶
This header includes Header hpx/local/barrier.hpp and Header hpx/distributed/barrier.hpp.
Header hpx/local/barrier.hpp¶
Corresponds to the C++ standard library header barrier.
Classes¶
hpx::lcos::local::cpp20_barrier
Header hpx/distributed/barrier.hpp¶
Contains a distributed barrier implementation. This functionality is also
exposed through the hpx::distributed namespace. The name in
hpx::distributed should be preferred.
Classes¶
Header hpx/channel.hpp¶
This header includes Header hpx/local/channel.hpp and Header hpx/distributed/channel.hpp.
Header hpx/local/channel.hpp¶
Contains a local channel implementation.
Classes¶
hpx::lcos::local::channel
Header hpx/distributed/channel.hpp¶
Contains a distributed channel implementation. This functionality is also
exposed through the hpx::distributed namespace. The name in
hpx::distributed should be preferred.
Classes¶
hpx::lcos::channel
Header hpx/chrono.hpp¶
Corresponds to the C++ standard library header chrono.
The following replacements and extensions are provided compared to
chrono. The classes below are also available in the
hpx::chrono namespace, not in the top-level hpx namespace.
Header hpx/condition_variable.hpp¶
Corresponds to the C++ standard library header condition_variable.
Header hpx/exception.hpp¶
Corresponds to the C++ standard library header exception.
hpx::exception extends std::exception and is the base class for
all exceptions thrown in HPX. HPX_THROW_EXCEPTION can be used to
throw HPX exceptions with file and line information attached to the exception.
Macros¶
Classes¶
Header hpx/execution.hpp¶
Corresponds to the C++ standard library header execution. See High level parallel facilities, Using parallel algorithms and Executor parameters and executor parameter traits for more information about execution policies and executor parameters.
Note
These names are also available in the hpx::execution namespace, but not
in the top-level hpx namespace.
Constants¶
Classes¶
Header hpx/functional.hpp¶
Corresponds to the C++ standard library header
functional. hpx::util::function is a more
efficient and serializable replacement for std::function.
Constants¶
The following constants are also available in hpx::placeholders, not the
top-level hpx namespace.
Classes¶
hpx::util::functionhpx::util::function_refhpx::util::unique_function
Header hpx/future.hpp¶
This header includes Header hpx/local/future.hpp and Header hpx/distributed/future.hpp.
Header hpx/local/future.hpp¶
Corresponds to the C++ standard library header future. See Extended facilities for futures for more information about extensions to futures compared to the C++ standard library.
Note
All names except hpx::lcos::local::promise are also available in
the top-level hpx namespace. hpx::promise refers to
hpx::lcos::promise, a distributed variant of
hpx::lcos::local::promise, but will eventually refer to
hpx::lcos::local::promise after a deprecation period.
Classes¶
hpx::lcos::futurehpx::lcos::shared_futurehpx::lcos::local::promise
Functions¶
Examples¶
#include <hpx/assert.hpp>
#include <hpx/future.hpp>
#include <hpx/hpx_main.hpp>
#include <hpx/tuple.hpp>
#include <iostream>
#include <utility>
int main()
{
// Asynchronous execution with futures
hpx::future<void> f1 = hpx::async(hpx::launch::async, []() {});
hpx::shared_future<int> f2 =
hpx::async(hpx::launch::async, []() { return 42; });
hpx::future<int> f3 =
f2.then([](hpx::shared_future<int>&& f) { return f.get() * 3; });
hpx::lcos::local::promise<double> p;
auto f4 = p.get_future();
HPX_ASSERT(!f4.is_ready());
p.set_value(123.45);
HPX_ASSERT(f4.is_ready());
hpx::packaged_task<int()> t([]() { return 43; });
hpx::future<int> f5 = t.get_future();
HPX_ASSERT(!f5.is_ready());
t();
HPX_ASSERT(f5.is_ready());
// Fire-and-forget
hpx::apply([]() {
std::cout << "This will be printed later\n" << std::flush;
});
// Synchronous execution
hpx::sync([]() {
std::cout << "This will be printed immediately\n" << std::flush;
});
// Combinators
hpx::future<double> f6 = hpx::async([]() { return 3.14; });
hpx::future<double> f7 = hpx::async([]() { return 42.0; });
std::cout
<< hpx::when_all(f6, f7)
.then([](hpx::future<
hpx::tuple<hpx::future<double>, hpx::future<double>>>
f) {
hpx::tuple<hpx::future<double>, hpx::future<double>> t =
f.get();
double pi = hpx::get<0>(t).get();
double r = hpx::get<1>(t).get();
return pi * r * r;
})
.get()
<< std::endl;
// Easier continuations with dataflow; it waits for all future or
// shared_future arguments before executing the continuation, and also
// accepts non-future arguments
hpx::future<double> f8 = hpx::async([]() { return 3.14; });
hpx::future<double> f9 = hpx::make_ready_future(42.0);
hpx::shared_future<double> f10 = hpx::async([]() { return 123.45; });
hpx::future<hpx::tuple<double, double>> f11 = hpx::dataflow(
[](hpx::future<double> a, hpx::future<double> b,
hpx::shared_future<double> c, double d) {
return hpx::make_tuple<>(a.get() + b.get(), c.get() / d);
},
f8, f9, f10, -3.9);
// split_future gives a tuple of futures from a future of tuple
hpx::tuple<hpx::future<double>, hpx::future<double>> f12 =
hpx::split_future(std::move(f11));
std::cout << hpx::get<1>(f12).get() << std::endl;
return 0;
}
Header hpx/distributed/future.hpp¶
Contains overloads of hpx::async, hpx::apply,
hpx::sync, and hpx::dataflow that can be used with
actions. See Action invocation for more information about invoking
actions.
Note
The alias from hpx::promise to hpx::lcos::promise is
deprecated and will be removed in a future release. The alias
hpx::distributed::promise should be used in new applications.
Classes¶
hpx::lcos::promise
Functions¶
Header hpx/init.hpp¶
This header contains functionality for starting, stopping, suspending, and resuming the HPX runtime. This is the main way to explicitly start the HPX runtime. See Starting the HPX runtime for more details on starting the HPX runtime.
Classes¶
Header hpx/latch.hpp¶
This header includes Header hpx/local/latch.hpp and Header hpx/distributed/latch.hpp.
Header hpx/distributed/latch.hpp¶
Contains a distributed latch implementation. This functionality is also exposed
through the hpx::distributed namespace. The name in hpx::distributed
should be preferred.
Classes¶
Header hpx/memory.hpp¶
Corresponds to the C++ standard library header memory. It contains parallel versions of the copy, fill, move, and construct helper functions in memory. See Using parallel algorithms for more information about the parallel algorithms.
Functions¶
Header hpx/numeric.hpp¶
Corresponds to the C++ standard library header numeric. See Using parallel algorithms for more information about the parallel algorithms.
Header hpx/optional.hpp¶
Corresponds to the C++ standard library header optional.
hpx::util::optional is compatible with std::optional.
Constants¶
Classes¶
hpx::util::optional
Functions¶
Header hpx/runtime.hpp¶
This header includes Header hpx/local/runtime.hpp and Header hpx/distributed/runtime.hpp.
Header hpx/local/runtime.hpp¶
This header contains functions for accessing local runtime information.
Header hpx/distributed/runtime.hpp¶
This header contains functions for accessing distributed runtime information.
Header hpx/task_block.hpp¶
Corresponds to the task_block feature in N4411. See
Using task blocks for more details on using task blocks.
Classes¶
hpx::parallel::v2::task_block
Header hpx/thread.hpp¶
Corresponds to the C++ standard library header thread. The functionality in this header is equivalent to the standard library thread functionality, with the exception that the HPX equivalents are implemented on top of lightweight threads and the HPX runtime.
Classes¶
Header hpx/semaphore.hpp¶
Corresponds to the C++ standard library header semaphore.
Classes¶
hpx::lcos::local::cpp20_binary_semaphorehpx::lcos::local::cpp20_counting_semaphore
Header hpx/stop_token.hpp¶
Corresponds to the C++ standard library header stop_token.
Constants¶
hpx::nostopstate
Classes¶
hpx::stop_callback
Header hpx/tuple.hpp¶
Corresponds to the C++ standard library header tuple.
hpx::util::tuple can be used in CUDA device code, unlike
std::tuple.
Constants¶
Classes¶
hpx::util::tuplehpx::util::tuple_element
Functions¶
Header hpx/type_traits.hpp¶
Corresponds to the C++ standard library header
type_traits. Provides
hpx::util::invoke_result as a replacement for
std::invoke_result.
Classes¶
hpx::util::invoke_result
Header hpx/version.hpp¶
This header provides version information about HPX.
Macros¶
HPX_VERSION_MAJORHPX_VERSION_MINORHPX_VERSION_SUBMINORHPX_VERSION_FULLHPX_VERSION_DATEHPX_VERSION_TAGHPX_AGAS_VERSION
Header hpx/wrap_main.hpp¶
This header does not provide any direct functionality but is used for implicitly
using main as the runtime entry point. See Re-use the main() function as the main HPX entry point for more details
on implicitly starting the HPX runtime.
Full API¶
The full API of HPX is presented below. The listings for the public API above refer to the full documentation below.
Note
Most names listed in the full API reference are implementation details or considered unstable. They are listed mostly for completeness. If there is a particular feature you think deserves being in the public API we may consider promoting it. In general we prioritize making sure features corresponding to C++ standard library features are stable and complete.
Main HPX library¶
This lists functionality in the main HPX library that has not been moved to modules yet.
-
template<typename
Action>
structasync_result¶ - #include <colocating_distribution_policy.hpp>
- Note
This function is part of the invocation policy implemented by this class
-
template<typename
Action>
structasync_result¶ - #include <default_distribution_policy.hpp>
- Note
This function is part of the invocation policy implemented by this class
-
struct
binpacking_distribution_policy¶ - #include <binpacking_distribution_policy.hpp>
This class specifies the parameters for a binpacking distribution policy to use for creating a given number of items on a given set of localities. The binpacking policy will distribute the new objects in a way such that each of the localities will equalize the number of overall objects of this type based on a given criteria (by default this criteria is the overall number of objects of this type).
Public Functions
-
binpacking_distribution_policy()¶ Default-construct a new instance of a binpacking_distribution_policy. This policy will represent one locality (the local locality).
-
binpacking_distribution_policy
operator()(std::vector<id_type> const &locs, char const *perf_counter_name = default_binpacking_counter_name) const¶ Create a new default_distribution policy representing the given set of localities.
- Parameters
locs: [in] The list of localities the new instance should representperf_counter_name: [in] The name of the performance counter which should be used as the distribution criteria (by default the overall number of existing instances of the given component type will be used).
-
binpacking_distribution_policy
operator()(std::vector<id_type> &&locs, char const *perf_counter_name = default_binpacking_counter_name) const¶ Create a new default_distribution policy representing the given set of localities.
- Parameters
locs: [in] The list of localities the new instance should representperf_counter_name: [in] The name of the performance counter which should be used as the distribution criteria (by default the overall number of existing instances of the given component type will be used).
-
binpacking_distribution_policy
operator()(id_type const &loc, char const *perf_counter_name = default_binpacking_counter_name) const¶ Create a new default_distribution policy representing the given locality
- Parameters
loc: [in] The locality the new instance should representperf_counter_name: [in] The name of the performance counter which should be used as the distribution criteria (by default the overall number of existing instances of the given component type will be used).
-
template<typename
Component, typename ...Ts>
hpx::future<hpx::id_type>create(Ts&&... vs) const¶ Create one object on one of the localities associated by this policy instance
- Return
A future holding the global address which represents the newly created object
- Parameters
vs: [in] The arguments which will be forwarded to the constructor of the new object.
-
template<typename
Component, typename ...Ts>
hpx::future<std::vector<bulk_locality_result>>bulk_create(std::size_t count, Ts&&... vs) const¶ Create multiple objects on the localities associated by this policy instance
- Return
A future holding the list of global addresses which represent the newly created objects
- Parameters
count: [in] The number of objects to createvs: [in] The arguments which will be forwarded to the constructors of the new objects.
-
-
struct
colocating_distribution_policy¶ - #include <colocating_distribution_policy.hpp>
This class specifies the parameters for a distribution policy to use for creating a given number of items on the locality where a given object is currently placed.
Public Functions
-
colocating_distribution_policy()¶ Default-construct a new instance of a colocating_distribution_policy. This policy will represent the local locality.
-
colocating_distribution_policy
operator()(id_type const &id) const¶ Create a new colocating_distribution_policy representing the locality where the given object os current located
- Parameters
id: [in] The global address of the object with which the new instances should be colocated on
-
template<typename
Client, typenameStub>
colocating_distribution_policyoperator()(client_base<Client, Stub> const &client) const¶ Create a new colocating_distribution_policy representing the locality where the given object os current located
- Parameters
client: [in] The client side representation of the object with which the new instances should be colocated on
-
template<typename
Component, typename ...Ts>
hpx::future<hpx::id_type>create(Ts&&... vs) const¶ Create one object on the locality of the object this distribution policy instance is associated with
- Note
This function is part of the placement policy implemented by this class
- Return
A future holding the global address which represents the newly created object
- Parameters
vs: [in] The arguments which will be forwarded to the constructor of the new object.
-
template<typename
Component, typename ...Ts>
hpx::future<std::vector<bulk_locality_result>>bulk_create(std::size_t count, Ts&&... vs) const¶ Create multiple objects colocated with the object represented by this policy instance
- Note
This function is part of the placement policy implemented by this class
- Return
A future holding the list of global addresses which represent the newly created objects
- Parameters
count: [in] The number of objects to createvs: [in] The arguments which will be forwarded to the constructors of the new objects.
-
template<typename
Action, typename ...Ts>
async_result<Action>::typeasync(launch policy, Ts&&... vs) const¶
-
template<typename
Action, typenameCallback, typename ...Ts>
async_result<Action>::typeasync_cb(launch policy, Callback &&cb, Ts&&... vs) const¶ - Note
This function is part of the invocation policy implemented by this class
-
template<typename
Action, typenameContinuation, typename ...Ts>
boolapply(Continuation &&c, threads::thread_priority priority, Ts&&... vs) const¶ - Note
This function is part of the invocation policy implemented by this class
-
template<typename
Action, typename ...Ts>
boolapply(threads::thread_priority priority, Ts&&... vs) const¶
-
template<typename
Action, typenameContinuation, typenameCallback, typename ...Ts>
boolapply_cb(Continuation &&c, threads::thread_priority priority, Callback &&cb, Ts&&... vs) const¶ - Note
This function is part of the invocation policy implemented by this class
-
template<typename
Action, typenameCallback, typename ...Ts>
boolapply_cb(threads::thread_priority priority, Callback &&cb, Ts&&... vs) const¶
-
-
struct
default_distribution_policy¶ - #include <default_distribution_policy.hpp>
This class specifies the parameters for a simple distribution policy to use for creating (and evenly distributing) a given number of items on a given set of localities.
Public Functions
-
default_distribution_policy()¶ Default-construct a new instance of a default_distribution_policy. This policy will represent one locality (the local locality).
-
default_distribution_policy
operator()(std::vector<id_type> const &locs) const¶ Create a new default_distribution policy representing the given set of localities.
- Parameters
locs: [in] The list of localities the new instance should represent
-
default_distribution_policy
operator()(std::vector<id_type> &&locs) const¶ Create a new default_distribution policy representing the given set of localities.
- Parameters
locs: [in] The list of localities the new instance should represent
-
default_distribution_policy
operator()(id_type const &loc) const¶ Create a new default_distribution policy representing the given locality
- Parameters
loc: [in] The locality the new instance should represent
-
template<typename
Component, typename ...Ts>
hpx::future<hpx::id_type>create(Ts&&... vs) const¶ Create one object on one of the localities associated by this policy instance
- Note
This function is part of the placement policy implemented by this class
- Return
A future holding the global address which represents the newly created object
- Parameters
vs: [in] The arguments which will be forwarded to the constructor of the new object.
-
template<typename
Component, typename ...Ts>
hpx::future<std::vector<bulk_locality_result>>bulk_create(std::size_t count, Ts&&... vs) const¶ Create multiple objects on the localities associated by this policy instance
- Note
This function is part of the placement policy implemented by this class
- Return
A future holding the list of global addresses which represent the newly created objects
- Parameters
count: [in] The number of objects to createvs: [in] The arguments which will be forwarded to the constructors of the new objects.
-
template<typename
Action, typename ...Ts>
async_result<Action>::typeasync(launch policy, Ts&&... vs) const¶
-
template<typename
Action, typenameCallback, typename ...Ts>
async_result<Action>::typeasync_cb(launch policy, Callback &&cb, Ts&&... vs) const¶ - Note
This function is part of the invocation policy implemented by this class
-
template<typename
Action, typenameContinuation, typename ...Ts>
boolapply(Continuation &&c, threads::thread_priority priority, Ts&&... vs) const¶ - Note
This function is part of the invocation policy implemented by this class
-
template<typename
Action, typename ...Ts>
boolapply(threads::thread_priority priority, Ts&&... vs) const¶
-
template<typename
Action, typenameContinuation, typenameCallback, typename ...Ts>
boolapply_cb(Continuation &&c, threads::thread_priority priority, Callback &&cb, Ts&&... vs) const¶ - Note
This function is part of the invocation policy implemented by this class
-
template<typename
Action, typenameCallback, typename ...Ts>
boolapply_cb(threads::thread_priority priority, Callback &&cb, Ts&&... vs) const¶
-
-
namespace
hpx¶ Functions
-
std::vector<Client>
find_all_from_basename(std::string base_name, std::size_t num_ids)¶ Return all registered ids from all localities from the given base name.
This function locates all ids which were registered with the given base name. It returns a list of futures representing those ids.
Return all registered clients from all localities from the given base name.
- Return
A list of futures representing the ids which were registered using the given base name.
- Note
The futures will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.num_ids: [in] The number of registered ids to expect.
This function locates all ids which were registered with the given base name. It returns a list of futures representing those ids.
- Return
A list of futures representing the ids which were registered using the given base name.
- Note
The futures embedded in the returned client objects will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.
- Template Parameters
Client: The client type to return
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.num_ids: [in] The number of registered ids to expect.
-
std::vector<Client>
find_from_basename(std::string base_name, std::vector<std::size_t> const &ids)¶ Return registered ids from the given base name and sequence numbers.
This function locates the ids which were registered with the given base name and the given sequence numbers. It returns a list of futures representing those ids.
Return registered clients from the given base name and sequence numbers.
- Return
A list of futures representing the ids which were registered using the given base name and sequence numbers.
- Note
The futures will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.ids: [in] The sequence numbers of the registered ids.
This function locates the ids which were registered with the given base name and the given sequence numbers. It returns a list of futures representing those ids.
- Return
A list of futures representing the ids which were registered using the given base name and sequence numbers.
- Note
The futures embedded in the returned client objects will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.
- Template Parameters
Client: The client type to return
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.ids: [in] The sequence numbers of the registered ids.
-
Client
find_from_basename(std::string base_name, std::size_t sequence_nr = ~static_cast<std::size_t>(0))¶ Return registered id from the given base name and sequence number.
This function locates the id which was registered with the given base name and the given sequence number. It returns a future representing those id.
This function locates the id which was registered with the given base name and the given sequence number. It returns a future representing those id.
- Return
A representing the id which was registered using the given base name and sequence numbers.
- Note
The future will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.sequence_nr: [in] The sequence number of the registered id.
- Return
A representing the id which was registered using the given base name and sequence numbers.
- Note
The future embedded in the returned client object will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.
- Template Parameters
Client: The client type to return
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.sequence_nr: [in] The sequence number of the registered id.
-
hpx::future<bool>
register_with_basename(std::string base_name, hpx::id_type id, std::size_t sequence_nr = ~static_cast<std::size_t>(0))¶ Register the given id using the given base name.
The function registers the given ids using the provided base name.
- Return
A future representing the result of the registration operation itself.
- Note
The operation will fail if the given sequence number is not unique.
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.id: [in] The id to register using the given base name.sequence_nr: [in, optional] The sequential number to use for the registration of the id. This number has to be unique system wide for each registration using the same base name. The default is the current locality identifier. Also, the sequence numbers have to be consecutive starting from zero.
-
hpx::future<bool>
register_with_basename(std::string base_name, hpx::future<hpx::id_type> f, std::size_t sequence_nr = ~static_cast<std::size_t>(0))¶ Register the id wrapped in the given future using the given base name.
The function registers the object the given future refers to using the provided base name.
- Return
A future representing the result of the registration operation itself.
- Note
The operation will fail if the given sequence number is not unique.
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.f: [in] The future which should be registered using the given base name.sequence_nr: [in, optional] The sequential number to use for the registration of the id. This number has to be unique system wide for each registration using the same base name. The default is the current locality identifier. Also, the sequence numbers have to be consecutive starting from zero.
-
template<typename
Client, typenameStub>
hpx::future<bool>register_with_basename(std::string base_name, components::client_base<Client, Stub> &client, std::size_t sequence_nr = ~static_cast<std::size_t>(0))¶ Register the id wrapped in the given client using the given base name.
The function registers the object the given client refers to using the provided base name.
- Return
A future representing the result of the registration operation itself.
- Note
The operation will fail if the given sequence number is not unique.
- Template Parameters
Client: The client type to register
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.client: [in] The client which should be registered using the given base name.sequence_nr: [in, optional] The sequential number to use for the registration of the id. This number has to be unique system wide for each registration using the same base name. The default is the current locality identifier. Also, the sequence numbers have to be consecutive starting from zero.
-
Client
unregister_with_basename(std::string base_name, std::size_t sequence_nr = ~static_cast<std::size_t>(0))¶ Unregister the given id using the given base name.
The function unregisters the given ids using the provided base name.
Unregister the given base name.
- Return
A future representing the result of the un-registration operation itself.
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.sequence_nr: [in, optional] The sequential number to use for the un-registration. This number has to be the same as has been used with register_with_basename before.
The function unregisters the given ids using the provided base name.
- Return
A future representing the result of the un-registration operation itself.
- Template Parameters
Client: The client type to return
- Parameters
base_name: [in] The base name for which to retrieve the registered ids.sequence_nr: [in, optional] The sequential number to use for the un-registration. This number has to be the same as has been used with register_with_basename before.
-
naming::id_type
find_here(error_code &ec = throws)¶ Return the global id representing this locality.
The function find_here() can be used to retrieve the global id usable to refer to the current locality.
- Note
Generally, the id of a locality can be used for instance to create new instances of components and to invoke plain actions (global functions).
- Return
The global id representing the locality this function has been called on.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
This function will return meaningful results only if called from an HPX-thread. It will return hpx::naming::invalid_id otherwise.
- See
- Parameters
ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
naming::id_type
find_root_locality(error_code &ec = throws)¶ Return the global id representing the root locality.
The function find_root_locality() can be used to retrieve the global id usable to refer to the root locality. The root locality is the locality where the main AGAS service is hosted.
- Note
Generally, the id of a locality can be used for instance to create new instances of components and to invoke plain actions (global functions).
- Return
The global id representing the root locality for this application.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
This function will return meaningful results only if called from an HPX-thread. It will return hpx::naming::invalid_id otherwise.
- See
- Parameters
ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
std::vector<naming::id_type>
find_all_localities(error_code &ec = throws)¶ Return the list of global ids representing all localities available to this application.
The function find_all_localities() can be used to retrieve the global ids of all localities currently available to this application.
- Note
Generally, the id of a locality can be used for instance to create new instances of components and to invoke plain actions (global functions).
- Return
The global ids representing the localities currently available to this application.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
This function will return meaningful results only if called from an HPX-thread. It will return an empty vector otherwise.
- See
- Parameters
ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
std::vector<naming::id_type>
find_all_localities(components::component_type type, error_code &ec = throws)¶ Return the list of global ids representing all localities available to this application which support the given component type.
The function find_all_localities() can be used to retrieve the global ids of all localities currently available to this application which support the creation of instances of the given component type.
- Note
Generally, the id of a locality can be used for instance to create new instances of components and to invoke plain actions (global functions).
- Return
The global ids representing the localities currently available to this application which support the creation of instances of the given component type. If no localities supporting the given component type are currently available, this function will return an empty vector.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
This function will return meaningful results only if called from an HPX-thread. It will return an empty vector otherwise.
- See
- Parameters
type: [in] The type of the components for which the function should return the available localities.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
std::vector<naming::id_type>
find_remote_localities(error_code &ec = throws)¶ Return the list of locality ids of remote localities supporting the given component type. By default this function will return the list of all remote localities (all but the current locality).
The function find_remote_localities() can be used to retrieve the global ids of all remote localities currently available to this application (i.e. all localities except the current one).
- Note
Generally, the id of a locality can be used for instance to create new instances of components and to invoke plain actions (global functions).
- Return
The global ids representing the remote localities currently available to this application.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
This function will return meaningful results only if called from an HPX-thread. It will return an empty vector otherwise.
- See
- Parameters
ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
std::vector<naming::id_type>
find_remote_localities(components::component_type type, error_code &ec = throws)¶ Return the list of locality ids of remote localities supporting the given component type. By default this function will return the list of all remote localities (all but the current locality).
The function find_remote_localities() can be used to retrieve the global ids of all remote localities currently available to this application (i.e. all localities except the current one) which support the creation of instances of the given component type.
- Note
Generally, the id of a locality can be used for instance to create new instances of components and to invoke plain actions (global functions).
- Return
The global ids representing the remote localities currently available to this application.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
This function will return meaningful results only if called from an HPX-thread. It will return an empty vector otherwise.
- See
- Parameters
type: [in] The type of the components for which the function should return the available remote localities.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
naming::id_type
find_locality(components::component_type type, error_code &ec = throws)¶ Return the global id representing an arbitrary locality which supports the given component type.
The function find_locality() can be used to retrieve the global id of an arbitrary locality currently available to this application which supports the creation of instances of the given component type.
- Note
Generally, the id of a locality can be used for instance to create new instances of components and to invoke plain actions (global functions).
- Return
The global id representing an arbitrary locality currently available to this application which supports the creation of instances of the given component type. If no locality supporting the given component type is currently available, this function will return hpx::naming::invalid_id.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
This function will return meaningful results only if called from an HPX-thread. It will return hpx::naming::invalid_id otherwise.
- See
- Parameters
type: [in] The type of the components for which the function should return any available locality.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
naming::id_type
get_colocation_id(launch::sync_policy, naming::id_type const &id, error_code &ec = throws)¶ Return the id of the locality where the object referenced by the given id is currently located on.
The function hpx::get_colocation_id() returns the id of the locality where the given object is currently located.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- See
- Parameters
id: [in] The id of the object to locate.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
lcos::future<naming::id_type>
get_colocation_id(naming::id_type const &id)¶ Asynchronously return the id of the locality where the object referenced by the given id is currently located on.
- See
hpx::get_colocation_id(launch::sync_policy)
- Parameters
id: [in] The id of the object to locate.
Returns a future referring to the pointer to the underlying memory of a component.
The function hpx::get_ptr can be used to extract a future referring to the pointer to the underlying memory of a given component.
- Return
This function returns a future representing the pointer to the underlying memory for the component instance with the given id.
- Note
This function will successfully return the requested result only if the given component is currently located on the calling locality. Otherwise the function will raise an error.
- Note
The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.
- Parameters
id: [in] The global id of the component for which the pointer to the underlying memory should be retrieved.
- Template Parameters
The: only template parameter has to be the type of the server side component.
Returns a future referring to the pointer to the underlying memory of a component.
The function hpx::get_ptr can be used to extract a future referring to the pointer to the underlying memory of a given component.
- Return
This function returns a future representing the pointer to the underlying memory for the component instance with the given id.
- Note
This function will successfully return the requested result only if the given component is currently located on the calling locality. Otherwise the function will raise an error.
- Note
The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.
- Parameters
c: [in] A client side representation of the component for which the pointer to the underlying memory should be retrieved.
Returns the pointer to the underlying memory of a component.
The function hpx::get_ptr_sync can be used to extract the pointer to the underlying memory of a given component.
- Return
This function returns the pointer to the underlying memory for the component instance with the given id.
- Note
This function will successfully return the requested result only if the given component is currently located on the requesting locality. Otherwise the function will raise and error.
- Note
The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
p: [in] The parameter p represents a placeholder type to turn make the call synchronous.id: [in] The global id of the component for which the pointer to the underlying memory should be retrieved.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
- Template Parameters
The: only template parameter has to be the type of the server side component.
Returns the pointer to the underlying memory of a component.
The function hpx::get_ptr_sync can be used to extract the pointer to the underlying memory of a given component.
- Return
This function returns the pointer to the underlying memory for the component instance with the given id.
- Note
This function will successfully return the requested result only if the given component is currently located on the requesting locality. Otherwise the function will raise and error.
- Note
The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
p: [in] The parameter p represents a placeholder type to turn make the call synchronous.c: [in] A client side representation of the component for which the pointer to the underlying memory should be retrieved.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
std::string
get_locality_name()¶ Return the name of the locality this function is called on.
This function returns the name for the locality on which this function is called.
- Return
This function returns the name for the locality on which the function is called. The name is retrieved from the underlying networking layer and may be different for different parcelports.
- See
future<std::string> get_locality_name(naming::id_type const& id)
-
future<std::string>
get_locality_name(naming::id_type const &id)¶ Return the name of the referenced locality.
This function returns a future referring to the name for the locality of the given id.
- Return
This function returns the name for the locality of the given id. The name is retrieved from the underlying networking layer and may be different for different parcel ports.
- See
std::string get_locality_name()
- Parameters
id: [in] The global id of the locality for which the name should be retrieved
-
void
trigger_lco_event(naming::id_type const &id, naming::address &&addr, bool move_credits = true)¶ Trigger the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should be triggered.addr: [in] This represents the addr of the LCO which should be triggered.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
trigger_lco_event(naming::id_type const &id, bool move_credits = true)¶ Trigger the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should be triggered.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
trigger_lco_event(naming::id_type const &id, naming::address &&addr, naming::id_type const &cont, bool move_credits = true)¶ Trigger the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should be triggered.addr: [in] This represents the addr of the LCO which should be triggered.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
trigger_lco_event(naming::id_type const &id, naming::id_type const &cont, bool move_credits = true)¶ Trigger the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should be triggered.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
template<typename
Result>
voidset_lco_value(naming::id_type const &id, naming::address &&addr, Result &&t, bool move_credits = true)¶ Set the result value for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the given value.addr: [in] This represents the addr of the LCO which should be triggered.t: [in] This is the value which should be sent to the LCO.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
template<typename
Result>
std::enable_if<!std::is_same<typename util::decay<Result>::type, naming::address>::value>::typeset_lco_value(naming::id_type const &id, Result &&t, bool move_credits = true)¶ Set the result value for the (managed) LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the given value.t: [in] This is the value which should be sent to the LCO.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
template<typename
Result>
std::enable_if<!std::is_same<typename util::decay<Result>::type, naming::address>::value>::typeset_lco_value_unmanaged(naming::id_type const &id, Result &&t, bool move_credits = true)¶ Set the result value for the (unmanaged) LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the given value.t: [in] This is the value which should be sent to the LCO.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
template<typename
Result>
voidset_lco_value(naming::id_type const &id, naming::address &&addr, Result &&t, naming::id_type const &cont, bool move_credits = true)¶ Set the result value for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the given value.addr: [in] This represents the addr of the LCO which should be triggered.t: [in] This is the value which should be sent to the LCO.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
template<typename
Result>
std::enable_if<!std::is_same<typename util::decay<Result>::type, naming::address>::value>::typeset_lco_value(naming::id_type const &id, Result &&t, naming::id_type const &cont, bool move_credits = true)¶ Set the result value for the (managed) LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the given value.t: [in] This is the value which should be sent to the LCO.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
template<typename
Result>
std::enable_if<!std::is_same<typename util::decay<Result>::type, naming::address>::value>::typeset_lco_value_unmanaged(naming::id_type const &id, Result &&t, naming::id_type const &cont, bool move_credits = true)¶ Set the result value for the (unmanaged) LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the given value.t: [in] This is the value which should be sent to the LCO.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, naming::address &&addr, std::exception_ptr const &e, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.addr: [in] This represents the addr of the LCO which should be triggered.e: [in] This is the error value which should be sent to the LCO.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, naming::address &&addr, std::exception_ptr &&e, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.addr: [in] This represents the addr of the LCO which should be triggered.e: [in] This is the error value which should be sent to the LCO.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, std::exception_ptr const &e, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.e: [in] This is the error value which should be sent to the LCO.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, std::exception_ptr &&e, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.e: [in] This is the error value which should be sent to the LCO.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, naming::address &&addr, std::exception_ptr const &e, naming::id_type const &cont, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.addr: [in] This represents the addr of the LCO which should be triggered.e: [in] This is the error value which should be sent to the LCO.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, naming::address &&addr, std::exception_ptr &&e, naming::id_type const &cont, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.addr: [in] This represents the addr of the LCO which should be triggered.e: [in] This is the error value which should be sent to the LCO.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, std::exception_ptr const &e, naming::id_type const &cont, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.e: [in] This is the error value which should be sent to the LCO.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
void
set_lco_error(naming::id_type const &id, std::exception_ptr &&e, naming::id_type const &cont, bool move_credits = true)¶ Set the error state for the LCO referenced by the given id.
- Parameters
id: [in] This represents the id of the LCO which should receive the error value.e: [in] This is the error value which should be sent to the LCO.cont: [in] This represents the LCO to trigger after completion.move_credits: [in] If this is set to true then it is ok to send all credits in id along with the generated message. The default value is true.
-
template<typename Component, typename ... Ts><unspecified> hpx::new_(id_type const & locality, Ts &&... vs) Create one or more new instances of the given Component type on the specified locality.
This function creates one or more new instances of the given Component type on the specified locality and returns a future object for the global address which can be used to reference the new component instance.
- Note
This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance:
hpx::future<hpx::id_type> f = hpx::new_<some_component>(hpx::find_here(), ...); hpx::id_type id = f.get();
- Return
The function returns different types depending on its use:
If the explicit template argument Component represents a component type (
traits::is_component<Component>::valueevaluates to true), the function will return an hpx::future object instance which can be used to retrieve the global address of the newly created component.If the explicit template argument Component represents a client side object (
traits::is_client<Component>::valueevaluates to true), the function will return a new instance of that type which can be used to refer to the newly created component instance.
- Parameters
locality: [in] The global address of the locality where the new instance should be created on.vs: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.
-
template<typename Component, typename ... Ts><unspecified> hpx::local_new(Ts &&... vs) Create one new instance of the given Component type on the current locality.
This function creates one new instance of the given Component type on the current locality and returns a future object for the global address which can be used to reference the new component instance.
- Note
This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance:
hpx::future<hpx::id_type> f = hpx::local_new<some_component>(...); hpx::id_type id = f.get();
- Return
The function returns different types depending on its use:
If the explicit template argument Component represents a component type (
traits::is_component<Component>::valueevaluates to true), the function will return an hpx::future object instance which can be used to retrieve the global address of the newly created component. If the first argument ishpx::launch::syncthe function will directly return anhpx::id_type.If the explicit template argument Component represents a client side object (
traits::is_client<Component>::valueevaluates to true), the function will return a new instance of that type which can be used to refer to the newly created component instance.
- Note
The difference of this function to hpx::new_ is that it can be used in cases where the supplied arguments are non-copyable and non-movable. All operations are guaranteed to be local only.
- Parameters
vs: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.
-
template<typename Component, typename ... Ts><unspecified> hpx::new_(id_type const & locality, std::size_t count, Ts &&... vs) Create multiple new instances of the given Component type on the specified locality.
This function creates multiple new instances of the given Component type on the specified locality and returns a future object for the global address which can be used to reference the new component instance.
- Note
This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance:
hpx::future<std::vector<hpx::id_type> > f = hpx::new_<some_component[]>(hpx::find_here(), 10, ...); hpx::id_type id = f.get();
- Return
The function returns different types depending on its use:
If the explicit template argument Component represents an array of a component type (i.e. Component[], where
traits::is_component<Component>::valueevaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a global address of one of the newly created components.If the explicit template argument Component represents an array of a client side object type (i.e. Component[], where
traits::is_client<Component>::valueevaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a client side instance of the given type, each representing one of the newly created components.
- Parameters
locality: [in] The global address of the locality where the new instance should be created on.count: [in] The number of component instances to createvs: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.
-
template<typename Component, typename DistPolicy, typename ... Ts><unspecified> hpx::new_(DistPolicy const & policy, Ts &&... vs) Create one or more new instances of the given Component type based on the given distribution policy.
This function creates one or more new instances of the given Component type on the localities defined by the given distribution policy and returns a future object for global address which can be used to reference the new component instance(s).
- Note
This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance:
hpx::future<hpx::id_type> f = hpx::new_<some_component>(hpx::default_layout, ...); hpx::id_type id = f.get();
- Return
The function returns different types depending on its use:
If the explicit template argument Component represents a component type (
traits::is_component<Component>::valueevaluates to true), the function will return an hpx::future object instance which can be used to retrieve the global address of the newly created component.If the explicit template argument Component represents a client side object (
traits::is_client<Component>::valueevaluates to true), the function will return a new instance of that type which can be used to refer to the newly created component instance.
- Parameters
policy: [in] The distribution policy used to decide where to place the newly created.vs: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.
-
template<typename Component, typename DistPolicy, typename ... Ts><unspecified> hpx::new_(DistPolicy const & policy, std::size_t count, Ts &&... vs) Create multiple new instances of the given Component type on the localities as defined by the given distribution policy.
This function creates multiple new instances of the given Component type on the localities defined by the given distribution policy and returns a future object for the global address which can be used to reference the new component instance.
- Note
This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance:
hpx::future<std::vector<hpx::id_type> > f = hpx::new_<some_component[]>(hpx::default_layout, 10, ...); hpx::id_type id = f.get();
- Return
The function returns different types depending on its use:
If the explicit template argument Component represents an array of a component type (i.e. Component[], where
traits::is_component<Component>::valueevaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a global address of one of the newly created components.If the explicit template argument Component represents an array of a client side object type (i.e. Component[], where
traits::is_client<Component>::valueevaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a client side instance of the given type, each representing one of the newly created components.
- Parameters
policy: [in] The distribution policy used to decide where to place the newly created.count: [in] The number of component instances to createvs: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.
-
std::vector<Client>
-
namespace
components¶ Functions
-
template<typename
Component>
future<naming::id_type>migrate_from_storage(naming::id_type const &to_resurrect, naming::id_type const &target = naming::invalid_id)¶ Migrate the component with the given id from the specified target storage (resurrect the object)
The function migrate_from_storage<Component> will migrate the component referenced by to_resurrect from the storage facility specified where the object is currently stored on. It returns a future referring to the migrated component instance. The component instance is resurrected on the locality specified by target_locality.
- Return
A future representing the global id of the migrated component instance. This should be the same as to_resurrect.
- Parameters
to_resurrect: [in] The global id of the component to migrate.target: [in] The optional locality to resurrect the object on. By default the object is resurrected on the locality it was located on last.
- Template Parameters
The: only template argument specifies the component type of the component to migrate from the given storage facility.
-
template<typename
Component>
future<naming::id_type>migrate_to_storage(naming::id_type const &to_migrate, naming::id_type const &target_storage)¶ Migrate the component with the given id to the specified target storage
The function migrate_to_storage<Component> will migrate the component referenced by to_migrate to the storage facility specified with target_storage. It returns a future referring to the migrated component instance.
- Return
A future representing the global id of the migrated component instance. This should be the same as migrate_to.
- Parameters
to_migrate: [in] The global id of the component to migrate.target_storage: [in] The id of the storage facility to migrate this object to.
- Template Parameters
The: only template argument specifies the component type of the component to migrate to the given storage facility.
-
template<typename
Derived, typenameStub>
Derivedmigrate_to_storage(client_base<Derived, Stub> const &to_migrate, hpx::components::component_storage const &target_storage)¶ Migrate the given component to the specified target storage
The function migrate_to_storage will migrate the component referenced by to_migrate to the storage facility specified with target_storage. It returns a future referring to the migrated component instance.
- Return
A client side representation of representing of the migrated component instance. This should be the same as migrate_to.
- Parameters
to_migrate: [in] The client side representation of the component to migrate.target_storage: [in] The id of the storage facility to migrate this object to.
-
template<typename
Component>
future<naming::id_type>copy(naming::id_type const &to_copy)¶ Copy given component to the specified target locality.
The function copy<Component> will create a copy of the component referenced by to_copy on the locality specified with target_locality. It returns a future referring to the newly created component instance.
- Return
A future representing the global id of the newly (copied) component instance.
- Note
The new component instance is created on the locality of the component instance which is to be copied.
- Parameters
to_copy: [in] The global id of the component to copy
- Template Parameters
The: only template argument specifies the component type to create.
-
template<typename
Component>
future<naming::id_type>copy(naming::id_type const &to_copy, naming::id_type const &target_locality)¶ Copy given component to the specified target locality.
The function copy<Component> will create a copy of the component referenced by to_copy on the locality specified with target_locality. It returns a future referring to the newly created component instance.
- Return
A future representing the global id of the newly (copied) component instance.
- Parameters
to_copy: [in] The global id of the component to copytarget_locality: [in ] The locality where the copy should be created.
- Template Parameters
The: only template argument specifies the component type to create.
-
template<typename
Derived, typenameStub>
Derivedcopy(client_base<Derived, Stub> const &to_copy, naming::id_type const &target_locality = naming::invalid_id)¶ Copy given component to the specified target locality.
The function copy will create a copy of the component referenced by the client side object to_copy on the locality specified with target_locality. It returns a new client side object future referring to the newly created component instance.
- Return
A future representing the global id of the newly (copied) component instance.
- Note
If the second argument is omitted (or is invalid_id) the new component instance is created on the locality of the component instance which is to be copied.
- Parameters
to_copy: [in] The client side object representing the component to copytarget_locality: [in, optional] The locality where the copy should be created (default is same locality as source).
- Template Parameters
The: only template argument specifies the component type to create.
-
template<typename
Component, typenameDistPolicy>
future<naming::id_type>migrate(naming::id_type const &to_migrate, DistPolicy const &policy)¶ Migrate the given component to the specified target locality
The function migrate<Component> will migrate the component referenced by to_migrate to the locality specified with target_locality. It returns a future referring to the migrated component instance.
- Return
A future representing the global id of the migrated component instance. This should be the same as migrate_to.
- Parameters
to_migrate: [in] The client side representation of the component to migrate.policy: [in] A distribution policy which will be used to determine the locality to migrate this object to.
- Template Parameters
Component: Specifies the component type of the component to migrate.DistPolicy: Specifies the distribution policy to use to determine the destination locality.
-
template<typename
Derived, typenameStub, typenameDistPolicy>
Derivedmigrate(client_base<Derived, Stub> const &to_migrate, DistPolicy const &policy)¶ Migrate the given component to the specified target locality
The function migrate<Component> will migrate the component referenced by to_migrate to the locality specified with target_locality. It returns a future referring to the migrated component instance.
- Return
A future representing the global id of the migrated component instance. This should be the same as migrate_to.
- Parameters
to_migrate: [in] The client side representation of the component to migrate.policy: [in] A distribution policy which will be used to determine the locality to migrate this object to.
- Template Parameters
Derived: Specifies the component type of the component to migrate.DistPolicy: Specifies the distribution policy to use to determine the destination locality.
-
template<typename
Component>
future<naming::id_type>migrate(naming::id_type const &to_migrate, naming::id_type const &target_locality)¶ Migrate the component with the given id to the specified target locality
The function migrate<Component> will migrate the component referenced by to_migrate to the locality specified with target_locality. It returns a future referring to the migrated component instance.
- Return
A future representing the global id of the migrated component instance. This should be the same as migrate_to.
- Parameters
to_migrate: [in] The global id of the component to migrate.target_locality: [in] The locality where the component should be migrated to.
- Template Parameters
Component: Specifies the component type of the component to migrate.
-
template<typename
Derived, typenameStub>
Derivedmigrate(client_base<Derived, Stub> const &to_migrate, naming::id_type const &target_locality)¶ Migrate the given component to the specified target locality
The function migrate<Component> will migrate the component referenced by to_migrate to the locality specified with target_locality. It returns a future referring to the migrated component instance.
- Return
A client side representation of representing of the migrated component instance. This should be the same as migrate_to.
- Parameters
to_migrate: [in] The client side representation of the component to migrate.target_locality: [in] The id of the locality to migrate this object to.
- Template Parameters
Derived: Specifies the component type of the component to migrate.
Variables
-
char const *const
default_binpacking_counter_name= "/runtime{locality/total}/count/component@"¶
-
binpacking_distribution_policy const
binpacked¶ A predefined instance of the binpacking distribution_policy. It will represent the local locality and will place all items to create here.
-
colocating_distribution_policy const
colocated¶ A predefined instance of the co-locating distribution_policy. It will represent the local locality and will place all items to create here.
-
default_distribution_policy const
default_layout= {}¶ A predefined instance of the default distribution_policy. It will represent the local locality and will place all items to create here.
-
template<typename
-
namespace
naming¶ Functions
-
id_type
unmanaged(id_type const &id)¶ The helper function hpx::unmanaged can be used to generate a global identifier which does not participate in the automatic garbage collection.
- Return
This function returns a new global id referencing the same object as the parameter id. The only difference is that the returned global identifier does not participate in the automatic garbage collection.
- Note
This function allows to apply certain optimizations to the process of memory management in HPX. It however requires the user to take full responsibility for keeping the referenced objects alive long enough.
- Parameters
id: [in] The id to generated the unmanaged global id from This parameter can be itself a managed or a unmanaged global id.
-
id_type
-
file
migrate_from_storage.hpp - #include <hpx/config.hpp>#include <hpx/components_base/traits/is_component.hpp>#include <hpx/futures/future.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/modules/memory.hpp>#include <hpx/runtime/naming_fwd.hpp>#include <hpx/modules/naming_base.hpp>#include <hpx/runtime/agas_fwd.hpp>#include <hpx/functional/function.hpp>#include <hpx/runtime_configuration/agas_service_mode.hpp>#include <cstdint>#include <string>#include <hpx/serialization/serialization_fwd.hpp>#include <iosfwd>#include <utility>#include <hpx/config/warnings_prefix.hpp>#include <hpx/config/warnings_suffix.hpp>#include <hpx/components/component_storage/server/migrate_from_storage.hpp>#include <type_traits>
-
file
migrate_to_storage.hpp - #include <hpx/config.hpp>#include <hpx/components_base/traits/is_component.hpp>#include <hpx/futures/future.hpp>#include <hpx/runtime/components/client_base.hpp>#include <hpx/actions_base/traits/action_remote_result.hpp>#include <hpx/assert.hpp>#include <hpx/functional/bind_back.hpp>#include <hpx/futures/traits/acquire_future.hpp>#include <hpx/futures/traits/future_access.hpp>#include <hpx/futures/traits/future_traits.hpp>#include <hpx/futures/traits/is_future.hpp>#include <hpx/memory/intrusive_ptr.hpp>#include <hpx/modules/errors.hpp>#include <hpx/modules/memory.hpp>#include <hpx/runtime/agas/interface.hpp>#include <hpx/runtime/components/component_type.hpp>#include <hpx/functional/unique_function.hpp>#include <hpx/preprocessor/cat.hpp>#include <hpx/preprocessor/expand.hpp>#include <hpx/preprocessor/nargs.hpp>#include <hpx/preprocessor/stringize.hpp>#include <hpx/preprocessor/strip_parens.hpp>#include <hpx/runtime/naming_fwd.hpp>#include <hpx/thread_support/atomic_count.hpp>#include <hpx/traits/component_type_database.hpp>#include <cstdint>#include <hpx/type_support/decay.hpp>#include <string>#include <hpx/runtime/components_fwd.hpp>#include <hpx/traits/managed_component_policies.hpp>#include <hpx/type_support/always_void.hpp>#include <cstddef>#include <hpx/async_base/launch_policy.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/allocator_support/internal_allocator.hpp>#include <hpx/execution_base/register_locks.hpp>#include <hpx/execution_base/this_thread.hpp>#include <hpx/concurrency/spinlock_pool.hpp>#include <hpx/futures/traits/get_remote_result.hpp>#include <hpx/futures/traits/promise_local_result.hpp>#include <hpx/modules/itt_notify.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/serialization/traits/is_bitwise_serializable.hpp>#include <functional>#include <iosfwd>#include <mutex>#include <vector>#include <hpx/config/warnings_prefix.hpp>#include <hpx/runtime/naming/id_type_impl.hpp>#include <hpx/config/warnings_suffix.hpp>#include <boost/dynamic_bitset.hpp>#include <map>#include <utility>#include <hpx/runtime/components/make_client.hpp>#include <hpx/traits/is_client.hpp>#include <type_traits>#include <hpx/runtime/components/stubs/stub_base.hpp>#include <hpx/async_distributed/detail/async_colocated_fwd.hpp>#include <hpx/async_distributed/detail/async_implementations_fwd.hpp>#include <hpx/async_local/async_fwd.hpp>#include <hpx/runtime/naming/unmanaged.hpp>#include <hpx/serialization/serialize.hpp>#include <exception>#include <hpx/components/component_storage/component_storage.hpp>#include <hpx/components/component_storage/server/migrate_to_storage.hpp>
-
file
basename_registration_fwd.hpp - #include <hpx/config.hpp>#include <hpx/components_fwd.hpp>#include <hpx/futures/future_fwd.hpp>#include <hpx/runtime/components/make_client.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <cstddef>#include <string>#include <utility>#include <vector>
-
file
binpacking_distribution_policy.hpp - #include <hpx/config.hpp>#include <hpx/assert.hpp>#include <hpx/async_distributed/dataflow.hpp>#include <hpx/futures/future.hpp>#include <hpx/performance_counters/performance_counter.hpp>#include <hpx/runtime/components/component_type.hpp>#include <hpx/runtime/components/stubs/stub_base.hpp>#include <hpx/runtime/find_here.hpp>#include <hpx/modules/errors.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/serialization/string.hpp>#include <hpx/serialization/vector.hpp>#include <hpx/traits/is_distribution_policy.hpp>#include <cstddef>#include <type_traits>#include <hpx/functional/bind_back.hpp>#include <hpx/pack_traversal/unwrap.hpp>#include <algorithm>#include <cstdint>#include <iterator>#include <string>#include <utility>#include <vector>
-
file
colocating_distribution_policy.hpp - #include <hpx/config.hpp>#include <hpx/actions_base/traits/extract_action.hpp>#include <hpx/async_base/launch_policy.hpp>#include <hpx/async_distributed/applier/detail/apply_colocated_callback_fwd.hpp>#include <hpx/async_distributed/applier/detail/apply_colocated_fwd.hpp>#include <hpx/async_distributed/applier/detail/apply_implementations.hpp>#include <hpx/async_distributed/detail/async_colocated.hpp>#include <hpx/async_distributed/detail/async_colocated_callback.hpp>#include <hpx/async_distributed/detail/async_implementations.hpp>#include <hpx/futures/future.hpp>#include <hpx/futures/traits/promise_local_result.hpp>#include <hpx/runtime/components/client_base.hpp>#include <hpx/runtime/components/stubs/stub_base.hpp>#include <hpx/runtime/find_here.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/traits/is_distribution_policy.hpp>#include <algorithm>#include <cstddef>#include <type_traits>#include <utility>#include <vector>
-
file
component_factory.hpp Defines
-
HPX_REGISTER_COMPONENT(type, name, mode)¶ Define a component factory for a component type.
This macro is used create and to register a minimal component factory for a component type which allows it to be remotely created using the hpx::new_<> function.
This macro can be invoked with one, two or three arguments
- Parameters
type: The type parameter is a (fully decorated) type of the component type for which a factory should be defined.name: The name parameter specifies the name to use to register the factory. This should uniquely (system-wide) identify the component type. The name parameter must conform to the C++ identifier rules (without any namespace). If this parameter is not given, the first parameter is used.mode: The mode parameter has to be one of the defined enumeration values of the enumeration hpx::components::factory_state_enum. The default for this parameter is hpx::components::factory_enabled.
-
-
file
copy_component.hpp - #include <hpx/config.hpp>#include <hpx/actions_base/plain_action.hpp>#include <hpx/async_distributed/async.hpp>#include <hpx/async_distributed/detail/async_colocated.hpp>#include <hpx/components_base/traits/is_component.hpp>#include <hpx/futures/future.hpp>#include <hpx/runtime/components/server/copy_component.hpp>#include <hpx/runtime/components/stubs/runtime_support.hpp>#include <hpx/modules/errors.hpp>#include <hpx/async_distributed/detail/async_colocated_fwd.hpp>#include <hpx/runtime/components/component_type.hpp>#include <hpx/runtime/components/server/runtime_support.hpp>#include <hpx/actions/base_action.hpp>#include <hpx/actions/transfer_action.hpp>#include <hpx/actions/transfer_continuation_action.hpp>#include <hpx/actions_base/component_action.hpp>#include <hpx/assert.hpp>#include <hpx/modules/plugin.hpp>#include <hpx/modules/program_options.hpp>#include <hpx/performance_counters/counters.hpp>#include <hpx/plugins/plugin_factory_base.hpp>#include <hpx/runtime_configuration/plugin_registry_base.hpp>#include <hpx/runtime_configuration/ini.hpp>#include <hpx/type_support/pack.hpp>#include <hpx/runtime/components/server/create_component.hpp>#include <hpx/runtime/components/server/create_component_fwd.hpp>#include <hpx/runtime/naming/address.hpp>#include <cstddef>#include <cstdint>#include <utility>#include <vector>#include <hpx/runtime/components/server/component_heap.hpp>#include <hpx/static_reinit/reinitializable_static.hpp>#include <sstream>#include <hpx/runtime/find_here.hpp>#include <hpx/runtime/parcelset/locality.hpp>#include <hpx/runtime/parcelset_fwd.hpp>#include <hpx/serialization/map.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/iterator_support/traits/is_iterator.hpp>#include <map>#include <memory>#include <string>#include <type_traits>#include <hpx/config/warnings_prefix.hpp>#include <hpx/config/warnings_suffix.hpp>#include <hpx/runtime_configuration/static_factory_data.hpp>#include <hpx/synchronization/condition_variable.hpp>#include <hpx/synchronization/mutex.hpp>#include <hpx/synchronization/spinlock.hpp>#include <hpx/traits/action_does_termination_detection.hpp>#include <atomic>#include <condition_variable>#include <list>#include <mutex>#include <set>#include <thread>#include <hpx/runtime/naming/name.hpp>#include <hpx/serialization/vector.hpp>#include <hpx/type_support/decay.hpp>#include <hpx/runtime/get_ptr.hpp>#include <hpx/async_base/launch_policy.hpp>#include <hpx/components_base/get_lva.hpp>#include <hpx/components_base/traits/component_pin_support.hpp>#include <hpx/functional/bind_back.hpp>#include <hpx/runtime/agas/gva.hpp>#include <hpx/runtime/components/client_base.hpp>#include <hpx/runtime_fwd.hpp>#include <hpx/traits/component_type_is_compatible.hpp>#include <hpx/futures/traits/get_remote_result.hpp>
-
file
default_distribution_policy.hpp - #include <hpx/config.hpp>#include <hpx/actions_base/actions_base_support.hpp>#include <hpx/actions_base/traits/extract_action.hpp>#include <hpx/assert.hpp>#include <hpx/async_base/launch_policy.hpp>#include <hpx/async_distributed/applier/apply.hpp>#include <hpx/async_distributed/dataflow.hpp>#include <hpx/futures/future.hpp>#include <hpx/futures/traits/promise_local_result.hpp>#include <hpx/lcos/packaged_action.hpp>#include <hpx/actions_base/traits/action_priority.hpp>#include <hpx/allocator_support/internal_allocator.hpp>#include <hpx/async_distributed/applier/apply_callback.hpp>#include <hpx/lcos/promise.hpp>#include <hpx/memory/intrusive_ptr.hpp>#include <hpx/modules/errors.hpp>#include <hpx/modules/memory.hpp>#include <hpx/runtime/components/component_type.hpp>#include <hpx/traits/action_was_object_migrated.hpp>#include <hpx/components_base/pinned_ptr.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/type_support/detail/wrap_int.hpp>#include <type_traits>#include <utility>#include <hpx/traits/component_supports_migration.hpp>#include <hpx/traits/component_type_is_compatible.hpp>#include <boost/asio/error.hpp>#include <exception>#include <memory>#include <hpx/modules/execution.hpp>#include <hpx/runtime/components/stubs/stub_base.hpp>#include <hpx/runtime/find_here.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/serialization/shared_ptr.hpp>#include <hpx/serialization/vector.hpp>#include <hpx/traits/is_distribution_policy.hpp>#include <algorithm>#include <cstddef>#include <vector>
-
file
migrate_component.hpp - #include <hpx/config.hpp>#include <hpx/actions_base/plain_action.hpp>#include <hpx/async_distributed/async.hpp>#include <hpx/async_distributed/detail/async_colocated.hpp>#include <hpx/components_base/traits/is_component.hpp>#include <hpx/futures/future.hpp>#include <hpx/runtime/components/client_base.hpp>#include <hpx/runtime/components/server/migrate_component.hpp>#include <hpx/runtime/agas/interface.hpp>#include <hpx/runtime/components/stubs/runtime_support.hpp>#include <hpx/runtime/get_ptr.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/traits/component_supports_migration.hpp>#include <cstdint>#include <memory>#include <utility>#include <hpx/runtime/components/target_distribution_policy.hpp>#include <hpx/actions_base/actions_base_support.hpp>#include <hpx/actions_base/traits/extract_action.hpp>#include <hpx/async_base/launch_policy.hpp>#include <hpx/async_distributed/applier/detail/apply_implementations_fwd.hpp>#include <hpx/async_distributed/dataflow.hpp>#include <hpx/async_distributed/detail/async_implementations_fwd.hpp>#include <hpx/futures/traits/promise_local_result.hpp>#include <hpx/lcos/packaged_action.hpp>#include <hpx/runtime/components/stubs/stub_base.hpp>#include <hpx/runtime/find_here.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/traits/is_distribution_policy.hpp>#include <algorithm>#include <cstddef>#include <type_traits>#include <vector>
-
file
new.hpp - #include <hpx/config.hpp>#include <hpx/async_base/launch_policy.hpp>#include <hpx/components_base/traits/is_component.hpp>#include <hpx/futures/future.hpp>#include <hpx/runtime/components/client_base.hpp>#include <hpx/runtime/components/default_distribution_policy.hpp>#include <hpx/actions_base/actions_base_support.hpp>#include <hpx/actions_base/traits/extract_action.hpp>#include <hpx/assert.hpp>#include <hpx/async_distributed/applier/apply.hpp>#include <hpx/async_distributed/dataflow.hpp>#include <hpx/futures/traits/promise_local_result.hpp>#include <hpx/lcos/packaged_action.hpp>#include <hpx/modules/execution.hpp>#include <hpx/runtime/components/stubs/stub_base.hpp>#include <hpx/runtime/find_here.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/serialization/shared_ptr.hpp>#include <hpx/serialization/vector.hpp>#include <hpx/traits/is_distribution_policy.hpp>#include <algorithm>#include <cstddef>#include <memory>#include <type_traits>#include <utility>#include <vector>#include <hpx/runtime/components/server/create_component.hpp>#include <hpx/traits/is_client.hpp>#include <hpx/type_support/lazy_enable_if.hpp>
-
file
find_here.hpp - #include <hpx/config.hpp>#include <hpx/modules/errors.hpp>#include <hpx/runtime/naming/id_type.hpp>
-
file
find_localities.hpp - #include <hpx/config.hpp>#include <hpx/modules/errors.hpp>#include <hpx/runtime/components/component_type.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <vector>
-
file
get_colocation_id.hpp - #include <hpx/async_base/launch_policy.hpp>#include <hpx/futures/future_fwd.hpp>#include <hpx/modules/errors.hpp>#include <hpx/runtime/naming/id_type.hpp>
-
file
get_locality_name.hpp - #include <hpx/config.hpp>#include <hpx/modules/futures.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <string>
-
file
get_ptr.hpp - #include <hpx/config.hpp>#include <hpx/assert.hpp>#include <hpx/async_base/launch_policy.hpp>#include <hpx/components_base/get_lva.hpp>#include <hpx/components_base/traits/component_pin_support.hpp>#include <hpx/functional/bind_back.hpp>#include <hpx/modules/errors.hpp>#include <hpx/runtime/agas/gva.hpp>#include <hpx/runtime/components/component_type.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/util/ios_flags_saver.hpp>#include <cstdint>#include <hpx/runtime/components/client_base.hpp>#include <hpx/runtime/naming/address.hpp>#include <hpx/runtime/naming_fwd.hpp>#include <hpx/serialization/serialization_fwd.hpp>#include <hpx/serialization/traits/is_bitwise_serializable.hpp>#include <iosfwd>#include <hpx/config/warnings_prefix.hpp>#include <hpx/config/warnings_suffix.hpp>#include <hpx/runtime_fwd.hpp>#include <hpx/runtime_local/runtime_local_fwd.hpp>#include <hpx/traits/component_type_is_compatible.hpp>#include <memory>
-
file
unmanaged.hpp - #include <hpx/config.hpp>#include <hpx/runtime/naming/name.hpp>
-
file
set_parcel_write_handler.hpp - #include <hpx/config.hpp>
-
file
trigger_lco.hpp - #include <hpx/config.hpp>#include <hpx/actions/actions_fwd.hpp>#include <hpx/actions_base/action_priority.hpp>#include <hpx/actions_base/continuation_fwd.hpp>#include <hpx/assert.hpp>#include <hpx/async_distributed/applier/detail/apply_implementations_fwd.hpp>#include <hpx/lcos_fwd.hpp>#include <hpx/components_base/traits/is_component.hpp>#include <hpx/futures/future_fwd.hpp>#include <hpx/futures/traits/promise_local_result.hpp>#include <hpx/futures/traits/promise_remote_result.hpp>#include <vector>#include <hpx/runtime/naming/address.hpp>#include <hpx/runtime/naming/id_type.hpp>#include <hpx/runtime/naming/name.hpp>#include <hpx/type_support/decay.hpp>#include <exception>#include <type_traits>#include <utility>
-
file
runtime_fwd.hpp - #include <hpx/config.hpp>#include <hpx/runtime_local/runtime_local_fwd.hpp>
-
dir
/hpx/source/components/component_storage
-
dir
/hpx/source/components/component_storage/include/hpx/components/component_storage
-
dir
/hpx/source/hpx/runtime/components
-
dir
/hpx/source/components/component_storage/include/hpx/components
-
dir
/hpx/source/components
-
dir
/hpx/source/hpx
-
dir
/hpx/source/components/component_storage/include/hpx
-
dir
/hpx/source/components/component_storage/include
-
dir
/hpx/source/hpx/runtime/naming
-
dir
/hpx/source/hpx/runtime
-
dir
/hpx/source
actions¶
The contents of this module can be included with the header
hpx/modules/actions.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/actions.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/actions/action_support.hpp¶
Header hpx/actions/actions_fwd.hpp¶
Header hpx/actions/base_action.hpp¶
Header hpx/actions/register_action.hpp¶
Header hpx/actions/transfer_action.hpp¶
Header hpx/actions/transfer_base_action.hpp¶
Header hpx/actions/transfer_continuation_action.hpp¶
actions_base¶
The contents of this module can be included with the header
hpx/modules/actions_base.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/actions_base.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/actions_base/action_priority.hpp¶
-
namespace
hpx -
namespace
actions¶ Functions
-
template<typename
Action>
threads::thread_priorityaction_priority()¶
-
template<typename
-
namespace
Header hpx/actions_base/actions_base_fwd.hpp¶
Header hpx/actions_base/actions_base_support.hpp¶
Header hpx/actions_base/basic_action.hpp¶
Defines
-
HPX_REGISTER_ACTION_DECLARATION(...)¶ Declare the necessary component action boilerplate code.
The macro HPX_REGISTER_ACTION_DECLARATION can be used to declare all the boilerplate code which is required for proper functioning of component actions in the context of HPX.
The parameter action is the type of the action to declare the boilerplate for.
This macro can be invoked with an optional second parameter. This parameter specifies a unique name of the action to be used for serialization purposes. The second parameter has to be specified if the first parameter is not usable as a plain (non-qualified) C++ identifier, i.e. the first parameter contains special characters which cannot be part of a C++ identifier, such as ‘<’, ‘>’, or ‘:’.
namespace app { // Define a simple component exposing one action 'print_greeting' class HPX_COMPONENT_EXPORT server : public hpx::components::simple_component_base<server> { void print_greeting () { hpx::cout << "Hey, how are you?\n" << hpx::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);
- Example:
- Note
This macro has to be used once for each of the component actions defined using one of the HPX_DEFINE_COMPONENT_ACTION macros. It has to be visible in all translation units using the action, thus it is recommended to place it into the header file defining the component.
-
HPX_REGISTER_ACTION_DECLARATION_(...)¶
-
HPX_REGISTER_ACTION_DECLARATION_1(action)¶
-
HPX_REGISTER_ACTION(...)¶ Define the necessary component action boilerplate code.
The macro HPX_REGISTER_ACTION can be used to define all the boilerplate code which is required for proper functioning of component actions in the context of HPX.
The parameter action is the type of the action to define the boilerplate for.
This macro can be invoked with an optional second parameter. This parameter specifies a unique name of the action to be used for serialization purposes. The second parameter has to be specified if the first parameter is not usable as a plain (non-qualified) C++ identifier, i.e. the first parameter contains special characters which cannot be part of a C++ identifier, such as ‘<’, ‘>’, or ‘:’.
- Note
This macro has to be used once for each of the component actions defined using one of the HPX_DEFINE_COMPONENT_ACTION or HPX_DEFINE_PLAIN_ACTION macros. It has to occur exactly once for each of the actions, thus it is recommended to place it into the source file defining the component.
- Note
Only one of the forms of this macro HPX_REGISTER_ACTION or HPX_REGISTER_ACTION_ID should be used for a particular action, never both.
-
HPX_REGISTER_ACTION_ID(action, actionname, actionid)¶ Define the necessary component action boilerplate code and assign a predefined unique id to the action.
The macro HPX_REGISTER_ACTION can be used to define all the boilerplate code which is required for proper functioning of component actions in the context of HPX.
The parameter action is the type of the action to define the boilerplate for.
The parameter actionname specifies an unique name of the action to be used for serialization purposes. The second parameter has to be usable as a plain (non-qualified) C++ identifier, it should not contain special characters which cannot be part of a C++ identifier, such as ‘<’, ‘>’, or ‘:’.
The parameter actionid specifies an unique integer value which will be used to represent the action during serialization.
- Note
This macro has to be used once for each of the component actions defined using one of the HPX_DEFINE_COMPONENT_ACTION or global actions HPX_DEFINE_PLAIN_ACTION macros. It has to occur exactly once for each of the actions, thus it is recommended to place it into the source file defining the component.
- Note
Only one of the forms of this macro HPX_REGISTER_ACTION or HPX_REGISTER_ACTION_ID should be used for a particular action, never both.
Header hpx/actions_base/basic_action_fwd.hpp¶
-
namespace
hpx -
namespace
actions -
template<typename
Component, typenameSignature, typenameDerived>
structbasic_action¶ - #include <basic_action_fwd.hpp>
- Template Parameters
Component: component typeSignature: return type and argumentsDerived: derived action class
-
template<typename
-
namespace
Header hpx/actions_base/component_action.hpp¶
Defines
-
HPX_DEFINE_COMPONENT_ACTION(...)¶ Registers a member function of a component as an action type with HPX.
The macro HPX_DEFINE_COMPONENT_ACTION can be used to register a member function of a component as an action type named action_type.
The parameter component is the type of the component exposing the member function func which should be associated with the newly defined action type. The parameter
action_typeis the name of the action type to register with HPX.namespace app { // Define a simple component exposing one action 'print_greeting' class HPX_COMPONENT_EXPORT server : public hpx::components::simple_component_base<server> { void print_greeting() const { hpx::cout << "Hey, how are you?\n" << hpx::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); }; }
- Example:
The first argument must provide the type name of the component the action is defined for.
The second argument must provide the member function name the action should wrap.
The default value for the third argument (the typename of the defined action) is derived from the name of the function (as passed as the second argument) by appending ‘_action’. The third argument can be omitted only if the second argument with an appended suffix ‘_action’ resolves to a valid, unqualified C++ type name.
- Note
The macro HPX_DEFINE_COMPONENT_ACTION can be used with 2 or 3 arguments. The third argument is optional.
Header hpx/actions_base/continuation_fwd.hpp¶
-
namespace
hpx -
namespace
actions Functions
-
template<typename
Result, typenameRemoteResult, typenameF, typename ...Ts>
voidtrigger(typed_continuation<Result, RemoteResult> &&cont, F &&f, Ts&&... vs)¶
-
template<typename
-
namespace
Header hpx/actions_base/plain_action.hpp¶
Defines
-
HPX_DEFINE_PLAIN_ACTION(...)¶ Defines a plain action type.
namespace app { void some_global_function(double d) { cout << d; } // This will define the action type 'app::some_global_action' which // represents the function 'app::some_global_function'. HPX_DEFINE_PLAIN_ACTION(some_global_function, some_global_action); }
- Example:
- Note
Usually this macro will not be used in user code unless the intent is to avoid defining the action_type in global namespace. Normally, the use of the macro HPX_PLAIN_ACTION is recommended.
- Note
The macro HPX_DEFINE_PLAIN_ACTION can be used with 1 or 2 arguments. The second argument is optional. The default value for the second argument (the typename of the defined action) is derived from the name of the function (as passed as the first argument) by appending ‘_action’. The second argument can be omitted only if the first argument with an appended suffix ‘_action’ resolves to a valid, unqualified C++ type name.
-
HPX_DECLARE_PLAIN_ACTION(...)¶ Declares a plain action type.
-
HPX_PLAIN_ACTION(...)¶ Defines a plain action type based on the given function func and registers it with HPX.
The macro HPX_PLAIN_ACTION can be used to define a plain action (e.g. an action encapsulating a global or free function) based on the given function func. It defines the action type name representing the given function. This macro additionally registers the newly define action type with HPX.
The parameter
funcis a global or free (non-member) function which should be encapsulated into a plain action. The parameternameis the name of the action type defined by this macro.namespace app { void some_global_function(double d) { cout << d; } } // This will define the action type 'some_global_action' which represents // the function 'app::some_global_function'. HPX_PLAIN_ACTION(app::some_global_function, some_global_action);
- Example:
- Note
The macro HPX_PLAIN_ACTION has to be used at global namespace even if the wrapped function is located in some other namespace. The newly defined action type is placed into the global namespace as well.
- Note
The macro HPX_PLAIN_ACTION_ID can be used with 1, 2, or 3 arguments. The second and third arguments are optional. The default value for the second argument (the typename of the defined action) is derived from the name of the function (as passed as the first argument) by appending ‘_action’. The second argument can be omitted only if the first argument with an appended suffix ‘_action’ resolves to a valid, unqualified C++ type name. The default value for the third argument is hpx::components::factory_check.
- Note
Only one of the forms of this macro HPX_PLAIN_ACTION or HPX_PLAIN_ACTION_ID should be used for a particular action, never both.
-
HPX_PLAIN_ACTION_ID(func, name, id)¶ Defines a plain action type based on the given function func and registers it with HPX.
The macro HPX_PLAIN_ACTION_ID can be used to define a plain action (e.g. an action encapsulating a global or free function) based on the given function func. It defines the action type actionname representing the given function. The parameter actionid
The parameter actionid specifies an unique integer value which will be used to represent the action during serialization.
The parameter
funcis a global or free (non-member) function which should be encapsulated into a plain action. The parameternameis the name of the action type defined by this macro.The second parameter has to be usable as a plain (non-qualified) C++ identifier, it should not contain special characters which cannot be part of a C++ identifier, such as ‘<’, ‘>’, or ‘:’.
namespace app { void some_global_function(double d) { cout << d; } } // This will define the action type 'some_global_action' which represents // the function 'app::some_global_function'. HPX_PLAIN_ACTION_ID(app::some_global_function, some_global_action, some_unique_id);
- Example:
- Note
The macro HPX_PLAIN_ACTION_ID has to be used at global namespace even if the wrapped function is located in some other namespace. The newly defined action type is placed into the global namespace as well.
- Note
Only one of the forms of this macro HPX_PLAIN_ACTION or HPX_PLAIN_ACTION_ID should be used for a particular action, never both.
Header hpx/actions_base/preassigned_action_id.hpp¶
Header hpx/actions_base/traits/action_continuation.hpp¶
Header hpx/actions_base/traits/action_priority.hpp¶
-
namespace
hpx -
namespace
traits -
template<typename
Action, typenameEnable= void>
structaction_priority¶ - #include <action_priority.hpp>
Public Static Attributes
-
constexpr threads::thread_priority
value= threads::thread_priority_default¶
-
constexpr threads::thread_priority
-
template<typename
-
namespace
Header hpx/actions_base/traits/action_remote_result.hpp¶
Header hpx/actions_base/traits/action_select_direct_execution.hpp¶
Header hpx/actions_base/traits/action_stacksize.hpp¶
-
namespace
hpx -
namespace
traits -
template<typename
Action, typenameEnable= void>
structaction_stacksize¶ - #include <action_stacksize.hpp>
Public Static Attributes
-
constexpr threads::thread_stacksize
value= threads::thread_stacksize_default¶
-
constexpr threads::thread_stacksize
-
template<typename
-
namespace
affinity¶
The contents of this module can be included with the header
hpx/modules/affinity.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/affinity.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/affinity/affinity_data.hpp¶
Header hpx/affinity/parse_affinity_options.hpp¶
-
namespace
hpx -
namespace
threads¶ Functions
-
void
parse_affinity_options(std::string const &spec, std::vector<mask_type> &affinities, std::size_t used_cores, std::size_t max_cores, std::size_t num_threads, std::vector<std::size_t> &num_pus, bool use_process_mask, error_code &ec = throws)¶
-
void
parse_affinity_options(std::string const &spec, std::vector<mask_type> &affinities, error_code &ec = throws)¶
-
void
-
namespace
algorithms¶
The contents of this module can be included with the header
hpx/modules/algorithms.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/algorithms.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/algorithms/traits/is_value_proxy.hpp¶
Header hpx/algorithms/traits/projected.hpp¶
-
template<typename
Iterator>
structprojected_iterator<Iterator, typename std::enable_if<is_segmented_iterator<Iterator>::value>::type>¶ - #include <projected.hpp>
Public Types
-
typedef segmented_iterator_traits<Iterator>::local_iterator
local_iterator¶
-
typedef segmented_local_iterator_traits<local_iterator>::local_raw_iterator
type¶
-
typedef segmented_iterator_traits<Iterator>::local_iterator
-
template<typename
Iterator>
structprojected_iterator<Iterator, typename hpx::util::always_void<typename hpx::util::decay<Iterator>::type::proxy_type>::type>¶ - #include <projected.hpp>
-
namespace
hpx -
namespace
parallel¶
-
namespace
traits -
template<typename
T, typenameEnable= void>
structprojected_iterator¶ - #include <projected.hpp>
-
template<typename
Iterator>
structprojected_iterator<Iterator, typename hpx::util::always_void<typename hpx::util::decay<Iterator>::type::proxy_type>::type> - #include <projected.hpp>
-
template<typename
Iterator>
structprojected_iterator<Iterator, typename std::enable_if<is_segmented_iterator<Iterator>::value>::type> - #include <projected.hpp>
Public Types
-
typedef segmented_iterator_traits<Iterator>::local_iterator
local_iterator
-
typedef segmented_local_iterator_traits<local_iterator>::local_raw_iterator
type
-
typedef segmented_iterator_traits<Iterator>::local_iterator
-
template<typename
-
namespace
Header hpx/algorithms/traits/projected_range.hpp¶
Header hpx/algorithms/traits/segmented_iterator_traits.hpp¶
-
namespace
hpx -
namespace
traits -
template<typename
Iterator, typenameEnable= void>
structsegmented_iterator_traits¶ - #include <segmented_iterator_traits.hpp>
-
template<typename
Iterator, typenameEnable= void>
structsegmented_local_iterator_traits¶ - #include <segmented_iterator_traits.hpp>
Public Types
-
typedef Iterator
iterator¶
-
typedef Iterator
local_iterator¶
-
typedef Iterator
local_raw_iterator¶
Public Static Functions
-
static local_raw_iterator const &
local(local_iterator const &it)¶
-
static local_iterator const &
remote(local_raw_iterator const &it)¶
-
static local_raw_iterator
local(local_iterator &&it)¶
-
static local_iterator
remote(local_raw_iterator &&it)¶
-
typedef Iterator
-
template<typename
-
namespace
Header hpx/parallel/algorithm.hpp¶
Header hpx/parallel/algorithms/adjacent_difference.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1¶ Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeadjacent_difference(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest)¶ Assigns each value in the range given by result its corresponding element in the range [first, last] and the one preceding it except *result, which is assigned *first
The difference operations in the parallel
adjacent_difference invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly (last - first) - 1 application of the binary operator and (last - first) assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the input range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the output range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the range the algorithm will be applied to.dest: Refers to the beginning of the sequence of elements the results will be assigned to.
The difference operations in the parallel adjacent_difference invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
This overload of
adjacent_find is available if the user decides to provide their algorithm their own binary predicate op.- Return
The adjacent_difference algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The adjacent_find algorithm returns an iterator to the last element in the output range.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameOp>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeadjacent_difference(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, Op &&op)¶ Assigns each value in the range given by result its corresponding element in the range [first, last] and the one preceding it except *result, which is assigned *first
The difference operations in the parallel
adjacent_difference invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly (last - first) - 1 application of the binary operator and (last - first) assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the input range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the output range (deduced). This iterator type must meet the requirements of an forward iterator.Op: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of adjacent_difference requires Op to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the range the algorithm will be applied to.dest: Refers to the beginning of the sequence of elements the results will be assigned to.op: The binary operator which returns the difference of elements. The signature should be equivalent to the following:bool op(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 must be such that objects of type FwdIter1 can be dereferenced and then implicitly converted to the dereferenced type of dest.
The difference operations in the parallel adjacent_difference invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The adjacent_difference algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The adjacent_find algorithm returns an iterator to the last element in the output range.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/adjacent_find.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenamePred= detail::equal_to>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter>::type>::typeadjacent_find(ExPolicy &&policy, FwdIter first, FwdIter last, Pred &&op = Pred())¶ Searches the range [first, last) for two consecutive identical elements. This version uses the given binary predicate op
The comparison operations in the parallel
adjacent_find invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly the smaller of (result - first) + 1 and (last - first) - 1 application of the predicate where result is the value returned
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of adjacent_find requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type1 .
The comparison operations in the parallel adjacent_find invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
This overload of
adjacent_find is available if the user decides to provide their algorithm their own binary predicate op.- Return
The adjacent_find algorithm returns a hpx::future<InIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns InIter otherwise. The adjacent_find algorithm returns an iterator to the first of the identical elements. If no such elements are found, last is returned.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/all_any_none.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typenone_of(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f, Proj &&proj = Proj())¶ Checks if unary predicate f returns true for no elements in the range [first, last).
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the predicate f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of none_of requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The none_of algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The none_of algorithm returns true if the unary predicate f returns true for no elements in the range, false otherwise. It returns true if the range is empty.
-
template<typename
ExPolicy, typenameFwdIter, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeany_of(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f, Proj &&proj = Proj())¶ Checks if unary predicate f returns true for at least one element in the range [first, last).
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the predicate f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of any_of requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The any_of algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The any_of algorithm returns true if the unary predicate f returns true for at least one element in the range, false otherwise. It returns false if the range is empty.
-
template<typename
ExPolicy, typenameFwdIter, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeall_of(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f, Proj &&proj = Proj())¶ Checks if unary predicate f returns true for all elements in the range [first, last).
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the predicate f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of all_of requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The all_of algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The all_of algorithm returns true if the unary predicate f returns true for all elements in the range, false otherwise. It returns true if the range is empty.
-
template<typename
Header hpx/parallel/algorithms/copy.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
hpx::parallel::util::detail::algorithm_result<ExPolicy, FwdIter2>::typecopy(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest)¶ Copies the elements in the range, defined by [first, last), to another range beginning at dest.
The assignments in the parallel
copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy algorithm returns a hpx::future<FwdIter2> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2> otherwise. The copy algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameSize, typenameFwdIter2>
hpx::parallel::util::detail::algorithm_result<ExPolicy, FwdIter2>::typecopy_n(ExPolicy &&policy, FwdIter1 first, Size count, FwdIter2 dest)¶ Copies the elements in the range [first, first + count), starting from first and proceeding to first + count - 1., to another range beginning at dest.
The assignments in the parallel
copy_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel copy_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy_n algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameF>
hpx::parallel::util::detail::algorithm_result<ExPolicy, FwdIter2>::typecopy_if(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, Pred &&pred)¶ Copies the elements in the range, defined by [first, last), to another range beginning at dest. Copies only the elements for which the predicate f returns true. The order of the elements that are not removed is preserved.
The assignments in the parallel
copy_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.
The assignments in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy_if algorithm returns a hpx::future<FwdIter2> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
Header hpx/parallel/algorithms/count.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIterB, typenameFwdIterE, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename std::iterator_traits<FwdIterB>::difference_type>::typecount(ExPolicy &&policy, FwdIterB first, FwdIterE last, T const &value, Proj &&proj = Proj())¶ Returns the number of elements in the range [first, last) satisfying a specific criteria. This version counts the elements that are equal to the given value.
The comparisons in the parallel
count algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first comparisons.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the comparisons.FwdIterB: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIterE: The type of the source end iterator used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to search for (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.value: The value to search for.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
- Note
The comparisons in the parallel count algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The count algorithm returns a hpx::future<difference_type> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by std::iterator_traits<FwdIterB>::difference_type. The count algorithm returns the number of elements satisfying the given criteria.
-
template<typename
ExPolicy, typenameIter, typenameSent, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename std::iterator_traits<Iter>::difference_type>::typecount_if(ExPolicy &&policy, Iter first, Sent last, F &&f, Proj &&proj = Proj())¶ Returns the number of elements in the range [first, last) satisfying a specific criteria. This version counts elements for which predicate f returns true.
- Note
Complexity: Performs exactly last - first applications of the predicate.
- Note
The assignments in the parallel count_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
- Note
The assignments in the parallel count_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The count_if algorithm returns hpx::future<difference_type> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by std::iterator_traits<FwdIterB>::difference_type. The count algorithm returns the number of elements satisfying the given criteria.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the comparisons.Iter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.Sent: The type of the source end iterator used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of count_if requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIterB can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
-
template<typename
Header hpx/parallel/algorithms/destroy.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter>
util::detail::algorithm_result<ExPolicy>::typedestroy(ExPolicy &&policy, FwdIter first, FwdIter last)¶ Destroys objects of type typename iterator_traits<ForwardIt>::value_type in the range [first, last).
The operations in the parallel
destroy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first operations.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.
The operations in the parallel destroy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The destroy algorithm returns a hpx::future<void>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize>
util::detail::algorithm_result<ExPolicy, FwdIter>::typedestroy_n(ExPolicy &&policy, FwdIter first, Size count)¶ Destroys objects of type typename iterator_traits<ForwardIt>::value_type in the range [first, first + count).
The operations in the parallel
destroy_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count operations, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply this algorithm to.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.
The operations in the parallel destroy_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The destroy_n algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The destroy_n algorithm returns the iterator to the element in the source range, one past the last element constructed.
-
template<typename
Header hpx/parallel/algorithms/equal.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::equal_to>
util::detail::algorithm_result<ExPolicy, bool>::typeequal(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, Pred &&op = Pred())¶ Returns true if the range [first1, last1) is equal to the range [first2, last2), and false otherwise.
The comparison operations in the parallel
equal algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most min(last1 - first1, last2 - first2) applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of equal requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively
The comparison operations in the parallel equal algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The two ranges are considered equal if, for every iterator i in the range [first1,last1), *i equals *(first2 + (i - first1)). This overload of equal uses operator== to determine if two elements are equal.
- Return
The equal algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The equal algorithm returns true if the elements in the two ranges are equal, otherwise it returns false. If the length of the range [first1, last1) does not equal the length of the range [first2, last2), it returns false.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::equal_to>
util::detail::algorithm_result<ExPolicy, bool>::typeequal(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, Pred &&op = Pred())¶ Returns true if the range [first1, last1) is equal to the range starting at first2, and false otherwise.
The comparison operations in the parallel
equal algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last1 - first1 applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of equal requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively
The comparison operations in the parallel equal algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The two ranges are considered equal if, for every iterator i in the range [first1,last1), *i equals *(first2 + (i - first1)). This overload of equal uses operator== to determine if two elements are equal.
- Return
The equal algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The equal algorithm returns true if the elements in the two ranges are equal, otherwise it returns false.
-
template<typename
Header hpx/parallel/algorithms/exclusive_scan.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameT, typenameOp>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeexclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, T init, Op &&op)¶ Assigns through each iterator i in [result, result + (last - first)) the value of GENERALIZED_NONCOMMUTATIVE_SUM(binary_op, init, *first, …, *(first + (i - result) - 1)).
The reduce operations in the parallel
exclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as initial (and intermediate) values (deduced).Op: The type of the binary function object used for the reduction operation.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.init: The initial value for the generalized sum.op: Specifies the function (or function object) which will be invoked for each of the values of the input sequence. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Ret must be such that an object of a type as given by the input sequence can be implicitly converted to any of those types.
The reduce operations in the parallel exclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
exclusive_scan and inclusive_scan is that inclusive_scan includes the ith input element in the ith sum. If op is not mathematically associative, the behavior of inclusive_scan may be non-deterministic.- Return
The exclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The exclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aN) is defined as:
a1 when N is 1
op(GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aK), GENERALIZED_NONCOMMUTATIVE_SUM(op, aM, …, aN)) where 1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameT>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeexclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, T init)¶ Assigns through each iterator i in [result, result + (last - first)) the value of GENERALIZED_NONCOMMUTATIVE_SUM(+, init, *first, …, *(first + (i - result) - 1))
The reduce operations in the parallel
exclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate std::plus<T>.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as initial (and intermediate) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.init: The initial value for the generalized sum.
The reduce operations in the parallel exclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
exclusive_scan and inclusive_scan is that inclusive_scan includes the ith input element in the ith sum.- Return
The exclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The exclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(+, a1, …, aN) is defined as:
a1 when N is 1
GENERALIZED_NONCOMMUTATIVE_SUM(+, a1, …, aK)
GENERALIZED_NONCOMMUTATIVE_SUM(+, aM, …, aN) where 1 < K+1 = M <= N.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/fill.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameT>
util::detail::algorithm_result<ExPolicy>::typefill(ExPolicy &&policy, FwdIter first, FwdIter last, T value)¶ Assigns the given value to the elements in the range [first, last).
The comparisons in the parallel
fill algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be assigned (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.value: The value to be assigned.
The comparisons in the parallel fill algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The fill algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by void.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize, typenameT>
util::detail::algorithm_result<ExPolicy, FwdIter>::typefill_n(ExPolicy &&policy, FwdIter first, Size count, T value)¶ Assigns the given value value to the first count elements in the range beginning at first if count > 0. Does nothing otherwise.
The comparisons in the parallel
fill_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, for count > 0.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an output iterator.Size: The type of the argument specifying the number of elements to apply f to.T: The type of the value to be assigned (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.value: The value to be assigned.
The comparisons in the parallel fill_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The fill_n algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by void.
-
template<typename
Header hpx/parallel/algorithms/find.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameT>
util::detail::algorithm_result<ExPolicy, FwdIter>::typefind(ExPolicy &&policy, FwdIter first, FwdIter last, T const &val)¶ Returns the first element in the range [first, last) that is equal to value
The comparison operations in the parallel
find algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the operator==().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to find (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.val: the value to compare the elements to
The comparison operations in the parallel find algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The find algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The find algorithm returns the first element in the range [first,last) that is equal to val. If no such element in the range of [first,last) is equal to val, then the algorithm returns last.
-
template<typename
ExPolicy, typenameFwdIter, typenameF>
util::detail::algorithm_result<ExPolicy, FwdIter>::typefind_if(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f)¶ Returns the first element in the range [first, last) for which predicate f returns true
The comparison operations in the parallel
find_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the predicate.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.f: The unary predicate which returns true for the required element. The signature of the predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type.
The comparison operations in the parallel find_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The find_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The find_if algorithm returns the first element in the range [first,last) that satisfies the predicate f. If no such element exists that satisfies the predicate f, the algorithm returns last.
-
template<typename
ExPolicy, typenameFwdIter, typenameF>
util::detail::algorithm_result<ExPolicy, FwdIter>::typefind_if_not(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f)¶ Returns the first element in the range [first, last) for which predicate f returns false
The comparison operations in the parallel
find_if_not algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the predicate.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.f: The unary predicate which returns false for the required element. The signature of the predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type.
The comparison operations in the parallel find_if_not algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The find_if_not algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The find_if_not algorithm returns the first element in the range [first, last) that does not satisfy the predicate f. If no such element exists that does not satisfy the predicate f, the algorithm returns last.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::equal_to>
util::detail::algorithm_result<ExPolicy, FwdIter1>::typefind_end(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, Pred &&op = Pred())¶ Returns the last subsequence of elements [first2, last2) found in the range [first, last) using the given predicate f to compare elements.
The comparison operations in the parallel
find_end algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most S*(N-S+1) comparisons where S = distance(first2, last2) and N = distance(first1, last1).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of replace requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of type dereferenced FwdIter1 and dereferenced FwdIter2.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements the algorithm will be searching for.last2: Refers to the end of the sequence of elements of the algorithm will be searching for.op: The binary predicate which returns true if the elements should be treated as equal. The signature should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively.proj: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced FwdIter1 and dereferenced FwdIter2 as a projection operation before the function f is invoked.
The comparison operations in the parallel find_end algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
This overload of
find_end is available if the user decides to provide the algorithm their own predicate f.- Return
The find_end algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The find_end algorithm returns an iterator to the beginning of the last subsequence [first2, last2) in range [first, last). If the length of the subsequence [first2, last2) is greater than the length of the range [first1, last1), last1 is returned. Additionally if the size of the subsequence is empty or no subsequence is found, last1 is also returned.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::equal_to>
util::detail::algorithm_result<ExPolicy, FwdIter1>::typefind_first_of(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 s_first, FwdIter2 s_last, Pred &&op = Pred())¶ Searches the range [first, last) for any elements in the range [s_first, s_last). Uses binary predicate p to compare elements
The comparison operations in the parallel
find_first_of algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most (S*N) comparisons where S = distance(s_first, s_last) and N = distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of equal requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of type dereferenced FwdIter1.Proj2: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of type dereferenced FwdIter2.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.s_first: Refers to the beginning of the sequence of elements the algorithm will be searching for.s_last: Refers to the end of the sequence of elements of the algorithm will be searching for.op: The binary predicate which returns true if the elements should be treated as equal. The signature should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively.proj1: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced FwdIter1 as a projection operation before the function op is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced FwdIter2 as a projection operation before the function op is invoked.
The comparison operations in the parallel find_first_of algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The find_first_of algorithm returns a hpx::future<FwdIter1> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter1 otherwise. The find_first_of algorithm returns an iterator to the first element in the range [first, last) that is equal to an element from the range [s_first, s_last). If the length of the subsequence [s_first, s_last) is greater than the length of the range [first, last), last is returned. Additionally if the size of the subsequence is empty or no subsequence is found, last is also returned. This overload of find_end is available if the user decides to provide the algorithm their own predicate f.
-
template<typename
Header hpx/parallel/algorithms/for_each.hpp¶
-
namespace
hpx Functions
-
template<typename
InIter, typenameF>
Ffor_each(InIter first, InIter last, F &&f)¶ Applies f to the result of dereferencing every iterator in the range [first, last).
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly last - first times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
- Return
f.
- Template Parameters
InIter: The type of the source begin and end iterator used (deduced). This iterator type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). F must meet requirements of MoveConstructible.
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.
-
template<typename
ExPolicy, typenameFwdIter, typenameF>
util::detail::algorithm_result<ExPolicy, void>::typefor_each(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f)¶ Applies f to the result of dereferencing every iterator in the range [first, last).
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly last - first times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
Unlike its sequential form, the parallel overload of for_each does not return a copy of its Function parameter, since parallelization may not permit efficient state accumulation.
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIte: The type of the source begin and end iterator used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The for_each algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
InIter, typenameSize, typenameF>
InIterfor_each_n(InIter first, Size count, F &&f)¶ Applies f to the result of dereferencing every iterator in the range [first, first + count), starting from first and proceeding to first + count - 1.
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly count times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
- Return
first + count for non-negative values of count and first for negative values.
- Template Parameters
InIter: The type of the source begin and end iterator used (deduced). This iterator type must meet the requirements of an input iterator.Size: The type of the argument specifying the number of elements to apply f to.F: The type of the function/function object to use (deduced). F must meet requirements of MoveConstructible.
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize, typenameF>
util::detail::algorithm_result<ExPolicy, FwdIter>::typefor_each_n(ExPolicy &&policy, FwdIter first, Size count, F &&f)¶ Applies f to the result of dereferencing every iterator in the range [first, first + count), starting from first and proceeding to first + count - 1.
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly count times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
Unlike its sequential form, the parallel overload of for_each does not return a copy of its Function parameter, since parallelization may not permit efficient state accumulation.
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The for_each_n algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns first + count for non-negative values of count and first for negative values.
-
template<typename
Header hpx/parallel/algorithms/for_loop.hpp¶
-
namespace
hpx Functions
-
template<typename
I, typename ...Args>
voidfor_loop(typename std::decay<I>::type first, I last, Args&&... args)¶ The for_loop implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
The execution of for_loop without specifying an execution policy is equivalent to specifying parallel::execution::seq as the execution policy.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
-
template<typename
ExPolicy, typenameI, typename ...Args>
util::detail::algorithm_result<ExPolicy>::typefor_loop(ExPolicy &&policy, typename std::decay<I>::type first, I last, Args&&... args)¶ The for_loop implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
- Return
The for_loop algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
I, typenameS, typename ...Args>
voidfor_loop_strided(typename std::decay<I>::type first, I last, S stride, Args&&... args)¶ The for_loop_strided implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
The execution of for_loop without specifying an execution policy is equivalent to specifying parallel::execution::seq as the execution policy.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.S: The type of the stride variable. This should be an integral type.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.stride: Refers to the stride of the iteration steps. This shall have non-zero value and shall be negative only if I has integral type or meets the requirements of a bidirectional iterator.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
-
template<typename
ExPolicy, typenameI, typenameS, typename ...Args>
util::detail::algorithm_result<ExPolicy>::typefor_loop_strided(ExPolicy &&policy, typename std::decay<I>::type first, I last, S stride, Args&&... args)¶ The for_loop_strided implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.S: The type of the stride variable. This should be an integral type.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.stride: Refers to the stride of the iteration steps. This shall have non-zero value and shall be negative only if I has integral type or meets the requirements of a bidirectional iterator.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
- Return
The for_loop_strided algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
I, typenameSize, typename ...Args>
voidfor_loop_n(I first, Size size, Args&&... args)¶ The for_loop implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
The execution of for_loop without specifying an execution policy is equivalent to specifying parallel::execution::seq as the execution policy.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.Size: The type of a non-negative integral value specifying the number of items to iterate over.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.size: Refers to the number of items the algorithm will be applied to.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
-
template<typename
ExPolicy, typenameI, typenameSize, typename ...Args>
util::detail::algorithm_result<ExPolicy>::typefor_loop_n(ExPolicy &&policy, I first, Size size, Args&&... args)¶ The for_loop_n implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.Size: The type of a non-negative integral value specifying the number of items to iterate over.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.size: Refers to the number of items the algorithm will be applied to.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
- Return
The for_loop_n algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
I, typenameSize, typenameS, typename ...Args>
voidfor_loop_n_strided(I first, Size size, S stride, Args&&... args)¶ The for_loop_n_strided implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
The execution of for_loop without specifying an execution policy is equivalent to specifying parallel::execution::seq as the execution policy.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.Size: The type of a non-negative integral value specifying the number of items to iterate over.S: The type of the stride variable. This should be an integral type.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.size: Refers to the number of items the algorithm will be applied to.stride: Refers to the stride of the iteration steps. This shall have non-zero value and shall be negative only if I has integral type or meets the requirements of a bidirectional iterator.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
-
template<typename
ExPolicy, typenameI, typenameSize, typenameS, typename ...Args>
util::detail::algorithm_result<ExPolicy>::typefor_loop_n_strided(ExPolicy &&policy, I first, Size size, S stride, Args&&... args)¶ The for_loop_n_strided implements loop functionality over a range specified by integral or iterator bounds. For the iterator case, these algorithms resemble for_each from the Parallelism TS, but leave to the programmer when and if to dereference the iterator.
Requires:
I shall be an integral type or meet the requirements of an input iterator type. The args parameter pack shall have at least one element, comprising objects returned by invocations of reduction and/or induction function templates followed by exactly one element invocable element-access function, f. f shall meet the requirements of MoveConstructible.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.I: The type of the iteration variable. This could be an (forward) iterator type or an integral type.Size: The type of a non-negative integral value specifying the number of items to iterate over.S: The type of the stride variable. This should be an integral type.Args: A parameter pack, it’s last element is a function object to be invoked for each iteration, the others have to be either conforming to the induction or reduction concept.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.size: Refers to the number of items the algorithm will be applied to.stride: Refers to the stride of the iteration steps. This shall have non-zero value and shall be negative only if I has integral type or meets the requirements of a bidirectional iterator.args: The last element of this parameter pack is the function (object) to invoke, while the remaining elements of the parameter pack are instances of either induction or reduction objects. The function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last) should expose a signature equivalent to:<ignored> pred(I const& a, ...);
The signature does not need to have const&. It will receive the current value of the iteration variable and one argument for each of the induction or reduction objects passed to the algorithms, representing their current values.
Effects: Applies f to each element in the input sequence, with additional arguments corresponding to the reductions and inductions in the args parameter pack. The length of the input sequence is last - first.
The first element in the input sequence is specified by first. Each subsequent element is generated by incrementing the previous element.
Along with an element from the input sequence, for each member of the
args parameter pack excluding f, an additional argument is passed to each application of f as follows:- Note
As described in the C++ standard, arithmetic on non-random-access iterators is performed using advance and distance.
- Note
The order of the elements of the input sequence is important for determining ordinal position of an application of f, even though the applications themselves may be unordered.
If the pack member is an object returned by a call to a reduction function listed in section, then the additional argument is a reference to a view of that reduction object. If the pack member is an object returned by a call to induction, then the additional argument is the induction value for that induction object corresponding to the position of the application of f in the input sequence.
Complexity: Applies f exactly once for each element of the input sequence.
Remarks: If f returns a result, the result is ignored.
- Return
The for_loop_n_strided algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
Header hpx/parallel/algorithms/for_loop_induction.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v2¶ Functions
-
template<typename
T>
constexpr detail::induction_stride_helper<T>induction(T &&value, std::size_t stride)¶ The function template returns an induction object of unspecified type having a value type and encapsulating an initial value value of that type and, optionally, a stride.
For each element in the input range, a looping algorithm over input sequence S computes an induction value from an induction variable and ordinal position p within S by the formula i + p * stride if a stride was specified or i + p otherwise. This induction value is passed to the element access function.
If the value argument to induction is a non-const lvalue, then that lvalue becomes the live-out object for the returned induction object. For each induction object that has a live-out object, the looping algorithm assigns the value of i + n * stride to the live-out object upon return, where n is the number of elements in the input range.
- Return
This returns an induction object with value type T, initial value value, and (if specified) stride stride. If T is an lvalue of non-const type, value is used as the live-out object for the induction object; otherwise there is no live-out object.
- Template Parameters
T: The value type to be used by the induction object.
- Parameters
value: [in] The initial value to use for the induction objectstride: [in] The (optional) stride to use for the induction object (default: 1)
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/for_loop_reduction.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v2 Functions
-
template<typename
T, typenameOp>
constexpr detail::reduction_helper<T, typename std::decay<Op>::type>reduction(T &var, T const &identity, Op &&combiner)¶ The function template returns a reduction object of unspecified type having a value type and encapsulating an identity value for the reduction, a combiner function object, and a live-out object from which the initial value is obtained and into which the final value is stored.
A parallel algorithm uses reduction objects by allocating an unspecified number of instances, called views, of the reduction’s value type. Each view is initialized with the reduction object’s identity value, except that the live-out object (which was initialized by the caller) comprises one of the views. The algorithm passes a reference to a view to each application of an element-access function, ensuring that no two concurrently-executing invocations share the same view. A view can be shared between two applications that do not execute concurrently, but initialization is performed only once per view.
Modifications to the view by the application of element access functions accumulate as partial results. At some point before the algorithm returns, the partial results are combined, two at a time, using the reduction object’s combiner operation until a single value remains, which is then assigned back to the live-out object.
T shall meet the requirements of CopyConstructible and MoveAssignable. The expression var = combiner(var, var) shall be well formed.
- Template Parameters
T: The value type to be used by the induction object.Op: The type of the binary function (object) used to perform the reduction operation.
- Parameters
var: [in,out] The life-out value to use for the reduction object. This will hold the reduced value after the algorithm is finished executing.identity: [in] The identity value to use for the reduction operation.combiner: [in] The binary function (object) used to perform a pairwise reduction on the elements.
- Note
In order to produce useful results, modifications to the view should be limited to commutative operations closely related to the combiner operation. For example if the combiner is plus<T>, incrementing the view would be consistent with the combiner but doubling it or assigning to it would not.
- Return
This returns a reduction object of unspecified type having a value type of T. When the return value is used by an algorithm, the reference to var is used as the live-out object, new views are initialized to a copy of identity, and views are combined by invoking the copy of combiner, passing it the two views to be combined.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/generate.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameF>
util::detail::algorithm_result<ExPolicy, FwdIter>::typegenerate(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f)¶ Assign each element in range [first, last) a value generated by the given function object f
The assignments in the parallel
generate algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly distance(first, last) invocations of f and assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: generator function that will be called. signature of function should be equivalent to the following:Ret fun();
The type
Ret must be such that an object of type FwdIter can be dereferenced and assigned a value of type Ret.
The assignments in the parallel generate algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize, typenameF>
util::detail::algorithm_result<ExPolicy, FwdIter>::typegenerate_n(ExPolicy &&policy, FwdIter first, Size count, F &&f)¶ Assigns each element in range [first, first+count) a value generated by the given function object g.
The assignments in the parallel
generate_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly count invocations of f and assignments, for count > 0.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements in the sequence the algorithm will be applied to.f: Refers to the generator function object that will be called. The signature of the function should be equivalent toRet fun();
The type
Ret must be such that an object of type OutputIt can be dereferenced and assigned a value of type Ret.
The assignments in the parallel generate_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
-
template<typename
Header hpx/parallel/algorithms/includes.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, bool>::type>::typeincludes(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, Pred &&op = Pred())¶ Returns true if every element from the sorted range [first2, last2) is found within the sorted range [first1, last1). Also returns true if [first2, last2) is empty. The version expects both ranges to be sorted with the user supplied binary predicate f.
The comparison operations in the parallel
includes algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
At most 2*(N1+N2-1) comparisons, where N1 = std::distance(first1, last1) and N2 = std::distance(first2, last2).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of includes requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as includes. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively
The comparison operations in the parallel includes algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The includes algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The includes algorithm returns true every element from the sorted range [first2, last2) is found within the sorted range [first1, last1). Also returns true if [first2, last2) is empty.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/inclusive_scan.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameOp, typenameT>
util::detail::algorithm_result<ExPolicy, FwdIter2>::typeinclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, Op &&op, T init)¶ Assigns through each iterator i in [result, result + (last - first)) the value of GENERALIZED_NONCOMMUTATIVE_SUM(op, init, *first, …, *(first + (i - result))).
The reduce operations in the parallel
inclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as initial (and intermediate) values (deduced).Op: The type of the binary function object used for the reduction operation.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.init: The initial value for the generalized sum.op: Specifies the function (or function object) which will be invoked for each of the values of the input sequence. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Ret must be such that an object of a type as given by the input sequence can be implicitly converted to any of those types.
The reduce operations in the parallel inclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
exclusive_scan and inclusive_scan is that inclusive_scan includes the ith input element in the ith sum. If op is not mathematically associative, the behavior of inclusive_scan may be non-deterministic.- Return
The inclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The inclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aN) is defined as:
a1 when N is 1
op(GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aK), GENERALIZED_NONCOMMUTATIVE_SUM(op, aM, …, aN)) where 1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameOp>
util::detail::algorithm_result<ExPolicy, FwdIter2>::typeinclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, Op &&op)¶ Assigns through each iterator i in [result, result + (last - first)) the value of GENERALIZED_NONCOMMUTATIVE_SUM(op, *first, …, *(first + (i - result))).
The reduce operations in the parallel
inclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.Op: The type of the binary function object used for the reduction operation.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.op: Specifies the function (or function object) which will be invoked for each of the values of the input sequence. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Ret must be such that an object of a type as given by the input sequence can be implicitly converted to any of those types.
The reduce operations in the parallel inclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
exclusive_scan and inclusive_scan is that inclusive_scan includes the ith input element in the ith sum.- Return
The inclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The inclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(+, a1, …, aN) is defined as:
a1 when N is 1
GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aK)
GENERALIZED_NONCOMMUTATIVE_SUM(+, aM, …, aN) where 1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeinclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest)¶ Assigns through each iterator i in [result, result + (last - first)) the value of gENERALIZED_NONCOMMUTATIVE_SUM(+, *first, …, *(first + (i - result))).
The reduce operations in the parallel
inclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The reduce operations in the parallel inclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
exclusive_scan and inclusive_scan is that inclusive_scan includes the ith input element in the ith sum.- Return
The inclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The inclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(+, a1, …, aN) is defined as:
a1 when N is 1
GENERALIZED_NONCOMMUTATIVE_SUM(+, a1, …, aK)
GENERALIZED_NONCOMMUTATIVE_SUM(+, aM, …, aN) where 1 < K+1 = M <= N.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/is_heap.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRandIter, typenameComp= detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeis_heap(ExPolicy &&policy, RandIter first, RandIter last, Comp &&comp = Comp(), Proj &&proj = Proj())¶ Returns whether the range is max heap. That is, true if the range is max heap, false otherwise. The function uses the given comparison function object comp (defaults to using operator<()).
comp has to induce a strict weak ordering on the values.
- Note
Complexity: Performs at most N applications of the comparison comp, at most 2 * N applications of the projection proj, where N = last - first.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.RandIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a random access iterator.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The is_heap algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The is_heap algorithm returns whether the range is max heap. That is, true if the range is max heap, false otherwise.
-
template<typename
ExPolicy, typenameRandIter, typenameComp= detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, RandIter>::typeis_heap_until(ExPolicy &&policy, RandIter first, RandIter last, Comp &&comp = Comp(), Proj &&proj = Proj())¶ Returns the upper bound of the largest range beginning at first which is a max heap. That is, the last iterator it for which range [first, it) is a max heap. The function uses the given comparison function object comp (defaults to using operator<()).
comp has to induce a strict weak ordering on the values.
- Note
Complexity: Performs at most N applications of the comparison comp, at most 2 * N applications of the projection proj, where N = last - first.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.RandIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a random access iterator.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The is_heap_until algorithm returns a hpx::future<RandIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns RandIter otherwise. The is_heap_until algorithm returns the upper bound of the largest range beginning at first which is a max heap. That is, the last iterator it for which range [first, it) is a max heap.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/is_partitioned.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenamePred>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, bool>::type>::typeis_partitioned(ExPolicy &&policy, FwdIter first, FwdIter last, Pred &&pred)¶ Determines if the range [first, last) is partitioned.
The predicate operations in the parallel
is_partitioned algorithm invoked with an execution policy object of type sequenced_policy executes in sequential order in the calling thread.- Note
Complexity: at most (N) predicate evaluations where N = distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the This iterator type must meet the requirements of a forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of that the algorithm will be applied to.last: Refers to the end of the sequence of elements of that the algorithm will be applied to.pred: Refers to the binary predicate which returns true if the first argument should be treated as less than the second argument. The signature of the function should be equivalent tobool pred(const Type &a, const Type &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type must be such that objects of types FwdIter can be dereferenced and then implicitly converted to Type.
The comparison operations in the parallel is_partitioned algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The is_partitioned algorithm returns a hpx::future<bool> if the execution policy is of type task_execution_policy and returns bool otherwise. The is_partitioned algorithm returns true if each element in the sequence for which pred returns true precedes those for which pred returns false. Otherwise is_partitioned returns false. If the range [first, last) contains less than two elements, the function is always true.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/is_sorted.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, bool>::type>::typeis_sorted(ExPolicy &&policy, FwdIter first, FwdIter last, Pred &&pred = Pred())¶ Determines if the range [first, last) is sorted. Uses pred to compare elements.
The comparison operations in the parallel
is_sorted algorithm invoked with an execution policy object of type sequenced_policy executes in sequential order in the calling thread.- Note
Complexity: at most (N+S-1) comparisons where N = distance(first, last). S = number of partitions
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the This iterator type must meet the requirements of a forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of is_sorted requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of that the algorithm will be applied to.last: Refers to the end of the sequence of elements of that the algorithm will be applied to.pred: Refers to the binary predicate which returns true if the first argument should be treated as less than the second argument. The signature of the function should be equivalent tobool pred(const Type &a, const Type &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type must be such that objects of types FwdIter can be dereferenced and then implicitly converted to Type.
The comparison operations in the parallel is_sorted algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The is_sorted algorithm returns a hpx::future<bool> if the execution policy is of type task_execution_policy and returns bool otherwise. The is_sorted algorithm returns a bool if each element in the sequence [first, last) satisfies the predicate passed. If the range [first, last) contains less than two elements, the function always returns true.
-
template<typename
ExPolicy, typenameFwdIter, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter>::type>::typeis_sorted_until(ExPolicy &&policy, FwdIter first, FwdIter last, Pred &&pred = Pred())¶ Returns the first element in the range [first, last) that is not sorted. Uses a predicate to compare elements or the less than operator.
The comparison operations in the parallel
is_sorted_until algorithm invoked with an execution policy object of type sequenced_policy executes in sequential order in the calling thread.- Note
Complexity: at most (N+S-1) comparisons where N = distance(first, last). S = number of partitions
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the This iterator type must meet the requirements of a forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of is_sorted_until requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of that the algorithm will be applied to.last: Refers to the end of the sequence of elements of that the algorithm will be applied to.pred: Refers to the binary predicate which returns true if the first argument should be treated as less than the second argument. The signature of the function should be equivalent tobool pred(const Type &a, const Type &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type must be such that objects of types FwdIter can be dereferenced and then implicitly converted to Type.
The comparison operations in the parallel is_sorted_until algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The is_sorted_until algorithm returns a hpx::future<FwdIter> if the execution policy is of type task_execution_policy and returns FwdIter otherwise. The is_sorted_until algorithm returns the first unsorted element. If the sequence has less than two elements or the sequence is sorted, last is returned.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/lexicographical_compare.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, bool>::type>::typelexicographical_compare(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, Pred &&pred = Pred())¶ Checks if the first range [first1, last1) is lexicographically less than the second range [first2, last2). uses a provided predicate to compare elements.
The comparison operations in the parallel
lexicographical_compare algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most 2 * min(N1, N2) applications of the comparison operation, where N1 = std::distance(first1, last) and N2 = std::distance(first2, last2).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of lexicographical_compare requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.pred: Refers to the comparison function that the first and second ranges will be applied to
The comparison operations in the parallel lexicographical_compare algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
Lexicographical comparison is an operation with the following properties
Two ranges are compared element by element
The first mismatching element defines which range is lexicographically less or greater than the other
If one range is a prefix of another, the shorter range is lexicographically less than the other
If two ranges have equivalent elements and are of the same length, then the ranges are lexicographically equal
An empty range is lexicographically less than any non-empty range
Two empty ranges are lexicographically equal
- Return
The lexicographically_compare algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The lexicographically_compare algorithm returns true if the first range is lexicographically less, otherwise it returns false. range [first2, last2), it returns false.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/merge.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRandIter1, typenameRandIter2, typenameRandIter3, typenameComp= detail::less, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in1(RandIter1), tag::in2(RandIter2), tag::out(RandIter3)>>::typemerge(ExPolicy &&policy, RandIter1 first1, RandIter1 last1, RandIter2 first2, RandIter2 last2, RandIter3 dest, Comp &&comp = Comp(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Merges two sorted ranges [first1, last1) and [first2, last2) into one sorted range beginning at dest. The order of equivalent elements in the each of original two ranges is preserved. For equivalent elements in the original two ranges, the elements from the first range precede the elements from the second range. The destination range cannot overlap with either of the input ranges.
The assignments in the parallel
merge algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs O(std::distance(first1, last1) + std::distance(first2, last2)) applications of the comparison comp and the each projection.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.RandIter1: The type of the source iterators used (deduced) representing the first sorted range. This iterator type must meet the requirements of an random access iterator.RandIter2: The type of the source iterators used (deduced) representing the second sorted range. This iterator type must meet the requirements of an random access iterator.RandIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an random access iterator.Comp: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of merge requires Comp to meet the requirements of CopyConstructible. This defaults to std::less<>Proj1: The type of an optional projection function to be used for elements of the first range. This defaults to util::projection_identityProj2: The type of an optional projection function to be used for elements of the second range. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first range of elements the algorithm will be applied to.last1: Refers to the end of the first range of elements the algorithm will be applied to.first2: Refers to the beginning of the second range of elements the algorithm will be applied to.last2: Refers to the end of the second range of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.comp: comp is a callable object which returns true if the first argument is less than the second, and false otherwise. The signature of this comparison should be equivalent to:bool comp(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types RandIter1 and RandIter2 can be dereferenced and then implicitly converted to both Type1 and Type2proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range as a projection operation before the actual comparison comp is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range as a projection operation before the actual comparison comp is invoked.
The assignments in the parallel merge algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The merge algorithm returns a hpx::future<tagged_tuple<tag::in1(RandIter1), tag::in2(RandIter2), tag::out(RandIter3)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_tuple<tag::in1(RandIter1), tag::in2(RandIter2), tag::out(RandIter3)> otherwise. The merge algorithm returns the tuple of the source iterator last1, the source iterator last2, the destination iterator to the end of the dest range.
-
template<typename
ExPolicy, typenameRandIter, typenameComp= detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, RandIter>::typeinplace_merge(ExPolicy &&policy, RandIter first, RandIter middle, RandIter last, Comp &&comp = Comp(), Proj &&proj = Proj())¶ Merges two consecutive sorted ranges [first, middle) and [middle, last) into one sorted range [first, last). The order of equivalent elements in the each of original two ranges is preserved. For equivalent elements in the original two ranges, the elements from the first range precede the elements from the second range.
The assignments in the parallel
inplace_merge algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs O(std::distance(first, last)) applications of the comparison comp and the each projection.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.RandIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an random access iterator.Comp: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of inplace_merge requires Comp to meet the requirements of CopyConstructible. This defaults to std::less<>Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the first sorted range the algorithm will be applied to.middle: Refers to the end of the first sorted range and the beginning of the second sorted range the algorithm will be applied to.last: Refers to the end of the second sorted range the algorithm will be applied to.comp: comp is a callable object which returns true if the first argument is less than the second, and false otherwise. The signature of this comparison should be equivalent to:bool comp(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types RandIter can be dereferenced and then implicitly converted to both Type1 and Type2proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel inplace_merge algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The inplace_merge algorithm returns a hpx::future<RandIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns RandIter otherwise. The inplace_merge algorithm returns the source iterator last
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/minmax.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameProj= util::projection_identity, typenameF= detail::less>
util::detail::algorithm_result<ExPolicy, FwdIter>::typemin_element(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f = F(), Proj &&proj = Proj())¶ Finds the smallest element in the range [first, last) using the given comparison function f.
The comparisons in the parallel
min_element algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly max(N-1, 0) comparisons, where N = std::distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of min_element requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: The binary predicate which returns true if the the left argument is less than the right element. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type1.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparisons in the parallel min_element algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The min_element algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The min_element algorithm returns the iterator to the smallest element in the range [first, last). If several elements in the range are equivalent to the smallest element, returns the iterator to the first such element. Returns last if the range is empty.
-
template<typename
ExPolicy, typenameFwdIter, typenameProj= util::projection_identity, typenameF= detail::less>
util::detail::algorithm_result<ExPolicy, FwdIter>::typemax_element(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f = F(), Proj &&proj = Proj())¶ Finds the greatest element in the range [first, last) using the given comparison function f.
The comparisons in the parallel
max_element algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly max(N-1, 0) comparisons, where N = std::distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of max_element requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: The binary predicate which returns true if the This argument is optional and defaults to std::less. the left argument is less than the right element. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type1.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparisons in the parallel max_element algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The max_element algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The max_element algorithm returns the iterator to the smallest element in the range [first, last). If several elements in the range are equivalent to the smallest element, returns the iterator to the first such element. Returns last if the range is empty.
-
template<typename
ExPolicy, typenameFwdIter, typenameProj= util::projection_identity, typenameF= detail::less>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::min(FwdIter), tag::max(FwdIter)>>::typeminmax_element(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f = F(), Proj &&proj = Proj())¶ Finds the greatest element in the range [first, last) using the given comparison function f.
The comparisons in the parallel
minmax_element algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most max(floor(3/2*(N-1)), 0) applications of the predicate, where N = std::distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of minmax_element requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: The binary predicate which returns true if the the left argument is less than the right element. This argument is optional and defaults to std::less. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type1.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparisons in the parallel minmax_element algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The minmax_element algorithm returns a hpx::future<tagged_pair<tag::min(FwdIter), tag::max(FwdIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::min(FwdIter), tag::max(FwdIter)> otherwise. The minmax_element algorithm returns a pair consisting of an iterator to the smallest element as the first element and an iterator to the greatest element as the second. Returns std::make_pair(first, first) if the range is empty. If several elements are equivalent to the smallest element, the iterator to the first such element is returned. If several elements are equivalent to the largest element, the iterator to the last such element is returned.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/mismatch.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::equal_to>
util::detail::algorithm_result<ExPolicy, std::pair<FwdIter1, FwdIter2>>::typemismatch(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, Pred &&op = Pred())¶ Returns true if the range [first1, last1) is mismatch to the range [first2, last2), and false otherwise.
The comparison operations in the parallel
mismatch algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most min(last1 - first1, last2 - first2) applications of the predicate f. If FwdIter1 and FwdIter2 meet the requirements of RandomAccessIterator and (last1 - first1) != (last2 - first2) then no applications of the predicate f are made.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of mismatch requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as mismatch. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively
The comparison operations in the parallel mismatch algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The two ranges are considered mismatch if, for every iterator i in the range [first1,last1), *i mismatchs *(first2 + (i - first1)). This overload of mismatch uses operator== to determine if two elements are mismatch.
- Return
The mismatch algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The mismatch algorithm returns true if the elements in the two ranges are mismatch, otherwise it returns false. If the length of the range [first1, last1) does not mismatch the length of the range [first2, last2), it returns false.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::equal_to>
util::detail::algorithm_result<ExPolicy, std::pair<FwdIter1, FwdIter2>>::typemismatch(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, Pred &&op = Pred())¶ Returns std::pair with iterators to the first two non-equivalent elements.
The comparison operations in the parallel
mismatch algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last1 - first1 applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of mismatch requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as mismatch. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively
The comparison operations in the parallel mismatch algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The mismatch algorithm returns a hpx::future<std::pair<FwdIter1, FwdIter2> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns std::pair<FwdIter1, FwdIter2> otherwise. The mismatch algorithm returns the first mismatching pair of elements from two ranges: one defined by [first1, last1) and another defined by [first2, last2).
-
template<typename
Header hpx/parallel/algorithms/move.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
util::detail::algorithm_result<ExPolicy, FwdIter2>::typemove(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest)¶ Moves the elements in the range [first, last), to another range beginning at dest. After this operation the elements in the moved-from range will still contain valid values of the appropriate type, but not necessarily the same values as before the move.
The move assignments in the parallel
move algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first move assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the move assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The move assignments in the parallel move algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The move algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The move algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element moved.
-
template<typename
Header hpx/parallel/algorithms/partition.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameBidirIter, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, BidirIter>::typestable_partition(ExPolicy &&policy, BidirIter first, BidirIter last, F &&f, Proj &&proj = Proj())¶ Permutes the elements in the range [first, last) such that there exists an iterator i such that for every iterator j in the range [first, i) INVOKE(f, INVOKE (proj, *j)) != false, and for every iterator k in the range [i, last), INVOKE(f, INVOKE (proj, *k)) == false
The invocations of
f in the parallel stable_partition algorithm invoked with an execution policy object of type sequenced_policy executes in sequential order in the calling thread.- Note
Complexity: At most (last - first) * log(last - first) swaps, but only linear number of swaps if there is enough extra memory. Exactly last - first applications of the predicate and projection.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the invocations of f.BidirIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of transform requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Unary predicate which returns true if the element should be ordered before other elements. Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:bool fun(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type BidirIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate f is invoked.
The invocations of f in the parallel stable_partition algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The stable_partition algorithm returns an iterator i such that for every iterator j in the range [first, i), f(*j) != false INVOKE(f, INVOKE(proj, *j)) != false, and for every iterator k in the range [i, last), f(*k) == false INVOKE(f, INVOKE (proj, *k)) == false. The relative order of the elements in both groups is preserved. If the execution policy is of type parallel_task_policy the algorithm returns a future<> referring to this iterator.
-
template<typename
ExPolicy, typenameFwdIter, typenamePred, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typepartition(ExPolicy &&policy, FwdIter first, FwdIter last, Pred &&pred, Proj &&proj = Proj())¶ Reorders the elements in the range [first, last) in such a way that all elements for which the predicate pred returns true precede the elements for which the predicate pred returns false. Relative order of the elements is not preserved.
The assignments in the parallel
partition algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most 2 * (last - first) swaps. Exactly last - first applications of the predicate and projection.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of partition requires Pred to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is an unary predicate for partitioning the source iterators. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel partition algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The partition algorithm returns a hpx::future<FwdIter> if the execution policy is of type parallel_task_policy and returns FwdIter otherwise. The partition algorithm returns the iterator to the first element of the second group.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameFwdIter3, typenamePred, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in(FwdIter1), tag::out1(FwdIter2), tag::out2(FwdIter3)>>::typepartition_copy(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest_true, FwdIter3 dest_false, Pred &&pred, Proj &&proj = Proj())¶ Copies the elements in the range, defined by [first, last), to two different ranges depending on the value returned by the predicate pred. The elements, that satisfy the predicate pred, are copied to the range beginning at dest_true. The rest of the elements are copied to the range beginning at dest_false. The order of the elements is preserved.
The assignments in the parallel
partition_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range for the elements that satisfy the predicate pred (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range for the elements that don’t satisfy the predicate pred (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of partition_copy requires Pred to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest_true: Refers to the beginning of the destination range for the elements that satisfy the predicate pred.dest_false: Refers to the beginning of the destination range for the elements that don’t satisfy the predicate pred.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is an unary predicate for partitioning the source iterators. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel partition_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The partition_copy algorithm returns a hpx::future<tagged_tuple<tag::in(InIter), tag::out1(OutIter1), tag::out2(OutIter2)> > if the execution policy is of type parallel_task_policy and returns tagged_tuple<tag::in(InIter), tag::out1(OutIter1), tag::out2(OutIter2)> otherwise. The partition_copy algorithm returns the tuple of the source iterator last, the destination iterator to the end of the dest_true range, and the destination iterator to the end of the dest_false range.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/reduce.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameT, typenameF>
util::detail::algorithm_result<ExPolicy, T>::typereduce(ExPolicy &&policy, FwdIter first, FwdIter last, T init, F &&f)¶ Returns GENERALIZED_SUM(f, init, *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source begin and end iterators used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.T: The type of the value to be used as initial (and intermediate) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&. The types
Type1 Ret must be such that an object of type FwdIter can be dereferenced and then implicitly converted to any of those types.init: The initial value for the generalized sum.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise. The reduce algorithm returns the result of the generalized sum over the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(op, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(op, b1, …, bK), GENERALIZED_SUM(op, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter, typenameT>
util::detail::algorithm_result<ExPolicy, T>::typereduce(ExPolicy &&policy, FwdIter first, FwdIter last, T init)¶ Returns GENERALIZED_SUM(+, init, *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the operator+().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source begin and end iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as initial (and intermediate) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.init: The initial value for the generalized sum.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise. The reduce algorithm returns the result of the generalized sum (applying operator+()) over the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(+, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(+, b1, …, bK), GENERALIZED_SUM(+, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter>
util::detail::algorithm_result<ExPolicy, typename std::iterator_traits<FwdIter>::value_type>::typereduce(ExPolicy &&policy, FwdIter first, FwdIter last)¶ Returns GENERALIZED_SUM(+, T(), *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the operator+().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source begin and end iterators used (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise (where T is the value_type of FwdIter). The reduce algorithm returns the result of the generalized sum (applying operator+()) over the elements given by the input range [first, last).
- Note
The type of the initial value (and the result type) T is determined from the value_type of the used FwdIter.
- Note
GENERALIZED_SUM(+, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(+, b1, …, bK), GENERALIZED_SUM(+, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
Header hpx/parallel/algorithms/reduce_by_key.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRanIter, typenameRanIter2, typenameFwdIter1, typenameFwdIter2, typenameCompare= std::equal_to<typename std::iterator_traits<RanIter>::value_type>, typenameFunc= std::plus<typename std::iterator_traits<RanIter2>::value_type>>
util::detail::algorithm_result<ExPolicy, util::in_out_result<FwdIter1, FwdIter2>>::typereduce_by_key(ExPolicy &&policy, RanIter key_first, RanIter key_last, RanIter2 values_first, FwdIter1 keys_output, FwdIter2 values_output, Compare &&comp = Compare(), Func &&func = Func())¶ Reduce by Key performs an inclusive scan reduction operation on elements supplied in key/value pairs. The algorithm produces a single output value for each set of equal consecutive keys in [key_first, key_last). the value being the GENERALIZED_NONCOMMUTATIVE_SUM(op, init, *first, …, *(first + (i - result))). for the run of consecutive matching keys. The number of keys supplied must match the number of values.
comp has to induce a strict weak ordering on the values.
- Note
Complexity: O(last - first) applications of the predicate op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.RanIter: The type of the key iterators used (deduced). This iterator type must meet the requirements of a random access iterator.RanIter2: The type of the value iterators used (deduced). This iterator type must meet the requirements of a random access iterator.FwdIter1: The type of the iterator representing the destination key range (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination value range (deduced). This iterator type must meet the requirements of an forward iterator.Compare: The type of the optional function/function object to use to compare keys (deduced). Assumed to be std::equal_to otherwise.Func: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.key_first: Refers to the beginning of the sequence of key elements the algorithm will be applied to.key_last: Refers to the end of the sequence of key elements the algorithm will be applied to.values_first: Refers to the beginning of the sequence of value elements the algorithm will be applied to.keys_output: Refers to the start output location for the keys produced by the algorithm.values_output: Refers to the start output location for the values produced by the algorithm.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.func: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&. The types
Type1 Ret must be such that an object of type FwdIter can be dereferenced and then implicitly converted to any of those types.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The reduce_by_key algorithm returns a hpx::future<pair<Iter1,Iter2>> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns pair<Iter1,Iter2> otherwise.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/remove.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenamePred, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typeremove_if(ExPolicy &&policy, FwdIter first, FwdIter last, Pred &&pred, Proj &&proj = Proj())¶ Removes all elements satisfying specific criteria from the range [first, last) and returns a past-the-end iterator for the new end of the range. This version removes all elements for which predicate pred returns true.
The assignments in the parallel
remove_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate pred and the projection proj.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of remove_if requires Pred to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The remove_if algorithm returns the iterator to the new end of the range.
-
template<typename
ExPolicy, typenameFwdIter, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typeremove(ExPolicy &&policy, FwdIter first, FwdIter last, T const &value, Proj &&proj = Proj())¶ Removes all elements satisfying specific criteria from the range [first, last) and returns a past-the-end iterator for the new end of the range. This version removes all elements that are equal to value.
The assignments in the parallel
remove algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the operator==() and the projection proj.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to remove (deduced). This value type must meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.value: Specifies the value of elements to remove.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The remove algorithm returns the iterator to the new end of the range.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/remove_copy.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, util::in_out_result<FwdIter1, FwdIter2>>::typeremove_copy(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, T const &val, Proj &&proj = Proj())¶ Copies the elements in the range, defined by [first, last), to another range beginning at dest. Copies only the elements for which the comparison operator returns false when compare to val. The order of the elements that are not removed is preserved.
Effects: Copies all the elements referred to by the iterator it in the range [first,last) for which the following corresponding conditions do not hold: INVOKE(proj, *it) == value
The assignments in the parallel
remove_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.T: The type that the result of dereferencing FwdIter1 is compared to.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.val: Value to be removed.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove_copy algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, util::in_out_result<FwdIter1, FwdIter2>>::typeremove_copy_if(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, F &&f, Proj &&proj = Proj())¶ Copies the elements in the range, defined by [first, last), to another range beginning at dest. Copies only the elements for which the predicate f returns false. The order of the elements that are not removed is preserved.
Effects: Copies all the elements referred to by the iterator it in the range [first,last) for which the following corresponding conditions do not hold: INVOKE(pred, INVOKE(proj, *it)) != false.
The assignments in the parallel
remove_copy_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the elements to be removed. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove_copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove_copy_if algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/replace.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameT1, typenameT2, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typereplace(ExPolicy &&policy, FwdIter first, FwdIter last, T1 const &old_value, T2 const &new_value, Proj &&proj = Proj())¶ Replaces all elements satisfying specific criteria with new_value in the range [first, last).
Effects: Substitutes elements referred by the iterator it in the range [first, last) with new_value, when the following corresponding conditions hold: INVOKE(proj, *it) == old_value
The assignments in the parallel
replace algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a forward iterator.T1: The type of the old value to replace (deduced).T2: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.old_value: Refers to the old value of the elements to replace.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise. It returns last.
-
template<typename
ExPolicy, typenameFwdIter, typenameF, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typereplace_if(ExPolicy &&policy, FwdIter first, FwdIter last, F &&f, T const &new_value, Proj &&proj = Proj())¶ Replaces all elements satisfying specific criteria (for which predicate f returns true) with new_value in the range [first, last).
Effects: Substitutes elements referred by the iterator it in the range [first, last) with new_value, when the following corresponding conditions hold: INVOKE(f, INVOKE(proj, *it)) != false
The assignments in the parallel
replace_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first applications of the predicate.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible. (deduced).T: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the elements which need to replaced. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameT1, typenameT2, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)>>::typereplace_copy(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, T1 const &old_value, T2 const &new_value, Proj &&proj = Proj())¶ Copies the all elements from the range [first, last) to another range beginning at dest replacing all elements satisfying a specific criteria with new_value.
Effects: Assigns to every iterator it in the range [result, result + (last - first)) either new_value or *(first + (it - result)) depending on whether the following corresponding condition holds: INVOKE(proj, *(first + (i - result))) == old_value
The assignments in the parallel
replace_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first applications of the predicate.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.T1: The type of the old value to replace (deduced).T2: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.old_value: Refers to the old value of the elements to replace.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_copy algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The copy algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameF, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)>>::typereplace_copy_if(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, F &&f, T const &new_value, Proj &&proj = Proj())¶ Copies the all elements from the range [first, last) to another range beginning at dest replacing all elements satisfying a specific criteria with new_value.
Effects: Assigns to every iterator it in the range [result, result + (last - first)) either new_value or *(first + (it - result)) depending on whether the following corresponding condition holds: INVOKE(f, INVOKE(proj, *(first + (i - result)))) != false
The assignments in the parallel
replace_copy_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first applications of the predicate.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible. (deduced).T: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the elements which need to replaced. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace_copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_copy_if algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The replace_copy_if algorithm returns the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/reverse.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameBidirIter>
util::detail::algorithm_result<ExPolicy, BidirIter>::typereverse(ExPolicy &&policy, BidirIter first, BidirIter last)¶ Reverses the order of the elements in the range [first, last). Behaves as if applying std::iter_swap to every pair of iterators first+i, (last-i) - 1 for each non-negative i < (last-first)/2.
The assignments in the parallel
reverse algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Linear in the distance between first and last.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.BidirIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an bidirectional iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.
The assignments in the parallel reverse algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The reverse algorithm returns a hpx::future<BidirIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns BidirIter otherwise. It returns last.
-
template<typename
ExPolicy, typenameBidirIter, typenameFwdIter>
util::detail::algorithm_result<ExPolicy, util::in_out_result<BidirIter, FwdIter>>::typereverse_copy(ExPolicy &&policy, BidirIter first, BidirIter last, FwdIter dest_first)¶ Copies the elements from the range [first, last) to another range beginning at dest_first in such a way that the elements in the new range are in reverse order. Behaves as if by executing the assignment *(dest_first + (last - first) - 1 - i) = *(first + i) once for each non-negative i < (last - first) If the source and destination ranges (that is, [first, last) and [dest_first, dest_first+(last-first)) respectively) overlap, the behavior is undefined.
The assignments in the parallel
reverse_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.BidirIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an bidirectional iterator.FwdIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest_first: Refers to the begin of the destination range.
The assignments in the parallel reverse_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The reverse_copy algorithm returns a hpx::future<tagged_pair<tag::in(BidirIter), tag::out(FwdIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(BidirIter), tag::out(FwdIter)> otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/rotate.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter>
util::detail::algorithm_result<ExPolicy, util::in_out_result<FwdIter, FwdIter>>::typerotate(ExPolicy &&policy, FwdIter first, FwdIter new_first, FwdIter last)¶ Performs a left rotation on a range of elements. Specifically, rotate swaps the elements in the range [first, last) in such a way that the element new_first becomes the first element of the new range and new_first - 1 becomes the last element.
The assignments in the parallel
rotate algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Linear in the distance between first and last.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.new_first: Refers to the element that should appear at the beginning of the rotated range.last: Refers to the end of the sequence of elements the algorithm will be applied to.
The assignments in the parallel rotate algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The type of dereferenced FwdIter must meet the requirements of MoveAssignable and MoveConstructible.
- Return
The rotate algorithm returns a hpx::future<tagged_pair<tag::begin(FwdIter), tag::end(FwdIter)> > if the execution policy is of type parallel_task_policy and returns tagged_pair<tag::begin(FwdIter), tag::end(FwdIter)> otherwise. The rotate algorithm returns the iterator equal to pair(first + (last - new_first), last).
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
util::detail::algorithm_result<ExPolicy, util::in_out_result<FwdIter1, FwdIter2>>::typerotate_copy(ExPolicy &&policy, FwdIter1 first, FwdIter1 new_first, FwdIter1 last, FwdIter2 dest_first)¶ Copies the elements from the range [first, last), to another range beginning at dest_first in such a way, that the element new_first becomes the first element of the new range and new_first - 1 becomes the last element.
The assignments in the parallel
rotate_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an bidirectional iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.new_first: Refers to the element that should appear at the beginning of the rotated range.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest_first: Refers to the begin of the destination range.
The assignments in the parallel rotate_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The rotate_copy algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The rotate_copy algorithm returns the output iterator to the element past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/search.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameFwdIter2, typenamePred= detail::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typesearch(ExPolicy &&policy, FwdIter first, FwdIter last, FwdIter2 s_first, FwdIter2 s_last, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Searches the range [first, last) for any elements in the range [s_first, s_last). Uses a provided predicate to compare elements.
The comparison operations in the parallel
search algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most (S*N) comparisons where S = distance(s_first, s_last) and N = distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an input iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of adjacent_find requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of type dereferenced FwdIter.Proj2: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of type dereferenced FwdIter2.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.s_first: Refers to the beginning of the sequence of elements the algorithm will be searching for.s_last: Refers to the end of the sequence of elements of the algorithm will be searching for.op: Refers to the binary predicate which returns true if the elements should be treated as equal. the signature of the function should be equivalent tobool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced FwdIter1 as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced FwdIter2 as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel search algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The search algorithm returns a hpx::future<FwdIter> if the execution policy is of type task_execution_policy and returns FwdIter otherwise. The search algorithm returns an iterator to the beginning of the first subsequence [s_first, s_last) in range [first, last). If the length of the subsequence [s_first, s_last) is greater than the length of the range [first, last), last is returned. Additionally if the size of the subsequence is empty first is returned. If no subsequence is found, last is returned.
-
template<typename
ExPolicy, typenameFwdIter, typenameFwdIter2, typenamePred= detail::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typesearch_n(ExPolicy &&policy, FwdIter first, std::size_t count, FwdIter2 s_first, FwdIter2 s_last, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Searches the range [first, last) for any elements in the range [s_first, s_last). Uses a provided predicate to compare elements.
The comparison operations in the parallel
search_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most (S*N) comparisons where S = distance(s_first, s_last) and N = count.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an input iterator.FwdIter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of adjacent_find requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.count: Refers to the range of elements of the first range the algorithm will be applied to.s_first: Refers to the beginning of the sequence of elements the algorithm will be searching for.s_last: Refers to the end of the sequence of elements of the algorithm will be searching for.op: Refers to the binary predicate which returns true if the elements should be treated as equal. the signature of the function should be equivalent tobool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced FwdIter1 as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced FwdIter2 as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel search_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The search_n algorithm returns a hpx::future<FwdIter> if the execution policy is of type task_execution_policy and returns FwdIter otherwise. The search_n algorithm returns an iterator to the beginning of the last subsequence [s_first, s_last) in range [first, first+count). If the length of the subsequence [s_first, s_last) is greater than the length of the range [first, first+count), first is returned. Additionally if the size of the subsequence is empty or no subsequence is found, first is also returned.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/set_difference.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameFwdIter3, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter3>::type>::typeset_difference(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, FwdIter3 dest, Pred &&op = Pred())¶ Constructs a sorted range beginning at dest consisting of all elements present in the range [first1, last1) and not present in the range [first2, last2). This algorithm expects both input ranges to be sorted with the given binary predicate f.
Equivalent elements are treated individually, that is, if some element is found
m times in [first1, last1) and n times in [first2, last2), it will be copied to dest exactly std::max(m-n, 0) times. The resulting range cannot overlap with either of the input ranges.- Note
Complexity: At most 2*(N1 + N2 - 1) comparisons, where N1 is the length of the first sequence and N2 is the length of the second sequence.
The resulting range cannot overlap with either of the input ranges.
The application of function objects in parallel algorithm invoked with a sequential execution policy object execute in sequential order in the calling thread (
sequenced_policy) or in a single new thread spawned from the current thread (for sequenced_task_policy).- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter1: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of set_difference requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.dest: Refers to the beginning of the destination range.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type InIter can be dereferenced and then implicitly converted to Type1
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The set_difference algorithm returns a hpx::future<FwdIter3> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter3 otherwise. The set_difference algorithm returns the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/set_intersection.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameFwdIter3, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter3>::type>::typeset_intersection(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, FwdIter3 dest, Pred &&op = Pred())¶ Constructs a sorted range beginning at dest consisting of all elements present in both sorted ranges [first1, last1) and [first2, last2). This algorithm expects both input ranges to be sorted with the given binary predicate f.
If some element is found
m times in [first1, last1) and n times in [first2, last2), the first std::min(m, n) elements will be copied from the first range to the destination range. The order of equivalent elements is preserved. The resulting range cannot overlap with either of the input ranges.- Note
Complexity: At most 2*(N1 + N2 - 1) comparisons, where N1 is the length of the first sequence and N2 is the length of the second sequence.
The resulting range cannot overlap with either of the input ranges.
The application of function objects in parallel algorithm invoked with a sequential execution policy object execute in sequential order in the calling thread (
sequenced_policy) or in a single new thread spawned from the current thread (for sequenced_task_policy).- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter1: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of set_intersection requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.dest: Refers to the beginning of the destination range.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type InIter can be dereferenced and then implicitly converted to Type1
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The set_intersection algorithm returns a hpx::future<FwdIter3> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter3 otherwise. The set_intersection algorithm returns the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/set_symmetric_difference.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameFwdIter3, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter3>::type>::typeset_symmetric_difference(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, FwdIter3 dest, Pred &&op = Pred())¶ Constructs a sorted range beginning at dest consisting of all elements present in either of the sorted ranges [first1, last1) and [first2, last2), but not in both of them are copied to the range beginning at dest. The resulting range is also sorted. This algorithm expects both input ranges to be sorted with the given binary predicate f.
If some element is found
m times in [first1, last1) and n times in [first2, last2), it will be copied to dest exactly std::abs(m-n) times. If m>n, then the last m-n of those elements are copied from [first1,last1), otherwise the last n-m elements are copied from [first2,last2). The resulting range cannot overlap with either of the input ranges.- Note
Complexity: At most 2*(N1 + N2 - 1) comparisons, where N1 is the length of the first sequence and N2 is the length of the second sequence.
The resulting range cannot overlap with either of the input ranges.
The application of function objects in parallel algorithm invoked with a sequential execution policy object execute in sequential order in the calling thread (
sequenced_policy) or in a single new thread spawned from the current thread (for sequenced_task_policy).- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter1: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of set_symmetric_difference requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.dest: Refers to the beginning of the destination range.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type InIter can be dereferenced and then implicitly converted to Type1
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The set_symmetric_difference algorithm returns a hpx::future<FwdIter3> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter3 otherwise. The set_symmetric_difference algorithm returns the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/set_union.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameFwdIter3, typenamePred= detail::less>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter3>::type>::typeset_union(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, FwdIter3 dest, Pred &&op = Pred())¶ Constructs a sorted range beginning at dest consisting of all elements present in one or both sorted ranges [first1, last1) and [first2, last2). This algorithm expects both input ranges to be sorted with the given binary predicate f.
If some element is found
m times in [first1, last1) and n times in [first2, last2), then all m elements will be copied from [first1, last1) to dest, preserving order, and then exactly std::max(n-m, 0) elements will be copied from [first2, last2) to dest, also preserving order.- Note
Complexity: At most 2*(N1 + N2 - 1) comparisons, where N1 is the length of the first sequence and N2 is the length of the second sequence.
The resulting range cannot overlap with either of the input ranges.
The application of function objects in parallel algorithm invoked with a sequential execution policy object execute in sequential order in the calling thread (
sequenced_policy) or in a single new thread spawned from the current thread (for sequenced_task_policy).- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter1: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators used (deduced) representing the first sequence. This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.Op: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of set_union requires Pred to meet the requirements of CopyConstructible. This defaults to std::less<>
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.dest: Refers to the beginning of the destination range.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type InIter can be dereferenced and then implicitly converted to Type1
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The set_union algorithm returns a hpx::future<FwdIter3> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter3 otherwise. The set_union algorithm returns the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/sort.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRandomIt, typenameCompare= detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, RandomIt>::typesort(ExPolicy &&policy, RandomIt first, RandomIt last, Compare &&comp = Compare(), Proj &&proj = Proj())¶ Sorts the elements in the range [first, last) in ascending order. The order of equal elements is not guaranteed to be preserved. The function uses the given comparison function object comp (defaults to using operator<()).
A sequence is sorted with respect to a comparator
comp and a projection proj if for every iterator i pointing to the sequence and every non-negative integer n such that i + n is a valid iterator pointing to an element of the sequence, and INVOKE(comp, INVOKE(proj, *(i + n)), INVOKE(proj, *i)) == false.- Note
Complexity: O(Nlog(N)), where N = std::distance(first, last) comparisons.
comp has to induce a strict weak ordering on the values.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.Iter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a random access iterator.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each pair of elements as a projection operation before the actual predicate comp is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The sort algorithm returns a hpx::future<RandomIt> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns RandomIt otherwise. The algorithm returns an iterator pointing to the first element after the last element in the input sequence.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/sort_by_key.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameKeyIter, typenameValueIter, typenameCompare= detail::less>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in1(KeyIter), tag::in2(ValueIter)>>::typesort_by_key(ExPolicy &&policy, KeyIter key_first, KeyIter key_last, ValueIter value_first, Compare &&comp = Compare())¶ Sorts one range of data using keys supplied in another range. The key elements in the range [key_first, key_last) are sorted in ascending order with the corresponding elements in the value range moved to follow the sorted order. The algorithm is not stable, the order of equal elements is not guaranteed to be preserved. The function uses the given comparison function object comp (defaults to using operator<()).
A sequence is sorted with respect to a comparator
comp and a projection proj if for every iterator i pointing to the sequence and every non-negative integer n such that i + n is a valid iterator pointing to an element of the sequence, and INVOKE(comp, INVOKE(proj, *(i + n)), INVOKE(proj, *i)) == false.- Note
Complexity: O(Nlog(N)), where N = std::distance(first, last) comparisons.
comp has to induce a strict weak ordering on the values.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.KeyIter: The type of the key iterators used (deduced). This iterator type must meet the requirements of a random access iterator.ValueIter: The type of the value iterators used (deduced). This iterator type must meet the requirements of a random access iterator.Comp: The type of the function/function object to use (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.key_first: Refers to the beginning of the sequence of key elements the algorithm will be applied to.key_last: Refers to the end of the sequence of key elements the algorithm will be applied to.value_first: Refers to the beginning of the sequence of value elements the algorithm will be applied to, the range of elements must match [key_first, key_last)comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The sort_by-key algorithm returns a hpx::future<tagged_pair<tag::in1(KeyIter>, tag::in2(ValueIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns otherwise. The algorithm returns a pair holding an iterator pointing to the first element after the last element in the input key sequence and an iterator pointing to the first element after the last element in the input value sequence.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/stable_sort.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRandomIt, typenameSentinel, typenameProj= util::projection_identity, typenameCompare= detail::less>
util::detail::algorithm_result<ExPolicy, RandomIt>::typestable_sort(ExPolicy &&policy, RandomIt first, Sentinel last, Compare &&comp = Compare(), Proj &&proj = Proj())¶ Sorts the elements in the range [first, last) in ascending order. The relative order of equal elements is preserved. The function uses the given comparison function object comp (defaults to using operator<()).
A sequence is sorted with respect to a comparator
comp and a projection proj if for every iterator i pointing to the sequence and every non-negative integer n such that i + n is a valid iterator pointing to an element of the sequence, and INVOKE(comp, INVOKE(proj, *(i + n)), INVOKE(proj, *i)) == false.- Note
Complexity: O(Nlog(N)), where N = std::distance(first, last) comparisons.
comp has to induce a strict weak ordering on the values.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.RandomIt: The type of the source iterators used (deduced). This iterator type must meet the requirements of a random access iterator.Sentinel: The type of the end iterators used (deduced). This iterator type must meet the requirements of a random access iterator and must be a valid sentinel type for RandomIt.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each pair of elements as a projection operation before the actual predicate comp is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The stable_sort algorithm returns a hpx::future<RandomIt> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns RandomIt otherwise. The algorithm returns an iterator pointing to the first element after the last element in the input sequence.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/swap_ranges.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeswap_ranges(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2)¶ Exchanges elements between range [first1, last1) and another range starting at first2.
The swap operations in the parallel
swap_ranges algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Linear in the distance between first1 and last1
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the swap operations.FwdIter1: The type of the first range of iterators to swap (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the second range of iterators to swap (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first sequence of elements the algorithm will be applied to.last1: Refers to the end of the first sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the algorithm will be applied to.
The swap operations in the parallel swap_ranges algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The swap_ranges algorithm returns a hpx::future<FwdIter2> if the execution policy is of type parallel_task_policy and returns FwdIter2 otherwise. The swap_ranges algorithm returns iterator to the element past the last element exchanged in the range beginning with first2.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/transform.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)>>::typetransform(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, F &&f, Proj &&proj = Proj())¶ Applies the given function f to the range [first, last) and stores the result in another range, beginning at dest.
The invocations of
f in the parallel transform algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly last - first applications of f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the invocations of f.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of transform requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type. The type Ret must be such that an object of type FwdIter2 can be dereferenced and assigned a value of type Ret.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate f is invoked.
The invocations of f in the parallel transform algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The transform algorithm returns a tuple holding an iterator referring to the first element after the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameFwdIter3, typenameF, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in1(FwdIter1), tag::in2(FwdIter2), tag::out(FwdIter3)>>::typetransform(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter3 dest, F &&f, Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Applies the given function f to pairs of elements from two ranges: one defined by [first1, last1) and the other beginning at first2, and stores the result in another range, beginning at dest.
The invocations of
f in the parallel transform algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly last - first applications of f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the invocations of f.FwdIter1: The type of the source iterators for the first range used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators for the second range used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of transform requires F to meet the requirements of CopyConstructible.Proj1: The type of an optional projection function to be used for elements of the first sequence. This defaults to util::projection_identityProj2: The type of an optional projection function to be used for elements of the second sequence. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first sequence of elements the algorithm will be applied to.last1: Refers to the end of the first sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. The type Ret must be such that an object of type FwdIter3 can be dereferenced and assigned a value of type Ret.proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first sequence as a projection operation before the actual predicate f is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second sequence as a projection operation before the actual predicate f is invoked.
The invocations of f in the parallel transform algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform algorithm returns a hpx::future<tagged_tuple<tag::in1(FwdIter1), tag::in2(FwdIter2), tag::out(FwdIter3)> > if the execution policy is of type parallel_task_policy and returns tagged_tuple<tag::in1(FwdIter1), tag::in2(FwdIter2), tag::out(FwdIter3)> otherwise. The transform algorithm returns a tuple holding an iterator referring to the first element after the first input sequence, an iterator referring to the first element after the second input sequence, and the output iterator referring to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameFwdIter3, typenameF, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in1(FwdIter1), tag::in2(FwdIter2), tag::out(FwdIter3)>>::typetransform(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, FwdIter3 dest, F &&f, Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Applies the given function f to pairs of elements from two ranges: one defined by [first1, last1) and the other beginning at first2, and stores the result in another range, beginning at dest.
The invocations of
f in the parallel transform algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly min(last2-first2, last1-first1) applications of f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the invocations of f.FwdIter1: The type of the source iterators for the first range used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the source iterators for the second range used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of transform requires F to meet the requirements of CopyConstructible.Proj1: The type of an optional projection function to be used for elements of the first sequence. This defaults to util::projection_identityProj2: The type of an optional projection function to be used for elements of the second sequence. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first sequence of elements the algorithm will be applied to.last1: Refers to the end of the first sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the algorithm will be applied to.last2: Refers to the end of the second sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. The type Ret must be such that an object of type FwdIter3 can be dereferenced and assigned a value of type Ret.proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first sequence as a projection operation before the actual predicate f is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second sequence as a projection operation before the actual predicate f is invoked.
The invocations of f in the parallel transform algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The algorithm will invoke the binary predicate until it reaches the end of the shorter of the two given input sequences
- Return
The transform algorithm returns a hpx::future<tagged_tuple<tag::in1(FwdIter1), tag::in2(FwdIter2), tag::out(FwdIter3)> > if the execution policy is of type parallel_task_policy and returns tagged_tuple<tag::in1(FwdIter1), tag::in2(FwdIter2), tag::out(FwdIter3)> otherwise. The transform algorithm returns a tuple holding an iterator referring to the first element after the first input sequence, an iterator referring to the first element after the second input sequence, and the output iterator referring to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/transform_exclusive_scan.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameT, typenameOp, typenameConv>
util::detail::algorithm_result<ExPolicy, FwdIter2>::typetransform_exclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, T init, Op &&op, Conv &&conv)¶ Assigns through each iterator i in [result, result + (last - first)) the value of GENERALIZED_NONCOMMUTATIVE_SUM(binary_op, init, conv(*first), …, conv(*(first + (i - result) - 1))).
The reduce operations in the parallel
transform_exclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicates op and conv.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.Conv: The type of the unary function object used for the conversion operation.T: The type of the value to be used as initial (and intermediate) values (deduced).Op: The type of the binary function object used for the reduction operation.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.conv: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a unary predicate. The signature of this predicate should be equivalent to:R fun(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type. The type R must be such that an object of this type can be implicitly converted to T.init: The initial value for the generalized sum.op: Specifies the function (or function object) which will be invoked for each of the values of the input sequence. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Ret must be such that an object of a type as given by the input sequence can be implicitly converted to any of those types.
The reduce operations in the parallel transform_exclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
Neither
conv nor op shall invalidate iterators or subranges, or modify elements in the ranges [first,last) or [result,result + (last - first)).- Return
The transform_exclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The transform_exclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aN) is defined as:
a1 when N is 1
op(GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aK), GENERALIZED_NONCOMMUTATIVE_SUM(op, aM, …, aN) where 1 < K+1 = M <= N.
The behavior of transform_exclusive_scan may be non-deterministic for a non-associative predicate.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/transform_inclusive_scan.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameOp, typenameConv, typenameT>
util::detail::algorithm_result<ExPolicy, FwdIter2>::typetransform_inclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, Op &&op, Conv &&conv, T init)¶ Assigns through each iterator i in [result, result + (last - first)) the value of GENERALIZED_NONCOMMUTATIVE_SUM(op, init, conv(*first), …, conv(*(first + (i - result)))).
The reduce operations in the parallel
transform_inclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.Conv: The type of the unary function object used for the conversion operation.T: The type of the value to be used as initial (and intermediate) values (deduced).Op: The type of the binary function object used for the reduction operation.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.conv: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a unary predicate. The signature of this predicate should be equivalent to:R fun(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type. The type R must be such that an object of this type can be implicitly converted to T.init: The initial value for the generalized sum.op: Specifies the function (or function object) which will be invoked for each of the values of the input sequence. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Ret must be such that an object of a type as given by the input sequence can be implicitly converted to any of those types.
The reduce operations in the parallel transform_inclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
Neither
conv nor op shall invalidate iterators or subranges, or modify elements in the ranges [first,last) or [result,result + (last - first)).- Return
The transform_inclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The transform_inclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aN) is defined as:
a1 when N is 1
op(GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aK), GENERALIZED_NONCOMMUTATIVE_SUM(op, aM, …, aN)) where 1 < K+1 = M <= N.
The difference between exclusive_scan and transform_inclusive_scan is that transform_inclusive_scan includes the ith input element in the ith sum. If op is not mathematically associative, the behavior of transform_inclusive_scan may be non-deterministic.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameConv, typenameOp>
util::detail::algorithm_result<ExPolicy, FwdIter2>::typetransform_inclusive_scan(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, Op &&op, Conv &&conv)¶ Assigns through each iterator i in [result, result + (last - first)) the value of GENERALIZED_NONCOMMUTATIVE_SUM(op, conv(*first), …, conv(*(first + (i - result)))).
The reduce operations in the parallel
transform_inclusive_scan algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.Conv: The type of the unary function object used for the conversion operation.T: The type of the value to be used as initial (and intermediate) values (deduced).Op: The type of the binary function object used for the reduction operation.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.conv: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a unary predicate. The signature of this predicate should be equivalent to:R fun(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type. The type R must be such that an object of this type can be implicitly converted to T.op: Specifies the function (or function object) which will be invoked for each of the values of the input sequence. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Ret must be such that an object of a type as given by the input sequence can be implicitly converted to any of those types.
The reduce operations in the parallel transform_inclusive_scan algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
Neither
conv nor op shall invalidate iterators or subranges, or modify elements in the ranges [first,last) or [result,result + (last - first)).- Return
The transform_inclusive_scan algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The transform_inclusive_scan algorithm returns the output iterator to the element in the destination range, one past the last element copied.
- Note
GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aN) is defined as:
a1 when N is 1
op(GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, …, aK), GENERALIZED_NONCOMMUTATIVE_SUM(op, aM, …, aN)) where 1 < K+1 = M <= N.
The difference between exclusive_scan and transform_inclusive_scan is that transform_inclusive_scan includes the ith input element in the ith sum.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/transform_reduce.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameT, typenameReduce, typenameConvert>
util::detail::algorithm_result<ExPolicy, T>::typetransform_reduce(ExPolicy &&policy, FwdIter first, FwdIter last, T init, Reduce &&red_op, Convert &&conv_op)¶ Returns GENERALIZED_SUM(red_op, init, conv_op(*first), …, conv_op(*(first + (last - first) - 1))).
The reduce operations in the parallel
transform_reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicates red_op and conv_op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.T: The type of the value to be used as initial (and intermediate) values (deduced).Reduce: The type of the binary function object used for the reduction operation.Convert: The type of the unary function object used to transform the elements of the input sequence before invoking the reduce function.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.conv_op: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a unary predicate. The signature of this predicate should be equivalent to:R fun(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type. The type R must be such that an object of this type can be implicitly converted to T.init: The initial value for the generalized sum.red_op: Specifies the function (or function object) which will be invoked for each of the values returned from the invocation of conv_op. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1, Type2, and Ret must be such that an object of a type as returned from conv_op can be implicitly converted to any of those types.
The reduce operations in the parallel transform_reduce algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
transform_reduce and accumulate is that the behavior of transform_reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The transform_reduce algorithm returns a hpx::future<T> if the execution policy is of type parallel_task_policy and returns T otherwise. The transform_reduce algorithm returns the result of the generalized sum over the values returned from conv_op when applied to the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(op, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(op, b1, …, bK), GENERALIZED_SUM(op, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameT>
util::detail::algorithm_result<ExPolicy, T>::typetransform_reduce(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, T init)¶ Returns the result of accumulating init with the inner products of the pairs formed by the elements of two ranges starting at first1 and first2.
The operations in the parallel
transform_reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op2.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the first source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the second source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as return) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first sequence of elements the result will be calculated with.last1: Refers to the end of the first sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the result will be calculated with.init: The initial value for the sum.
The operations in the parallel transform_reduce algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform_reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenameT, typenameReduce, typenameConvert>
util::detail::algorithm_result<ExPolicy, T>::typetransform_reduce(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, T init, Reduce &&red_op, Convert &&conv_op)¶ Returns the result of accumulating init with the inner products of the pairs formed by the elements of two ranges starting at first1 and first2.
The operations in the parallel
transform_reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op2.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the first source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the second source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as return) values (deduced).Reduce: The type of the binary function object used for the multiplication operation.Convert: The type of the unary function object used to transform the elements of the input sequence before invoking the reduce function.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first sequence of elements the result will be calculated with.last1: Refers to the end of the first sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the result will be calculated with.init: The initial value for the sum.red_op: Specifies the function (or function object) which will be invoked for the initial value and each of the return values of op2. This is a binary predicate. The signature of this predicate should be equivalent to should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Ret must be such that it can be implicitly converted to a type of T.conv_op: Specifies the function (or function object) which will be invoked for each of the input values of the sequence. This is a binary predicate. The signature of this predicate should be equivalent toRet fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Ret must be such that it can be implicitly converted to an object for the second argument type of op1.
The operations in the parallel transform_reduce algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform_reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise.
-
template<typename
Header hpx/parallel/algorithms/transform_reduce_binary.hpp¶
Header hpx/parallel/algorithms/uninitialized_copy.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeuninitialized_copy(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest)¶ Copies the elements in the range, defined by [first, last), to an uninitialized memory area beginning at dest. If an exception is thrown during the copy operation, the function has no effects.
The assignments in the parallel
uninitialized_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of a forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel uninitialized_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_copy algorithm returns a hpx::future<FwdIter2>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The uninitialized_copy algorithm returns the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameSize, typenameFwdIter2>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy, FwdIter2>::type>::typeuninitialized_copy_n(ExPolicy &&policy, FwdIter1 first, Size count, FwdIter2 dest)¶ Copies the elements in the range [first, first + count), starting from first and proceeding to first + count - 1., to another range beginning at dest. If an exception is thrown during the copy operation, the function has no effects.
The assignments in the parallel
uninitialized_copy_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an input iterator.Size: The type of the argument specifying the number of elements to apply f to.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of a forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel uninitialized_copy_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_copy_n algorithm returns a hpx::future<FwdIter2> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The uninitialized_copy_n algorithm returns the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/uninitialized_default_construct.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter>
util::detail::algorithm_result<ExPolicy>::typeuninitialized_default_construct(ExPolicy &&policy, FwdIter first, FwdIter last)¶ Constructs objects of type typename iterator_traits<ForwardIt>::value_type in the uninitialized storage designated by the range [first, last) by default-initialization. If an exception is thrown during the initialization, the function has no effects.
The assignments in the parallel
uninitialized_default_construct algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.
The assignments in the parallel uninitialized_default_construct algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_default_construct algorithm returns a hpx::future<void>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize>
util::detail::algorithm_result<ExPolicy, FwdIter>::typeuninitialized_default_construct_n(ExPolicy &&policy, FwdIter first, Size count)¶ Constructs objects of type typename iterator_traits<ForwardIt>::value_type in the uninitialized storage designated by the range [first, first + count) by default-initialization. If an exception is thrown during the initialization, the function has no effects.
The assignments in the parallel
uninitialized_default_construct_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.
The assignments in the parallel uninitialized_default_construct_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_default_construct_n algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The uninitialized_default_construct_n algorithm returns the iterator to the element in the source range, one past the last element constructed.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/uninitialized_fill.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameT>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy>::type>::typeuninitialized_fill(ExPolicy &&policy, FwdIter first, FwdIter last, T const &value)¶ Copies the given value to an uninitialized memory area, defined by the range [first, last). If an exception is thrown during the initialization, the function has no effects.
The initializations in the parallel
uninitialized_fill algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Linear in the distance between first and last
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be assigned (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.value: The value to be assigned.
The initializations in the parallel uninitialized_fill algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_fill algorithm returns a hpx::future<void>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns nothing otherwise.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize, typenameT>
std::enable_if<execution::is_execution_policy<ExPolicy>::value, typename util::detail::algorithm_result<ExPolicy>::type>::typeuninitialized_fill_n(ExPolicy &&policy, FwdIter first, Size count, T const &value)¶ Copies the given value value to the first count elements in an uninitialized memory area beginning at first. If an exception is thrown during the initialization, the function has no effects.
The initializations in the parallel
uninitialized_fill_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of a forward iterator.Size: The type of the argument specifying the number of elements to apply f to.T: The type of the value to be assigned (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.value: The value to be assigned.
The initializations in the parallel uninitialized_fill_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_fill_n algorithm returns a hpx::future<void>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns nothing otherwise.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/uninitialized_move.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2>
util::detail::algorithm_result<ExPolicy, FwdIter2>::typeuninitialized_move(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest)¶ Moves the elements in the range, defined by [first, last), to an uninitialized memory area beginning at dest. If an exception is thrown during the initialization, some objects in [first, last) are left in a valid but unspecified state.
The assignments in the parallel
uninitialized_move algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first move operations.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of a forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel uninitialized_move algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_move algorithm returns a hpx::future<FwdIter2>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter2 otherwise. The uninitialized_move algorithm returns the output iterator to the element in the destination range, one past the last element moved.
-
template<typename
ExPolicy, typenameFwdIter1, typenameSize, typenameFwdIter2>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)>>::typeuninitialized_move_n(ExPolicy &&policy, FwdIter1 first, Size count, FwdIter2 dest)¶ Moves the elements in the range [first, first + count), starting from first and proceeding to first + count - 1., to another range beginning at dest. If an exception is thrown during the initialization, some objects in [first, first + count) are left in a valid but unspecified state.
The assignments in the parallel
uninitialized_move_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count movements, if count > 0, no move operations otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of a forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel uninitialized_move_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_move_n algorithm returns a hpx::future<std::pair<FwdIter1, FwdIter2>> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns std::pair<FwdIter1, FwdIter2> otherwise. The uninitialized_move_n algorithm returns the pair of the input iterator to the element past in the source range and an output iterator to the element in the destination range, one past the last element moved.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/uninitialized_value_construct.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter>
util::detail::algorithm_result<ExPolicy>::typeuninitialized_value_construct(ExPolicy &&policy, FwdIter first, FwdIter last)¶ Constructs objects of type typename iterator_traits<ForwardIt>::value_type in the uninitialized storage designated by the range [first, last) by default-initialization. If an exception is thrown during the initialization, the function has no effects.
The assignments in the parallel
uninitialized_value_construct algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.
The assignments in the parallel uninitialized_value_construct algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_value_construct algorithm returns a hpx::future<void>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize>
util::detail::algorithm_result<ExPolicy, FwdIter>::typeuninitialized_value_construct_n(ExPolicy &&policy, FwdIter first, Size count)¶ Constructs objects of type typename iterator_traits<ForwardIt>::value_type in the uninitialized storage designated by the range [first, first + count) by default-initialization. If an exception is thrown during the initialization, the function has no effects.
The assignments in the parallel
uninitialized_value_construct_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.
The assignments in the parallel uninitialized_value_construct_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The uninitialized_value_construct_n algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The uninitialized_value_construct_n algorithm returns the iterator to the element in the source range, one past the last element constructed.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/algorithms/unique.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameFwdIter, typenamePred= detail::equal_to, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typeunique(ExPolicy &&policy, FwdIter first, FwdIter last, Pred &&pred = Pred(), Proj &&proj = Proj())¶ Eliminates all but the first element from every consecutive group of equivalent elements from the range [first, last) and returns a past-the-end iterator for the new logical end of the range.
The assignments in the parallel
unique algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first - 1 applications of the predicate pred and no more than twice as many applications of the projection proj.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of unique requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is an binary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter can be dereferenced and then implicitly converted to both Type1 and Type2proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel unique algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The unique algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The unique algorithm returns the iterator to the new end of the range.
-
template<typename
ExPolicy, typenameFwdIter1, typenameFwdIter2, typenamePred= detail::equal_to, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)>>::typeunique_copy(ExPolicy &&policy, FwdIter1 first, FwdIter1 last, FwdIter2 dest, Pred &&pred = Pred(), Proj &&proj = Proj())¶ Copies the elements from the range [first, last), to another range beginning at dest in such a way that there are no consecutive equal elements. Only the first element of each group of equal elements is copied.
The assignments in the parallel
unique_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first - 1 applications of the predicate pred and no more than twice as many applications of the projection proj
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of unique_copy requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is an binary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a, const Type &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel unique_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The unique_copy algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The unique_copy algorithm returns the pair of the source iterator to last, and the destination iterator to the end of the dest range.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms.hpp¶
Header hpx/parallel/container_algorithms/all_any_none.hpp¶
-
namespace
hpx -
namespace
ranges¶ Functions
-
template<typename
ExPolicy, typenameRng, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typenone_of(ExPolicy &&policy, Rng &&rng, F &&f, Proj &&proj = Proj())¶ Checks if unary predicate f returns true for no elements in the range rng.
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most std::distance(begin(rng), end(rng)) applications of the predicate f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of none_of requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The none_of algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The none_of algorithm returns true if the unary predicate f returns true for no elements in the range, false otherwise. It returns true if the range is empty.
-
template<typename
ExPolicy, typenameRng, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeany_of(ExPolicy &&policy, Rng &&rng, F &&f, Proj &&proj = Proj())¶ Checks if unary predicate f returns true for at least one element in the range rng.
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most std::distance(begin(rng), end(rng)) applications of the predicate f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of none_of requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The any_of algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The any_of algorithm returns true if the unary predicate f returns true for at least one element in the range, false otherwise. It returns false if the range is empty.
-
template<typename
ExPolicy, typenameRng, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeall_of(ExPolicy &&policy, Rng &&rng, F &&f, Proj &&proj = Proj())¶ Checks if unary predicate f returns true for all elements in the range rng.
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most std::distance(begin(rng), end(rng)) applications of the predicate f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of none_of requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The all_of algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The all_of algorithm returns true if the unary predicate f returns true for all elements in the range, false otherwise. It returns true if the range is empty.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/copy.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy, typenameIter1, typenameSent1, typenameFwdIter>
hpx::parallel::util::detail::algorithm_result<ExPolicy, hpx::ranges::copy_result<Iter1, Iter>>::typecopy(ExPolicy &&policy, Iter1 iter, Sent1 sent, FwdIter dest)¶ Copies the elements in the range, defined by [first, last), to another range beginning at dest.
The assignments in the parallel
copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iter1: The type of the begin source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Sent1: The type of the end source iterators used (deduced). This iterator type must meet the requirements of an sentinel for Iter1.FwdIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.iter: Refers to the beginning of the sequence of elements the algorithm will be applied to.sent: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy algorithm returns a hpx::future<ranges::copy_result<FwdIter1, FwdIter> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns ranges::copy_result<FwdIter1, FwdIter> otherwise. The copy algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameRng, typenameFwdIter>
hpx::parallel::util::detail::algorithm_result<ExPolicy, hpx::ranges::copy_result<typename hpx::traits::range_traits<Rng>::iterator_type, FwdIter>>::typecopy(ExPolicy &&policy, Rng &&rng, FwdIter dest)¶ Copies the elements in the range rng to another range beginning at dest.
The assignments in the parallel
copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly std::distance(begin(rng), end(rng)) assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.FwdIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy algorithm returns a hpx::future<ranges::copy_result<iterator_t<Rng>, FwdIter2>> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns ranges::copy_result<iterator_t<Rng>, FwdIter2> otherwise. The copy algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameSize, typenameFwdIter2>
hpx::parallel::util::detail::algorithm_result<ExPolicy, hpx::ranges::copy_n_result<FwdIter1, FwdIter2>>::typecopy_n(ExPolicy &&policy, FwdIter1 first, Size count, FwdIter2 dest)¶ Copies the elements in the range [first, first + count), starting from first and proceeding to first + count - 1., to another range beginning at dest.
The assignments in the parallel
copy_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel copy_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy_n algorithm returns a hpx::future<ranges::copy_n_result<FwdIter1, FwdIter2> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns ranges::copy_n_result<FwdIter1, FwdIter2> otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameFwdIter1, typenameSent1, typenameFwdIter, typenameF, typenameProj= hpx::parallel::util::projection_identity>
hpx::parallel::util::detail::algorithm_result<ExPolicy, hpx::ranges::copy_if_result<typename hpx::traits::range_traits<Rng>::iterator_type, OutIter>>::typecopy_if(ExPolicy &&policy, FwdIter1 iter, Sent1 sent, FwdIter dest, F &&f, Proj &&proj = Proj())¶ Copies the elements in the range, defined by [first, last) to another range beginning at dest. Copies only the elements for which the predicate f returns true. The order of the elements that are not removed is preserved.
The assignments in the parallel
copy_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than std::distance(begin(rng), end(rng)) assignments, exactly std::distance(begin(rng), end(rng)) applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the begin source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Sent1: The type of the end source iterators used (deduced). This iterator type must meet the requirements of an sentinel for FwdIter1.FwdIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.iter: Refers to the beginning of the sequence of elements the algorithm will be applied to.sent: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy_if algorithm returns a hpx::future<ranges::copy_if_result<iterator_t<Rng>, FwdIter2>> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns ranges::copy_if_result<iterator_t<Rng>, FwdIter2> otherwise. The copy_if algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameRng, typenameOutIter, typenameF, typenameProj= hpx::parallel::util::projection_identity>
hpx::parallel::util::detail::algorithm_result<ExPolicy, hpx::ranges::copy_if_result<typename hpx::traits::range_traits<Rng>::iterator_type, OutIter>>::typecopy_if(ExPolicy &&policy, Rng &&rng, OutIter dest, F &&f, Proj &&proj = Proj())¶ Copies the elements in the range rng to another range beginning at dest. Copies only the elements for which the predicate f returns true. The order of the elements that are not removed is preserved.
The assignments in the parallel
copy_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than std::distance(begin(rng), end(rng)) assignments, exactly std::distance(begin(rng), end(rng)) applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The copy_if algorithm returns a hpx::future<ranges::copy_if_result<iterator_t<Rng>, FwdIter2>> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns ranges::copy_if_result<iterator_t<Rng>, FwdIter2> otherwise. The copy_if algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/count.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy, typenameRng, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename std::iterator_traits<typename hpx::traits::range_traits<Rng>::iterator_type>::difference_type>::typecount(ExPolicy &&policy, Rng &&rng, T const &value, Proj &&proj = Proj())¶ Returns the number of elements in the range [first, last) satisfying a specific criteria. This version counts the elements that are equal to the given value.
The comparisons in the parallel
count algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first comparisons.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the comparisons.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.T: The type of the value to search for (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.value: The value to search for.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
- Note
The comparisons in the parallel count algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The count algorithm returns a hpx::future<difference_type> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by std::iterator_traits<FwdIter>::difference_type. The count algorithm returns the number of elements satisfying the given criteria.
-
template<typename
ExPolicy, typenameRng, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename std::iterator_traits<typename hpx::traits::range_traits<Rng>::iterator_type>::difference_type>::typecount_if(ExPolicy &&policy, Rng &&rng, F &&f, Proj &&proj = Proj())¶ Returns the number of elements in the range [first, last) satisfying a specific criteria. This version counts elements for which predicate f returns true.
- Note
Complexity: Performs exactly last - first applications of the predicate.
- Note
The assignments in the parallel count_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
- Note
The assignments in the parallel count_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The count_if algorithm returns hpx::future<difference_type> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by std::iterator_traits<FwdIter>::difference_type. The count algorithm returns the number of elements satisfying the given criteria.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the comparisons.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of count_if requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/destroy.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy>
util::detail::algorithm_result<ExPolicy, typename traits::range_iterator<Rng>::type>::typedestroy(ExPolicy &&policy, Rng &&rng)¶ Destroys objects of type typename iterator_traits<ForwardIt>::value_type in the range [first, last).
The operations in the parallel
destroy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first operations.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.
The operations in the parallel destroy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The destroy algorithm returns a hpx::future<void>, if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize>
util::detail::algorithm_result<ExPolicy, FwdIter>::typedestroy_n(ExPolicy &&policy, FwdIter first, Size count)¶ Destroys objects of type typename iterator_traits<ForwardIt>::value_type in the range [first, first + count).
The operations in the parallel
destroy_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count operations, if count > 0, no assignments otherwise.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply this algorithm to.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.
The operations in the parallel destroy_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The destroy_n algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The destroy_n algorithm returns the iterator to the element in the source range, one past the last element constructed.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/equal.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy, typenameIter1, typenameSent1, typenameIter2, typenameSent2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeequal(ExPolicy &&policy, Iter1 first1, Sent1 last1, Iter2 first2, Sent2 last2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Returns true if the range [first1, last1) is equal to the range [first2, last2), and false otherwise.
The comparison operations in the parallel
equal algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most min(last1 - first1, last2 - first2) applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.Sent1: The type of the source iterators used for the end of the first range (deduced).Iter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Sent2: The type of the source iterators used for the end of the second range (deduced).Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of equal requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function applied to the first range. This defaults to util::projection_identityProj2: The type of an optional projection function applied to the second range. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel equal algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The two ranges are considered equal if, for every iterator i in the range [first1,last1), *i equals *(first2 + (i - first1)). This overload of equal uses operator== to determine if two elements are equal.
- Return
The equal algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The equal algorithm returns true if the elements in the two ranges are equal, otherwise it returns false. If the length of the range [first1, last1) does not equal the length of the range [first2, last2), it returns false.
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeequal(ExPolicy &&policy, Rng1 &&rng1, Rng2 &&rng2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Returns true if the range [first1, last1) is equal to the range starting at first2, and false otherwise.
The comparison operations in the parallel
equal algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last1 - first1 applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the first source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Rng2: The type of the second source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of equal requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function applied to the first range. This defaults to util::projection_identityProj2: The type of an optional projection function applied to the second range. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the first sequence of elements the algorithm will be applied to.rng2: Refers to the second sequence of elements the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel equal algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The two ranges are considered equal if, for every iterator i in the range [first1,last1), *i equals *(first2 + (i - first1)). This overload of equal uses operator== to determine if two elements are equal.
- Return
The equal algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The equal algorithm returns true if the elements in the two ranges are equal, otherwise it returns false.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/fill.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameRng, typenameT>
util::detail::algorithm_result<ExPolicy>::typefill(ExPolicy &&policy, Rng &&rng, T const &value)¶ Assigns the given value to the elements in the range [first, last).
The comparisons in the parallel
fill algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.T: The type of the value to be assigned (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.value: The value to be assigned.
The comparisons in the parallel fill algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The fill algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by void.
-
template<typename
ExPolicy, typenameIterator, typenameSize, typenameT>
util::detail::algorithm_result<ExPolicy, Iterator>::typefill_n(ExPolicy &&policy, Iterator first, Size count, T const &value)¶ Assigns the given value value to the first count elements in the range beginning at first if count > 0. Does nothing otherwise.
The comparisons in the parallel
fill_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly count assignments, for count > 0.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iterator: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.T: The type of the value to be assigned (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.value: The value to be assigned.
The comparisons in the parallel fill_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The fill_n algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns difference_type otherwise (where difference_type is defined by void.
-
template<typename
Header hpx/parallel/container_algorithms/find.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy, typenameIter, typenameSent, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, Iter>::typefind(ExPolicy &&policy, Iter first, Sent last, T const &val, Proj &&proj = Proj())¶ Returns the first element in the range [first, last) that is equal to value
The comparison operations in the parallel
find algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the operator==().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iter: The type of the begin source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Sent: The type of the end source iterators used (deduced). This iterator type must meet the requirements of an sentinel for Iter.T: The type of the value to find (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.val: the value to compare the elements toproj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel find algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The find algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The find algorithm returns the first element in the range [first,last) that is equal to val. If no such element in the range of [first,last) is equal to val, then the algorithm returns last.
-
template<typename
ExPolicy, typenameRng, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, Iter>::typefind(ExPolicy &&policy, Rng &&rng, T const &val, Proj &&proj = Proj())¶ Returns the first element in the range [first, last) that is equal to value
The comparison operations in the parallel
find algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last - first applications of the operator==().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.T: The type of the value to find (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.val: the value to compare the elements toproj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel find algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The find algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The find algorithm returns the first element in the range [first,last) that is equal to val. If no such element in the range of [first,last) is equal to val, then the algorithm returns last.
-
template<typename
ExPolicy, typenameIter1, typenameSent1, typenameIter2, typenameSent2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng1>::type>::typefind_end(ExPolicy &&policy, Iter1 first1, Sent1 last1, Iter2 first2, Sent2 last2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Returns the last subsequence of elements [first2, last2) found in the range [first1, last1) using the given predicate f to compare elements.
The comparison operations in the parallel
find_end algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most S*(N-S+1) comparisons where S = distance(first2, last2) and N = distance(first1, last1).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iter1: The type of the begin source iterators for the first sequence used (deduced). This iterator type must meet the requirements of an forward iterator.Sent1: The type of the end source iterators for the first sequence used (deduced). This iterator type must meet the requirements of an sentinel for Iter1.Iter2: The type of the begin source iterators for the second sequence used (deduced). This iterator type must meet the requirements of an forward iterator.Sent2: The type of the end source iterators for the second sequence used (deduced). This iterator type must meet the requirements of an sentinel for Iter2.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of replace requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function applied to the first sequence. This defaults to util::projection_identityProj2: The type of an optional projection function applied to the second sequence. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first sequence of elements the algorithm will be applied to.last1: Refers to the end of the first sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the algorithm will be applied to.last2: Refers to the end of the second sequence of elements the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types iterator_t<Rng> and iterator_t<Rng2> can be dereferenced and then implicitly converted to Type1 and Type2 respectively.proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range of type dereferenced iterator_t<Rng1> as a projection operation before the function op is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range of type dereferenced iterator_t<Rng2> as a projection operation before the function op is invoked.
The comparison operations in the parallel find_end algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
This overload of
find_end is available if the user decides to provide the algorithm their own predicate op.- Return
The find_end algorithm returns a hpx::future<iterator_t<Rng> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns iterator_t<Rng> otherwise. The find_end algorithm returns an iterator to the beginning of the last subsequence rng2 in range rng. If the length of the subsequence rng2 is greater than the length of the range rng, end(rng) is returned. Additionally if the size of the subsequence is empty or no subsequence is found, end(rng) is also returned.
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng1>::type>::typefind_end(ExPolicy &&policy, Rng1 &&rng, Rng2 &&rng2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Returns the last subsequence of elements rng2 found in the range rng using the given predicate f to compare elements.
The comparison operations in the parallel
find_end algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most S*(N-S+1) comparisons where S = distance(begin(rng2), end(rng2)) and N = distance(begin(rng), end(rng)).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the first source range (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.Rng2: The type of the second source range (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of replace requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function applied to the first sequence. This defaults to util::projection_identityProj2: The type of an optional projection function applied to the second sequence. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the first sequence of elements the algorithm will be applied to.rng2: Refers to the second sequence of elements the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types iterator_t<Rng> and iterator_t<Rng2> can be dereferenced and then implicitly converted to Type1 and Type2 respectively.proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range of type dereferenced iterator_t<Rng1> as a projection operation before the function op is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range of type dereferenced iterator_t<Rng2> as a projection operation before the function op is invoked.
The comparison operations in the parallel find_end algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
This overload of
find_end is available if the user decides to provide the algorithm their own predicate op.- Return
The find_end algorithm returns a hpx::future<iterator_t<Rng> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns iterator_t<Rng> otherwise. The find_end algorithm returns an iterator to the beginning of the last subsequence rng2 in range rng. If the length of the subsequence rng2 is greater than the length of the range rng, end(rng) is returned. Additionally if the size of the subsequence is empty or no subsequence is found, end(rng) is also returned.
-
template<typename
ExPolicy, typenameIter1, typenameSent1, typenameIter2, typenameSent2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng1>::type>::typefind_first_of(ExPolicy &&policy, Iter1 first1, Sent1 last1, Iter2 first2, Sent2 last2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Searches the range [first1, last1) for any elements in the range [first2, last2). Uses binary predicate p to compare elements
The comparison operations in the parallel
find_first_of algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most (S*N) comparisons where S = distance(first2, last2) and N = distance(first1, last1).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iter1: The type of the begin source iterators for the first sequence used (deduced). This iterator type must meet the requirements of an forward iterator.Sent1: The type of the end source iterators for the first sequence used (deduced). This iterator type must meet the requirements of an sentinel for Iter1.Iter2: The type of the begin source iterators for the second sequence used (deduced). This iterator type must meet the requirements of an forward iterator.Sent2: The type of the end source iterators for the second sequence used (deduced). This iterator type must meet the requirements of an sentinel for Iter2.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of replace requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements in rng1.Proj2: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements in rng2.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the first sequence of elements the algorithm will be applied to.last1: Refers to the end of the first sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the algorithm will be applied to.last2: Refers to the end of the second sequence of elements the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types iterator_t<Rng1> and iterator_t<Rng2> can be dereferenced and then implicitly converted to Type1 and Type2 respectively.proj1: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced iterator_t<Rng1> before the function op is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced iterator_t<Rng2> before the function op is invoked.
The comparison operations in the parallel find_first_of algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
This overload of
find_first_of is available if the user decides to provide the algorithm their own predicate op.- Return
The find_end algorithm returns a hpx::future<iterator_t<Rng1> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns iterator_t<Rng1> otherwise. The find_first_of algorithm returns an iterator to the first element in the range rng1 that is equal to an element from the range rng2. If the length of the subsequence rng2 is greater than the length of the range rng1, end(rng1) is returned. Additionally if the size of the subsequence is empty or no subsequence is found, end(rng1) is also returned.
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng1>::type>::typefind_first_of(ExPolicy &&policy, Rng1 &&rng1, Rng2 &&rng2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Searches the range rng1 for any elements in the range rng2. Uses binary predicate p to compare elements
The comparison operations in the parallel
find_first_of algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most (S*N) comparisons where S = distance(begin(rng2), end(rng2)) and N = distance(begin(rng1), end(rng1)).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the first source range (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.Rng2: The type of the second source range (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of replace requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements in rng1.Proj2: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements in rng2.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the first sequence of elements the algorithm will be applied to.rng2: Refers to the second sequence of elements the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as equal. The signature should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types iterator_t<Rng1> and iterator_t<Rng2> can be dereferenced and then implicitly converted to Type1 and Type2 respectively.proj1: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced iterator_t<Rng1> before the function op is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of type dereferenced iterator_t<Rng2> before the function op is invoked.
The comparison operations in the parallel find_first_of algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
This overload of
find_first_of is available if the user decides to provide the algorithm their own predicate op.- Return
The find_end algorithm returns a hpx::future<iterator_t<Rng1> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns iterator_t<Rng1> otherwise. The find_first_of algorithm returns an iterator to the first element in the range rng1 that is equal to an element from the range rng2. If the length of the subsequence rng2 is greater than the length of the range rng1, end(rng1) is returned. Additionally if the size of the subsequence is empty or no subsequence is found, end(rng1) is also returned.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/for_each.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
InIter, typenameSent, typenameF, typenameProj= util::projection_identity>
hpx::ranges::for_each_result<InIter, F>for_each(InIter first, Sent last, F &&f, Proj &&proj = Proj())¶ Applies f to the result of dereferencing every iterator in the range [first, last).
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly last - first times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
Applies
f to the result of dereferencing every iterator in the range [first, first + count), starting from first and proceeding to first + count - 1.- Return
{last, std::move(f)} where last is the iterator corresponding to the input sentinel last.
- Template Parameters
InIter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an input iterator.Sent: The type of the source sentinel (deduced). This sentinel type must be a sentinel for InIter.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly last - first times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
- Return
{first + count, std::move(f)}
- Template Parameters
InIter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an input iterator.Size: The type of the argument specifying the number of elements to apply f to.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
-
template<typename
ExPolicy, typenameFwdIter, typenameSent, typenameF, typenameProj= util::projection_identity>
FwdIterfor_each(ExPolicy &&policy, FwdIter first, Sent last, F &&f, Proj &&proj = Proj())¶ Applies f to the result of dereferencing every iterator in the range [first, last).
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly last - first times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
Unlike its sequential form, the parallel overload of for_each does not return a copy of its Function parameter, since parallelization may not permit efficient state accumulation.
- Return
The for_each algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.Sent: The type of the source sentinel (deduced). This sentinel type must be a sentinel for InIter.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
-
template<typename
Rng, typenameF, typenameProj= util::projection_identity>
hpx::ranges::for_each_result<typename hpx::traits::range_iterator<Rng>::type, F>for_each(ExPolicy &&policy, Rng &&rng, F &&f, Proj &&proj = Proj())¶ Applies f to the result of dereferencing every iterator in the given range rng.
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly size(rng) times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
- Return
{std::end(rng), std::move(f)}
- Template Parameters
Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
-
template<typename
ExPolicy, typenameRng, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typefor_each(ExPolicy &&policy, Rng &&rng, F &&f, Proj &&proj = Proj())¶ Applies f to the result of dereferencing every iterator in the given range rng.
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly size(rng) times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
Unlike its sequential form, the parallel overload of for_each does not return a copy of its Function parameter, since parallelization may not permit efficient state accumulation.
The application of function objects in parallel algorithm invoked with an execution policy object of type
sequenced_policy execute in sequential order in the calling thread.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The for_each algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, FwdIter>::typefor_each_n(ExPolicy &&policy, FwdIter first, Size count, F &&f, Proj &&proj = Proj())¶ Applies f to the result of dereferencing every iterator in the range [first, first + count), starting from first and proceeding to first + count - 1.
If
f returns a result, the result is ignored.- Note
Complexity: Applies f exactly count times.
If the type of first satisfies the requirements of a mutable iterator, f may apply non-constant functions through the dereferenced iterator.
Unlike its sequential form, the parallel overload of for_each does not return a copy of its Function parameter, since parallelization may not permit efficient state accumulation.
- Return
The for_each algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.FwdIter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.Size: The type of the argument specifying the number of elements to apply f to.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of for_each requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements starting at first the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). The signature of this predicate should be equivalent to:<ignored> pred(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/generate.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy, typenameRng, typenameF>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typegenerate(ExPolicy &&policy, Rng &&rng, F &&f)¶ Assign each element in range [first, last) a value generated by the given function object f
The assignments in the parallel
generate algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly distance(first, last) invocations of f and assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: generator function that will be called. signature of function should be equivalent to the following:Ret fun();
The type
Ret must be such that an object of type FwdIter can be dereferenced and assigned a value of type Ret.
The assignments in the parallel generate algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
-
template<typename
ExPolicy, typenameIter, typenameSent, typenameF>
util::detail::algorithm_result<ExPolicy, Iter>::typegenerate(ExPolicy &&policy, Iter first, Sent last, F &&f)¶ Assign each element in range [first, last) a value generated by the given function object f
The assignments in the parallel
generate algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly distance(first, last) invocations of f and assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.Sent: The type of the source end iterator used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: generator function that will be called. signature of function should be equivalent to the following:Ret fun();
The type
Ret must be such that an object of type FwdIter can be dereferenced and assigned a value of type Ret.
The assignments in the parallel generate algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
-
template<typename
ExPolicy, typenameFwdIter, typenameSize, typenameF>
util::detail::algorithm_result<ExPolicy, FwdIter>::typegenerate_n(ExPolicy &&policy, FwdIter first, Size count, F &&f)¶ Assigns each element in range [first, first+count) a value generated by the given function object g.
The assignments in the parallel
generate_n algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly count invocations of f and assignments, for count > 0.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.count: Refers to the number of elements in the sequence the algorithm will be applied to.f: Refers to the generator function object that will be called. The signature of the function should be equivalent toRet fun();
The type
Ret must be such that an object of type OutputIt can be dereferenced and assigned a value of type Ret.
The assignments in the parallel generate_n algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. It returns last.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/is_heap.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenameComp= detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, bool>::typeis_heap(ExPolicy &&policy, Rng &&rng, Comp &&comp = Comp(), Proj &&proj = Proj())¶ Returns whether the range is max heap. That is, true if the range is max heap, false otherwise. The function uses the given comparison function object comp (defaults to using operator<()).
comp has to induce a strict weak ordering on the values.
- Note
Complexity: Performs at most N applications of the comparison comp, at most 2 * N applications of the projection proj, where N = last - first.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an random access iterator.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The is_heap algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The is_heap algorithm returns whether the range is max heap. That is, true if the range is max heap, false otherwise.
-
template<typename
ExPolicy, typenameRng, typenameComp= detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typeis_heap_until(ExPolicy &&policy, Rng &&rng, Comp &&comp = Comp(), Proj &&proj = Proj())¶ Returns the upper bound of the largest range beginning at first which is a max heap. That is, the last iterator it for which range [first, it) is a max heap. The function uses the given comparison function object comp (defaults to using operator<()).
comp has to induce a strict weak ordering on the values.
- Note
Complexity: Performs at most N applications of the comparison comp, at most 2 * N applications of the projection proj, where N = last - first.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an random access iterator.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The is_heap_until algorithm returns a hpx::future<RandIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns RandIter otherwise. The is_heap_until algorithm returns the upper bound of the largest range beginning at first which is a max heap. That is, the last iterator it for which range [first, it) is a max heap.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/merge.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenameRandIter3, typenameComp= detail::less, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in1(typename hpx::traits::range_iterator<Rng1>::type), tag::in2(typename hpx::traits::range_iterator<Rng2>::type), tag::out(RandIter3)>>::typemerge(ExPolicy &&policy, Rng1 &&rng1, Rng2 &&rng2, RandIter3 dest, Comp &&comp = Comp(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Merges two sorted ranges [first1, last1) and [first2, last2) into one sorted range beginning at dest. The order of equivalent elements in the each of original two ranges is preserved. For equivalent elements in the original two ranges, the elements from the first range precede the elements from the second range. The destination range cannot overlap with either of the input ranges.
The assignments in the parallel
merge algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs O(std::distance(first1, last1) + std::distance(first2, last2)) applications of the comparison comp and the each projection.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the first source range used (deduced). The iterators extracted from this range type must meet the requirements of an random access iterator.Rng2: The type of the second source range used (deduced). The iterators extracted from this range type must meet the requirements of an random access iterator.RandIter3: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an random access iterator.Comp: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of merge requires Comp to meet the requirements of CopyConstructible. This defaults to std::less<>Proj1: The type of an optional projection function to be used for elements of the first range. This defaults to util::projection_identityProj2: The type of an optional projection function to be used for elements of the second range. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the first range of elements the algorithm will be applied to.rng2: Refers to the second range of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.comp: comp is a callable object which returns true if the first argument is less than the second, and false otherwise. The signature of this comparison should be equivalent to:bool comp(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types RandIter1 and RandIter2 can be dereferenced and then implicitly converted to both Type1 and Type2proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range as a projection operation before the actual comparison comp is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range as a projection operation before the actual comparison comp is invoked.
The assignments in the parallel merge algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The merge algorithm returns a hpx::future<tagged_tuple<tag::in1(RandIter1), tag::in2(RandIter2), tag::out(RandIter3)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_tuple<tag::in1(RandIter1), tag::in2(RandIter2), tag::out(RandIter3)> otherwise. The merge algorithm returns the tuple of the source iterator last1, the source iterator last2, the destination iterator to the end of the dest range.
-
template<typename
ExPolicy, typenameRng, typenameRandIter, typenameComp= detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, RandIter>::typeinplace_merge(ExPolicy &&policy, Rng &&rng, RandIter middle, Comp &&comp = Comp(), Proj &&proj = Proj())¶ Merges two consecutive sorted ranges [first, middle) and [middle, last) into one sorted range [first, last). The order of equivalent elements in the each of original two ranges is preserved. For equivalent elements in the original two ranges, the elements from the first range precede the elements from the second range.
The assignments in the parallel
inplace_merge algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs O(std::distance(first, last)) applications of the comparison comp and the each projection.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an random access iterator.RandIter: The type of the source iterators used (deduced). This iterator type must meet the requirements of an random access iterator.Comp: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of inplace_merge requires Comp to meet the requirements of CopyConstructible. This defaults to std::less<>Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the range of elements the algorithm will be applied to.middle: Refers to the end of the first sorted range and the beginning of the second sorted range the algorithm will be applied to.comp: comp is a callable object which returns true if the first argument is less than the second, and false otherwise. The signature of this comparison should be equivalent to:bool comp(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types RandIter can be dereferenced and then implicitly converted to both Type1 and Type2proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel inplace_merge algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The inplace_merge algorithm returns a hpx::future<RandIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns RandIter otherwise. The inplace_merge algorithm returns the source iterator last
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/minmax.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenameProj= util::projection_identity, typenameF= detail::less>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_traits<Rng>::iterator_type>::typemin_element(ExPolicy &&policy, Rng &&rng, F &&f = F(), Proj &&proj = Proj())¶ Finds the smallest element in the range [first, last) using the given comparison function f.
The comparisons in the parallel
min_element algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly max(N-1, 0) comparisons, where N = std::distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of min_element requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: The binary predicate which returns true if the the left argument is less than the right element. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type1.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparisons in the parallel min_element algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The min_element algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The min_element algorithm returns the iterator to the smallest element in the range [first, last). If several elements in the range are equivalent to the smallest element, returns the iterator to the first such element. Returns last if the range is empty.
-
template<typename
ExPolicy, typenameRng, typenameProj= util::projection_identity, typenameF= detail::less>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_traits<Rng>::iterator_type>::typemax_element(ExPolicy &&policy, Rng &&rng, F &&f = F(), Proj &&proj = Proj())¶ Finds the greatest element in the range [first, last) using the given comparison function f.
The comparisons in the parallel
max_element algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly max(N-1, 0) comparisons, where N = std::distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of max_element requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: The binary predicate which returns true if the This argument is optional and defaults to std::less. the left argument is less than the right element. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type1.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparisons in the parallel max_element algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The max_element algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The max_element algorithm returns the iterator to the smallest element in the range [first, last). If several elements in the range are equivalent to the smallest element, returns the iterator to the first such element. Returns last if the range is empty.
-
template<typename
ExPolicy, typenameRng, typenameProj= util::projection_identity, typenameF= detail::less>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::min(typename hpx::traits::range_traits<Rng>::iterator_type), tag::max(typename hpx::traits::range_traits<Rng>::iterator_type)>>::typeminmax_element(ExPolicy &&policy, Rng &&rng, F &&f = F(), Proj &&proj = Proj())¶ Finds the greatest element in the range [first, last) using the given comparison function f.
The comparisons in the parallel
minmax_element algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most max(floor(3/2*(N-1)), 0) applications of the predicate, where N = std::distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of minmax_element requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: The binary predicate which returns true if the the left argument is less than the right element. This argument is optional and defaults to std::less. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type1 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The type
Type1 must be such that objects of type FwdIter can be dereferenced and then implicitly converted to Type1.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The comparisons in the parallel minmax_element algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The minmax_element algorithm returns a hpx::future<tagged_pair<tag::min(FwdIter), tag::max(FwdIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::min(FwdIter), tag::max(FwdIter)> otherwise. The minmax_element algorithm returns a pair consisting of an iterator to the smallest element as the first element and an iterator to the greatest element as the second. Returns std::make_pair(first, first) if the range is empty. If several elements are equivalent to the smallest element, the iterator to the first such element is returned. If several elements are equivalent to the largest element, the iterator to the last such element is returned.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/mismatch.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy, typenameIter1, typenameSent1, typenameIter2, typenameSent2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, ranges::mismatch_result<FwdIter1, FwdIter2>>::typemismatch(ExPolicy &&policy, FwdIter1 first1, FwdIter1 last1, FwdIter2 first2, FwdIter2 last2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Returns true if the range [first1, last1) is mismatch to the range [first2, last2), and false otherwise.
The comparison operations in the parallel
mismatch algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most min(last1 - first1, last2 - first2) applications of the predicate f. If FwdIter1 and FwdIter2 meet the requirements of RandomAccessIterator and (last1 - first1) != (last2 - first2) then no applications of the predicate f are made.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Iter1: The type of the source iterators used for the first range (deduced). This iterator type must meet the requirements of an forward iterator.Sent1: The type of the source iterators used for the end of the first range (deduced).Iter2: The type of the source iterators used for the second range (deduced). This iterator type must meet the requirements of an forward iterator.Sent2: The type of the source iterators used for the end of the second range (deduced).Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of mismatch requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function applied to the first range. This defaults to util::projection_identityProj2: The type of an optional projection function applied to the second range. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first1: Refers to the beginning of the sequence of elements of the first range the algorithm will be applied to.last1: Refers to the end of the sequence of elements of the first range the algorithm will be applied to.first2: Refers to the beginning of the sequence of elements of the second range the algorithm will be applied to.last2: Refers to the end of the sequence of elements of the second range the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as mismatch. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel mismatch algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The two ranges are considered mismatch if, for every iterator i in the range [first1,last1), *i mismatchs *(first2 + (i - first1)). This overload of mismatch uses operator== to determine if two elements are mismatch.
- Return
The mismatch algorithm returns a hpx::future<bool> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns bool otherwise. The mismatch algorithm returns true if the elements in the two ranges are mismatch, otherwise it returns false. If the length of the range [first1, last1) does not mismatch the length of the range [first2, last2), it returns false.
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenamePred= ranges::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, ranges::mimatch_result<FwdIter1, FwdIter2>>::typemismatch(ExPolicy &&policy, Rng1 &&rng1, Rng2 &&rng2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Returns std::pair with iterators to the first two non-equivalent elements.
The comparison operations in the parallel
mismatch algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: At most last1 - first1 applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the first source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Rng2: The type of the second source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of mismatch requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function applied to the first range. This defaults to util::projection_identityProj2: The type of an optional projection function applied to the second range. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the first sequence of elements the algorithm will be applied to.rng2: Refers to the second sequence of elements the algorithm will be applied to.op: The binary predicate which returns true if the elements should be treated as mismatch. The signature of the predicate function should be equivalent to the following:bool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of the first range as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second range as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel mismatch algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The mismatch algorithm returns a hpx::future<std::pair<FwdIter1, FwdIter2> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns std::pair<FwdIter1, FwdIter2> otherwise. The mismatch algorithm returns the first mismatching pair of elements from two ranges: one defined by [first1, last1) and another defined by [first2, last2).
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/move.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameFwdIter1, typenameSent1, typenameFwdIter>
util::detail::algorithm_result<ExPolicy, ranges::move_result<FwdIter1, FwdIter>>::typemove(ExPolicy &&policy, FwdIter1 iter, Sent1 sent, FwdIter dest)¶ Moves the elements in the range rng to another range beginning at dest. After this operation the elements in the moved-from range will still contain valid values of the appropriate type, but not necessarily the same values as before the move.
The assignments in the parallel
copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly std::distance(begin(rng), end(rng)) assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter1: The type of the begin source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.Sent1: The type of the end source iterators used (deduced). This iterator type must meet the requirements of an sentinel for FwdIter1.FwdIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The move algorithm returns a hpx::future<ranges::move_result<iterator_t<Rng>, FwdIter2>> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns ranges::move_result<iterator_t<Rng>, FwdIter2> otherwise. The move algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element moved.
-
template<typename
ExPolicy, typenameRng, typenameFwdIter>
util::detail::algorithm_result<ExPolicy, ranges::move_result<typename hpx::traits::range_traits<Rng>::iterator_type, FwdIter>>::typemove(ExPolicy &&policy, Rng &&rng, FwdIter dest)¶ Moves the elements in the range rng to another range beginning at dest. After this operation the elements in the moved-from range will still contain valid values of the appropriate type, but not necessarily the same values as before the move.
The assignments in the parallel
copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly std::distance(begin(rng), end(rng)) assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.FwdIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.
The assignments in the parallel copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The move algorithm returns a hpx::future<ranges::move_result<iterator_t<Rng>, FwdIter2>> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns ranges::move_result<iterator_t<Rng>, FwdIter2> otherwise. The move algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element moved.
-
template<typename
Header hpx/parallel/container_algorithms/partition.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenamePred, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typepartition(ExPolicy &&policy, Rng &&rng, Pred &&pred, Proj &&proj = Proj())¶ Reorders the elements in the range rng in such a way that all elements for which the predicate pred returns true precede the elements for which the predicate pred returns false. Relative order of the elements is not preserved.
The assignments in the parallel
partition algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs at most 2 * N swaps, exactly N applications of the predicate and projection, where N = std::distance(begin(rng), end(rng)).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of partition requires Pred to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by the range rng. This is an unary predicate for partitioning the source iterators. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel partition algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The partition algorithm returns a hpx::future<FwdIter> if the execution policy is of type parallel_task_policy and returns FwdIter otherwise. The partition algorithm returns the iterator to the first element of the second group.
-
template<typename
ExPolicy, typenameRng, typenameFwdIter2, typenameFwdIter3, typenamePred, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in(typename hpx::traits::range_iterator<Rng>::type), tag::out1(FwdIter2), tag::out2(FwdIter3)>>::typepartition_copy(ExPolicy &&policy, Rng &&rng, FwdIter2 dest_true, FwdIter3 dest_false, Pred &&pred, Proj &&proj = Proj())¶ Copies the elements in the range rng, to two different ranges depending on the value returned by the predicate pred. The elements, that satisfy the predicate pred, are copied to the range beginning at dest_true. The rest of the elements are copied to the range beginning at dest_false. The order of the elements is preserved.
The assignments in the parallel
partition_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than N assignments, exactly N applications of the predicate pred, where N = std::distance(begin(rng), end(rng)).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range for the elements that satisfy the predicate pred (deduced). This iterator type must meet the requirements of an forward iterator.FwdIter3: The type of the iterator representing the destination range for the elements that don’t satisfy the predicate pred (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of partition_copy requires Pred to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest_true: Refers to the beginning of the destination range for the elements that satisfy the predicate pred.dest_false: Refers to the beginning of the destination range for the elements that don’t satisfy the predicate pred.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by the range rng. This is an unary predicate for partitioning the source iterators. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel partition_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The partition_copy algorithm returns a hpx::future<tagged_tuple<tag::in(InIter), tag::out1(OutIter1), tag::out2(OutIter2)> > if the execution policy is of type parallel_task_policy and returns tagged_tuple<tag::in(InIter), tag::out1(OutIter1), tag::out2(OutIter2)> otherwise. The partition_copy algorithm returns the tuple of the source iterator last, the destination iterator to the end of the dest_true range, and the destination iterator to the end of the dest_false range.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/reduce.hpp¶
-
namespace
hpx -
namespace
ranges Functions
-
template<typename
ExPolicy, typenameFwdIter, typenameSent, typenameT, typenameF>
util::detail::algorithm_result<ExPolicy, T>::typereduce(ExPolicy &&policy, FwdIter first, Sent last, T init, F &&f)¶ Returns GENERALIZED_SUM(f, init, *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.Sent: The type of the source sentinel used (deduced). This iterator type must meet the requirements of an forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.T: The type of the value to be used as initial (and intermediate) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&. The types
Type1 Ret must be such that an object of type FwdIterB can be dereferenced and then implicitly converted to any of those types.init: The initial value for the generalized sum.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise. The reduce algorithm returns the result of the generalized sum over the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(op, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(op, b1, …, bK), GENERALIZED_SUM(op, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter, typenameSent, typenameT>
util::detail::algorithm_result<ExPolicy, T>::typereduce(ExPolicy &&policy, FwdIter first, Sent last, T init)¶ Returns GENERALIZED_SUM(+, init, *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the operator+().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.Sent: The type of the source sentinel used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as initial (and intermediate) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.init: The initial value for the generalized sum.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise. The reduce algorithm returns the result of the generalized sum (applying operator+()) over the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(+, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(+, b1, …, bK), GENERALIZED_SUM(+, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameFwdIter, typenameSent>
util::detail::algorithm_result<ExPolicy, typename std::iterator_traits<FwdIter>::value_type>::typereduce(ExPolicy &&policy, FwdIter first, Sent last)¶ Returns GENERALIZED_SUM(+, T(), *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the operator+().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.FwdIter: The type of the source begin iterator used (deduced). This iterator type must meet the requirements of an forward iterator.Sent: The type of the source sentinel used (deduced). This iterator type must meet the requirements of an forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.first: Refers to the beginning of the sequence of elements the algorithm will be applied to.last: Refers to the end of the sequence of elements the algorithm will be applied to.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise (where T is the value_type of FwdIterB). The reduce algorithm returns the result of the generalized sum (applying operator+()) over the elements given by the input range [first, last).
- Note
The type of the initial value (and the result type) T is determined from the value_type of the used FwdIterB.
- Note
GENERALIZED_SUM(+, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(+, b1, …, bK), GENERALIZED_SUM(+, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameRng, typenameT, typenameF>
util::detail::algorithm_result<ExPolicy, T>::typereduce(ExPolicy &&policy, Rng &&rng, T init, F &&f)¶ Returns GENERALIZED_SUM(f, init, *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.T: The type of the value to be used as initial (and intermediate) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&. The types
Type1 Ret must be such that an object of type FwdIterB can be dereferenced and then implicitly converted to any of those types.init: The initial value for the generalized sum.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise. The reduce algorithm returns the result of the generalized sum over the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(op, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(op, b1, …, bK), GENERALIZED_SUM(op, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameRng, typenameT>
util::detail::algorithm_result<ExPolicy, T>::typereduce(ExPolicy &&policy, Rng &&rng, T init)¶ Returns GENERALIZED_SUM(+, init, *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the operator+().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.T: The type of the value to be used as initial (and intermediate) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.init: The initial value for the generalized sum.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise. The reduce algorithm returns the result of the generalized sum (applying operator+()) over the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(+, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(+, b1, …, bK), GENERALIZED_SUM(+, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameRng>
util::detail::algorithm_result<ExPolicy, typename std::iterator_traits<typename hpx::traits::range_traits<Rng>::iterator_type>::value_type>::typereduce(ExPolicy &&policy, Rng &&rng)¶ Returns GENERALIZED_SUM(+, T(), *first, …, *(first + (last - first) - 1)).
The reduce operations in the parallel
reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the operator+().
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.
The reduce operations in the parallel copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
reduce and accumulate is that the behavior of reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise (where T is the value_type of FwdIterB). The reduce algorithm returns the result of the generalized sum (applying operator+()) over the elements given by the input range [first, last).
- Note
The type of the initial value (and the result type) T is determined from the value_type of the used FwdIterB.
- Note
GENERALIZED_SUM(+, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(+, b1, …, bK), GENERALIZED_SUM(+, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
-
namespace
Header hpx/parallel/container_algorithms/remove.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typeremove(ExPolicy &&policy, Rng &&rng, T const &value, Proj &&proj = Proj())¶ Removes all elements satisfying specific criteria from the range [first, last) and returns a past-the-end iterator for the new end of the range. This version removes all elements that are equal to value.
The assignments in the parallel
remove algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the operator==() and the projection proj.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.T: The type of the value to remove (deduced). This value type must meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.value: Specifies the value of elements to remove.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The remove algorithm returns the iterator to the new end of the range.
-
template<typename
ExPolicy, typenameRng, typenamePred, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typeremove_if(ExPolicy &&policy, Rng &&rng, Pred &&pred, Proj &&proj = Proj())¶ Removes all elements satisfying specific criteria from the range [first, last) and returns a past-the-end iterator for the new end of the range. This version removes all elements for which predicate pred returns true.
The assignments in the parallel
remove_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate pred and the projection proj.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of remove_if requires Pred to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The remove_if algorithm returns the iterator to the new end of the range.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/remove_copy.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenameOutIter, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, util::in_out_result<typename hpx::traits::range_traits<Rng>::iterator_type, OutIter>>::typeremove_copy(ExPolicy &&policy, Rng &&rng, OutIter dest, T const &val, Proj &&proj = Proj())¶ Copies the elements in the range, defined by [first, last), to another range beginning at dest. Copies only the elements for which the comparison operator returns false when compare to val. The order of the elements that are not removed is preserved.
Effects: Copies all the elements referred to by the iterator it in the range [first,last) for which the following corresponding conditions do not hold: INVOKE(proj, *it) == value
The assignments in the parallel
remove_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.T: The type that the result of dereferencing InIter is compared to.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.val: Value to be removed.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove_copy algorithm returns a hpx::future<tagged_pair<tag::in(InIter), tag::out(OutIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(InIter), tag::out(OutIter)> otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameRng, typenameOutIter, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, util::in_out_result<typename hpx::traits::range_traits<Rng>::iterator_type, OutIter>>::typeremove_copy_if(ExPolicy &&policy, Rng &&rng, OutIter dest, F &&f, Proj &&proj = Proj())¶ Copies the elements in the range, defined by [first, last), to another range beginning at dest. Copies only the elements for which the predicate f returns false. The order of the elements that are not removed is preserved.
Effects: Copies all the elements referred to by the iterator it in the range [first,last) for which the following corresponding conditions do not hold: INVOKE(pred, INVOKE(proj, *it)) != false.
The assignments in the parallel
remove_copy_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than last - first assignments, exactly last - first applications of the predicate f.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the elements to be removed. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel remove_copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The remove_copy_if algorithm returns a hpx::future<tagged_pair<tag::in(InIter), tag::out(OutIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(InIter), tag::out(OutIter)> otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/replace.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenameT1, typenameT2, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_traits<Rng>::iterator_type>::typereplace(ExPolicy &&policy, Rng &&rng, T1 const &old_value, T2 const &new_value, Proj &&proj = Proj())¶ Replaces all elements satisfying specific criteria with new_value in the range [first, last).
Effects: Substitutes elements referred by the iterator it in the range [first,last) with new_value, when the following corresponding conditions hold: INVOKE(proj, *i) == old_value
- Note
Complexity: Performs exactly last - first assignments.
The assignments in the parallel
replace algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.T1: The type of the old value to replace (deduced).T2: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.old_value: Refers to the old value of the elements to replace.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace algorithm returns a hpx::future<void> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise.
-
template<typename
ExPolicy, typenameRng, typenameF, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_traits<Rng>::iterator_type>::typereplace_if(ExPolicy &&policy, Rng &&rng, F &&f, T const &new_value, Proj &&proj = Proj())¶ Replaces all elements satisfying specific criteria (for which predicate f returns true) with new_value in the range [first, last).
Effects: Substitutes elements referred by the iterator it in the range [first, last) with new_value, when the following corresponding conditions hold: INVOKE(f, INVOKE(proj, *it)) != false
- Note
Complexity: Performs exactly last - first applications of the predicate.
The assignments in the parallel
replace_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible. (deduced).T: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the elements which need to replaced. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_if algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns void otherwise. It returns last.
-
template<typename
ExPolicy, typenameRng, typenameOutIter, typenameT1, typenameT2, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(typename hpx::traits::range_traits<Rng>::iterator_type), tag::out(OutIter)>>::typereplace_copy(ExPolicy &&policy, Rng &&rng, OutIter dest, T1 const &old_value, T2 const &new_value, Proj &&proj = Proj())¶ Copies the all elements from the range [first, last) to another range beginning at dest replacing all elements satisfying a specific criteria with new_value.
Effects: Assigns to every iterator it in the range [result, result + (last - first)) either new_value or *(first + (it - result)) depending on whether the following corresponding condition holds: INVOKE(proj, *(first + (i - result))) == old_value
The assignments in the parallel
replace_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first applications of the predicate.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.T1: The type of the old value to replace (deduced).T2: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.old_value: Refers to the old value of the elements to replace.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_copy algorithm returns a hpx::future<tagged_pair<tag::in(InIter), tag::out(OutIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(InIter), tag::out(OutIter)> otherwise. The copy algorithm returns the pair of the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameRng, typenameOutIter, typenameF, typenameT, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(typename hpx::traits::range_traits<Rng>::iterator_type), tag::out(OutIter)>>::typereplace_copy_if(ExPolicy &&policy, Rng &&rng, OutIter dest, F &&f, T const &new_value, Proj &&proj = Proj())¶ Copies the all elements from the range [first, last) to another range beginning at dest replacing all elements satisfying a specific criteria with new_value.
Effects: Assigns to every iterator it in the range [result, result + (last - first)) either new_value or *(first + (it - result)) depending on whether the following corresponding condition holds: INVOKE(f, INVOKE(proj, *(first + (i - result)))) != false
The assignments in the parallel
replace_copy_if algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first applications of the predicate.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of equal requires F to meet the requirements of CopyConstructible. (deduced).T: The type of the new values to replace (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate which returns true for the elements which need to replaced. The signature of this predicate should be equivalent to:bool pred(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter can be dereferenced and then implicitly converted to Type.new_value: Refers to the new value to use as the replacement.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel replace_copy_if algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The replace_copy_if algorithm returns a hpx::future<tagged_pair<tag::in(InIter), tag::out(OutIter)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(InIter), tag::out(OutIter)> otherwise. The replace_copy_if algorithm returns the input iterator last and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/reverse.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typereverse(ExPolicy &&policy, Rng &&rng)¶ Reverses the order of the elements in the range [first, last). Behaves as if applying std::iter_swap to every pair of iterators first+i, (last-i) - 1 for each non-negative i < (last-first)/2.
The assignments in the parallel
reverse algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Linear in the distance between first and last.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of a bidirectional iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.
The assignments in the parallel reverse algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The reverse algorithm returns a hpx::future<BidirIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns BidirIter otherwise. It returns last.
-
template<typename
ExPolicy, typenameRng, typenameOutIter>
util::detail::algorithm_result<ExPolicy, util::in_out_result<typename hpx::traits::range_iterator<Rng>::type, OutIter>>::typereverse_copy(ExPolicy &&policy, Rng &&rng, OutIter dest_first)¶ Copies the elements from the range [first, last) to another range beginning at dest_first in such a way that the elements in the new range are in reverse order. Behaves as if by executing the assignment *(dest_first + (last - first) - 1 - i) = *(first + i) once for each non-negative i < (last - first) If the source and destination ranges (that is, [first, last) and [dest_first, dest_first+(last-first)) respectively) overlap, the behavior is undefined.
The assignments in the parallel
reverse_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of a bidirectional iterator.OutputIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest_first: Refers to the begin of the destination range.
The assignments in the parallel reverse_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The reverse_copy algorithm returns a hpx::future<in_out_result<BidirIter, OutIter> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns in_out_result<BidirIter, OutIter> otherwise. The copy algorithm returns the pair of the input iterator forwarded to the first element after the last in the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/rotate.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng>
util::detail::algorithm_result<ExPolicy, util::in_out_result<typename hpx::traits::range_iterator<Rng>::type, typename hpx::traits::range_iterator<Rng>::type>>::typerotate(ExPolicy &&policy, Rng &&rng, typename hpx::traits::range_iterator<Rng>::type middle)¶ Performs a left rotation on a range of elements. Specifically, rotate swaps the elements in the range [first, last) in such a way that the element new_first becomes the first element of the new range and new_first - 1 becomes the last element.
The assignments in the parallel
rotate algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Linear in the distance between first and last.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.middle: Refers to the element that should appear at the beginning of the rotated range.
The assignments in the parallel rotate algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The type of dereferenced FwdIter must meet the requirements of MoveAssignable and MoveConstructible.
- Return
The rotate algorithm returns a hpx::future<tagged_pair<tag::begin(FwdIter), tag::end(FwdIter)> > if the execution policy is of type parallel_task_policy and returns tagged_pair<tag::begin(FwdIter), tag::end(FwdIter)> otherwise. The rotate algorithm returns the iterator equal to pair(first + (last - new_first), last).
-
template<typename
ExPolicy, typenameRng, typenameOutIter>
util::detail::algorithm_result<ExPolicy, util::in_out_result<typename hpx::traits::range_iterator<Rng>::type, OutIter>>::typerotate_copy(ExPolicy &&policy, Rng &&rng, typename hpx::traits::range_iterator<Rng>::type middle, OutIter dest_first)¶ Copies the elements from the range [first, last), to another range beginning at dest_first in such a way, that the element new_first becomes the first element of the new range and new_first - 1 becomes the last element.
The assignments in the parallel
rotate_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs exactly last - first assignments.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of a forward iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.middle: Refers to the element that should appear at the beginning of the rotated range.dest_first: Refers to the begin of the destination range.
The assignments in the parallel rotate_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The rotate_copy algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter), tag::out(OutIter)> > if the execution policy is of type parallel_task_policy and returns tagged_pair<tag::in(FwdIter), tag::out(OutIter)> otherwise. The rotate_copy algorithm returns the output iterator to the element past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/search.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenamePred= detail::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng1>::type>::typesearch(ExPolicy &&policy, Rng1 &&rng1, Rng2 &&rng2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Searches the range [first, last) for any elements in the range [s_first, s_last). Uses a provided predicate to compare elements.
The comparison operations in the parallel
search algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most (S*N) comparisons where S = distance(s_first, s_last) and N = distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the examine range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.Rng2: The type of the search range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of adjacent_find requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of Rng1.Proj2: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of Rng2.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the sequence of elements the algorithm will be examining.rng2: Refers to the sequence of elements the algorithm will be searching for.op: Refers to the binary predicate which returns true if the elements should be treated as equal. the signature of the function should be equivalent tobool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of rng1 as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of rng2 as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel search algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The search algorithm returns a hpx::future<FwdIter> if the execution policy is of type task_execution_policy and returns FwdIter otherwise. The search algorithm returns an iterator to the beginning of the first subsequence [s_first, s_last) in range [first, last). If the length of the subsequence [s_first, s_last) is greater than the length of the range [first, last), last is returned. Additionally if the size of the subsequence is empty first is returned. If no subsequence is found, last is returned.
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenamePred= detail::equal_to, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng1>::type>::typesearch_n(ExPolicy &&policy, Rng1 &&rng1, std::size_t count, Rng2 &&rng2, Pred &&op = Pred(), Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Searches the range [first, last) for any elements in the range [s_first, s_last). Uses a provided predicate to compare elements.
The comparison operations in the parallel
search algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: at most (S*N) comparisons where S = distance(s_first, s_last) and N = distance(first, last).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the examine range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.Rng2: The type of the search range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.Pred: The type of an optional function/function object to use. Unlike its sequential form, the parallel overload of adjacent_find requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj1: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of Rng1.Proj2: The type of an optional projection function. This defaults to util::projection_identity and is applied to the elements of Rng2.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the sequence of elements the algorithm will be examining.count: The number of elements to apply the algorithm on.rng2: Refers to the sequence of elements the algorithm will be searching for.op: Refers to the binary predicate which returns true if the elements should be treated as equal. the signature of the function should be equivalent tobool pred(const Type1 &a, const Type2 &b);
The signature does not need to have const &, but the function must not modify the objects passed to it. The types
Type1 and Type2 must be such that objects of types FwdIter1 and FwdIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectivelyproj1: Specifies the function (or function object) which will be invoked for each of the elements of rng1 as a projection operation before the actual predicate is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of rng2 as a projection operation before the actual predicate is invoked.
The comparison operations in the parallel search algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The search algorithm returns a hpx::future<FwdIter> if the execution policy is of type task_execution_policy and returns FwdIter otherwise. The search algorithm returns an iterator to the beginning of the first subsequence [s_first, s_last) in range [first, last). If the length of the subsequence [s_first, s_last) is greater than the length of the range [first, last), last is returned. Additionally if the size of the subsequence is empty first is returned. If no subsequence is found, last is returned.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/sort.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
rangev1¶ Functions
-
template<typename
ExPolicy, typenameRng, typenameCompare= v1::detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typesort(ExPolicy &&policy, Rng &&rng, Compare &&comp = Compare(), Proj &&proj = Proj())¶ Sorts the elements in the range rng in ascending order. The order of equal elements is not guaranteed to be preserved. The function uses the given comparison function object comp (defaults to using operator<()).
A sequence is sorted with respect to a comparator
comp and a projection proj if for every iterator i pointing to the sequence and every non-negative integer n such that i + n is a valid iterator pointing to an element of the sequence, and INVOKE(comp, INVOKE(proj, *(i + n)), INVOKE(proj, *i)) == false.- Note
Complexity: O(Nlog(N)), where N = std::distance(begin(rng), end(rng)) comparisons.
comp has to induce a strict weak ordering on the values.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each pair of elements as a projection operation before the actual predicate comp is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The sort algorithm returns a hpx::future<Iter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns Iter otherwise. It returns last.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/stable_sort.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
rangev1 Functions
-
template<typename
ExPolicy, typenameRng, typenameCompare= v1::detail::less, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typestable_sort(ExPolicy &&policy, Rng &&rng, Compare &&comp = Compare(), Proj &&proj = Proj())¶ Sorts the elements in the range [first, last) in ascending order. The relative order of equal elements is preserved. The function uses the given comparison function object comp (defaults to using operator<()).
A sequence is sorted with respect to a comparator
comp and a projection proj if for every iterator i pointing to the sequence and every non-negative integer n such that i + n is a valid iterator pointing to an element of the sequence, and INVOKE(comp, INVOKE(proj, *(i + n)), INVOKE(proj, *i)) == false.- Note
Complexity: O(Nlog(N)), where N = std::distance(first, last) comparisons.
comp has to induce a strict weak ordering on the values.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it applies user-provided function objects.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.Comp: The type of the function/function object to use (deduced).Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.comp: comp is a callable object. The return value of the INVOKE operation applied to an object of type Comp, when contextually converted to bool, yields true if the first argument of the call is less than the second, and false otherwise. It is assumed that comp will not apply any non-constant function through the dereferenced iterator.proj: Specifies the function (or function object) which will be invoked for each pair of elements as a projection operation before the actual predicate comp is invoked.
The application of function objects in parallel algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.
The application of function objects in parallel algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The stable_sort algorithm returns a hpx::future<RandomIt> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns RandomIt otherwise. The algorithm returns an iterator pointing to the first element after the last element in the input sequence.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/transform.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenameOutIter, typenameF, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(typename hpx::traits::range_iterator<Rng>::type), tag::out(OutIter)>>::typetransform(ExPolicy &&policy, Rng &&rng, OutIter dest, F &&f, Proj &&proj = Proj())¶ Applies the given function f to the given range rng and stores the result in another range, beginning at dest.
The invocations of
f in the parallel transform algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly size(rng) applications of f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the invocations of f.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of transform requires F to meet the requirements of CopyConstructible.Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is an unary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type &a);
The signature does not need to have const&. The type
Type must be such that an object of type InIter can be dereferenced and then implicitly converted to Type. The type Ret must be such that an object of type OutIter can be dereferenced and assigned a value of type Ret.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate f is invoked.
The invocations of f in the parallel transform algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform algorithm returns a hpx::future<tagged_pair<tag::in(InIter), tag::out(OutIter)> > if the execution policy is of type parallel_task_policy and returns tagged_pair<tag::in(InIter), tag::out(OutIter)> otherwise. The transform algorithm returns a tuple holding an iterator referring to the first element after the input sequence and the output iterator to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameRng, typenameInIter2, typenameOutIter, typenameF, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in1(typename hpx::traits::range_iterator<Rng>::type), tag::in2(InIter2), tag::out(OutIter)>>::typetransform(ExPolicy &&policy, Rng &&rng, InIter2 first2, OutIter dest, F &&f, Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Applies the given function f to pairs of elements from two ranges: one defined by rng and the other beginning at first2, and stores the result in another range, beginning at dest.
The invocations of
f in the parallel transform algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly size(rng) applications of f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the invocations of f.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.InIter2: The type of the source iterators for the second range used (deduced). This iterator type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of transform requires F to meet the requirements of CopyConstructible.Proj1: The type of an optional projection function to be used for elements of the first sequence. This defaults to util::projection_identityProj2: The type of an optional projection function to be used for elements of the second sequence. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&. The types
Type1 and Type2 must be such that objects of types InIter1 and InIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. The type Ret must be such that an object of type OutIter can be dereferenced and assigned a value of type Ret.proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first sequence as a projection operation before the actual predicate f is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second sequence as a projection operation before the actual predicate f is invoked.
The invocations of f in the parallel transform algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform algorithm returns a hpx::future<tagged_tuple<tag::in1(InIter1), tag::in2(InIter2), tag::out(OutIter)> > if the execution policy is of type parallel_task_policy and returns tagged_tuple<tag::in1(InIter1), tag::in2(InIter2), tag::out(OutIter)> otherwise. The transform algorithm returns a tuple holding an iterator referring to the first element after the first input sequence, an iterator referring to the first element after the second input sequence, and the output iterator referring to the element in the destination range, one past the last element copied.
-
template<typename
ExPolicy, typenameRng1, typenameRng2, typenameOutIter, typenameF, typenameProj1= util::projection_identity, typenameProj2= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_tuple<tag::in1(typename hpx::traits::range_iterator<Rng1>::type), tag::in2(typename hpx::traits::range_iterator<Rng2>::type), tag::out(OutIter)>>::typetransform(ExPolicy &&policy, Rng1 &&rng1, Rng2 &&rng2, OutIter dest, F &&f, Proj1 &&proj1 = Proj1(), Proj2 &&proj2 = Proj2())¶ Applies the given function f to pairs of elements from two ranges: one defined by [first1, last1) and the other beginning at first2, and stores the result in another range, beginning at dest.
The invocations of
f in the parallel transform algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Exactly min(last2-first2, last1-first1) applications of f
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the invocations of f.Rng1: The type of the first source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.Rng2: The type of the second source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.OutIter: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an output iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of transform requires F to meet the requirements of CopyConstructible.Proj1: The type of an optional projection function to be used for elements of the first sequence. This defaults to util::projection_identityProj2: The type of an optional projection function to be used for elements of the second sequence. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the first sequence of elements the algorithm will be applied to.rng2: Refers to the second sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.f: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last).This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&. The types
Type1 and Type2 must be such that objects of types InIter1 and InIter2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. The type Ret must be such that an object of type OutIter can be dereferenced and assigned a value of type Ret.proj1: Specifies the function (or function object) which will be invoked for each of the elements of the first sequence as a projection operation before the actual predicate f is invoked.proj2: Specifies the function (or function object) which will be invoked for each of the elements of the second sequence as a projection operation before the actual predicate f is invoked.
The invocations of f in the parallel transform algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Note
The algorithm will invoke the binary predicate until it reaches the end of the shorter of the two given input sequences
- Return
The transform algorithm returns a hpx::future<tagged_tuple<tag::in1(InIter1), tag::in2(InIter2), tag::out(OutIter)> > if the execution policy is of type parallel_task_policy and returns tagged_tuple<tag::in1(InIter1), tag::in2(InIter2), tag::out(OutIter)> otherwise. The transform algorithm returns a tuple holding an iterator referring to the first element r the first input sequence, an iterator referring to the first element after the second input sequence, and the output iterator referring to the element in the destination range, one past the last element copied.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_algorithms/transform_reduce.hpp¶
-
namespace
hpx Functions
-
template<typename
ExPolicy, typenameRng, typenameT, typenameReduce, typenameConvert>
util::detail::algorithm_result<ExPolicy, T>::typetransform_reduce(ExPolicy &&policy, Rng &&rng, T init, Reduce &&red_op, Convert &&conv_op)¶ Returns GENERALIZED_SUM(red_op, init, conv_op(*first), …, conv_op(*(first + (last - first) - 1))).
The reduce operations in the parallel
transform_reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicates red_op and conv_op.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.F: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of copy_if requires F to meet the requirements of CopyConstructible.T: The type of the value to be used as initial (and intermediate) values (deduced).Reduce: The type of the binary function object used for the reduction operation.Convert: The type of the unary function object used to transform the elements of the input sequence before invoking the reduce function.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.init: The initial value for the generalized sum.red_op: Specifies the function (or function object) which will be invoked for each of the values returned from the invocation of conv_op. This is a binary predicate. The signature of this predicate should be equivalent to:Ret fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The types
Type1, Type2, and Ret must be such that an object of a type as returned from conv_op can be implicitly converted to any of those types.conv_op: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is a unary predicate. The signature of this predicate should be equivalent to:R fun(const Type &a);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type Iter can be dereferenced and then implicitly converted to Type. The type R must be such that an object of this type can be implicitly converted to T.
The reduce operations in the parallel transform_reduce algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
The difference between
transform_reduce and accumulate is that the behavior of transform_reduce may be non-deterministic for non-associative or non-commutative binary predicate.- Return
The transform_reduce algorithm returns a hpx::future<T> if the execution policy is of type parallel_task_policy and returns T otherwise. The transform_reduce algorithm returns the result of the generalized sum over the values returned from conv_op when applied to the elements given by the input range [first, last).
- Note
GENERALIZED_SUM(op, a1, …, aN) is defined as follows:
a1 when N is 1
op(GENERALIZED_SUM(op, b1, …, bK), GENERALIZED_SUM(op, bM, …, bN)), where:
b1, …, bN may be any permutation of a1, …, aN and
1 < K+1 = M <= N.
-
template<typename
ExPolicy, typenameRng1, typenameFwdIter2, typenameT>
util::detail::algorithm_result<ExPolicy, T>::typetransform_reduce(ExPolicy &&policy, Rng1 &&rng1, FwdIter2 first2, T init)¶ Returns the result of accumulating init with the inner products of the pairs formed by the elements of two ranges starting at first1 and first2.
The operations in the parallel
transform_reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op2.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.FwdIter2: The type of the second source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as return) values (deduced).
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the result will be calculated with.init: The initial value for the sum.
The operations in the parallel transform_reduce algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform_reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise.
-
template<typename
ExPolicy, typenameRng1, typenameFwdIter2, typenameT, typenameReduce, typenameConvert>
util::detail::algorithm_result<ExPolicy, T>::typetransform_reduce(ExPolicy &&policy, Rng1 &&rng1, FwdIter2 first2, T init, Reduce &&red_op, Convert &&conv_op)¶ Returns the result of accumulating init with the inner products of the pairs formed by the elements of two ranges starting at first1 and first2.
The operations in the parallel
transform_reduce algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: O(last - first) applications of the predicate op2.
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng1: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an input iterator.FwdIter2: The type of the second source iterators used (deduced). This iterator type must meet the requirements of an forward iterator.T: The type of the value to be used as return) values (deduced).Reduce: The type of the binary function object used for the multiplication operation.Convert: The type of the unary function object used to transform the elements of the input sequence before invoking the reduce function.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng1: Refers to the sequence of elements the algorithm will be applied to.first2: Refers to the beginning of the second sequence of elements the result will be calculated with.init: The initial value for the sum.red_op: Specifies the function (or function object) which will be invoked for the initial value and each of the return values of op2. This is a binary predicate. The signature of this predicate should be equivalent to should be equivalent to:Ret fun(const Type1 &a, const Type1 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Ret must be such that it can be implicitly converted to a type of T.conv_op: Specifies the function (or function object) which will be invoked for each of the input values of the sequence. This is a binary predicate. The signature of this predicate should be equivalent toRet fun(const Type1 &a, const Type2 &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Ret must be such that it can be implicitly converted to an object for the second argument type of op1.
The operations in the parallel transform_reduce algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The transform_reduce algorithm returns a hpx::future<T> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns T otherwise.
-
template<typename
Header hpx/parallel/container_algorithms/unique.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v1 Functions
-
template<typename
ExPolicy, typenameRng, typenamePred= detail::equal_to, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, typename hpx::traits::range_iterator<Rng>::type>::typeunique(ExPolicy &&policy, Rng &&rng, Pred &&pred = Pred(), Proj &&proj = Proj())¶ Eliminates all but the first element from every consecutive group of equivalent elements from the range rng and returns a past-the-end iterator for the new logical end of the range.
The assignments in the parallel
unique algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than N assignments, exactly N - 1 applications of the predicate pred and no more than twice as many applications of the projection proj, where N = std::distance(begin(rng), end(rng)).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of unique requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by [first, last). This is an binary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a, const Type &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel unique algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The unique algorithm returns a hpx::future<FwdIter> if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns FwdIter otherwise. The unique algorithm returns the iterator to the new end of the range.
-
template<typename
ExPolicy, typenameRng, typenameFwdIter2, typenamePred= detail::equal_to, typenameProj= util::projection_identity>
util::detail::algorithm_result<ExPolicy, hpx::util::tagged_pair<tag::in(typename hpx::traits::range_iterator<Rng>::type), tag::out(FwdIter2)>>::typeunique_copy(ExPolicy &&policy, Rng &&rng, FwdIter2 dest, Pred &&pred = Pred(), Proj &&proj = Proj())¶ Copies the elements from the range rng, to another range beginning at dest in such a way that there are no consecutive equal elements. Only the first element of each group of equal elements is copied.
The assignments in the parallel
unique_copy algorithm invoked with an execution policy object of type sequenced_policy execute in sequential order in the calling thread.- Note
Complexity: Performs not more than N assignments, exactly N - 1 applications of the predicate pred, where N = std::distance(begin(rng), end(rng)).
- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the algorithm may be parallelized and the manner in which it executes the assignments.Rng: The type of the source range used (deduced). The iterators extracted from this range type must meet the requirements of an forward iterator.FwdIter2: The type of the iterator representing the destination range (deduced). This iterator type must meet the requirements of an forward iterator.Pred: The type of the function/function object to use (deduced). Unlike its sequential form, the parallel overload of unique_copy requires Pred to meet the requirements of CopyConstructible. This defaults to std::equal_to<>Proj: The type of an optional projection function. This defaults to util::projection_identity
- Parameters
policy: The execution policy to use for the scheduling of the iterations.rng: Refers to the sequence of elements the algorithm will be applied to.dest: Refers to the beginning of the destination range.pred: Specifies the function (or function object) which will be invoked for each of the elements in the sequence specified by the range rng. This is an binary predicate which returns true for the required elements. The signature of this predicate should be equivalent to:bool pred(const Type &a, const Type &b);
The signature does not need to have const&, but the function must not modify the objects passed to it. The type
Type must be such that an object of type FwdIter1 can be dereferenced and then implicitly converted to Type.proj: Specifies the function (or function object) which will be invoked for each of the elements as a projection operation before the actual predicate is invoked.
The assignments in the parallel unique_copy algorithm invoked with an execution policy object of type parallel_policy or parallel_task_policy are permitted to execute in an unordered fashion in unspecified threads, and indeterminately sequenced within each thread.
- Return
The unique_copy algorithm returns a hpx::future<tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> > if the execution policy is of type sequenced_task_policy or parallel_task_policy and returns tagged_pair<tag::in(FwdIter1), tag::out(FwdIter2)> otherwise. The unique_copy algorithm returns the pair of the source iterator to last, and the destination iterator to the end of the dest range.
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/container_memory.hpp¶
Header hpx/parallel/container_numeric.hpp¶
Header hpx/parallel/datapar.hpp¶
Header hpx/parallel/datapar/iterator_helpers.hpp¶
Header hpx/parallel/datapar/loop.hpp¶
Header hpx/parallel/datapar/transform_loop.hpp¶
Header hpx/parallel/datapar/zip_iterator.hpp¶
Header hpx/parallel/memory.hpp¶
Header hpx/parallel/numeric.hpp¶
Header hpx/parallel/spmd_block.hpp¶
-
namespace
hpx -
namespace
lcos¶ -
namespace
local¶ Functions
-
template<typename
ExPolicy, typenameF, typename ...Args, typename = typename std::enable_if<hpx::parallel::execution::is_async_execution_policy<ExPolicy>::value>::type>
std::vector<hpx::future<void>>define_spmd_block(ExPolicy &&policy, std::size_t num_images, F &&f, Args&&... args)¶
-
struct
spmd_block¶ - #include <spmd_block.hpp>
The class spmd_block defines an interface for launching multiple images while giving handles to each image to interact with the remaining images. The define_spmd_block function templates create multiple images of a user-defined function (or lambda) and launches them in a possibly separate thread. A temporary spmd block object is created and diffused to each image. The constraint for the function (or lambda) given to the define_spmd_block function is to accept a spmd_block as first parameter.
Public Functions
-
spmd_block(std::size_t num_images, std::size_t image_id, barrier_type &barrier, table_type &barriers, mutex_type &mtx)¶
-
spmd_block(spmd_block&&)¶
-
spmd_block(spmd_block const&)¶
-
spmd_block &
operator=(spmd_block&&)¶
-
spmd_block &
operator=(spmd_block const&)¶
-
void
sync_all() const¶
Private Types
Private Members
-
std::reference_wrapper<barrier_type>
barrier_¶
-
std::reference_wrapper<table_type>
barriers_¶
-
std::reference_wrapper<mutex_type>
mtx_¶
-
-
template<typename
-
namespace
-
namespace
parallel -
namespace
v2 Typedefs
-
using
spmd_block= hpx::lcos::local::spmd_block¶ The class spmd_block defines an interface for launching multiple images while giving handles to each image to interact with the remaining images. The define_spmd_block function templates create multiple images of a user-defined function (or lambda) and launches them in a possibly separate thread. A temporary spmd block object is created and diffused to each image. The constraint for the function (or lambda) given to the define_spmd_block function is to accept a spmd_block as first parameter.
Functions
-
template<typename
ExPolicy, typenameF, typename ...Args, typename = typename std::enable_if<hpx::parallel::execution::is_async_execution_policy<ExPolicy>::value>::type>
std::vector<hpx::future<void>>define_spmd_block(ExPolicy &&policy, std::size_t num_images, F &&f, Args&&... args)¶
-
using
-
namespace
-
namespace
Header hpx/parallel/tagspec.hpp¶
Header hpx/parallel/task_block.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
v2 Functions
-
template<typename
ExPolicy, typenameF>
util::detail::algorithm_result<ExPolicy>::typedefine_task_block(ExPolicy &&policy, F &&f)¶ Constructs a task_block, tr, using the given execution policy policy,and invokes the expression f(tr) on the user-provided object, f.
Postcondition: All tasks spawned from
f have finished execution. A call to define_task_block may return on a different thread than that on which it was called.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the task block may be parallelized.F: The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.f: The user defined function to invoke inside the task block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.
- Note
It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).
- Exceptions
An: exception_list, as specified in Exception Handling.
-
template<typename
F>
voiddefine_task_block(F &&f)¶ Constructs a task_block, tr, and invokes the expression f(tr) on the user-provided object, f. This version uses parallel_policy for task scheduling.
Postcondition: All tasks spawned from
f have finished execution. A call to define_task_block may return on a different thread than that on which it was called.- Template Parameters
F: The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.
- Parameters
f: The user defined function to invoke inside the task block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.
- Note
It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).
- Exceptions
An: exception_list, as specified in Exception Handling.
-
template<typename
ExPolicy, typenameF>
util::detail::algorithm_result<ExPolicy>::typedefine_task_block_restore_thread(ExPolicy &&policy, F &&f)¶ Constructs a task_block, tr, and invokes the expression f(tr) on the user-provided object, f.
Postcondition: All tasks spawned from
f have finished execution. A call to define_task_block_restore_thread always returns on the same thread as that on which it was called.- Template Parameters
ExPolicy: The type of the execution policy to use (deduced). It describes the manner in which the execution of the task block may be parallelized.F: The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.
- Parameters
policy: The execution policy to use for the scheduling of the iterations.f: The user defined function to invoke inside the define_task_block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.
- Exceptions
An: exception_list, as specified in Exception Handling.
- Note
It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).
-
template<typename
F>
voiddefine_task_block_restore_thread(F &&f)¶ Constructs a task_block, tr, and invokes the expression f(tr) on the user-provided object, f. This version uses parallel_policy for task scheduling.
Postcondition: All tasks spawned from
f have finished execution. A call to define_task_block_restore_thread always returns on the same thread as that on which it was called.- Template Parameters
F: The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.
- Parameters
f: The user defined function to invoke inside the define_task_block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.
- Exceptions
An: exception_list, as specified in Exception Handling.
- Note
It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).
-
template<typename
ExPolicy= parallel::execution::parallel_policy>
classtask_block¶ - #include <task_block.hpp>
The class task_block defines an interface for forking and joining parallel tasks. The define_task_block and define_task_block_restore_thread function templates create an object of type task_block and pass a reference to that object to a user-provided callable object.
An object of class task_block cannot be constructed, destroyed, copied, or moved except by the implementation of the task region library. Taking the address of a task_block object via operator& or addressof is ill formed. The result of obtaining its address by any other means is unspecified.
is active if it was created by the nearest enclosing task block, where “task block” refers to an invocation of define_task_block or define_task_block_restore_thread and “nearest
enclosing” means the most recent invocation that has not yet completed. Code designated for execution in another thread by means other than the facilities in this section (e.g., using thread or async) are not enclosed in the task region and a
task_block passed to (or captured by) such code is not active within that code. Performing any operation on a task_block that is not active results in undefined behavior.The task_block that is active before a specific call to the run member function is not active within the asynchronous function that invoked run. (The invoked function should not, therefore, capture the task_block from the surrounding block.)
Example: define_task_block([&](auto& tr) { tr.run([&] { tr.run([] { f(); }); // Error: tr is not active define_task_block([&](auto& tr) { // Nested task block tr.run(f); // OK: inner tr is active /// ... }); }); /// ... });
- Template Parameters
ExPolicy: The execution policy an instance of a task_block was created with. This defaults to parallel_policy.
Public Types
-
typedef ExPolicy
execution_policy¶ Refers to the type of the execution policy used to create the task_block.
Public Functions
-
execution_policy const &
get_execution_policy() const¶ Return the execution policy instance used to create this task_block
-
template<typename
F, typename ...Ts>
voidrun(F &&f, Ts&&... ts)¶ Causes the expression f() to be invoked asynchronously. The invocation of f is permitted to run on an unspecified thread in an unordered fashion relative to the sequence of operations following the call to run(f) (the continuation), or indeterminately sequenced within the same thread as the continuation.
The call to run synchronizes with the invocation of f. The completion of f() synchronizes with the next invocation of wait on the same task_block or completion of the nearest enclosing task block (i.e., the define_task_block or define_task_block_restore_thread that created this task block).
Requires: F shall be MoveConstructible. The expression, (void)f(), shall be well-formed.
Precondition: this shall be the active task_block.
Postconditions: A call to run may return on a different thread than that on which it was called.
- Note
The call to run is sequenced before the continuation as if run returns on the same thread. The invocation of the user-supplied callable object f may be immediate or may be delayed until compute resources are available. run might or might not return before invocation of f completes.
- Exceptions
This: function may throw task_canceled_exception, as described in Exception Handling.
-
template<typename
Executor, typenameF, typename ...Ts>
voidrun(Executor &exec, F &&f, Ts&&... ts)¶ Causes the expression f() to be invoked asynchronously using the given executor. The invocation of f is permitted to run on an unspecified thread associated with the given executor and in an unordered fashion relative to the sequence of operations following the call to run(exec, f) (the continuation), or indeterminately sequenced within the same thread as the continuation.
The call to run synchronizes with the invocation of f. The completion of f() synchronizes with the next invocation of wait on the same task_block or completion of the nearest enclosing task block (i.e., the define_task_block or define_task_block_restore_thread that created this task block).
Requires: Executor shall be a type modeling the Executor concept. F shall be MoveConstructible. The expression, (void)f(), shall be well-formed.
Precondition: this shall be the active task_block.
Postconditions: A call to run may return on a different thread than that on which it was called.
- Note
The call to run is sequenced before the continuation as if run returns on the same thread. The invocation of the user-supplied callable object f may be immediate or may be delayed until compute resources are available. run might or might not return before invocation of f completes.
- Exceptions
This: function may throw task_canceled_exception, as described in Exception Handling.
-
void
wait()¶ Blocks until the tasks spawned using this task_block have finished.
Precondition: this shall be the active task_block.
Postcondition: All tasks spawned by the nearest enclosing task region have finished. A call to wait may return on a different thread than that on which it was called.
Example: define_task_block([&](auto& tr) { tr.run([&]{ process(a, w, x); }); // Process a[w] through a[x] if (y < x) tr.wait(); // Wait if overlap between [w, x) and [y, z) process(a, y, z); // Process a[y] through a[z] });
- Note
The call to wait is sequenced before the continuation as if wait returns on the same thread.
- Exceptions
This: function may throw task_canceled_exception, as described in Exception Handling.
-
ExPolicy &
policy()¶ Returns a reference to the execution policy used to construct this object.
Precondition: this shall be the active task_block.
-
ExPolicy const &
policy() const¶ Returns a reference to the execution policy used to construct this object.
Precondition: this shall be the active task_block.
-
class
task_canceled_exception: public exception¶ - #include <task_block.hpp>
The class task_canceled_exception defines the type of objects thrown by task_block::run or task_block::wait if they detect that an exception is pending within the current parallel region.
Public Functions
-
task_canceled_exception()¶
-
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/cancellation_token.hpp¶
-
namespace
hpx
Header hpx/parallel/util/compare_projected.hpp¶
-
template<typename
Compare>
structcompare_projected<Compare, util::projection_identity>¶ - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_>compare_projected(Compare_ &&comp, util::projection_identity)¶
Public Members
-
Compare
comp_¶
-
template<typename
-
template<typename
Compare, typenameProj2>
structcompare_projected<Compare, util::projection_identity, Proj2>¶ - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_, typenameProj2_>compare_projected(Compare_ &&comp, util::projection_identity, Proj2_ &&proj2)¶
-
template<typename
-
template<typename
Compare, typenameProj1>
structcompare_projected<Compare, Proj1, util::projection_identity>¶ - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_, typenameProj1_>compare_projected(Compare_ &&comp, Proj1_ &&proj1, util::projection_identity)¶
-
template<typename
-
template<typename
Compare>
structcompare_projected<Compare, util::projection_identity, util::projection_identity>¶ - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_>compare_projected(Compare_ &&comp, util::projection_identity, util::projection_identity)¶
Public Members
-
Compare
comp_
-
template<typename
-
namespace
hpx -
namespace
parallel -
namespace
util -
template<typename
Compare, typenameProj>
structcompare_projected<Compare, Proj>¶ - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare, typenameProj1, typenameProj2>
structcompare_projected<Compare, Proj1, Proj2>¶ - #include <compare_projected.hpp>
Public Functions
Public Members
-
Compare
comp_
-
Proj1
proj1_
-
Proj2
proj2_
-
Compare
-
template<typename
Compare, typenameProj1>
structcompare_projected<Compare, Proj1, util::projection_identity> - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_, typenameProj1_>compare_projected(Compare_ &&comp, Proj1_ &&proj1, util::projection_identity)
Public Members
-
Compare
comp_
-
Proj1
proj1_
-
template<typename
-
template<typename
Compare>
structcompare_projected<Compare, util::projection_identity> - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_>compare_projected(Compare_ &&comp, util::projection_identity)
Public Members
-
Compare
comp_
-
template<typename
-
template<typename
Compare, typenameProj2>
structcompare_projected<Compare, util::projection_identity, Proj2> - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_, typenameProj2_>compare_projected(Compare_ &&comp, util::projection_identity, Proj2_ &&proj2)
Public Members
-
Compare
comp_
-
Proj2
proj2_
-
template<typename
-
template<typename
Compare>
structcompare_projected<Compare, util::projection_identity, util::projection_identity> - #include <compare_projected.hpp>
Public Functions
-
template<typename
Compare_>compare_projected(Compare_ &&comp, util::projection_identity, util::projection_identity)
Public Members
-
Compare
comp_
-
template<typename
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/foreach_partitioner.hpp¶
Header hpx/parallel/util/invoke_projected.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util -
template<typename
Pred, typenameProj>
structinvoke_projected¶ - #include <invoke_projected.hpp>
Public Types
Public Functions
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/loop.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util Functions
-
template<typename
ExPolicy, typenameVecOnly, typenameF, typename ...Iters>
std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, typename hpx::util::invoke_result<F, Iters...>::type>::typeloop_step(VecOnly, F &&f, Iters&... its)¶
-
template<typename
ExPolicy, typenameIter>
constexpr std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, bool>::typeloop_optimization(Iter, Iter)¶
-
template<typename
ExPolicy, typenameBegin, typenameEnd, typenameF>
constexpr Beginloop(ExPolicy&&, Begin begin, End end, F &&f)¶
-
template<typename
ExPolicy, typenameBegin, typenameEnd, typenameCancelToken, typenameF>
constexpr Beginloop(ExPolicy&&, Begin begin, End end, CancelToken &tok, F &&f)¶
-
template<typename
ExPolicy, typenameVecOnly, typenameBegin1, typenameEnd1, typenameBegin2, typenameF>
constexpr std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, std::pair<Begin1, Begin2>>::typeloop2(VecOnly, Begin1 begin1, End1 end1, Begin2 begin2, F &&f)¶
-
template<typename
ExPolicy, typenameIter, typenameF>
constexpr std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, Iter>::typeloop_n(Iter it, std::size_t count, F &&f)¶
-
template<typename
ExPolicy, typenameIter, typenameCancelToken, typenameF>
constexpr std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, Iter>::typeloop_n(Iter it, std::size_t count, CancelToken &tok, F &&f)¶
-
template<typename
Iter, typenameF, typenameCleanup>
constexpr Iterloop_with_cleanup(Iter it, Iter last, F &&f, Cleanup &&cleanup)¶
-
template<typename
Iter, typenameFwdIter, typenameF, typenameCleanup>
constexpr FwdIterloop_with_cleanup(Iter it, Iter last, FwdIter dest, F &&f, Cleanup &&cleanup)¶
-
template<typename
Iter, typenameF, typenameCleanup>
constexpr Iterloop_with_cleanup_n(Iter it, std::size_t count, F &&f, Cleanup &&cleanup)¶
-
template<typename
Iter, typenameFwdIter, typenameF, typenameCleanup>
constexpr FwdIterloop_with_cleanup_n(Iter it, std::size_t count, FwdIter dest, F &&f, Cleanup &&cleanup)¶
-
template<typename
Iter, typenameCancelToken, typenameF, typenameCleanup>
constexpr Iterloop_with_cleanup_n_with_token(Iter it, std::size_t count, CancelToken &tok, F &&f, Cleanup &&cleanup)¶
-
template<typename
Iter, typenameFwdIter, typenameCancelToken, typenameF, typenameCleanup>
constexpr FwdIterloop_with_cleanup_n_with_token(Iter it, std::size_t count, FwdIter dest, CancelToken &tok, F &&f, Cleanup &&cleanup)¶
-
template<typename
Iter, typenameF>
constexpr Iterloop_idx_n(std::size_t base_idx, Iter it, std::size_t count, F &&f)¶
-
template<typename
Iter, typenameCancelToken, typenameF>
constexpr Iterloop_idx_n(std::size_t base_idx, Iter it, std::size_t count, CancelToken &tok, F &&f)¶
-
template<typename
Iter, typenameT, typenamePred>
Taccumulate_n(Iter it, std::size_t count, T init, Pred &&f)¶
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/low_level.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util Functions
-
template<typename
Value, typename ...Args>
voidconstruct_object(Value *ptr, Args&&... args)¶ create an object in the memory specified by ptr
- Template Parameters
Value: : typename of the object to createArgs: : parameters for the constructor
- Parameters
[in] ptr: : pointer to the memory where to create the object[in] args: : arguments to the constructor
-
template<typename
Value>
voiddestroy_object(Value *ptr)¶ destroy an object in the memory specified by ptr
- Template Parameters
Value: : typename of the object to create
- Parameters
[in] ptr: : pointer to the object to destroy
-
template<typename
Iter, typenameSent>
voidinit(Iter first, Sent last, typename std::iterator_traits<Iter>::value_type &val)¶ Initialize a range of objects with the object val moving across them
- Return
range initialized
- Parameters
[in] r: : range of elements not initialized[in] val: : object used for the initialization
-
template<typename
Value, typename ...Args>
voidconstruct(Value *ptr, Args&&... args)¶ create an object in the memory specified by ptr
- Template Parameters
Value: : typename of the object to createArgs: : parameters for the constructor
- Parameters
[in] ptr: : pointer to the memory where to create the object[in] args: : arguments to the constructor
-
template<typename
Iter1, typenameSent1, typenameIter2>
Iter2init_move(Iter2 it_dest, Iter1 first, Sent1 last)¶ Move objets.
- Template Parameters
Iter: : iterator to the elementsValue: : typename of the object to create
- Parameters
[in] itdest: : iterator to the final place of the objects[in] R: : range to move
-
template<typename
Iter, typenameSent, typenameValue= typename std::iterator_traits<Iter>::value_type>
Value *uninit_move(Value *ptr, Iter first, Sent last)¶ Move objets to uninitialized memory.
- Template Parameters
Iter: : iterator to the elementsValue: : typename of the object to construct
- Parameters
[in] ptr: : pointer to the memory where to create the object[in] R: : range to move
-
template<typename
Iter, typenameSent>
voiddestroy(Iter first, Sent last)¶ Move objects to uninitialized memory.
- Template Parameters
Iter: : iterator to the elementsValue: : typename of the object to construct
- Parameters
[in] ptr: : pointer to the memory where to construct the object[in] R: : range to move
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameCompare>
Iter2full_merge(Iter1 buf1, Sent1 end_buf1, Iter1 buf2, Sent1 end_buf2, Iter2 buf_out, Compare comp)¶ Merge two contiguous buffers pointed by buf1 and buf2 , and put in the buffer pointed by buf_out.
- Parameters
[in] buf1: : iterator to the first element in the first buffer[in] end_buf1: : final iterator of first buffer[in] buf2: : iterator to the first iterator to the second buffer[in] end_buf2: : final iterator of the second buffer[in] buf_out: : buffer where move the elements merged[in] comp: : comparison object
-
template<typename
Iter, typenameSent, typenameValue, typenameCompare>
Value *uninit_full_merge(Iter first1, Sent last1, Iter first2, Sent last2, Value *it_out, Compare comp)¶ Merge two contiguous buffers pointed by first1 and first2 , and put in the uninitialized buffer pointed by it_out.
- Parameters
[in] first1: : iterator to the first element in the first buffer[in] last: : last iterator of the first buffer[in] first2: : iterator to the first element to the second buffer[in] last22: : final iterator of the second buffer[in] it_out: : uninitialized buffer where move the elements merged[in] comp: : comparison object
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
Iter2half_merge(Iter1 buf1, Sent1 end_buf1, Iter2 buf2, Sent2 end_buf2, Iter2 buf_out, Compare comp)¶ : Merge two buffers. The first buffer is in a separate memory. The second buffer have a empty space before buf2 of the same size than the (end_buf1 - buf1)
- Remark
The elements pointed by Iter1 and Iter2 must be the same
- Parameters
[in] buf1: : iterator to the first element of the first buffer[in] end_buf1: : iterator to the last element of the first buffer[in] buf2: : iterator to the first element of the second buffer[in] end_buf2: : iterator to the last element of the second buffer[in] buf_out: : iterator to the first element to the buffer where put the result[in] comp: : object for Compare two elements of the type pointed by the Iter1 and Iter2
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameIter3, typenameCompare>
boolin_place_merge_uncontiguous(Iter1 src1, Sent1 end_src1, Iter2 src2, Sent2 end_src2, Iter3 aux, Compare comp)¶ Merge two non contiguous buffers, placing the results in the buffers for to do this use an auxiliary buffer pointed by aux
- Parameters
[in] src1: : iterator to the first element of the first buffer[in] end_src1: : last iterator of the first buffer[in] src2: : iterator to the first element of the second buffer[in] end_src2: : last iterator of the second buffer[in] aux: : iterator to the first element of the auxiliary buffer[in] comp: : object for to Compare elements
- Exceptions
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameCompare>
boolin_place_merge(Iter1 src1, Iter1 src2, Sent1 end_src2, Iter2 buf, Compare comp)¶ : merge two contiguous buffers,using an auxiliary buffer pointed by buf
- Parameters
[in] src1: iterator to the first position of the first buffer[in] src2: final iterator of the first buffer and first iterator of the second buffer[in] end_src2: : final iterator of the second buffer[in] buf: : iterator to buffer used as auxiliary memory[in] comp: : object for to Compare elements
- Exceptions
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/merge_four.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util Functions
-
template<typename
Iter, typenameSent, typenameCompare>
boolless_range(Iter it1, std::uint32_t pos1, Sent it2, std::uint32_t pos2, Compare comp)¶ Compare the elements pointed by it1 and it2, and if they are equals, compare their position, doing a stable comparison.
- Return
result of the comparison
- Parameters
[in] it1: : iterator to the first element[in] pos1: : position of the object pointed by it1[in] it2: : iterator to the second element[in] pos2: : position of the element pointed by it2[in] comp: : comparison object
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
util::range<Iter1, Sent1>full_merge4(util::range<Iter1, Sent1> &rdest, util::range<Iter2, Sent2> vrange_input[4], std::uint32_t nrange_input, Compare comp)¶ Merge four ranges.
- Return
range with all the elements move with the size adjusted
- Parameters
[in] dest: range where move the elements merged. Their size must be greater or equal than the sum of the sizes of the ranges in the array R[in] R: : array of ranges to merge[in] nrange_input: : number of ranges in R[in] comp: : comparison object
-
template<typename
Value, typenameIter, typenameSent, typenameCompare>
util::range<Value*>uninit_full_merge4(util::range<Value*> const &dest, util::range<Iter, Sent> vrange_input[4], std::uint32_t nrange_input, Compare comp)¶ Merge four ranges and put the result in uninitialized memory.
- Return
range with all the elements move with the size adjusted
- Parameters
[in] dest: range where create and move the elements merged. Their size must be greater or equal than the sum of the sizes of the ranges in the array R[in] R: : array of ranges to merge[in] nrange_input: : number of ranges in vrange_input[in] comp: : comparison object
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/merge_vector.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util Functions
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
voidmerge_level4(util::range<Iter1, Sent1> dest, std::vector<util::range<Iter2, Sent2>> &v_input, std::vector<util::range<Iter1, Sent1>> &v_output, Compare comp)¶ Merge the ranges in the vector v_input using full_merge4. The v_output vector is used as auxiliary memory in the internal process The final results is in the dest range. All the ranges of v_output are inside the range dest
- Return
range with all the elements moved
- Parameters
[in] dest: : range where move the elements merged[in] v_input: : vector of ranges to merge[in] v_output: : vector of ranges obtained[in] comp: : comparison object
-
template<typename
Value, typenameIter, typenameSent, typenameCompare>
voiduninit_merge_level4(util::range<Value*> dest, std::vector<util::range<Iter, Sent>> &v_input, std::vector<util::range<Value*>> &v_output, Compare comp)¶ Merge the ranges over uninitialized memory,in the vector v_input using full_merge4. The v_output vector is used as auxiliary memory in the internal process. The final results is in the dest range. All the ranges of v_output are inside the range dest
- Return
range with all the elements moved
- Parameters
[in] dest: : range where move the elements merged[in] v_input: : vector of ranges to merge[in] v_output: : vector of ranges obtained[in] comp: : comparison object
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
util::range<Iter2, Sent2>merge_vector4(util::range<Iter1, Sent1> range_input, util::range<Iter2, Sent2> range_output, std::vector<util::range<Iter1, Sent1>> &v_input, std::vector<util::range<Iter2, Sent2>> &v_output, Compare comp)¶ Merge the ranges in the vector v_input using merge_level4. The v_output vector is used as auxiliary memory in the internal process The final results is in the range_output range. All the ranges of v_output are inside the range range_output All the ranges of v_input are inside the range range_input
- Parameters
[in] range_input: : range including all the ranges of v_input
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/nbits.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util Functions
Variables
-
HPX_INLINE_CONSTEXPR_VARIABLE std::uint32_t const hpx::parallel::util::tmsb[256]= {0, 1, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 4, 4, 4, 4, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8}
-
-
namespace
-
namespace
Header hpx/parallel/util/partitioner.hpp¶
Header hpx/parallel/util/partitioner_with_cleanup.hpp¶
Header hpx/parallel/util/prefetching.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util
-
namespace
-
namespace
Header hpx/parallel/util/projection_identity.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util -
struct
projection_identity¶ - #include <projection_identity.hpp>
-
struct
-
namespace
-
namespace
Header hpx/parallel/util/range.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util -
Functions
-
template<typename
Iter, typenameSent>
range<Iter, Sent>concat(range<Iter, Sent> const &it1, range<Iter, Sent> const &it2)¶ concatenate two contiguous ranges
- Return
range resulting of the concatenation
- Parameters
[in] it1: : first range[in] it2: : second range
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2>
range<Iter2, Iter2>init_move(range<Iter2, Sent2> const &dest, range<Iter1, Sent1> const &src)¶ Move objects from the range src to dest.
- Return
range with the objects moved and the size adjusted
- Parameters
[in] dest: : range where move the objects[in] src: : range from where move the objects
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2>
range<Iter2, Sent2>uninit_move(range<Iter2, Sent2> const &dest, range<Iter1, Sent1> const &src)¶ Move objects from the range src creating them in dest.
- Return
range with the objects moved and the size adjusted
- Parameters
[in] dest: : range where move and create the objects[in] src: : range from where move the objects
-
template<typename
Iter, typenameSent>
voiddestroy_range(range<Iter, Sent> r)¶ destroy a range of objects
- Parameters
[in] r: : range to destroy
-
template<typename
Iter, typenameSent>
range<Iter, Sent>init(range<Iter, Sent> const &r, typename std::iterator_traits<Iter>::value_type &val)¶ initialize a range of objects with the object val moving across them
- Return
range initialized
- Parameters
[in] r: : range of elements not initialized[in] val: : object used for the initialization
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
boolis_mergeable(range<Iter1, Sent1> const &src1, range<Iter2, Sent2> const &src2, Compare comp)¶ : indicate if two ranges have a possible merge
- Parameters
[in] src1: : first range[in] src2: : second range[in] comp: : object for to compare elements
- Exceptions
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameIter3, typenameSent3, typenameCompare>
range<Iter3, Sent3>full_merge(range<Iter3, Sent3> const &dest, range<Iter1, Sent1> const &src1, range<Iter2, Sent2> const &src2, Compare comp)¶ Merge two contiguous ranges src1 and src2 , and put the result in the range dest, returning the range merged.
- Return
range with the elements merged and the size adjusted
- Parameters
[in] dest: : range where locate the lements merged. the size of dest must be greater or equal than the sum of the sizes of src1 and src2[in] src1: : first range to merge[in] src2: : second range to merge[in] comp: : comparison object
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameValue, typenameCompare>
range<Value*>uninit_full_merge(const range<Value*> &dest, range<Iter1, Sent1> const &src1, range<Iter2, Sent2> const &src2, Compare comp)¶ Merge two contiguous ranges src1 and src2 , and create and move the result in the uninitialized range dest, returning the range merged.
- Return
range with the elements merged and the size adjusted
- Parameters
[in] dest: : range where locate the elements merged. the size of dest must be greater or equal than the sum of the sizes of src1 and src2. Initially is uninitialize memory[in] src1: : first range to merge[in] src2: : second range to merge[in] comp: : comparison object
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
range<Iter2, Sent2>half_merge(range<Iter2, Sent2> const &dest, range<Iter1, Sent1> const &src1, range<Iter2, Sent2> const &src2, Compare comp)¶ : Merge two buffers. The first buffer is in a separate memory
- Return
: range with the two buffers merged
- Parameters
[in] dest: : range where finish the two buffers merged[in] src1: : first range to merge in a separate memory[in] src2: : second range to merge, in the final part of the range where deposit the final results[in] comp: : object for compare two elements of the type pointed by the Iter1 and Iter2
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameIter3, typenameSent3, typenameCompare>
boolin_place_merge_uncontiguous(range<Iter1, Sent1> const &src1, range<Iter2, Sent2> const &src2, range<Iter3, Sent3> &aux, Compare comp)¶ : merge two non contiguous buffers src1 , src2, using the range aux as auxiliary memory
- Parameters
[in] src1: : first range to merge[in] src2: : second range to merge[in] aux: : auxiliary range used in the merge[in] comp: : object for to compare elements
- Exceptions
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
range<Iter1, Sent1>in_place_merge(range<Iter1, Sent1> const &src1, range<Iter1, Sent1> const &src2, range<Iter2, Sent2> &buf, Compare comp)¶ : merge two contiguous buffers ( src1, src2) using buf as auxiliary memory
- Parameters
[in] src1: : first range to merge[in] src1: : second range to merge[in] buf: : auxiliary memory used in the merge[in] comp: : object for to compare elements
- Exceptions
-
template<typename
Iter1, typenameSent1, typenameIter2, typenameSent2, typenameCompare>
voidmerge_flow(range<Iter1, Sent1> rng1, range<Iter2, Sent2> rbuf, range<Iter1, Sent1> rng2, Compare cmp)¶ : merge two contiguous buffers
- Template Parameters
Iter: : iterator to the elementscompare: : object for to compare two elements pointed by Iter iterators
- Parameters
[in] first: : iterator to the first element[in] last: : iterator to the element after the last in the range[in] comp: : object for to compare elements
- Exceptions
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/result_types.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util -
template<typename
I, typenameF>
structin_fun_result¶ - #include <result_types.hpp>
Public Functions
-
template<typename
I2, typenameF2, typenameEnable= typename std::enable_if<std::is_convertible<I const&, I2&>::value && std::is_convertible<F const&, F2&>::value>::type>
constexproperator in_fun_result<I2, F2>() const &¶
Public Members
-
HPX_NO_UNIQUE_ADDRESS I hpx::parallel::util::in_fun_result::in
-
HPX_NO_UNIQUE_ADDRESS F hpx::parallel::util::in_fun_result::fun
-
template<typename
-
template<typename
I1, typenameI2>
structin_in_result¶ - #include <result_types.hpp>
Public Functions
-
template<typename
II1, typenameII2, typenameEnable= typename std::enable_if<std::is_convertible<I1 const&, II1&>::value && std::is_convertible<I2 const&, II2&>::value>::type>
constexproperator in_in_result<II1, II2>() const &¶
Public Members
-
HPX_NO_UNIQUE_ADDRESS I1 hpx::parallel::util::in_in_result::in1
-
HPX_NO_UNIQUE_ADDRESS I2 hpx::parallel::util::in_in_result::in2
-
template<typename
-
template<typename
I, typenameO>
structin_out_result¶ - #include <result_types.hpp>
Public Functions
-
template<typename
I2, typenameO2, typenameEnable= typename std::enable_if<std::is_convertible<I const&, I2&>::value && std::is_convertible<O const&, O2&>::value>::type>
constexproperator in_out_result<I2, O2>() const &¶
Public Members
-
HPX_NO_UNIQUE_ADDRESS I hpx::parallel::util::in_out_result::in
-
HPX_NO_UNIQUE_ADDRESS O hpx::parallel::util::in_out_result::out
-
template<typename
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/scan_partitioner.hpp¶
Header hpx/parallel/util/tagged_pair.hpp¶
-
namespace
hpx -
namespace
util¶
-
namespace
Header hpx/parallel/util/tagged_tuple.hpp¶
-
namespace
hpx -
namespace
util
-
namespace
Header hpx/parallel/util/transfer.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util Functions
-
template<typename
InIter, typenameSent, typenameOutIter>
in_out_result<InIter, OutIter>copy(InIter first, Sent last, OutIter dest)¶
-
template<typename
InIter, typenameOutIter>
in_out_result<InIter, OutIter>copy_n(InIter first, std::size_t count, OutIter dest)¶
-
template<typename
InIter, typenameOutIter>
voidcopy_synchronize(InIter const &first, OutIter const &dest)¶
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/transform_loop.hpp¶
-
namespace
hpx -
namespace
parallel -
namespace
util Functions
-
template<typename
ExPolicy, typenameIter, typenameOutIter, typenameF>
std::pair<Iter, OutIter>transform_loop(ExPolicy&&, Iter it, Iter end, OutIter dest, F &&f)¶
-
template<typename
ExPolicy, typenameInIter1, typenameInIter2, typenameOutIter, typenameF>
std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, hpx::util::tuple<InIter1, InIter2, OutIter>>::typetransform_binary_loop(InIter1 first1, InIter1 last1, InIter2 first2, OutIter dest, F &&f)¶
-
template<typename
ExPolicy, typenameInIter1, typenameInIter2, typenameOutIter, typenameF>
std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, hpx::util::tuple<InIter1, InIter2, OutIter>>::typetransform_binary_loop(InIter1 first1, InIter1 last1, InIter2 first2, InIter2 last2, OutIter dest, F &&f)¶
-
template<typename
ExPolicy, typenameIter, typenameOutIter, typenameF>
std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, std::pair<Iter, OutIter>>::typetransform_loop_n(Iter it, std::size_t count, OutIter dest, F &&f)¶
-
template<typename
ExPolicy, typenameInIter1, typenameInIter2, typenameOutIter, typenameF>
std::enable_if<!execution::is_vectorpack_execution_policy<ExPolicy>::value, hpx::util::tuple<InIter1, InIter2, OutIter>>::typetransform_binary_loop_n(InIter1 first1, std::size_t count, InIter2 first2, OutIter dest, F &&f)¶
-
template<typename
-
namespace
-
namespace
Header hpx/parallel/util/zip_iterator.hpp¶
allocator_support¶
The contents of this module can be included with the header
hpx/modules/allocator_support.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/allocator_support.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/allocator_support/allocator_deleter.hpp¶
asio¶
The contents of this module can be included with the header
hpx/modules/asio.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/asio.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/asio/asio_util.hpp¶
-
namespace
hpx -
namespace
util
-
namespace
Header hpx/asio/map_hostnames.hpp¶
-
namespace
hpx -
namespace
util -
struct
map_hostnames¶ - #include <map_hostnames.hpp>
Public Types
-
typedef util::function_nonser<std::string(std::string const&)>
transform_function_type¶
Public Functions
-
map_hostnames(bool debug = false)¶
-
void
use_transform(transform_function_type const &f)¶
-
typedef util::function_nonser<std::string(std::string const&)>
-
struct
-
namespace
assertion¶
The contents of this module can be included with the header
hpx/modules/assertion.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/assertion.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/assert.hpp¶
Header hpx/assertion/evaluate_assert.hpp¶
Header hpx/assertion/source_location.hpp¶
Header hpx/modules/assertion.hpp¶
Defines
-
HPX_ASSERT(expr)¶ This macro asserts that expr evaluates to true.
If
exprevaluates to false, The source location andmsgis being printed along with the expression and additional. Afterwards the program is being aborted. The assertion handler can be customized by calling hpx::assertion::set_assertion_handler().- Parameters
expr: The expression to assert on. This can either be an expression that’s convertible to bool or a callable which returns boolmsg: The optional message that is used to give further information if the assert fails. This should be convertible to a std::string
Asserts are enabled if HPX_DEBUG is set. This is the default for
CMAKE_BUILD_TYPE=Debug
-
HPX_ASSERT_MSG(expr, msg)¶ - See
-
namespace
hpx -
namespace
assertion Typedefs
-
using
assertion_handler= void (*)(source_location const &loc, const char *expr, std::string const &msg)¶ The signature for an assertion handler.
Functions
-
void
set_assertion_handler(assertion_handler handler)¶ Set the assertion handler to be used within a program. If the handler has been set already once, the call to this function will be ignored.
- Note
This function is not thread safe
-
using
-
namespace
async_base¶
The contents of this module can be included with the header
hpx/modules/async_base.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/async_base.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/async_base/apply.hpp¶
-
namespace
hpx
Header hpx/async_base/async.hpp¶
-
namespace
hpx
Header hpx/async_base/dataflow.hpp¶
-
namespace
hpx
Header hpx/async_base/launch_policy.hpp¶
-
namespace
hpx -
struct
launch: public detail::policy_holder<>¶ - #include <launch_policy.hpp>
Launch policies for hpx::async etc.
Public Functions
-
constexpr
launch()¶ Default constructor. This creates a launch policy representing all possible launch modes
Public Static Attributes
-
const detail::fork_policy
fork¶ Predefined launch policy representing asynchronous execution.The new thread is executed in a preferred way
-
const detail::sync_policy
sync¶ Predefined launch policy representing synchronous execution.
-
const detail::deferred_policy
deferred¶ Predefined launch policy representing deferred execution.
-
const detail::apply_policy
apply¶ Predefined launch policy representing fire and forget execution.
-
const detail::select_policy_generator
select¶ Predefined launch policy representing delayed policy selection.
-
constexpr
-
struct
Header hpx/async_base/sync.hpp¶
-
namespace
hpx
Header hpx/async_base/traits/is_launch_policy.hpp¶
async_combinators¶
The contents of this module can be included with the header
hpx/modules/async_combinators.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/async_combinators.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/async_combinators/split_future.hpp¶
-
namespace
hpx Functions
-
template<typename ...
Ts>
tuple<future<Ts>...>split_future(future<tuple<Ts...>> &&f)¶ The function split_future is an operator allowing to split a given future of a sequence of values (any tuple, std::pair, or std::array) into an equivalent container of futures where each future represents one of the values from the original future. In some sense this function provides the inverse operation of when_all.
- Return
Returns an equivalent container (same container type as passed as the argument) of futures, where each future refers to the corresponding value in the input parameter. All of the returned futures become ready once the input future has become ready. If the input future is exceptional, all output futures will be exceptional as well.
- Note
The following cases are special:
here the returned futures are directly representing the futures which were passed to the function.tuple<future<void> > split_future(future<tuple<> > && f); array<future<void>, 1> split_future(future<array<T, 0> > && f);
- Parameters
f: [in] A future holding an arbitrary sequence of values stored in a tuple-like container. This facility supports hpx::util::tuple<>, std::pair<T1, T2>, and std::array<T, N>
-
template<typename
T>
std::vector<future<T>>split_future(future<std::vector<T>> &&f, std::size_t size)¶ The function split_future is an operator allowing to split a given future of a sequence of values (any std::vector) into a std::vector of futures where each future represents one of the values from the original std::vector. In some sense this function provides the inverse operation of when_all.
- Return
Returns a std::vector of futures, where each future refers to the corresponding value in the input parameter. All of the returned futures become ready once the input future has become ready. If the input future is exceptional, all output futures will be exceptional as well.
- Parameters
f: [in] A future holding an arbitrary sequence of values stored in a std::vector.size: [in] The number of elements the vector will hold once the input future has become ready
-
template<typename ...
Header hpx/async_combinators/wait_all.hpp¶
-
namespace
hpx Functions
-
template<typename
InputIter>
voidwait_all(InputIter first, InputIter last)¶ The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.
- Note
The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns.
- Parameters
first: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_all should wait.last: The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_all should wait.
-
template<typename
R>
voidwait_all(std::vector<future<R>> &&futures)¶ The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.
- Note
The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns.
- Parameters
futures: A vector or array holding an arbitrary amount of future or shared_future objects for which wait_all should wait.
-
template<typename
R, std::size_tN>
voidwait_all(std::array<future<R>, N> &&futures)¶ The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.
- Note
The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns.
- Parameters
futures: A vector or array holding an arbitrary amount of future or shared_future objects for which wait_all should wait.
-
template<typename ...
T>
voidwait_all(T&&... futures)¶ The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.
- Note
The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns.
- Parameters
futures: An arbitrary number of future or shared_future objects, possibly holding different types for which wait_all should wait.
-
template<typename
InputIter>
InputIterwait_all_n(InputIter begin, std::size_t count)¶ The function wait_all_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.
- Return
The function wait_all_n will return an iterator referring to the first element in the input sequence after the last processed element.
- Note
The function wait_all_n returns after all futures have become ready. All input futures are still valid after wait_all_n returns.
- Parameters
begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_all_n should wait.count: The number of elements in the sequence starting at first.
-
template<typename
Header hpx/async_combinators/wait_any.hpp¶
-
namespace
hpx Functions
-
template<typename
InputIter>
voidwait_any(InputIter first, InputIter last, error_code &ec = throws)¶ The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.
- Note
The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_any should wait.last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_any should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
R>
voidwait_any(std::vector<future<R>> &futures, error_code &ec = throws)¶ The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.
- Note
The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
futures: [in] A vector holding an arbitrary amount of future or shared_future objects for which wait_any should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename R, std:;size_t N>void hpx::wait_any(std::array< future< R >, N > & futures, error_code & ec = throws) The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.
- Note
The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
futures: [in] Amn array holding an arbitrary amount of future or shared_future objects for which wait_any should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename ...
T>
voidwait_any(error_code &ec, T&&... futures)¶ The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.
- Note
The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which wait_any should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename ...
T>
voidwait_any(T&&... futures)¶ The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.
- Note
The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which wait_any should wait.
-
template<typename
InputIter>
InputIterwait_any_n(InputIter first, std::size_t count, error_code &ec = throws)¶ The function wait_any_n is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.
- Note
The function wait_any_n returns after at least one future has become ready. All input futures are still valid after wait_any_n returns.
- Return
The function wait_all_n will return an iterator referring to the first element in the input sequence after the last processed element.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_any_n should wait.count: [in] The number of elements in the sequence starting at first.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
Header hpx/async_combinators/wait_each.hpp¶
-
namespace
hpx Functions
-
template<typename
F, typenameFuture>
voidwait_each(F &&f, std::vector<Future> &&futures)¶ The function wait_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready. wait_each returns after all futures have been become ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.futures: A vector holding an arbitrary amount of future or shared_future objects for which wait_each should wait.
-
template<typename
F, typenameIterator>
voidwait_each(F &&f, Iterator begin, Iterator end)¶ The function wait_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready. wait_each returns after all futures have been become ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each should wait.end: The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_each should wait.
-
template<typename
F, typename ...T>
voidwait_each(F &&f, T&&... futures)¶ The function wait_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready. wait_each returns after all futures have been become ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.futures: An arbitrary number of future or shared_future objects, possibly holding different types for which wait_each should wait.
-
template<typename
F, typenameIterator>
voidwait_each_n(F &&f, Iterator begin, std::size_t count)¶ The function wait_each is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each_n should wait.count: The number of elements in the sequence starting at first.
-
template<typename
Header hpx/async_combinators/wait_some.hpp¶
-
namespace
hpx Functions
-
template<typename
InputIter>
future<vector<future<typename std::iterator_traits<InputIter>::value_type>>>wait_some(std::size_t n, Iterator first, Iterator last, error_code &ec = throws)¶ The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The future returned by the function wait_some becomes ready when at least n argument futures have become ready.
- Return
Returns a future holding the same list of futures as has been passed to wait_some.
future<vector<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type.
- Note
Calling this version of wait_some where first == last, returns a future with an empty vector that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_all should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
R>
voidwait_some(std::size_t n, std::vector<future<R>> &&futures, error_code &ec = throws)¶ The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.
- Note
Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.futures: [in] A vector holding an arbitrary amount of future or shared_future objects for which wait_some should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
R, std::size_tN>
voidwait_some(std::size_t n, std::array<future<R>, N> &&futures, error_code &ec = throws)¶ The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.
- Note
Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.futures: [in] An array holding an arbitrary amount of future or shared_future objects for which wait_some should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename ...
T>
voidwait_some(std::size_t n, T&&... futures, error_code &ec = throws)¶ The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.
- Note
Calling this version of wait_some where first == last, returns a future with an empty vector that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which wait_some should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
InputIter>
InputIterwait_some_n(std::size_t n, Iterator first, std::size_t count, error_code &ec = throws)¶ The function wait_some_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.
- Return
This function returns an Iterator referring to the first element after the last processed input element.
- Note
Calling this version of wait_some_n where count == 0, returns a future with the same elements as the arguments that is immediately ready. Possibly none of the futures in that vector are ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some_n will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.count: [in] The number of elements in the sequence starting at first.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
Header hpx/async_combinators/when_all.hpp¶
-
namespace
hpx Functions
-
template<typename
InputIter, typenameContainer= vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<Container>when_all(InputIter first, InputIter last)¶ The function when_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.
- Return
Returns a future holding the same list of futures as has been passed to when_all.
future<Container<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.
- Note
Calling this version of when_all where first == last, returns a future with an empty container that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_all will not throw an exception, but the futures held in the output collection may.
- Parameters
first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_all should wait.
-
template<typename
Range>
future<Range>when_all(Range &&values)¶ The function when_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.
- Return
Returns a future holding the same list of futures as has been passed to when_all.
future<Container<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type.
- Note
Calling this version of when_all where the input container is empty, returns a future with an empty container that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_all will not throw an exception, but the futures held in the output collection may.
- Parameters
values: [in] A range holding an arbitrary amount of future or shared_future objects for which when_all should wait.
-
template<typename ...
T>
future<tuple<future<T>...>>when_all(T&&... futures)¶ The function when_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.
- Return
Returns a future holding the same list of futures as has been passed to when_all.
future<tuple<future<T0>, future<T1>, future<T2>…>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.
future<tuple<>> if when_all is called with zero arguments. The returned future will be initially ready.
- Note
Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_all will not throw an exception, but the futures held in the output collection may.
- Parameters
futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_all should wait.
-
template<typename
InputIter, typenameContainer= vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<Container>when_all_n(InputIter begin, std::size_t count)¶ The function when_all_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.
- Return
Returns a future holding the same list of futures as has been passed to when_all_n.
future<Container<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output vector will be the same as given by the input iterator.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
begin: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_all_n should wait.count: [in] The number of elements in the sequence starting at first.
- Exceptions
This: function will throw errors which are encountered while setting up the requested operation only. Errors encountered while executing the operations delivering the results to be stored in the futures are reported through the futures themselves.
-
template<typename
Header hpx/async_combinators/when_any.hpp¶
-
namespace
hpx Functions
-
template<typename
InputIter, typenameContainer= vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_any_result<Container>>when_any(InputIter first, InputIter last)¶ The function when_any is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.
- Return
Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future.
future<when_any_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.
- Parameters
first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_any should wait.last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_any should wait.
-
template<typename
Range>
future<when_any_result<Range>>when_any(Range &values)¶ The function when_any is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.
- Return
Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future.
future<when_any_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.
- Parameters
values: [in] A range holding an arbitrary amount of futures or shared_future objects for which when_any should wait.
-
template<typename ...
T>
future<when_any_result<tuple<future<T>...>>>when_any(T&&... futures)¶ The function when_any is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.
- Return
Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future..
future<when_any_result<tuple<future<T0>, future<T1>…>>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.
future<when_any_result<tuple<>>> if when_any is called with zero arguments. The returned future will be initially ready.
- Parameters
futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_any should wait.
-
template<typename
InputIter, typenameContainer= vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_any_result<Container>>when_any_n(InputIter first, std::size_t count)¶ The function when_any_n is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.
- Return
Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future.
future<when_any_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.
- Note
None of the futures in the input sequence are invalidated.
- Parameters
first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_any_n should wait.count: [in] The number of elements in the sequence starting at first.
-
template<typename
Sequence>
structwhen_any_result¶ - #include <when_any.hpp>
Result type for when_any, contains a sequence of futures and an index pointing to a ready future.
Public Members
-
Sequence
futures¶ The sequence of futures as passed to hpx::when_any.
-
Sequence
-
template<typename
Header hpx/async_combinators/when_each.hpp¶
-
namespace
hpx Functions
-
template<typename
F, typenameFuture>
future<void>when_each(F &&f, std::vector<Future> &&futures)¶ The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Return
Returns a future representing the event of all input futures being ready.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.futures: A vector holding an arbitrary amount of future or shared_future objects for which wait_each should wait.
-
template<typename
F, typenameIterator>
future<Iterator>when_each(F &&f, Iterator begin, Iterator end)¶ The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Return
Returns a future representing the event of all input futures being ready.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each should wait.end: The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_each should wait.
-
template<typename
F, typename ...Ts>
future<void>when_each(F &&f, Ts&&... futures)¶ The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Return
Returns a future representing the event of all input futures being ready.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.futures: An arbitrary number of future or shared_future objects, possibly holding different types for which wait_each should wait.
-
template<typename
F, typenameIterator>
future<Iterator>when_each_n(F &&f, Iterator begin, std::size_t count)¶ The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.
- Note
This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.
- Return
Returns a future holding the iterator pointing to the first element after the last one.
- Parameters
f: The function which will be called for each of the input futures once the future has become ready.begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each_n should wait.count: The number of elements in the sequence starting at first.
-
template<typename
Header hpx/async_combinators/when_some.hpp¶
-
namespace
hpx Functions
-
template<typename
InputIter, typenameContainer= vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_some_result<Container>>when_some(std::size_t n, Iterator first, Iterator last, error_code &ec = throws)¶ The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The future returned by the function when_some becomes ready when at least n argument futures have become ready.
- Return
Returns a when_some_result holding the same list of futures as has been passed to when_some and indices pointing to ready futures.
future<when_some_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.
- Note
Calling this version of when_some where first == last, returns a future with an empty container that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_all should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
Range>
future<when_some_result<Range>>when_some(std::size_t n, Range &&futures, error_code &ec = throws)¶ The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The future returned by the function when_some becomes ready when at least n argument futures have become ready.
- Return
Returns a when_some_result holding the same list of futures as has been passed to when_some and indices pointing to ready futures.
future<when_some_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.
- Note
Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.futures: [in] A container holding an arbitrary amount of future or shared_future objects for which when_some should wait.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename ...
T>
future<when_some_result<tuple<future<T>...>>>when_some(std::size_t n, error_code &ec, T&&... futures)¶ The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The future returned by the function when_some becomes ready when at least n argument futures have become ready.
- Return
Returns a when_some_result holding the same list of futures as has been passed to when_some and an index pointing to a ready future..
future<when_some_result<tuple<future<T0>, future<T1>…>>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.
future<when_some_result<tuple<>>> if when_some is called with zero arguments. The returned future will be initially ready.
- Note
Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_some should wait.
-
template<typename ...
T>
future<when_some_result<tuple<future<T>...>>>when_some(std::size_t n, T&&... futures)¶ The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The future returned by the function when_some becomes ready when at least n argument futures have become ready.
- Return
Returns a when_some_result holding the same list of futures as has been passed to when_some and an index pointing to a ready future..
future<when_some_result<tuple<future<T0>, future<T1>…>>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.
future<when_some_result<tuple<>>> if when_some is called with zero arguments. The returned future will be initially ready.
- Note
Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_some should wait.
-
template<typename
InputIter, typenameContainer= vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_some_result<Container>>when_some_n(std::size_t n, Iterator first, std::size_t count, error_code &ec = throws)¶ The function when_some_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.
- Note
The future returned by the function when_some_n becomes ready when at least n argument futures have become ready.
- Return
Returns a when_some_result holding the same list of futures as has been passed to when_some and indices pointing to ready futures.
future<when_some_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.
- Note
Calling this version of when_some_n where count == 0, returns a future with the same elements as the arguments that is immediately ready. Possibly none of the futures in that container are ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some_n will not throw an exception, but the futures held in the output collection may.
- Parameters
n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.count: [in] The number of elements in the sequence starting at first.ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
template<typename
Sequence>
structwhen_some_result¶ - #include <when_some.hpp>
Result type for when_some, contains a sequence of futures and indices pointing to ready futures.
Public Members
-
Sequence
futures¶ The sequence of futures as passed to hpx::when_some.
-
Sequence
-
template<typename
async_cuda¶
The contents of this module can be included with the header
hpx/modules/async_cuda.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/async_cuda.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/async_cuda/cublas_executor.hpp¶
-
namespace
hpx -
namespace
cuda¶ -
namespace
experimental¶ Functions
-
cublasStatus_t
check_cublas_error(cublasStatus_t err)¶
-
struct
cublas_exception: public exception¶ - #include <cublas_executor.hpp>
Public Functions
-
cublasStatus_t
get_cublas_errorcode()¶
Protected Attributes
-
cublasStatus_t
err_¶
-
cublasStatus_t
-
struct
cublas_executor: public hpx::cuda::experimental::cuda_executor¶ - #include <cublas_executor.hpp>
Public Functions
-
cublas_executor(std::size_t device, cublasPointerMode_t pointer_mode = CUBLAS_POINTER_MODE_HOST, bool event_mode = false)¶
-
~cublas_executor()¶
Protected Functions
-
template<typename
R, typename ...Params, typename ...Args>
std::enable_if<std::is_same<cublasStatus_t, R>::value, R>::typeapply(R (*cublas_function)(Params...), Args&&... args, )¶
-
template<typename
R, typename ...Params, typename ...Args>
std::enable_if<std::is_same<cudaError_t, R>::value, void>::typeapply(R (*cuda_function)(Params...), Args&&... args, )¶
-
template<typename
R, typename ...Params, typename ...Args>
hpx::future<typename std::enable_if<std::is_same<cublasStatus_t, R>::value, void>::type>async(R (*cublas_function)(Params...), Args&&... args, )¶
-
template<typename
R, typename ...Params, typename ...Args>
hpx::future<typename std::enable_if<std::is_same<cudaError_t, R>::value, void>::type>async(R (*cuda_function)(Params...), Args&&... args, )¶
-
cublasHandle_t
get_handle()¶
-
-
cublasStatus_t
-
namespace
-
namespace
Header hpx/async_cuda/cuda_event.hpp¶
-
namespace
hpx -
namespace
cuda -
namespace
experimental -
struct
cuda_event_pool¶ - #include <cuda_event.hpp>
Public Functions
-
cuda_event_pool()¶
-
~cuda_event_pool()¶
-
bool
pop(cudaEvent_t &event)¶
-
bool
push(cudaEvent_t event)¶
Public Static Functions
-
static cuda_event_pool &
get_event_pool()¶
Public Static Attributes
-
constexpr int
initial_events_in_pool= 128¶
Private Functions
-
void
add_event_to_pool()¶
-
-
struct
-
namespace
-
namespace
Header hpx/async_cuda/cuda_exception.hpp¶
-
namespace
hpx -
namespace
cuda
-
namespace
Header hpx/async_cuda/cuda_executor.hpp¶
-
namespace
hpx -
namespace
cuda -
namespace
experimental -
struct
cuda_executor: public hpx::cuda::experimental::cuda_executor_base¶ - #include <cuda_executor.hpp>
Subclassed by hpx::cuda::experimental::cublas_executor
Public Functions
-
~cuda_executor()¶
-
-
struct
cuda_executor_base¶ - #include <cuda_executor.hpp>
Subclassed by hpx::cuda::experimental::cuda_executor
-
struct
-
namespace
-
namespace
Header hpx/async_cuda/cuda_future.hpp¶
-
namespace
hpx -
namespace
cuda
-
namespace
Header hpx/async_cuda/get_targets.hpp¶
-
namespace
hpx -
namespace
cuda -
namespace
experimental
-
namespace
-
namespace
Header hpx/async_cuda/target.hpp¶
-
namespace
hpx -
namespace
cuda -
namespace
experimental -
-
struct
target¶ - #include <target.hpp>
Public Functions
-
target()¶
-
target(int device)¶
-
native_handle_type &
native_handle()¶
-
native_handle_type const &
native_handle() const¶
-
void
synchronize() const¶
Private Members
-
native_handle_type
handle_¶
Friends
-
bool
operator==(target const &lhs, target const &rhs)¶
-
struct
native_handle_type¶ - #include <target.hpp>
Public Functions
-
native_handle_type(int device = 0)¶
-
~native_handle_type()¶
-
native_handle_type(native_handle_type const &rhs)¶
-
native_handle_type(native_handle_type &&rhs)¶
-
native_handle_type &
operator=(native_handle_type const &rhs)¶
-
native_handle_type &
operator=(native_handle_type &&rhs)¶
-
cudaStream_t
get_stream() const¶
-
int
get_device() const¶
-
void
reset()¶
Private Functions
-
void
init_processing_units()¶
Friends
-
friend
hpx::cuda::experimental::target
-
-
-
struct
-
namespace
-
namespace
async_distributed¶
The contents of this module can be included with the header
hpx/modules/async_distributed.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/async_distributed.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/async.hpp¶
Header hpx/async_distributed/applier/applier.hpp¶
Header hpx/async_distributed/applier/apply.hpp¶
-
namespace
hpx Functions
-
template<typename
Action, typename ...Ts>
boolapply_p(naming::id_type const &id, threads::thread_priority priority, Ts&&... vs)¶
-
template<typename
Action, typenameClient, typenameStub, typename ...Ts>
boolapply_p(components::client_base<Client, Stub> const &c, threads::thread_priority priority, Ts&&... vs)¶
-
template<typename
Action, typenameDistPolicy, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_p(DistPolicy const &policy, threads::thread_priority priority, Ts&&... vs)¶
-
template<typename
Action, typenameClient, typenameStub, typename ...Ts>
boolapply(components::client_base<Client, Stub> const &c, Ts&&... vs)¶
-
template<typename
Action, typenameDistPolicy, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply(DistPolicy const &policy, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typename ...Ts>
std::enable_if<traits::is_continuation<Continuation>::value, bool>::typeapply_p(Continuation &&c, naming::id_type const &gid, threads::thread_priority priority, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameClient, typenameStub, typename ...Ts>
std::enable_if<traits::is_continuation<Continuation>::value, bool>::typeapply_p(Continuation &&cont, components::client_base<Client, Stub> const &c, threads::thread_priority priority, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameDistPolicy, typename ...Ts>
std::enable_if<traits::is_continuation<Continuation>::value && traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_p(Continuation &&c, DistPolicy const &policy, threads::thread_priority priority, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typename ...Ts>
std::enable_if<traits::is_continuation<Continuation>::value, bool>::typeapply(Continuation &&c, naming::id_type const &gid, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameClient, typenameStub, typename ...Ts>
std::enable_if<traits::is_continuation<Continuation>::value, bool>::typeapply(Continuation &&cont, components::client_base<Client, Stub> const &c, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameDistPolicy, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value && traits::is_continuation<Continuation>::value, bool>::typeapply(Continuation &&c, DistPolicy const &policy, Ts&&... vs)¶
-
template<typename
Action, typename ...Ts>
boolapply_c_p(naming::id_type const &contgid, naming::id_type const &gid, threads::thread_priority priority, Ts&&... vs)¶
-
template<typename
Header hpx/async_distributed/applier/apply_callback.hpp¶
-
namespace
hpx Functions
-
template<typename
Action, typenameCallback, typename ...Ts>
boolapply_p_cb(naming::id_type const &gid, threads::thread_priority priority, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameCallback, typename ...Ts>
boolapply_cb(naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameCallback, typename ...Ts>
boolapply_cb(hpx::actions::basic_action<Component, Signature, Derived>, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_p_cb(DistPolicy const &policy, threads::thread_priority priority, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_cb(DistPolicy const &policy, Callback &&cb, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_cb(hpx::actions::basic_action<Component, Signature, Derived>, DistPolicy const &policy, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameCallback, typename ...Ts>
boolapply_p_cb(Continuation &&c, naming::address &&addr, naming::id_type const &gid, threads::thread_priority priority, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameCallback, typename ...Ts>
boolapply_p_cb(Continuation &&c, naming::id_type const &gid, threads::thread_priority priority, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameCallback, typename ...Ts>
boolapply_cb(Continuation &&c, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Component, typenameContinuation, typenameSignature, typenameDerived, typenameCallback, typename ...Ts>
boolapply_cb(Continuation &&c, hpx::actions::basic_action<Component, Signature, Derived>, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_continuation<Continuation>::value && traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_p_cb(Continuation &&c, DistPolicy const &policy, threads::thread_priority priority, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameContinuation, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_continuation<Continuation>::value && traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_cb(Continuation &&c, DistPolicy const &policy, Callback &&cb, Ts&&... vs)¶
-
template<typename
Component, typenameContinuation, typenameSignature, typenameDerived, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, bool>::typeapply_cb(Continuation &&c, hpx::actions::basic_action<Component, Signature, Derived>, DistPolicy const &policy, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameCallback, typename ...Ts>
boolapply_c_p_cb(naming::id_type const &contgid, naming::id_type const &gid, threads::thread_priority priority, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameCallback, typename ...Ts>
boolapply_c_cb(naming::id_type const &contgid, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
namespace
functional¶ Functions
-
template<typename
Action, typenameCallback, typename ...Ts>
apply_c_p_cb_impl<Action, typename util::decay<Callback>::type, typename util::decay<Ts>::type...>apply_c_p_cb(naming::id_type const &contid, naming::address &&addr, naming::id_type const &id, threads::thread_priority p, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameCallback, typename ...Ts>
structapply_c_p_cb_impl¶ - #include <apply_callback.hpp>
Public Functions
-
template<typename ...
Ts_>apply_c_p_cb_impl(naming::id_type const &contid, naming::address &&addr, naming::id_type const &id, threads::thread_priority p, Callback &&cb, Ts_&&... vs)¶
-
apply_c_p_cb_impl(apply_c_p_cb_impl &&rhs)¶
-
apply_c_p_cb_impl &
operator=(apply_c_p_cb_impl &&rhs)¶
-
void
operator()()¶
Protected Functions
-
template<std::size_t...
Is>
voidapply_action(util::index_pack<Is...>)¶
-
template<typename ...
-
template<typename
-
template<typename
Header hpx/async_distributed/applier/apply_continue.hpp¶
-
namespace
hpx Functions
-
template<typename
Action, typenameCont, typename ...Ts>
boolapply_continue(Cont &&cont, naming::id_type const &gid, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameCont, typename ...Ts>
boolapply_continue(hpx::actions::basic_action<Component, Signature, Derived>, Cont &&cont, naming::id_type const &gid, Ts&&... vs)¶
-
template<typename
Header hpx/async_distributed/applier/apply_continue_callback.hpp¶
-
namespace
hpx Functions
-
template<typename
Action, typenameCont, typenameCallback, typename ...Ts>
boolapply_continue_cb(Cont &&cont, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameCont, typenameCallback, typename ...Ts>
boolapply_continue_cb(hpx::actions::basic_action<Component, Signature, Derived>, Cont &&cont, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Header hpx/async_distributed/applier/apply_continue_fwd.hpp¶
Header hpx/async_distributed/applier/apply_helper.hpp¶
-
namespace
hpx Functions
-
bool
is_pre_startup()¶
-
bool
Header hpx/async_distributed/applier/bind_naming_wrappers.hpp¶
-
namespace
hpx -
namespace
applier¶ Functions
-
bool
bind_gid_local(naming::gid_type const&, naming::address const&, error_code &ec = throws)¶
-
void
unbind_gid_local(naming::gid_type const&, error_code &ec = throws)¶
-
bool
bind_range_local(naming::gid_type const&, std::size_t, naming::address const&, std::size_t, error_code &ec = throws)¶
-
void
unbind_range_local(naming::gid_type const&, std::size_t, error_code &ec = throws)¶
-
bool
-
namespace
Header hpx/async_distributed/applier/register_apply_colocated.hpp¶
Header hpx/async_distributed/applier/trigger.hpp¶
-
namespace
hpx -
namespace
applier
-
namespace
Header hpx/async_distributed/applier_fwd.hpp¶
-
namespace
hpx -
namespace
applier
-
namespace
-
namespace
applier¶ The namespace applier contains all definitions needed for the class hpx::applier::applier and its related functionality. This namespace is part of the HPX core module.
Header hpx/async_distributed/apply.hpp¶
Header hpx/async_distributed/async.hpp¶
-
namespace
hpx
Header hpx/async_distributed/async_callback.hpp¶
-
namespace
hpx
Header hpx/async_distributed/async_callback_fwd.hpp¶
Header hpx/async_distributed/async_continue.hpp¶
-
namespace
hpx Functions
-
template<typename
Action, typenameCont, typename ...Ts>
lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Action, Cont>::type>::type>async_continue(Cont &&cont, naming::id_type const &gid, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameCont, typename ...Ts>
lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Derived, Cont>::type>::type>async_continue(hpx::actions::basic_action<Component, Signature, Derived>, Cont &&cont, naming::id_type const &gid, Ts&&... vs)¶
-
template<typename
Action, typenameCont, typenameDistPolicy, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Action, Cont>::type>::type>>::typeasync_continue(Cont &&cont, DistPolicy const &policy, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameCont, typenameDistPolicy, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Derived, Cont>::type>::type>>::typeasync_continue(hpx::actions::basic_action<Component, Signature, Derived>, Cont &&cont, DistPolicy const &policy, Ts&&... vs)¶
-
template<typename
Header hpx/async_distributed/async_continue_callback.hpp¶
-
namespace
hpx Functions
-
template<typename
Action, typenameCont, typenameCallback, typename ...Ts>
lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Action, Cont>::type>::type>async_continue_cb(Cont &&cont, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameCont, typenameCallback, typename ...Ts>
lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Derived, Cont>::type>::type>async_continue_cb(hpx::actions::basic_action<Component, Signature, Derived>, Cont &&cont, naming::id_type const &gid, Callback &&cb, Ts&&... vs)¶
-
template<typename
Action, typenameCont, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Action, Cont>::type>::type>>::typeasync_continue_cb(Cont &&cont, DistPolicy const &policy, Callback &&cb, Ts&&... vs)¶
-
template<typename
Component, typenameSignature, typenameDerived, typenameCont, typenameDistPolicy, typenameCallback, typename ...Ts>
std::enable_if<traits::is_distribution_policy<DistPolicy>::value, lcos::future<typename traits::promise_local_result<typename detail::result_of_async_continue<Derived, Cont>::type>::type>>::typeasync_continue_cb(hpx::actions::basic_action<Component, Signature, Derived>, Cont &&cont, DistPolicy const &policy, Callback &&cb, Ts&&... vs)¶
-
template<typename
Header hpx/async_distributed/async_continue_callback_fwd.hpp¶
Header hpx/async_distributed/async_continue_fwd.hpp¶
Header hpx/async_distributed/dataflow.hpp¶
-
namespace
hpx
Header hpx/async_distributed/sync.hpp¶
-
namespace
hpx
Header hpx/modules/async_distributed.hpp¶
async_local¶
The contents of this module can be included with the header
hpx/modules/async_local.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/async_local.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/async_local/apply.hpp¶
Header hpx/async_local/async.hpp¶
Header hpx/async_local/async_fwd.hpp¶
-
namespace
hpx
Header hpx/async_local/dataflow.hpp¶
Header hpx/async_local/sync.hpp¶
async_mpi¶
The contents of this module can be included with the header
hpx/modules/async_mpi.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/async_mpi.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/async_mpi/mpi_executor.hpp¶
-
namespace
hpx -
namespace
mpi¶ -
namespace
experimental¶ -
struct
executor¶ - #include <mpi_executor.hpp>
Public Types
-
using
execution_category= parallel::execution::parallel_execution_tag¶
-
using
executor_parameters_type= hpx::parallel::execution::static_chunk_size¶
Public Functions
-
constexpr
executor(MPI_Comm communicator = MPI_COMM_WORLD)¶
Private Members
-
MPI_Comm
communicator_¶
-
using
-
struct
-
namespace
-
namespace
Header hpx/async_mpi/mpi_future.hpp¶
-
namespace
hpx -
namespace
mpi -
namespace
experimental -
Functions
-
static constexpr print_on hpx::mpi::experimental::mpi_debug("MPI_FUT")
-
void
set_error_handler()¶
-
void
poll()¶
-
void
wait()¶
-
struct
enable_user_polling¶ - #include <mpi_future.hpp>
-
-
namespace
-
namespace
batch_environments¶
The contents of this module can be included with the header
hpx/modules/batch_environments.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/batch_environments.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/batch_environments/alps_environment.hpp¶
-
namespace
hpx -
namespace
util
-
namespace
Header hpx/batch_environments/batch_environment.hpp¶
-
namespace
hpx -
namespace
util -
struct
batch_environment¶ - #include <batch_environment.hpp>
Public Types
-
struct
-
namespace
Header hpx/batch_environments/pbs_environment.hpp¶
Header hpx/batch_environments/slurm_environment.hpp¶
cache¶
The contents of this module can be included with the header
hpx/modules/cache.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/cache.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/cache/entries/entry.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache¶ -
namespace
entries¶ -
template<typename
Value, typenameDerived>
classentry: private hpx::util::cache::entries::detail::less_than_comparable<detail::derived<Value, Derived>::type>¶ - #include <hpx/cache/entries/entry.hpp>
- Template Parameters
Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.Derived: The (optional) type for which this type is used as a base class.
Public Types
-
typedef Value
value_type¶
Public Functions
-
entry()¶ Any cache entry has to be default constructible.
-
entry(value_type const &val)¶ Construct a new instance of a cache entry holding the given value.
-
bool
touch()¶ The function touch is called by a cache holding this instance whenever it has been requested (touched).
- Note
It is possible to change the entry in a way influencing the sort criteria mandated by the UpdatePolicy. In this case the function should return true to indicate this to the cache, forcing to reorder the cache entries.
- Note
This function is part of the CacheEntry concept
- Return
This function should return true if the cache needs to update it’s internal heap. Usually this is needed if the entry has been changed by touch() in a way influencing the sort order as mandated by the cache’s UpdatePolicy
-
bool
insert()¶ The function insert is called by a cache whenever it is about to be inserted into the cache.
- Note
This function is part of the CacheEntry concept
- Return
This function should return true if the entry should be added to the cache, otherwise it should return false.
-
bool
remove()¶ The function remove is called by a cache holding this instance whenever it is about to be removed from the cache.
- Note
This function is part of the CacheEntry concept
- Return
The return value can be used to avoid removing this instance from the cache. If the value is true it is ok to remove the entry, other wise it will stay in the cache.
-
std::size_t
get_size() const¶ Return the ‘size’ of this entry. By default the size of each entry is just one (1), which is sensible if the cache has a limit (capacity) measured in number of entries.
-
value_type &
get()¶ Get a reference to the stored data value.
- Note
This function is part of the CacheEntry concept
-
value_type const &
get() const¶
Private Members
-
value_type
value_¶
Friends
-
bool
operator<(entry const &lhs, entry const &rhs)¶ Forwarding operator< allowing to compare entries instead of the values.
-
template<typename
-
namespace
-
namespace
-
namespace
Header hpx/cache/entries/fifo_entry.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
namespace
entries -
template<typename
Value>
classfifo_entry: public hpx::util::cache::entries::entry<Value, fifo_entry<Value>>¶ - #include <hpx/cache/entries/fifo_entry.hpp>
The fifo_entry type can be used to store arbitrary values in a cache. Using this type as the cache’s entry type makes sure that the least recently inserted entries are discarded from the cache first.
- Note
The fifo_entry conforms to the CacheEntry concept.
- Note
This type can be used to model a ‘last in first out’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).
- Template Parameters
Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.
Public Functions
-
fifo_entry()¶ Any cache entry has to be default constructible.
-
fifo_entry(Value const &val)¶ Construct a new instance of a cache entry holding the given value.
-
bool
insert()¶ The function insert is called by a cache whenever it is about to be inserted into the cache.
- Note
This function is part of the CacheEntry concept
- Return
This function should return true if the entry should be added to the cache, otherwise it should return false.
Private Types
-
typedef entry<Value, fifo_entry<Value>>
base_type¶
Friends
-
bool
operator<(fifo_entry const &lhs, fifo_entry const &rhs)¶ Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has been created earlier (FIFO).
-
template<typename
-
namespace
-
namespace
-
namespace
Header hpx/cache/entries/lfu_entry.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
namespace
entries -
template<typename
Value>
classlfu_entry: public hpx::util::cache::entries::entry<Value, lfu_entry<Value>>¶ - #include <hpx/cache/entries/lfu_entry.hpp>
The lfu_entry type can be used to store arbitrary values in a cache. Using this type as the cache’s entry type makes sure that the least frequently used entries are discarded from the cache first.
- Note
The lfu_entry conforms to the CacheEntry concept.
- Note
This type can be used to model a ‘most frequently used’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).
- Template Parameters
Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.
Public Functions
-
lfu_entry()¶ Any cache entry has to be default constructible.
-
lfu_entry(Value const &val)¶ Construct a new instance of a cache entry holding the given value.
-
bool
touch()¶ The function touch is called by a cache holding this instance whenever it has been requested (touched).
In the case of the LFU entry we store the reference count tracking the number of times this entry has been requested. This which will be used to compare the age of an entry during the invocation of the operator<().
- Return
This function should return true if the cache needs to update it’s internal heap. Usually this is needed if the entry has been changed by touch() in a way influencing the sort order as mandated by the cache’s UpdatePolicy
-
unsigned long const &
get_access_count() const¶
Private Types
-
typedef entry<Value, lfu_entry<Value>>
base_type¶
Private Members
-
unsigned long
ref_count_¶
Friends
-
bool
operator<(lfu_entry const &lhs, lfu_entry const &rhs)¶ Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has been accessed less frequently (LFU).
-
template<typename
-
namespace
-
namespace
-
namespace
Header hpx/cache/entries/lru_entry.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
namespace
entries -
template<typename
Value>
classlru_entry: public hpx::util::cache::entries::entry<Value, lru_entry<Value>>¶ - #include <hpx/cache/entries/lru_entry.hpp>
The lru_entry type can be used to store arbitrary values in a cache. Using this type as the cache’s entry type makes sure that the least recently used entries are discarded from the cache first.
- Note
The lru_entry conforms to the CacheEntry concept.
- Note
This type can be used to model a ‘most recently used’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).
- Template Parameters
Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.
Public Functions
-
lru_entry()¶ Any cache entry has to be default constructible.
-
lru_entry(Value const &val)¶ Construct a new instance of a cache entry holding the given value.
-
bool
touch()¶ The function touch is called by a cache holding this instance whenever it has been requested (touched).
In the case of the LRU entry we store the time of the last access which will be used to compare the age of an entry during the invocation of the operator<().
- Return
This function should return true if the cache needs to update it’s internal heap. Usually this is needed if the entry has been changed by touch() in a way influencing the sort order as mandated by the cache’s UpdatePolicy
Private Types
-
typedef entry<Value, lru_entry<Value>>
base_type¶
Friends
-
bool
operator<(lru_entry const &lhs, lru_entry const &rhs)¶ Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has been accessed less recently (LRU).
-
template<typename
-
namespace
-
namespace
-
namespace
Header hpx/cache/entries/size_entry.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
namespace
entries -
template<typename
Value, typenameDerived>
classsize_entry: public hpx::util::cache::entries::entry<Value, detail::size_derived<Value, Derived>::type>¶ - #include <hpx/cache/entries/size_entry.hpp>
The size_entry type can be used to store values in a cache which have a size associated (such as files, etc.). Using this type as the cache’s entry type makes sure that the entries with the biggest size are discarded from the cache first.
- Note
The size_entry conforms to the CacheEntry concept.
- Note
This type can be used to model a ‘discard smallest first’ cache policy if it is used with a std::greater as the caches’ UpdatePolicy (instead of the default std::less).
- Template Parameters
Value: The data type to be stored in a cache. It has to be default constructible, copy constructible and less_than_comparable.Derived: The (optional) type for which this type is used as a base class.
Public Functions
-
size_entry()¶ Any cache entry has to be default constructible.
Private Types
-
typedef detail::size_derived<Value, Derived>::type
derived_type¶
-
typedef entry<Value, derived_type>
base_type¶
Friends
-
bool
operator<(size_entry const &lhs, size_entry const &rhs)¶ Compare the ‘age’ of two entries. An entry is ‘older’ than another entry if it has a bigger size.
-
template<typename
-
namespace
-
namespace
-
namespace
Header hpx/cache/local_cache.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
template<typename
Key, typenameEntry, typenameUpdatePolicy= std::less<Entry>, typenameInsertPolicy= policies::always<Entry>, typenameCacheStorage= std::map<Key, Entry>, typenameStatistics= statistics::no_statistics>
classlocal_cache¶ - #include <hpx/cache/local_cache.hpp>
The local_cache implements the basic functionality needed for a local (non-distributed) cache.
- Template Parameters
Key: The type of the keys to use to identify the entries stored in the cacheEntry: The type of the items to be held in the cache, must model the CacheEntry conceptUpdatePolicy: A (optional) type specifying a (binary) function object used to sort the cache entries based on their ‘age’. The ‘oldest’ entries (according to this sorting criteria) will be discarded first if the maximum capacity of the cache is reached. The default is std::less<Entry>. The function object will be invoked using 2 entry instances of the type Entry. This type must model the UpdatePolicy model.InsertPolicy: A (optional) type specifying a (unary) function object used to allow global decisions whether a particular entry should be added to the cache or not. The default is policies::always, imposing no global insert related criteria on the cache. The function object will be invoked using the entry instance to be inserted into the cache. This type must model the InsertPolicy model.CacheStorage: A (optional) container type used to store the cache items. The container must be an associative and STL compatible container.The default is a std::map<Key, Entry>.Statistics: A (optional) type allowing to collect some basic statistics about the operation of the cache instance. The type must conform to the CacheStatistics concept. The default value is the type statistics::no_statistics which does not collect any numbers, but provides empty stubs allowing the code to compile.
Public Types
-
typedef Key
key_type¶
-
typedef Entry
entry_type¶
-
typedef UpdatePolicy
update_policy_type¶
-
typedef InsertPolicy
insert_policy_type¶
-
typedef CacheStorage
storage_type¶
-
typedef Statistics
statistics_type¶
-
typedef entry_type::value_type
value_type¶
-
typedef storage_type::size_type
size_type¶
-
typedef storage_type::value_type
storage_value_type¶
Public Functions
-
local_cache(size_type max_size = 0, update_policy_type const &up = update_policy_type(), insert_policy_type const &ip = insert_policy_type())¶ Construct an instance of a local_cache.
- Parameters
max_size: [in] The maximal size this cache is allowed to reach any time. The default is zero (no size limitation). The unit of this value is usually determined by the unit of the values returned by the entry’s get_size function.up: [in] An instance of the UpdatePolicy to use for this cache. The default is to use a default constructed instance of the type as defined by the UpdatePolicy template parameter.ip: [in] An instance of the InsertPolicy to use for this cache. The default is to use a default constructed instance of the type as defined by the InsertPolicy template parameter.
-
local_cache(local_cache &&other)¶
-
size_type
size() const¶ Return current size of the cache.
- Return
The current size of this cache instance.
-
size_type
capacity() const¶ Access the maximum size the cache is allowed to grow to.
- Note
The unit of this value is usually determined by the unit of the return values of the entry’s function entry::get_size.
- Return
The maximum size this cache instance is currently allowed to reach. If this number is zero the cache has no limitation with regard to a maximum size.
-
bool
reserve(size_type max_size)¶ Change the maximum size this cache can grow to.
- Return
This function returns true if successful. It returns false if the new max_size is smaller than the current limit and the cache could not be shrunk to the new maximum size.
- Parameters
max_size: [in] The new maximum size this cache will be allowed to grow to.
-
bool
holds_key(key_type const &k) const¶ Check whether the cache currently holds an entry identified by the given key.
- Note
This function does not call the entry’s function entry::touch. It just checks if the cache contains an entry corresponding to the given key.
- Return
This function returns true if the cache holds the referenced entry, otherwise it returns false.
- Parameters
k: [in] The key for the entry which should be looked up in the cache.
-
bool
get_entry(key_type const &k, key_type &realkey, entry_type &val)¶ Get a specific entry identified by the given key.
- Note
The function will call the entry’s entry::touch function if the value corresponding to the provided key is found in the cache.
- Return
This function returns true if the cache holds the referenced entry, otherwise it returns false.
- Parameters
k: [in] The key for the entry which should be retrieved from the cache.val: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding entry.
-
bool
get_entry(key_type const &k, entry_type &val)¶ Get a specific entry identified by the given key.
- Note
The function will call the entry’s entry::touch function if the value corresponding to the provided key is found in the cache.
- Return
This function returns true if the cache holds the referenced entry, otherwise it returns false.
- Parameters
k: [in] The key for the entry which should be retrieved from the cache.val: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding entry.
-
bool
get_entry(key_type const &k, value_type &val)¶ Get a specific entry identified by the given key.
- Note
The function will call the entry’s entry::touch function if the value corresponding to the provided is found in the cache.
- Return
This function returns true if the cache holds the referenced entry, otherwise it returns false.
- Parameters
k: [in] The key for the entry which should be retrieved from the cacheval: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding value.
-
bool
insert(key_type const &k, value_type const &val)¶ Insert a new element into this cache.
- Note
This function invokes both, the insert policy as provided to the constructor and the function entry::insert of the newly constructed entry instance. If either of these functions returns false the key/value pair doesn’t get inserted into the cache and the insert function will return false. Other reasons for this function to fail (return false) are a) the key/value pair is already held in the cache or b) inserting the new value into the cache maxed out its capacity and it was not possible to free any of the existing entries.
- Return
This function returns true if the entry has been successfully added to the cache, otherwise it returns false.
- Parameters
k: [in] The key for the entry which should be added to the cache.value: [in] The value which should be added to the cache.
-
bool
insert(key_type const &k, entry_type &e)¶ Insert a new entry into this cache.
- Note
This function invokes both, the insert policy as provided to the constructor and the function entry::insert of the provided entry instance. If either of these functions returns false the key/value pair doesn’t get inserted into the cache and the insert function will return false. Other reasons for this function to fail (return false) are a) the key/value pair is already held in the cache or b) inserting the new value into the cache maxed out its capacity and it was not possible to free any of the existing entries.
- Return
This function returns true if the entry has been successfully added to the cache, otherwise it returns false.
- Parameters
k: [in] The key for the entry which should be added to the cache.value: [in] The entry which should be added to the cache.
-
bool
update(key_type const &k, value_type const &val)¶ Update an existing element in this cache.
- Note
The function will call the entry’s entry::touch function if the indexed value is found in the cache.
- Note
The difference to the other overload of the insert function is that this overload replaces the cached value only, while the other overload replaces the whole cache entry, updating the cache entry properties.
- Return
This function returns true if the entry has been successfully updated, otherwise it returns false. If the entry currently is not held by the cache it is added and the return value reflects the outcome of the corresponding insert operation.
- Parameters
k: [in] The key for the value which should be updated in the cache.value: [in] The value which should be used as a replacement for the existing value in the cache. Any existing cache entry is not changed except for its value.
-
template<typename
F>
boolupdate_if(key_type const &k, value_type const &val, F f)¶ Update an existing element in this cache.
- Note
The function will call the entry’s entry::touch function if the indexed value is found in the cache.
- Note
The difference to the other overload of the insert function is that this overload replaces the cached value only, while the other overload replaces the whole cache entry, updating the cache entry properties.
- Return
This function returns true if the entry has been successfully updated, otherwise it returns false. If the entry currently is not held by the cache it is added and the return value reflects the outcome of the corresponding insert operation.
- Parameters
k: [in] The key for the value which should be updated in the cache.value: [in] The value which should be used as a replacement for the existing value in the cache. Any existing cache entry is not changed except for its value.f: [in] A callable taking two arguments, k and the key found in the cache (in that order). If f returns true, then the update will continue. If f returns false, then the update will not succeed.
-
bool
update(key_type const &k, entry_type &e)¶ Update an existing entry in this cache.
- Note
The function will call the entry’s entry::touch function if the indexed value is found in the cache.
- Note
The difference to the other overload of the insert function is that this overload replaces the whole cache entry, while the other overload retplaces the cached value only, leaving the cache entry properties untouched.
- Return
This function returns true if the entry has been successfully updated, otherwise it returns false. If the entry currently is not held by the cache it is added and the return value reflects the outcome of the corresponding insert operation.
- Parameters
k: [in] The key for the entry which should be updated in the cache.value: [in] The entry which should be used as a replacement for the existing entry in the cache. Any existing entry is first removed and then this entry is added.
-
template<typename
Func>
size_typeerase(Func const &ep = policies::always<storage_value_type>())¶ Remove stored entries from the cache for which the supplied function object returns true.
- Return
This function returns the overall size of the removed entries (which is the sum of the values returned by the entry::get_size functions of the removed entries).
- Parameters
ep: [in] This parameter has to be a (unary) function object. It is invoked for each of the entries currently held in the cache. An entry is considered for removal from the cache whenever the value returned from this invocation is true. Even then the entry might not be removed from the cache as its entry::remove function might return false.
-
size_type
erase()¶ Remove all stored entries from the cache.
- Note
All entries are considered for removal, but in the end an entry might not be removed from the cache as its entry::remove function might return false. This function is very useful for instance in conjunction with an entry’s entry::remove function enforcing additional criteria like entry expiration, etc.
- Return
This function returns the overall size of the removed entries (which is the sum of the values returned by the entry::get_size functions of the removed entries).
-
void
clear()¶ Clear the cache.
Unconditionally removes all stored entries from the cache.
-
statistics_type const &
get_statistics() const¶ Allow to access the embedded statistics instance.
- Return
This function returns a reference to the statistics instance embedded inside this cache
-
statistics_type &
get_statistics()¶
Protected Functions
-
bool
free_space(long num_free)¶
Private Types
-
typedef storage_type::iterator
iterator¶
-
typedef storage_type::const_iterator
const_iterator¶
-
typedef statistics_type::update_on_exit
update_on_exit¶
Private Members
-
storage_type
store_¶
-
adapted_update_policy_type
update_policy_¶
-
insert_policy_type
insert_policy_¶
-
statistics_type
statistics_¶
-
template<typename
-
namespace
-
namespace
Header hpx/cache/lru_cache.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
template<typename
Key, typenameEntry, typenameStatistics= statistics::no_statistics>
classlru_cache¶ - #include <hpx/cache/lru_cache.hpp>
The lru_cache implements the basic functionality needed for a local (non-distributed) LRU cache.
- Template Parameters
Key: The type of the keys to use to identify the entries stored in the cacheEntry: The type of the items to be held in the cache.Statistics: A (optional) type allowing to collect some basic statistics about the operation of the cache instance. The type must conform to the CacheStatistics concept. The default value is the type statistics::no_statistics which does not collect any numbers, but provides empty stubs allowing the code to compile.
Public Types
-
typedef Key
key_type¶
-
typedef Entry
entry_type¶
-
typedef Statistics
statistics_type¶
-
typedef std::pair<key_type, entry_type>
entry_pair¶
-
typedef std::list<entry_pair>
storage_type¶
-
typedef std::map<Key, typename storage_type::iterator>
map_type¶
Public Functions
-
lru_cache(size_type max_size = 0)¶ Construct an instance of a lru_cache.
- Parameters
max_size: [in] The maximal size this cache is allowed to reach any time. The default is zero (no size limitation). The unit of this value is usually determined by the unit of the values returned by the entry’s get_size function.
-
size_type
size() const¶ Return current size of the cache.
- Return
The current size of this cache instance.
-
size_type
capacity() const¶ Access the maximum size the cache is allowed to grow to.
- Note
The unit of this value is usually determined by the unit of the return values of the entry’s function entry::get_size.
- Return
The maximum size this cache instance is currently allowed to reach. If this number is zero the cache has no limitation with regard to a maximum size.
-
void
reserve(size_type max_size)¶ Change the maximum size this cache can grow to.
- Parameters
max_size: [in] The new maximum size this cache will be allowed to grow to.
-
bool
holds_key(key_type const &key)¶ Check whether the cache currently holds an entry identified by the given key.
- Note
This function does not call the entry’s function entry::touch. It just checks if the cache contains an entry corresponding to the given key.
- Return
This function returns true if the cache holds the referenced entry, otherwise it returns false.
- Parameters
k: [in] The key for the entry which should be looked up in the cache.
-
bool
get_entry(key_type const &key, key_type &realkey, entry_type &entry)¶ Get a specific entry identified by the given key.
- Note
The function will “touch” the entry and mark it as recently used if the key was found in the cache.
- Return
This function returns true if the cache holds the referenced entry, otherwise it returns false.
- Parameters
key: [in] The key for the entry which should be retrieved from the cache.entry: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding entry.
-
bool
get_entry(key_type const &key, entry_type &entry)¶ Get a specific entry identified by the given key.
- Note
The function will “touch” the entry and mark it as recently used if the key was found in the cache.
- Return
This function returns true if the cache holds the referenced entry, otherwise it returns false.
- Parameters
key: [in] The key for the entry which should be retrieved from the cache.entry: [out] If the entry indexed by the key is found in the cache this value on successful return will be a copy of the corresponding entry.
-
bool
insert(key_type const &key, entry_type const &entry)¶ Insert a new entry into this cache.
- Note
This function assumes that the entry is not in the cache already. Inserting an already existing entry is considered undefined behavior
- Parameters
key: [in] The key for the entry which should be added to the cache.entry: [in] The entry which should be added to the cache.
-
void
insert_nonexist(key_type const &key, entry_type const &entry)¶
-
void
update(key_type const &key, entry_type const &entry)¶ Update an existing element in this cache.
- Note
The function will “touch” the entry and mark it as recently used if the key was found in the cache.
- Note
The difference to the other overload of the insert function is that this overload replaces the cached value only, while the other overload replaces the whole cache entry, updating the cache entry properties.
- Parameters
key: [in] The key for the value which should be updated in the cache.entry: [in] The entry which should be used as a replacement for the existing value in the cache. Any existing cache entry is not changed except for its value.
-
template<typename
F>
boolupdate_if(key_type const &key, entry_type const &entry, F &&f)¶ Update an existing element in this cache.
- Note
The function will “touch” the entry and mark it as recently used if the key was found in the cache.
- Note
The difference to the other overload of the insert function is that this overload replaces the cached value only, while the other overload replaces the whole cache entry, updating the cache entry properties.
- Return
This function returns true if the entry has been successfully updated, otherwise it returns false. If the entry currently is not held by the cache it is added and the return value reflects the outcome of the corresponding insert operation.
- Parameters
key: [in] The key for the value which should be updated in the cache.entry: [in] The value which should be used as a replacement for the existing value in the cache. Any existing cache entry is not changed except for its value.f: [in] A callable taking two arguments, k and the key found in the cache (in that order). If f returns true, then the update will continue. If f returns false, then the update will not succeed.
-
template<typename
Func>
size_typeerase(Func const &ep)¶ Remove stored entries from the cache for which the supplied function object returns true.
- Return
This function returns the overall size of the removed entries (which is the sum of the values returned by the entry::get_size functions of the removed entries).
- Parameters
ep: [in] This parameter has to be a (unary) function object. It is invoked for each of the entries currently held in the cache. An entry is considered for removal from the cache whenever the value returned from this invocation is true.
-
size_type
erase()¶ Remove all stored entries from the cache.
- Return
This function returns the overall size of the removed entries (which is the sum of the values returned by the entry::get_size functions of the removed entries).
-
statistics_type const &
get_statistics() const¶ Allow to access the embedded statistics instance.
- Return
This function returns a reference to the statistics instance embedded inside this cache
-
statistics_type &
get_statistics()¶
Private Types
-
typedef statistics_type::update_on_exit
update_on_exit¶
-
template<typename
-
namespace
-
namespace
Header hpx/cache/policies/always.hpp¶
Header hpx/cache/statistics/local_full_statistics.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
namespace
statistics¶ -
class
local_full_statistics: public hpx::util::cache::statistics::local_statistics¶ - #include <local_full_statistics.hpp>
Public Functions
-
std::int64_t
get_get_entry_count(bool reset)¶ The function get_get_entry_count returns the number of invocations of the get_entry() API function of the cache.
-
std::int64_t
get_insert_entry_count(bool reset)¶ The function get_insert_entry_count returns the number of invocations of the insert_entry() API function of the cache.
-
std::int64_t
get_update_entry_count(bool reset)¶ The function get_update_entry_count returns the number of invocations of the update_entry() API function of the cache.
-
std::int64_t
get_erase_entry_count(bool reset)¶ The function get_erase_entry_count returns the number of invocations of the erase() API function of the cache.
-
std::int64_t
get_get_entry_time(bool reset)¶ The function get_get_entry_time returns the overall time spent executing of the get_entry() API function of the cache.
-
std::int64_t
get_insert_entry_time(bool reset)¶ The function get_insert_entry_time returns the overall time spent executing of the insert_entry() API function of the cache.
Private Members
-
api_counter_data
get_entry_¶
-
api_counter_data
insert_entry_¶
-
api_counter_data
update_entry_¶
-
api_counter_data
erase_entry_¶
Friends
-
friend
hpx::util::cache::statistics::update_on_exit
-
struct
update_on_exit¶ - #include <local_full_statistics.hpp>
Helper class to update timings and counts on function exit.
Private Static Functions
-
static api_counter_data &
get_api_counter_data(local_full_statistics &stat, method m)¶
-
static api_counter_data &
-
std::int64_t
-
class
-
namespace
-
namespace
-
namespace
Header hpx/cache/statistics/local_statistics.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
namespace
statistics -
class
local_statistics: public hpx::util::cache::statistics::no_statistics¶ - #include <local_statistics.hpp>
Subclassed by hpx::util::cache::statistics::local_full_statistics
Public Functions
-
local_statistics()¶
-
void
got_hit()¶ The function got_hit will be called by a cache instance whenever a entry got touched.
-
void
got_miss()¶ The function got_miss will be called by a cache instance whenever a requested entry has not been found in the cache.
-
void
got_insertion()¶ The function got_insertion will be called by a cache instance whenever a new entry has been inserted.
-
void
got_eviction()¶ The function got_eviction will be called by a cache instance whenever an entry has been removed from the cache because a new inserted entry let the cache grow beyond its capacity.
-
void
clear()¶ Reset all statistics.
-
-
class
-
namespace
-
namespace
-
namespace
Header hpx/cache/statistics/no_statistics.hpp¶
-
namespace
hpx -
namespace
util -
namespace
cache -
namespace
statistics Enums
-
class
no_statistics¶ - #include <no_statistics.hpp>
Subclassed by hpx::util::cache::statistics::local_statistics
Public Functions
-
void
got_hit()¶ The function got_hit will be called by a cache instance whenever a entry got touched.
-
void
got_miss()¶ The function got_miss will be called by a cache instance whenever a requested entry has not been found in the cache.
-
void
got_insertion()¶ The function got_insertion will be called by a cache instance whenever a new entry has been inserted.
-
void
got_eviction()¶ The function got_eviction will be called by a cache instance whenever an entry has been removed from the cache because a new inserted entry let the cache grow beyond its capacity.
-
void
clear()¶ Reset all statistics.
-
std::int64_t
get_get_entry_count(bool)¶ The function get_get_entry_count returns the number of invocations of the get_entry() API function of the cache.
-
std::int64_t
get_insert_entry_count(bool)¶ The function get_insert_entry_count returns the number of invocations of the insert_entry() API function of the cache.
-
std::int64_t
get_update_entry_count(bool)¶ The function get_update_entry_count returns the number of invocations of the update_entry() API function of the cache.
-
std::int64_t
get_erase_entry_count(bool)¶ The function get_erase_entry_count returns the number of invocations of the erase() API function of the cache.
-
std::int64_t
get_get_entry_time(bool)¶ The function get_get_entry_time returns the overall time spent executing of the get_entry() API function of the cache.
-
std::int64_t
get_insert_entry_time(bool)¶ The function get_insert_entry_time returns the overall time spent executing of the insert_entry() API function of the cache.
-
struct
update_on_exit¶ - #include <no_statistics.hpp>
Helper class to update timings and counts on function exit.
Public Functions
-
update_on_exit(no_statistics const&, method)¶
-
-
void
-
class
-
namespace
-
namespace
-
namespace
checkpoint¶
The contents of this module can be included with the header
hpx/modules/checkpoint.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/checkpoint.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/checkpoint/checkpoint.hpp¶
This header defines the save_checkpoint and restore_checkpoint functions. These functions are designed to help HPX application developer’s checkpoint their applications. Save_checkpoint serializes one or more objects and saves them as a byte stream. Restore_checkpoint converts the byte stream back into instances of the objects.
-
namespace
hpx -
namespace
util Functions
-
std::ostream &
operator<<(std::ostream &ost, checkpoint const &ckp)¶ Operator<< Overload
This overload is the main way to write data from a checkpoint to an object such as a file. Inside the function, the size of the checkpoint will be written to the stream before the checkpoint’s data. The operator>> overload uses this to read the correct number of bytes. Be mindful of this additional write and read when you use different facilities to write out or read in data to a checkpoint!
- Parameters
ost: Output stream to write to.ckp: Checkpoint to copy from.
- Return
Operator<< returns the ostream object.
-
std::istream &
operator>>(std::istream &ist, checkpoint &ckp)¶ Operator>> Overload
This overload is the main way to read in data from an object such as a file to a checkpoint. It is important to note that inside the function, the first variable to be read is the size of the checkpoint. This size variable is written to the stream before the checkpoint’s data in the operator<< overload. Be mindful of this additional read and write when you use different facilities to read in or write out data from a checkpoint!
- Parameters
ist: Input stream to write from.ckp: Checkpoint to write to.
- Return
Operator>> returns the ostream object.
-
template<typename
T, typename ...Ts, typenameU= typename std::enable_if<!hpx::traits::is_launch_policy<T>::value && !std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
hpx::future<checkpoint>save_checkpoint(T &&t, Ts&&... ts)¶ Save_checkpoint
Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.
- Template Parameters
T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.U: This parameter is used to make sure that T is not a launch policy or a checkpoint. This forces the compiler to choose the correct overload.
- Parameters
t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
- Return
Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.
-
template<typename
T, typename ...Ts>
hpx::future<checkpoint>save_checkpoint(checkpoint &&c, T &&t, Ts&&... ts)¶ Save_checkpoint - Take a pre-initialized checkpoint
Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.
- Template Parameters
T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.
- Parameters
c: Takes a pre-initialized checkpoint to copy data into.t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
- Return
Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.
-
template<typename
T, typename ...Ts, typenameU= typename std::enable_if<!std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
hpx::future<checkpoint>save_checkpoint(hpx::launch p, T &&t, Ts&&... ts)¶ Save_checkpoint - Policy overload
Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.
- Template Parameters
T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.
- Parameters
p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
- Return
Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.
-
template<typename
T, typename ...Ts>
hpx::future<checkpoint>save_checkpoint(hpx::launch p, checkpoint &&c, T &&t, Ts&&... ts)¶ Save_checkpoint - Policy overload & pre-initialized checkpoint
Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.
- Template Parameters
T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.
- Parameters
p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.c: Takes a pre-initialized checkpoint to copy data into.t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
- Return
Save_checkpoint returns a future to a checkpoint with one exception: if you pass hpx::launch::sync as the first argument. In this case save_checkpoint will simply return a checkpoint.
-
template<typename
T, typename ...Ts, typenameU= typename std::enable_if<!std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
checkpointsave_checkpoint(hpx::launch::sync_policy sync_p, T &&t, Ts&&... ts)¶ Save_checkpoint - Sync_policy overload
Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.
- Template Parameters
T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.U: This parameter is used to make sure that T is not a checkpoint. This forces the compiler to choose the correct overload.
- Parameters
sync_p: hpx::launch::sync_policyt: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
- Return
Save_checkpoint which is passed hpx::launch::sync_policy will return a checkpoint which contains the serialized values checkpoint.
-
template<typename
T, typename ...Ts>
checkpointsave_checkpoint(hpx::launch::sync_policy sync_p, checkpoint &&c, T &&t, Ts&&... ts)¶ Save_checkpoint - Sync_policy overload & pre-init. checkpoint
Save_checkpoint takes any number of objects which a user may wish to store and returns a future to a checkpoint object. This function can also store a component either by passing a shared_ptr to the component or by passing a component’s client instance to save_checkpoint. Additionally the function can take a policy as a first object which changes its behavior depending on the policy passed to it. Most notably, if a sync policy is used save_checkpoint will simply return a checkpoint object.
- Template Parameters
T: Containers passed to save_checkpoint to be serialized and placed into a checkpoint object.Ts: More containers passed to save_checkpoint to be serialized and placed into a checkpoint object.
- Parameters
sync_p: hpx::launch::sync_policyc: Takes a pre-initialized checkpoint to copy data into.t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
- Return
Save_checkpoint which is passed hpx::launch::sync_policy will return a checkpoint which contains the serialized values checkpoint.
-
template<typename
T, typename ...Ts, typenameU= typename std::enable_if<!hpx::traits::is_launch_policy<T>::value && !std::is_same<typename std::decay<T>::type, checkpoint>::value>::type>
hpx::future<checkpoint>prepare_checkpoint(T const &t, Ts const&... ts)¶ prepare_checkpoint
prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.
- Return
prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.
- Template Parameters
T: A container to restore.Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.
- Parameters
t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
-
template<typename
T, typename ...Ts>
hpx::future<checkpoint>prepare_checkpoint(checkpoint &&c, T const &t, Ts const&... ts)¶ prepare_checkpoint
prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.
- Return
prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.
- Template Parameters
T: A container to restore.Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.
- Parameters
c: Takes a pre-initialized checkpoint to preparet: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
-
template<typename
T, typename ...Ts, typenameU= typename std::enable_if<!std::is_same<T, checkpoint>::value>::type>
hpx::future<checkpoint>prepare_checkpoint(hpx::launch p, T const &t, Ts const&... ts)¶ prepare_checkpoint
prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.
- Return
prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.
- Template Parameters
T: A container to restore.Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.
- Parameters
p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
-
template<typename
T, typename ...Ts>
hpx::future<checkpoint>prepare_checkpoint(hpx::launch p, checkpoint &&c, T const &t, Ts const&... ts)¶ prepare_checkpoint
prepare_checkpoint takes the containers which have to be filled from the byte stream by a subsequent restore_checkpoint invocation. prepare_checkpoint will calculate the necessary buffer size and will return an appropriately sized checkpoint object.
- Return
prepare_checkpoint returns a properly resized checkpoint object that can be used for a subsequent restore_checkpoint operation.
- Template Parameters
T: A container to restore.Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.
- Parameters
p: Takes an HPX launch policy. Allows the user to change the way the function is launched i.e. async, sync, etc.c: Takes a pre-initialized checkpoint to preparet: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
-
template<typename
T, typename ...Ts>
voidrestore_checkpoint(checkpoint const &c, T &t, Ts&... ts)¶ Restore_checkpoint
Restore_checkpoint takes a checkpoint object as a first argument and the containers which will be filled from the byte stream (in the same order as they were placed in save_checkpoint). Restore_checkpoint can resurrect a stored component in two ways: by passing in a instance of a component’s shared_ptr or by passing in an instance of the component’s client.
- Return
Restore_checkpoint returns void.
- Template Parameters
T: A container to restore.Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.
- Parameters
c: The checkpoint to restore.t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
-
class
checkpoint¶ - #include <checkpoint.hpp>
Checkpoint Object
Checkpoint is the container object which is produced by save_checkpoint and is consumed by a restore_checkpoint. A checkpoint may be moved into the save_checkpoint object to write the byte stream to the pre-created checkpoint object.
Checkpoints are able to store all containers which are able to be serialized including components.
Public Functions
-
checkpoint()¶
-
~checkpoint()¶
-
checkpoint(checkpoint const &c)¶
-
checkpoint(checkpoint &&c)¶
-
checkpoint &
operator=(checkpoint const &c)¶
-
checkpoint &
operator=(checkpoint &&c)¶
-
const_iterator
begin() const¶
-
const_iterator
end() const¶
-
char *
data()¶
-
char const *
data() const¶
Private Functions
Friends
-
friend
hpx::util::hpx::serialization::access
-
std::ostream &
operator<<(std::ostream &ost, checkpoint const &ckp)¶ Operator<< Overload
This overload is the main way to write data from a checkpoint to an object such as a file. Inside the function, the size of the checkpoint will be written to the stream before the checkpoint’s data. The operator>> overload uses this to read the correct number of bytes. Be mindful of this additional write and read when you use different facilities to write out or read in data to a checkpoint!
- Parameters
ost: Output stream to write to.ckp: Checkpoint to copy from.
- Return
Operator<< returns the ostream object.
-
std::istream &
operator>>(std::istream &ist, checkpoint &ckp)¶ Operator>> Overload
This overload is the main way to read in data from an object such as a file to a checkpoint. It is important to note that inside the function, the first variable to be read is the size of the checkpoint. This size variable is written to the stream before the checkpoint’s data in the operator<< overload. Be mindful of this additional read and write when you use different facilities to read in or write out data from a checkpoint!
- Parameters
ist: Input stream to write from.ckp: Checkpoint to write to.
- Return
Operator>> returns the ostream object.
-
template<typename
T, typename ...Ts>
voidrestore_checkpoint(checkpoint const &c, T &t, Ts&... ts)¶ Restore_checkpoint
Restore_checkpoint takes a checkpoint object as a first argument and the containers which will be filled from the byte stream (in the same order as they were placed in save_checkpoint). Restore_checkpoint can resurrect a stored component in two ways: by passing in a instance of a component’s shared_ptr or by passing in an instance of the component’s client.
- Return
Restore_checkpoint returns void.
- Template Parameters
T: A container to restore.Ts: Other containers to restore. Containers must be in the same order that they were inserted into the checkpoint.
- Parameters
c: The checkpoint to restore.t: A container to restore.ts: Other containers to restore Containers must be in the same order that they were inserted into the checkpoint.
-
bool
operator==(checkpoint const &lhs, checkpoint const &rhs)¶
-
bool
operator!=(checkpoint const &lhs, checkpoint const &rhs)¶
-
-
std::ostream &
-
namespace
checkpoint_base¶
The contents of this module can be included with the header
hpx/modules/checkpoint_base.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/checkpoint_base.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/checkpoint_base/checkpoint_data.hpp¶
-
namespace
hpx -
namespace
util Functions
-
template<typename
Container, typename ...Ts>
voidsave_checkpoint_data(Container &data, Ts&&... ts)¶ save_checkpoint_data
Save_checkpoint_data takes any number of objects which a user may wish to store in the given container.
- Template Parameters
Container: Container used to store the check-pointed data.Ts: Types of variables to checkpoint
- Parameters
cont: Container instance used to store the checkpoint datats: Variable instances to be inserted into the checkpoint.
-
template<typename ...
Ts>
std::size_tprepare_checkpoint_data(Ts const&... ts)¶ prepare_checkpoint_data
prepare_checkpoint_data takes any number of objects which a user may wish to store in a subsequent save_checkpoint_data operation. The function will return the number of bytes necessary to store the data that will be produced.
- Template Parameters
Ts: Types of variables to checkpoint
- Parameters
ts: Variable instances to be inserted into the checkpoint.
-
template<typename
Container, typename ...Ts>
voidrestore_checkpoint_data(Container const &cont, Ts&... ts)¶ restore_checkpoint_data
restore_checkpoint_data takes any number of objects which a user may wish to restore from the given container. The sequence of objects has to correspond to the sequence of objects for the corresponding call to save_checkpoint_data that had used the given container instance.
- Template Parameters
Container: Container used to restore the check-pointed data.Ts: Types of variables to restore
- Parameters
cont: Container instance used to restore the checkpoint datats: Variable instances to be restored from the container
-
template<typename
-
namespace
collectives¶
The contents of this module can be included with the header
hpx/modules/collectives.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/collectives.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/collectives/all_gather.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename
T>
hpx::future<std::vector<T>>all_gather(char const *basename, hpx::future<T> &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ AllToAll a set of values from different call sites
This function receives a set of values from all call sites operating on the given base name.
- Note
Each all_gather operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_gather.
- Return
This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_gather operation has been completed.
- Parameters
basename: The base name identifying the all_gather operationlocal_result: A future referring to the value to transmit to all participating sites from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the all_gather operation performed on the given base name. This is optional and needs to be supplied only if the all_gather operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns. root_site The site that is responsible for creating the all_gather support object. This value is optional and defaults to ‘0’ (zero).
-
template<typename
T>
hpx::future<std::vector<typename std::decay<T>::type>>all_gather(char const *basename, T &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ AllToAll a set of values from different call sites
This function receives a set of values from all call sites operating on the given base name.
- Note
Each all_gather operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_gather.
- Return
This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_gather operation has been completed.
- Parameters
basename: The base name identifying the all_gather operationlocal_result: The value to transmit to all participating sites from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the all_gather operation performed on the given base name. This is optional and needs to be supplied only if the all_gather operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns. root_site The site that is responsible for creating the all_gather support object. This value is optional and defaults to ‘0’ (zero).
-
template<typename
-
namespace
Header hpx/collectives/all_reduce.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename
T, typenameF>
hpx::future<T>all_reduce(char const *basename, hpx::future<T> result, F &&op, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ AllReduce a set of values from different call sites
This function receives a set of values that are the result of applying a given operator on values supplied from all call sites operating on the given base name.
- Note
Each all_reduce operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLREDUCE macro to define the necessary internal facilities used by all_reduce.
- Return
This function returns a future holding a value calculated based on the values send by all participating sites. It will become ready once the all_reduce operation has been completed.
- Parameters
basename: The base name identifying the all_reduce operationlocal_result: A future referring to the value to transmit to all participating sites from this call site.op: Reduction operation to apply to all values supplied from all participating sitesnum_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the all_reduce operation performed on the given base name. This is optional and needs to be supplied only if the all_reduce operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns. root_site The site that is responsible for creating the all_reduce support object. This value is optional and defaults to ‘0’ (zero).
-
template<typename
T, typenameF>
hpx::future<std::decay_t<T>>all_reduce(char const *basename, T &&result, F &&op, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ AllReduce a set of values from different call sites
This function receives a set of values from all call sites operating on the given base name.
- Note
Each all_reduce operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLREDUCE macro to define the necessary internal facilities used by all_reduce.
- Return
This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_reduce operation has been completed.
- Parameters
basename: The base name identifying the all_reduce operationlocal_result: The value to transmit to all participating sites from this call site.op: Reduction operation to apply to all values supplied from all participating sitesnum_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the all_reduce operation performed on the given base name. This is optional and needs to be supplied only if the all_reduce operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns. root_site The site that is responsible for creating the all_reduce support object. This value is optional and defaults to ‘0’ (zero).
-
template<typename
-
namespace
Header hpx/collectives/all_to_all.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename
T>
hpx::future<std::vector<T>>all_to_all(char const *basename, hpx::future<std::vector<T>> &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ AllToAll a set of values from different call sites
This function receives a set of values from all call sites operating on the given base name.
- Note
Each all_to_all operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_to_all.
- Return
This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_to_all operation has been completed.
- Parameters
basename: The base name identifying the all_to_all operationlocal_result: A future referring to the value to transmit to all participating sites from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the all_to_all operation performed on the given base name. This is optional and needs to be supplied only if the all_to_all operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns. root_site The site that is responsible for creating the all_to_all support object. This value is optional and defaults to ‘0’ (zero).
-
template<typename
T>
hpx::future<std::vector<typename std::decay<T>::type>>all_to_all(char const *basename, T &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ AllToAll a set of values from different call sites
This function receives a set of values from all call sites operating on the given base name.
- Note
Each all_to_all operation has to be accompanied with a unique usage of the HPX_REGISTER_ALLTOALL macro to define the necessary internal facilities used by all_to_all.
- Return
This function returns a future holding a vector with all values send by all participating sites. It will become ready once the all_to_all operation has been completed.
- Parameters
basename: The base name identifying the all_to_all operationlocal_result: The value to transmit to all participating sites from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the all_to_all operation performed on the given base name. This is optional and needs to be supplied only if the all_to_all operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns. root_site The site that is responsible for creating the all_to_all support object. This value is optional and defaults to ‘0’ (zero).
-
template<typename
-
namespace
Header hpx/collectives/barrier.hpp¶
-
namespace
hpx -
namespace
lcos -
class
barrier¶ - #include <barrier.hpp>
The barrier is an implementation performing a barrier over a number of participating threads. The different threads don’t have to be on the same locality. This barrier can be invoked in a distributed application.
For a local only barrier
- See
hpx::lcos::local::barrier.
Public Functions
-
barrier(std::string const &base_name)¶ Creates a barrier, rank is locality id, size is number of localities
A barrier
base_name is created. It expects that hpx::get_num_localities() participate and the local rank is hpx::get_locality_id().- Parameters
base_name: The name of the barrier
-
barrier(std::string const &base_name, std::size_t num)¶ Creates a barrier with a given size, rank is locality id
A barrier
base_name is created. It expects that num participate and the local rank is hpx::get_locality_id().- Parameters
base_name: The name of the barriernum: The number of participating threads
-
barrier(std::string const &base_name, std::size_t num, std::size_t rank)¶ Creates a barrier with a given size and rank
A barrier
base_name is created. It expects that num participate and the local rank is rank.- Parameters
base_name: The name of the barriernum: The number of participating threadsrank: The rank of the calling site for this invocation
-
barrier(std::string const &base_name, std::vector<std::size_t> const &ranks, std::size_t rank)¶ Creates a barrier with a vector of ranks
A barrier
base_name is created. It expects that ranks.size() and the local rank is rank (must be contained in ranks).- Parameters
base_name: The name of the barrierranks: Gives a list of participating ranks (this could be derived from a list of locality idsrank: The rank of the calling site for this invocation
-
void
wait()¶ Wait until each participant entered the barrier. Must be called by all participants
- Return
This function returns once all participants have entered the barrier (have called wait).
Public Static Functions
-
static void
synchronize()¶ Perform a global synchronization using the default global barrier The barrier is created once at startup and can be reused throughout the lifetime of an HPX application.
- Note
This function currently does not support dynamic connection and disconnection of localities.
-
class
-
namespace
Header hpx/collectives/broadcast.hpp¶
Header hpx/collectives/broadcast_direct.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename Action, typename ArgN, ...>hpx::future<std::vector<decltype(Action(hpx::id_type, ArgN, ...))> > hpx::lcos::broadcast(std::vector< hpx::id_type > const & ids, ArgN argN, ...) Perform a distributed broadcast operation.
The function hpx::lcos::broadcast performs a distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.
- Return
This function returns a future representing the result of the overall reduction operation.
- Note
If decltype(Action(…)) is void, then the result of this function is future<void>.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.
-
template<typename Action, typename ArgN, ...>void hpx::lcos::broadcast_apply(std::vector< hpx::id_type > const & ids, ArgN argN, ...) Perform an asynchronous (fire&forget) distributed broadcast operation.
The function hpx::lcos::broadcast_apply performs an asynchronous (fire&forget) distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.
-
template<typename Action, typename ArgN, ...>hpx::future< std::vector<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> > hpx::lcos::broadcast_with_index(std::vector< hpx::id_type > const & ids, ArgN argN, ...) Perform a distributed broadcast operation.
The function hpx::lcos::broadcast_with_index performs a distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.
The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.
- Return
This function returns a future representing the result of the overall reduction operation.
- Note
If decltype(Action(…)) is void, then the result of this function is future<void>.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.
-
template<typename Action, typename ArgN, ...>void hpx::lcos::broadcast_apply_with_index(std::vector< hpx::id_type > const & ids, ArgN argN, ...) Perform an asynchronous (fire&forget) distributed broadcast operation.
The function hpx::lcos::broadcast_apply_with_index performs an asynchronous (fire&forget) distributed broadcast operation resulting in action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
The given action is invoked asynchronously on all given identifiers, and the arguments ArgN are passed along to those invocations.
The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.argN: [in] Any number of arbitrary arguments (passed by const reference) which will be forwarded to the action invocation.
-
-
namespace
Header hpx/collectives/fold.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ...))> hpx::lcos::fold(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...) Perform a distributed fold operation.
The function hpx::lcos::fold performs a distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
- Note
The type of the initial value must be convertible to the result type returned from the invoked action.
- Return
This function returns a future representing the result of the overall folding operation.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.init: [in] The initial value to be used for the folding operationargN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.
-
template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> hpx::lcos::fold_with_index(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...) Perform a distributed folding operation.
The function hpx::lcos::fold_with_index performs a distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.
- Note
The type of the initial value must be convertible to the result type returned from the invoked action.
- Return
This function returns a future representing the result of the overall folding operation.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.init: [in] The initial value to be used for the folding operationargN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.
-
template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ...))> hpx::lcos::inverse_fold(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...) Perform a distributed inverse folding operation.
The function hpx::lcos::inverse_fold performs an inverse distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
- Note
The type of the initial value must be convertible to the result type returned from the invoked action.
- Return
This function returns a future representing the result of the overall folding operation.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.init: [in] The initial value to be used for the folding operationargN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.
-
template<typename Action, typename FoldOp, typename Init, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> hpx::lcos::inverse_fold_with_index(std::vector< hpx::id_type > const & ids, FoldOp && fold_op, Init && init, ArgN argN, ...) Perform a distributed inverse folding operation.
The function hpx::lcos::inverse_fold_with_index performs an inverse distributed folding operation over results returned from action invocations on a given set of global identifiers. The action can be either plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.
- Note
The type of the initial value must be convertible to the result type returned from the invoked action.
- Return
This function returns a future representing the result of the overall folding operation.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.fold_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the folding operation performed on its arguments.init: [in] The initial value to be used for the folding operationargN: [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the action invocation.
-
-
namespace
Header hpx/collectives/gather.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename
T>
hpx::future<std::vector<T>>gather_here(char const *basename, hpx::future<T> result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))¶ Gather a set of values from different call sites
This function receives a set of values from all call sites operating on the given base name.
- Note
Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there
- Return
This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.
- Parameters
basename: The base name identifying the gather operationresult: A future referring to the value to transmit to the central gather point from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the gather operation performed on the given base name. This is optional and needs to be supplied only if the gather operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.
-
template<typename
T>
hpx::future<std::vector<T>>gather_there(char const *basename, hpx::future<T> result, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ Gather a given value at the given call site
This function transmits the value given by result to a central gather site (where the corresponding gather_here is executed)
- Note
Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there
- Return
This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.
- Parameters
basename: The base name identifying the gather operationresult: A future referring to the value to transmit to the central gather point from this call site.generation: The generational counter identifying the sequence number of the gather operation performed on the given base name. This is optional and needs to be supplied only if the gather operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.root_site: The sequence number of the central gather point (usually the locality id). This value is optional and defaults to 0.
-
template<typename
T>
hpx::future<std::vector<typename std::decay<T>::type>>gather_here(char const *basename, T &&result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))¶ Gather a set of values from different call sites
This function receives a set of values from all call sites operating on the given base name.
- Note
Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there
- Return
This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.
- Parameters
basename: The base name identifying the gather operationresult: The value to transmit to the central gather point from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the gather operation performed on the given base name. This is optional and needs to be supplied only if the gather operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.
-
template<typename
T>
hpx::future<std::vector<typename std::decay<T>::type>>gather_there(char const *basename, T &&result, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ Gather a given value at the given call site
This function transmits the value given by result to a central gather site (where the corresponding gather_here is executed)
- Note
Each gather operation has to be accompanied with a unique usage of the HPX_REGISTER_GATHER macro to define the necessary internal facilities used by gather_here and gather_there
- Return
This function returns a future holding a vector with all gathered values. It will become ready once the gather operation has been completed.
- Parameters
basename: The base name identifying the gather operationresult: The value to transmit to the central gather point from this call site.generation: The generational counter identifying the sequence number of the gather operation performed on the given base name. This is optional and needs to be supplied only if the gather operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.root_site: The sequence number of the central gather point (usually the locality id). This value is optional and defaults to 0.
-
template<typename
-
namespace
Header hpx/collectives/latch.hpp¶
-
namespace
hpx -
namespace
lcos -
class
latch: public components::client_base<latch, lcos::server::latch>¶ - #include <latch.hpp>
Public Functions
-
latch()¶
-
latch(std::ptrdiff_t count)¶ Initialize the latch
Requires: count >= 0. Synchronization: None Postconditions: counter_ == count.
-
latch(naming::id_type const &id)¶ Extension: Create a client side representation for the existing server::latch instance with the given global id id.
-
latch(hpx::future<naming::id_type> &&f)¶ Extension: Create a client side representation for the existing server::latch instance with the given global id id.
Extension: Create a client side representation for the existing server::latch instance with the given global id id.
-
void
count_down_and_wait()¶ Decrements counter_ by 1 . Blocks at the synchronization point until counter_ reaches 0.
Requires: counter_ > 0.
Synchronization: Synchronizes with all calls that block on this latch and with all is_ready calls on this latch that return true.
- Exceptions
Nothing.:
-
void
count_down(std::ptrdiff_t n)¶ Decrements counter_ by n. Does not block.
Requires: counter_ >= n and n >= 0.
Synchronization: Synchronizes with all calls that block on this latch and with all is_ready calls on this latch that return true .
- Exceptions
Nothing.:
-
bool
is_ready() const¶ Returns: counter_ == 0. Does not block.
- Exceptions
Nothing.:
-
void
wait() const¶ If counter_ is 0, returns immediately. Otherwise, blocks the calling thread at the synchronization point until counter_ reaches 0.
- Exceptions
Nothing.:
Private Types
-
typedef components::client_base<latch, lcos::server::latch>
base_type¶
-
-
class
-
namespace
Header hpx/collectives/reduce.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename Action, typename ReduceOp, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ...))> hpx::lcos::reduce(std::vector< hpx::id_type > const & ids, ReduceOp && reduce_op, ArgN argN, ...) Perform a distributed reduction operation.
The function hpx::lcos::reduce performs a distributed reduction operation over results returned from action invocations on a given set of global identifiers. The action can be either a plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
- Return
This function returns a future representing the result of the overall reduction operation.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.reduce_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the reduction operation performed on its arguments.argN: [in] Any number of arbitrary arguments (passed by by const reference) which will be forwarded to the action invocation.
-
template<typename Action, typename ReduceOp, typename ArgN, ...>hpx::future<decltype(Action(hpx::id_type, ArgN, ..., std::size_t))> hpx::lcos::reduce_with_index(std::vector< hpx::id_type > const & ids, ReduceOp && reduce_op, ArgN argN, ...) Perform a distributed reduction operation.
The function hpx::lcos::reduce_with_index performs a distributed reduction operation over results returned from action invocations on a given set of global identifiers. The action can be either plain action (in which case the global identifiers have to refer to localities) or a component action (in which case the global identifiers have to refer to instances of a component type which exposes the action.
The function passes the index of the global identifier in the given list of identifiers as the last argument to the action.
- Return
This function returns a future representing the result of the overall reduction operation.
- Parameters
ids: [in] A list of global identifiers identifying the target objects for which the given action will be invoked.reduce_op: [in] A binary function expecting two results as returned from the action invocations. The function (or function object) is expected to return the result of the reduction operation performed on its arguments.argN: [in] Any number of arbitrary arguments (passed by by const reference) which will be forwarded to the action invocation.
-
-
namespace
Header hpx/collectives/scatter.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
template<typename
T>
hpx::future<T>scatter_from(char const *basename, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1), std::size_t root_site = 0)¶ Scatter (receive) a set of values to different call sites
This function receives an element of a set of values operating on the given base name.
Scatter (receive) a set of values to different call sites
- Note
Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to
- Return
This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.
- Parameters
basename: The base name identifying the scatter operationresult: A future referring to the value to transmit to the central scatter point from this call site.generation: The generational counter identifying the sequence number of the scatter operation performed on the given base name. This is optional and needs to be supplied only if the scatter operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.root_site: The sequence number of the central scatter point (usually the locality id). This value is optional and defaults to 0.
This function receives an element of a set of values operating on the given base name.
- Note
Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to
- Return
This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.
- Parameters
basename: The base name identifying the scatter operationresult: The value to transmit to the central scatter point from this call site.generation: The generational counter identifying the sequence number of the scatter operation performed on the given base name. This is optional and needs to be supplied only if the scatter operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.root_site: The sequence number of the central scatter point (usually the locality id). This value is optional and defaults to 0.
-
template<typename
T>
hpx::future<T>scatter_to(char const *basename, hpx::future<std::vector<T>> result, std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))¶ Scatter (send) a part of the value set at the given call site
This function transmits the value given by result to a central scatter site (where the corresponding scatter_from is executed)
- Note
Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to
- Return
This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.
- Parameters
basename: The base name identifying the scatter operationresult: A future referring to the value to transmit to the central scatter point from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the scatter operation performed on the given base name. This is optional and needs to be supplied only if the scatter operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.
-
template<typename
T>
hpx::future<T>scatter_to(char const *basename, std::vector<T> const &result, std::size_t num_sites = std::size_t(-1), std::size_t generation = std::size_t(-1), std::size_t this_site = std::size_t(-1))¶ Scatter (send) a part of the value set at the given call site
This function transmits the value given by result to a central scatter site (where the corresponding scatter_from is executed)
- Note
Each scatter operation has to be accompanied with a unique usage of the HPX_REGISTER_SCATTER macro to define the necessary internal facilities used by scatter_from and scatter_to
- Return
This function returns a future holding a the scattered value. It will become ready once the scatter operation has been completed.
- Parameters
basename: The base name identifying the scatter operationresult: The value to transmit to the central scatter point from this call site.num_sites: The number of participating sites (default: all localities).generation: The generational counter identifying the sequence number of the scatter operation performed on the given base name. This is optional and needs to be supplied only if the scatter operation on the given base name has to be performed more than once.this_site: The sequence number of this invocation (usually the locality id). This value is optional and defaults to whatever hpx::get_locality_id() returns.
-
template<typename
-
namespace
Header hpx/collectives/spmd_block.hpp¶
-
namespace
hpx -
namespace
lcos Functions
-
struct
spmd_block¶ - #include <spmd_block.hpp>
The class spmd_block defines an interface for launching multiple images while giving handles to each image to interact with the remaining images. The define_spmd_block function templates create multiple images of a user-defined action and launches them in a possibly separate thread. A temporary spmd block object is created and diffused to each image. The constraint for the action given to the define_spmd_block function is to accept a spmd_block as first parameter.
Public Functions
-
spmd_block()¶
-
spmd_block(std::string const &name, std::size_t images_per_locality, std::size_t num_images, std::size_t image_id)¶
-
void
sync_all() const¶
-
template<typename
Iterator>
std::enable_if<traits::is_input_iterator<Iterator>::value>::typesync_images(Iterator begin, Iterator end) const¶
-
template<typename ...
I>
std::enable_if<util::all_of<typename std::is_integral<I>::type...>::value>::typesync_images(I... i)¶
-
hpx::future<void>
sync_images(hpx::launch::async_policy const &policy, std::set<std::size_t> const &images) const¶
-
hpx::future<void>
sync_images(hpx::launch::async_policy const &policy, std::vector<std::size_t> const &input_images) const¶
Private Types
Friends
-
friend
hpx::lcos::hpx::serialization::access
-
-
struct
-
namespace
Header hpx/distributed/barrier.hpp¶
Header hpx/distributed/latch.hpp¶
command_line_handling¶
The contents of this module can be included with the header
hpx/modules/command_line_handling.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/command_line_handling.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/command_line_handling/command_line_handling.hpp¶
-
namespace
hpx -
namespace
util Functions
-
std::size_t
get_num_high_priority_queues(util::command_line_handling const &cfg, std::size_t num_threads)¶
-
std::string
get_affinity_domain(util::command_line_handling const &cfg)¶
-
std::size_t
get_affinity_description(util::command_line_handling const &cfg, std::string &affinity_desc)¶
-
std::size_t
get_pu_offset(util::command_line_handling const &cfg)¶
-
std::size_t
get_pu_step(util::command_line_handling const &cfg)¶
-
struct
command_line_handling¶ - #include <command_line_handling.hpp>
Public Members
-
hpx::program_options::variables_map
vm_¶
-
util::runtime_configuration
rtcfg_¶
-
util::function_nonser<int(hpx::program_options::variables_map &vm)>
hpx_main_f_¶
-
bool
use_process_mask_¶
-
bool
cmd_line_parsed_¶
-
bool
info_printed_¶
-
bool
version_printed_¶
-
int
parse_result_¶
Protected Functions
-
bool
handle_arguments(util::manage_config &cfgmap, hpx::program_options::variables_map &vm, std::vector<std::string> &ini_config, std::size_t &node, bool initial = false)¶
-
void
enable_logging_settings(hpx::program_options::variables_map &vm, std::vector<std::string> &ini_config)¶
-
void
store_command_line(int argc, char **argv)¶
-
void
store_unregistered_options(std::string const &cmd_name, std::vector<std::string> const &unregistered_options)¶
-
bool
handle_help_options(hpx::program_options::options_description const &help)¶
-
void
handle_attach_debugger()¶
-
hpx::program_options::variables_map
-
std::size_t
-
namespace
Header hpx/command_line_handling/parse_command_line.hpp¶
-
namespace
hpx -
namespace
util Enums
Functions
-
bool
parse_commandline(hpx::util::section const &rtcfg, hpx::program_options::options_description const &app_options, std::string const &cmdline, hpx::program_options::variables_map &vm, std::size_t node, int error_mode = return_on_error, hpx::runtime_mode mode = runtime_mode::default_, hpx::program_options::options_description *visible = nullptr, std::vector<std::string> *unregistered_options = nullptr)¶
-
bool
parse_commandline(hpx::util::section const &rtcfg, hpx::program_options::options_description const &app_options, std::string const &arg0, std::vector<std::string> const &args, hpx::program_options::variables_map &vm, std::size_t node, int error_mode = return_on_error, hpx::runtime_mode mode = runtime_mode::default_, hpx::program_options::options_description *visible = nullptr, std::vector<std::string> *unregistered_options = nullptr)¶
-
std::string
reconstruct_command_line(hpx::program_options::variables_map const &vm)¶
-
bool
-
namespace
components_base¶
The contents of this module can be included with the header
hpx/modules/components_base.hpp. These headers may be used by user-code but are not
guaranteed stable (neither header location nor contents). You are using these at
your own risk. If you wish to use non-public functionality from a module we
strongly suggest only including the module header hpx/modules/components_base.hpp, not
the particular header in which the functionality you would like to use is
defined. See Public API for a list of names that are part of the public
HPX API.
Header hpx/components_base/get_lva.hpp¶
-
template<typename
Component>
structget_lva<Component, typename std::enable_if<!traits::is_managed_component<Component>::value>::type>¶ - #include <get_lva.hpp>
Public Static Functions
-
static Component *
call(naming::address_type lva)¶
-
static Component *
-
template<typename
Component>
structget_lva<Component, typename std::enable_if<traits::is_managed_component<Component>::value && !std::is_const<Component>::value>::type>¶ - #include <get_lva.hpp>
Public Static Functions
-
static Component *
call(naming::address_type lva)
-
static Component *
-
template<typename
Component>
structget_lva<Component, typename std::enable_if<traits::is_managed_component<Component>::value && std::is_const<Component>::value>::type>¶ - #include <get_lva.hpp>
Public Static Functions
-
static Component *
call(naming::address_type lva)
-
static Component *
-
namespace
hpx -
template<typename
Component, typenameEnable= void>
structget_lva¶ - #include <get_lva.hpp>
The get_lva template is a helper structure allowing to convert a local virtual address as stored in a local address (returned from the function resolver_client::resolve) to the address of the component implementing the action.
The default implementation uses the template argument Component to deduce the type wrapping the component implementing the action. This is used to get the needed address.
- Template Parameters
Component: This is the type of the component implementing the action to execute.
-
template<typename
Component>
structget_lva<Component, typename std::enable_if<!traits::is_managed_component<Component>::value>::type> - #include <get_lva.hpp>
Public Static Functions
-
static Component *
call(naming::address_type lva)
-
static Component *
-
template<typename
Component>
structget_lva<Component, typename std::enable_if<traits::is_managed_component<Component>::value && !std::is_const<Component>::value>::type> - #include <get_lva.hpp>
Public Static Functions
-
static Component *
call(naming::address_type lva)
-
static Component *
-
template<typename
Component>
structget_lva<Component, typename std::enable_if<traits::is_managed_component<Component>::value && std::is_const<Component>::value>::type> - #include <get_lva.hpp>
Public Static Functions
-
static Component *
call(naming::address_type lva)
-
static Component *
-
template<typename
Header hpx/components_base/pinned_ptr.hpp¶
-
template<typename
Component>