API reference

template <typename Action>
struct async_result

#include <colocating_distribution_policy.hpp>

Note

This function is part of the invocation policy implemented by this class

Public Types

template<>
using type = hpx::future<typename traits::promise_local_result<typename hpx::traits::extract_action<Action>::remote_result_type>::type>

template <typename Action>
struct async_result

#include <default_distribution_policy.hpp>

Note

This function is part of the invocation policy implemented by this class

Public Types

template<>
using type = hpx::future<typename traits::promise_local_result<typename hpx::traits::extract_action<Action>::remote_result_type>::type>

struct auto_chunk_size

#include <auto_chunk_size.hpp>

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 parameters type makes sure that as many loop iterations are combined as necessary to run for the amount of time specified.

Public Functions

auto_chunk_size()

Construct an auto_chunk_size executor parameters object

Note

Default constructed auto_chunk_size executor parameter types will use 80 microseconds as the minimal time for which any of the scheduled chunks should run.

auto_chunk_size(hpx::util::steady_duration const &rel_time)

Construct an auto_chunk_size executor parameters object

Parameters

• rel_time: [in] The time duration to use as the minimum to decide how many loop iterations should be combined.

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 barrier
• num: 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 barrier
• num: The number of participating threads
• rank: 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).

hpx::future<void> wait(hpx::launch::async_policy)

Wait until each participant entered the barrier. Must be called by all participants

Return

a future that becomes ready 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.

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 represent
• perf_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 represent
• perf_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 represent
• perf_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 create
• vs: [in] The arguments which will be forwarded to the constructors of the new objects.

std::string const &get_counter_name() const

Returns the name of the performance counter associated with this policy instance.

std::size_t get_num_localities() const

Returns the number of associated localities for this distribution policy

Note

This function is part of the creation policy implemented by this class

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.

Public Types

using const_iterator = std::vector::const_iterator

Public Functions

checkpoint()

checkpoint(checkpoint const &c)

checkpoint(checkpoint &&c)

~checkpoint()

checkpoint(std::vector<char> const &vec)

checkpoint(std::vector<char> &&vec)

checkpoint &operator=(checkpoint const &c)

checkpoint &operator=(checkpoint &&c)

bool operator==(checkpoint const &c) const

bool operator!=(checkpoint const &c) const

const_iterator begin() const

const_iterator end() const

size_t size() const

Private Functions

template <typename Archive>
void serialize(Archive &arch, const unsigned int version)

Private Members

std::vector<char> data

Friends

friend hpx::util::checkpoint::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>
void restore_checkpoint(checkpoint const &c, T &t, Ts&... ts)

Resurrect

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).

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.

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, typename Stub>
colocating_distribution_policy operator()(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 create
• vs: [in] The arguments which will be forwarded to the constructors of the new objects.

template <typename Action, typename ... Ts>
async_result<Action>::type async(launch policy, Ts&&... vs) const

template <typename Action, typename Callback, typename ... Ts>
async_result<Action>::type async_cb(launch policy, Callback &&cb, Ts&&... vs) const

Note

This function is part of the invocation policy implemented by this class

template <typename Action, typename Continuation, typename ... Ts>
bool apply(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>
bool apply(threads::thread_priority priority, Ts&&... vs) const

template <typename Action, typename Continuation, typename Callback, typename ... Ts>
bool apply_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, typename Callback, typename ... Ts>
bool apply_cb(threads::thread_priority priority, Callback &&cb, Ts&&... vs) const

std::size_t get_num_localities() const

Returns the number of associated localities for this distribution policy

Note

This function is part of the creation policy implemented by this class

hpx::id_type get_next_target() const

Returns the locality which is anticipated to be used for the next async operation

class core

#include <partitioner.hpp>

Public Functions

core(std::size_t id = invalid_core_id, numa_domain *domain = nullptr)

std::vector<pu> const &pus() const

std::size_t id() const

Private Functions

std::vector<core> cores_sharing_numa_domain()

Private Members

std::size_t id_

numa_domain *domain_

std::vector<pu> pus_

Private Static Attributes

const std::size_t invalid_core_id = std::size_t(-1)

Friends

friend hpx::resource::core::pu

friend hpx::resource::core::numa_domain

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 create
• vs: [in] The arguments which will be forwarded to the constructors of the new objects.

template <typename Action, typename ... Ts>
async_result<Action>::type async(launch policy, Ts&&... vs) const

template <typename Action, typename Callback, typename ... Ts>
async_result<Action>::type async_cb(launch policy, Callback &&cb, Ts&&... vs) const

Note

This function is part of the invocation policy implemented by this class

template <typename Action, typename Continuation, typename ... Ts>
bool apply(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>
bool apply(threads::thread_priority priority, Ts&&... vs) const

template <typename Action, typename Continuation, typename Callback, typename ... Ts>
bool apply_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, typename Callback, typename ... Ts>
bool apply_cb(threads::thread_priority priority, Callback &&cb, Ts&&... vs) const

std::size_t get_num_localities() const

Returns the number of associated localities for this distribution policy

Note

This function is part of the creation policy implemented by this class

hpx::id_type get_next_target() const

Returns the locality which is anticipated to be used for the next async operation

struct dynamic_chunk_size

#include <dynamic_chunk_size.hpp>

Loop iterations are divided into pieces of size chunk_size and then dynamically scheduled among the threads; when a thread finishes one chunk, it is dynamically assigned another If chunk_size is not specified, the default chunk size is 1.

Note

This executor parameters type is equivalent to OpenMP’s DYNAMIC scheduling directive.

Public Functions

dynamic_chunk_size(std::size_t chunk_size = 1)

Construct a dynamic_chunk_size executor parameters object

Parameters

• chunk_size: [in] The optional chunk size to use as the number of loop iterations to schedule together. The default chunk size is 1.

class error_code : public error_code

#include <error_code.hpp>

A hpx::error_code represents an arbitrary error condition.

The class hpx::error_code describes an object used to hold error code values, such as those originating from the operating system or other low-level application program interfaces.

Note

Class hpx::error_code is an adjunct to error reporting by exception

Public Functions

error_code(throwmode mode = plain)

Construct an object of type error_code.

Parameters

• mode: The parameter mode specifies whether the constructed hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

Exceptions

• nothing:

error_code(error e, throwmode mode = plain)

Construct an object of type error_code.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• mode: The parameter mode specifies whether the constructed hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

Exceptions

• nothing:

error_code(error e, char const *func, char const *file, long line, throwmode mode = plain)

Construct an object of type error_code.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• func: The name of the function where the error was raised.
• file: The file name of the code where the error was raised.
• line: The line number of the code line where the error was raised.
• mode: The parameter mode specifies whether the constructed hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

Exceptions

• nothing:

error_code(error e, char const *msg, throwmode mode = plain)

Construct an object of type error_code.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• msg: The parameter msg holds the error message the new exception should encapsulate.
• mode: The parameter mode specifies whether the constructed hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

error_code(error e, char const *msg, char const *func, char const *file, long line, throwmode mode = plain)

Construct an object of type error_code.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• msg: The parameter msg holds the error message the new exception should encapsulate.
• func: The name of the function where the error was raised.
• file: The file name of the code where the error was raised.
• line: The line number of the code line where the error was raised.
• mode: The parameter mode specifies whether the constructed hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

error_code(error e, std::string const &msg, throwmode mode = plain)

Construct an object of type error_code.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• msg: The parameter msg holds the error message the new exception should encapsulate.
• mode: The parameter mode specifies whether the constructed hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

error_code(error e, std::string const &msg, char const *func, char const *file, long line, throwmode mode = plain)

Construct an object of type error_code.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• msg: The parameter msg holds the error message the new exception should encapsulate.
• func: The name of the function where the error was raised.
• file: The file name of the code where the error was raised.
• line: The line number of the code line where the error was raised.
• mode: The parameter mode specifies whether the constructed hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

std::string get_message() const

Return a reference to the error message stored in the hpx::error_code.

Exceptions

• nothing:

void clear()

Clear this error_code object. The postconditions of invoking this method are.

• value() == hpx::success and category() == hpx::get_hpx_category()

error_code(error_code const &rhs)

Copy constructor for error_code

Note

This function maintains the error category of the left hand side if the right hand side is a success code.

error_code &operator=(error_code const &rhs)

Assignment operator for error_code

Note

This function maintains the error category of the left hand side if the right hand side is a success code.

Private Functions

error_code(int err, hpx::exception const &e)

error_code(std::exception_ptr const &e)

Private Members

std::exception_ptr exception_

Friends

friend hpx::error_code::exception

error_code make_error_code(std::exception_ptr const &e)

class exception : public system_error

#include <exception.hpp>

A hpx::exception is the main exception type used by HPX to report errors.

The hpx::exception type is the main exception type used by HPX to report errors. Any exceptions thrown by functions in the HPX library are either of this type or of a type derived from it. This implies that it is always safe to use this type only in catch statements guarding HPX library calls.

Subclassed by hpx::exception_list, hpx::parallel::v2::task_canceled_exception

Public Functions

exception(error e = success)

Construct a hpx::exception from a hpx::error.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.

exception(boost::system::system_error const &e)

Construct a hpx::exception from a boost::system_error.

exception(boost::system::error_code const &e)

Construct a hpx::exception from a boost::system::error_code (this is new for Boost V1.69). This constructor is required to compensate for the changes introduced as a resolution to LWG3162 (https://cplusplus.github.io/LWG/issue3162).

exception(error e, char const *msg, throwmode mode = plain)

Construct a hpx::exception from a hpx::error and an error message.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• msg: The parameter msg holds the error message the new exception should encapsulate.
• mode: The parameter mode specifies whether the returned hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

exception(error e, std::string const &msg, throwmode mode = plain)

Construct a hpx::exception from a hpx::error and an error message.

Parameters

• e: The parameter e holds the hpx::error code the new exception should encapsulate.
• msg: The parameter msg holds the error message the new exception should encapsulate.
• mode: The parameter mode specifies whether the returned hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

~exception()

Destruct a hpx::exception

Exceptions

• nothing:

error get_error() const

The function get_error() returns the hpx::error code stored in the referenced instance of a hpx::exception. It returns the hpx::error code this exception instance was constructed from.

Exceptions

• nothing:

error_code get_error_code(throwmode mode = plain) const

The function get_error_code() returns a hpx::error_code which represents the same error condition as this hpx::exception instance.

Parameters

• mode: The parameter mode specifies whether the returned hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

class exception_list : public hpx::exception

#include <exception_list.hpp>

The class exception_list is a container of exception_ptr objects parallel algorithms may use to communicate uncaught exceptions encountered during parallel execution to the caller of the algorithm

The type exception_list::const_iterator fulfills the requirements of a forward iterator.

Public Types

typedef exception_list_type::const_iterator iterator

bidirectional iterator

Public Functions

std::size_t size() const

The number of exception_ptr objects contained within the exception_list.

Note

Complexity: Constant time.

exception_list_type::const_iterator begin() const

An iterator referring to the first exception_ptr object contained within the exception_list.

exception_list_type::const_iterator end() const

An iterator which is the past-the-end value for the exception_list.

Private Types

typedef hpx::lcos::local::spinlock mutex_type

typedef std::list<std::exception_ptr> exception_list_type

Private Members

exception_list_type exceptions_

mutex_type mtx_

struct guided_chunk_size

#include <guided_chunk_size.hpp>

Iterations are dynamically assigned to threads in blocks as threads request them until no blocks remain to be assigned. Similar to dynamic_chunk_size except 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 to number_of_iterations / number_of_cores. Subsequent blocks are proportional to number_of_iterations_remaining / number_of_cores. The optional chunk size parameter defines the minimum block size. The default chunk size is 1.

Note

This executor parameters type is equivalent to OpenMP’s GUIDED scheduling directive.

Public Functions

guided_chunk_size(std::size_t min_chunk_size = 1)

Construct a guided_chunk_size executor parameters object

Parameters

• min_chunk_size: [in] The optional minimal chunk size to use as the minimal number of loop iterations to schedule together. The default minimal chunk size is 1.

template <typename T>
struct is_async_execution_policy : public execution::detail::is_async_execution_policy<hpx::util::decay<T>::type>

#include <is_execution_policy.hpp>

Extension: Detect whether given execution policy makes algorithms asynchronous

1. The type is_async_execution_policy can be used to detect asynchronous execution policies for the purpose of excluding function signatures from otherwise ambiguous overload resolution participation.
2. If T is the type of a standard or implementation-defined execution policy, is_async_execution_policy<T> shall be publicly derived from integral_constant<bool, true>, otherwise from integral_constant<bool, false>.
3. The behavior of a program that adds specializations for is_async_execution_policy is undefined.

template <typename T>
struct is_execution_policy : public execution::detail::is_execution_policy<hpx::util::decay<T>::type>

#include <is_execution_policy.hpp>

1. The type is_execution_policy can be used to detect execution policies for the purpose of excluding function signatures from otherwise ambiguous overload resolution participation.
2. If T is the type of a standard or implementation-defined execution policy, is_execution_policy<T> shall be publicly derived from integral_constant<bool, true>, otherwise from integral_constant<bool, false>.
3. The behavior of a program that adds specializations for is_execution_policy is undefined.

template <typename T>
struct is_parallel_execution_policy : public execution::detail::is_parallel_execution_policy<hpx::util::decay<T>::type>

#include <is_execution_policy.hpp>

Extension: Detect whether given execution policy enables parallelization

1. The type is_parallel_execution_policy can be used to detect parallel execution policies for the purpose of excluding function signatures from otherwise ambiguous overload resolution participation.
2. If T is the type of a standard or implementation-defined execution policy, is_parallel_execution_policy<T> shall be publicly derived from integral_constant<bool, true>, otherwise from integral_constant<bool, false>.
3. The behavior of a program that adds specializations for is_parallel_execution_policy is undefined.

template <typename T>
struct is_sequenced_execution_policy : public execution::detail::is_sequenced_execution_policy<hpx::util::decay<T>::type>

#include <is_execution_policy.hpp>

Extension: Detect whether given execution policy does not enable parallelization

1. The type is_sequenced_execution_policy can be used to detect non-parallel execution policies for the purpose of excluding function signatures from otherwise ambiguous overload resolution participation.
2. If T is the type of a standard or implementation-defined execution policy, is_sequenced_execution_policy<T> shall be publicly derived from integral_constant<bool, true>, otherwise from integral_constant<bool, false>.
3. The behavior of a program that adds specializations for is_sequenced_execution_policy is undefined.

struct launch : public detail::policy_holder<>

#include <launch_policy.hpp>

Launch policies for hpx::async etc.

Public Functions

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.

class numa_domain

#include <partitioner.hpp>

Public Functions

numa_domain(std::size_t id = invalid_numa_domain_id)

std::vector<core> const &cores() const

std::size_t id() const

Private Members

std::size_t id_

std::vector<core> cores_

Private Static Attributes

const std::size_t invalid_numa_domain_id

=

std::size_t(-1)

Friends

friend hpx::resource::numa_domain::pu

friend hpx::resource::numa_domain::core

struct parallel_execution_tag

#include <execution_fwd.hpp>

Function invocations executed by a group of parallel execution agents execute in unordered fashion. Any such invocations executing in the same thread are indeterminately sequenced with respect to each other.

Note

parallel_execution_tag is weaker than sequenced_execution_tag.

struct parallel_policy

#include <execution_policy.hpp>

The class parallel_policy is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be parallelized.

Subclassed by hpx::parallel::execution::parallel_policy_shim< Executor, Parameters >

Public Types

typedef parallel_executor executor_type

The type of the executor associated with this execution policy.

typedef execution::extract_executor_parameters<executor_type>::type executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef parallel_execution_tag execution_category

The category of the execution agents created by this execution policy.

Public Functions

parallel_task_policy operator()(task_policy_tag) const

Create a new parallel_policy referencing a chunk size.

Return

The new parallel_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor>
rebind_executor<parallel_policy, Executor, executor_parameters_type>::type on(Executor &&exec) const

Create a new parallel_policy referencing an executor and a chunk size.

Return

The new parallel_policy

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with

template <typename... Parameters, typename ParametersType = typename executor_parameters_join<Parameters...>::type>
rebind_executor<parallel_policy, executor_type, ParametersType>::type with(Parameters&&... params) const

Create a new parallel_policy from the given execution parameters

Note

Requires: is_executor_parameters<Parameters>::value is true

Return

The new parallel_policy

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

executor_type &executor()

Return the associated executor object.

executor_type const &executor() const

Return the associated executor object.

executor_parameters_type &parameters()

Return the associated executor parameters object.

executor_parameters_type const &parameters() const

Return the associated executor parameters object.

Private Functions

template <typename Archive>
void serialize(Archive &ar, const unsigned int version)

Private Members

executor_type exec_

executor_parameters_type params_

Friends

friend hpx::parallel::execution::parallel_policy::hpx::serialization::access

template <typename Policy>
struct parallel_policy_executor

#include <parallel_executor.hpp>

A parallel_executor creates groups of parallel execution agents which execute in threads implicitly created by the executor. This executor prefers continuing with the creating thread first before executing newly created threads.

This executor conforms to the concepts of a TwoWayExecutor, and a BulkTwoWayExecutor

Public Types

typedef parallel_execution_tag execution_category

Associate the parallel_execution_tag executor tag type as a default with this executor.

typedef static_chunk_size executor_parameters_type

Associate the static_chunk_size executor parameters type as a default with this executor.

Public Functions

parallel_policy_executor(Policy l = detail::get_default_policy<Policy>::call(), std::size_t spread = 4, std::size_t tasks = std::size_t(-1))

Create a new parallel executor.

template <typename Executor, typename Parameters>
struct parallel_policy_shim : public hpx::parallel::execution::parallel_policy

#include <execution_policy.hpp>

The class parallel_policy_shim is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be parallelized.

Public Types

typedef Executor executor_type

The type of the executor associated with this execution policy.

typedef Parameters executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef hpx::traits::executor_execution_category<executor_type>::type execution_category

The category of the execution agents created by this execution policy.

Public Functions

parallel_task_policy_shim<Executor, Parameters> operator()(task_policy_tag tag) const

Create a new parallel_policy referencing a chunk size.

Return

The new parallel_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor_>
rebind_executor<parallel_policy_shim, Executor_, executor_parameters_type>::type on(Executor_ &&exec) const

Create a new parallel_policy from the given executor

Note

Requires: is_executor<Executor>::value is true

Return

The new parallel_policy

Template Parameters

• Executor: The type of the executor to associate with this execution policy.

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with.

template <typename... Parameters_, typename ParametersType = typename executor_parameters_join<Parameters_...>::type>
rebind_executor<parallel_policy_shim, executor_type, ParametersType>::type with(Parameters_&&... params) const

Create a new parallel_policy_shim from the given execution parameters

Note

Requires: is_executor_parameters<Parameters>::value is true

Return

The new parallel_policy_shim

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

Executor &executor()

Return the associated executor object.

Executor const &executor() const

Return the associated executor object.

Parameters &parameters()

Return the associated executor parameters object.

Parameters const &parameters() const

Return the associated executor parameters object.

struct parallel_task_policy

#include <execution_policy.hpp>

Extension: The class parallel_task_policy is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be parallelized.

The algorithm returns a future representing the result of the corresponding algorithm when invoked with the parallel_policy.

Subclassed by hpx::parallel::execution::parallel_task_policy_shim< Executor, Parameters >

Public Types

typedef parallel_executor executor_type

The type of the executor associated with this execution policy.

typedef execution::extract_executor_parameters<executor_type>::type executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef parallel_execution_tag execution_category

The category of the execution agents created by this execution policy.

Public Functions

parallel_task_policy operator()(task_policy_tag) const

Create a new parallel_task_policy from itself

Return

The new parallel_task_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor>
rebind_executor<parallel_task_policy, Executor, executor_parameters_type>::type on(Executor &&exec) const

Create a new parallel_task_policy from given executor

Note

Requires: is_executor<Executor>::value is true

Return

The new parallel_task_policy

Template Parameters

• Executor: The type of the executor to associate with this execution policy.

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with.

template <typename... Parameters, typename ParametersType = typename executor_parameters_join<Parameters...>::type>
rebind_executor<parallel_task_policy, executor_type, ParametersType>::type with(Parameters&&... params) const

Create a new parallel_policy_shim from the given execution parameters

Note

Requires: all parameters are executor_parameters, different parameter types can’t be duplicated

Return

The new parallel_policy_shim

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

executor_type &executor()

Return the associated executor object.

executor_type const &executor() const

Return the associated executor object.

executor_parameters_type &parameters()

Return the associated executor parameters object.

executor_parameters_type const &parameters() const

Return the associated executor parameters object.

Private Functions

template <typename Archive>
void serialize(Archive &ar, const unsigned int version)

Private Members

executor_type exec_

executor_parameters_type params_

Friends

friend hpx::parallel::execution::parallel_task_policy::hpx::serialization::access

template <typename Executor, typename Parameters>
struct parallel_task_policy_shim : public hpx::parallel::execution::parallel_task_policy

#include <execution_policy.hpp>

Extension: The class parallel_task_policy_shim is an execution policy type used as a unique type to disambiguate parallel algorithm overloading based on combining a underlying parallel_task_policy and an executor and indicate that a parallel algorithm’s execution may be parallelized.

Public Types

typedef Executor executor_type

The type of the executor associated with this execution policy.

typedef Parameters executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef hpx::traits::executor_execution_category<executor_type>::type execution_category

The category of the execution agents created by this execution policy.

Public Functions

parallel_task_policy_shim operator()(task_policy_tag tag) const

Create a new parallel_task_policy_shim from itself

Return

The new sequenced_task_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor_>
rebind_executor<parallel_task_policy_shim, Executor_, executor_parameters_type>::type on(Executor_ &&exec) const

Create a new parallel_task_policy from the given executor

Note

Requires: is_executor<Executor>::value is true

Return

The new parallel_task_policy

Template Parameters

• Executor: The type of the executor to associate with this execution policy.

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with.

template <typename... Parameters_, typename ParametersType = typename executor_parameters_join<Parameters_...>::type>
rebind_executor<parallel_task_policy_shim, executor_type, ParametersType>::type with(Parameters_&&... params) const

Create a new parallel_policy_shim from the given execution parameters

Note

Requires: all parameters are executor_parameters, different parameter types can’t be duplicated

Return

The new parallel_policy_shim

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

Executor &executor()

Return the associated executor object.

Executor const &executor() const

Return the associated executor object.

Parameters &parameters()

Return the associated executor parameters object.

Parameters const &parameters() const

Return the associated executor parameters object.

struct parallel_unsequenced_policy

#include <execution_policy.hpp>

The class parallel_unsequenced_policy is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be vectorized.

Public Types

typedef parallel_executor executor_type

The type of the executor associated with this execution policy.

typedef execution::extract_executor_parameters<executor_type>::type executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef parallel_execution_tag execution_category

The category of the execution agents created by this execution policy.

Public Functions

parallel_unsequenced_policy operator()(task_policy_tag) const

Create a new parallel_unsequenced_policy from itself

Return

The new parallel_unsequenced_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

executor_type &executor()

Return the associated executor object.

executor_type const &executor() const

Return the associated executor object.

executor_parameters_type &parameters()

Return the associated executor parameters object.

executor_parameters_type const &parameters() const

Return the associated executor parameters object.

Private Functions

template <typename Archive>
void serialize(Archive &ar, const unsigned int version)

Private Members

executor_type exec_

executor_parameters_type params_

Friends

friend hpx::parallel::execution::parallel_unsequenced_policy::hpx::serialization::access

class partitioner

#include <partitioner.hpp>

Public Functions

partitioner(util::function_nonser<int(boost::program_options::variables_map &vm)> const &f, boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> ini_config, resource::partitioner_mode rpmode = resource::mode_default, runtime_mode mode = runtime_mode_default, )

partitioner(util::function_nonser<int(int, char **)> const &f, int argc, char **argv, resource::partitioner_mode rpmode = resource::mode_default, hpx::runtime_mode mode = hpx::runtime_mode_default, )

partitioner(util::function_nonser<int(int, char **)> const &f, int argc, char **argv, std::vector<std::string> const &cfg, resource::partitioner_mode rpmode = resource::mode_default, hpx::runtime_mode mode = hpx::runtime_mode_default, )

partitioner(int argc, char **argv, resource::partitioner_mode rpmode = resource::mode_default, runtime_mode mode = runtime_mode_default)

partitioner(int argc, char **argv, std::vector<std::string> ini_config, resource::partitioner_mode rpmode = resource::mode_default, runtime_mode mode = runtime_mode_default)

partitioner(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, resource::partitioner_mode rpmode = resource::mode_default, runtime_mode mode = runtime_mode_default)

partitioner(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> ini_config, resource::partitioner_mode rpmode = resource::mode_default, runtime_mode mode = runtime_mode_default)

partitioner(std::nullptr_t f, int argc, char **argv, resource::partitioner_mode rpmode = resource::mode_default, hpx::runtime_mode mode = hpx::runtime_mode_default)

partitioner(std::nullptr_t f, int argc, char **argv, std::vector<std::string> const &cfg, resource::partitioner_mode rpmode = resource::mode_default, hpx::runtime_mode mode = hpx::runtime_mode_default)

partitioner(std::nullptr_t f, boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> ini_config, resource::partitioner_mode rpmode = resource::mode_default, runtime_mode mode = runtime_mode_default)

void create_thread_pool(std::string const &name, scheduling_policy sched = scheduling_policy::unspecified, hpx::threads::policies::scheduler_mode = hpx::threads::policies::scheduler_mode::default_mode)

void create_thread_pool(std::string const &name, scheduler_function scheduler_creation)

void set_default_pool_name(std::string const &name)

const std::string &get_default_pool_name() const

void add_resource(hpx::resource::pu const &p, std::string const &pool_name, std::size_t num_threads = 1)

void add_resource(hpx::resource::pu const &p, std::string const &pool_name, bool exclusive, std::size_t num_threads = 1)

void add_resource(std::vector<hpx::resource::pu> const &pv, std::string const &pool_name, bool exclusive = true)

void add_resource(hpx::resource::core const &c, std::string const &pool_name, bool exclusive = true)

void add_resource(std::vector<hpx::resource::core> &cv, std::string const &pool_name, bool exclusive = true)

void add_resource(hpx::resource::numa_domain const &nd, std::string const &pool_name, bool exclusive = true)

void add_resource(std::vector<hpx::resource::numa_domain> const &ndv, std::string const &pool_name, bool exclusive = true)

std::vector<numa_domain> const &numa_domains() const

Private Members

detail::partitioner &partitioner_

struct persistent_auto_chunk_size

#include <persistent_auto_chunk_size.hpp>

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 parameters type makes sure that as many loop iterations are combined as necessary to run for the amount of time specified.

Public Functions

persistent_auto_chunk_size()

Construct an persistent_auto_chunk_size executor parameters object

Note

Default constructed persistent_auto_chunk_size executor parameter types will use 0 microseconds as the execution time for each chunk and 80 microseconds as the minimal time for which any of the scheduled chunks should run.

persistent_auto_chunk_size(hpx::util::steady_duration const &time_cs)

Construct an persistent_auto_chunk_size executor parameters object

Parameters

• time_cs: The execution time for each chunk.

persistent_auto_chunk_size(hpx::util::steady_duration const &time_cs, hpx::util::steady_duration const &rel_time)

Construct an persistent_auto_chunk_size executor parameters object

Parameters

• rel_time: [in] The time duration to use as the minimum to decide how many loop iterations should be combined.
• time_cs: The execution time for each chunk.

class pu

#include <partitioner.hpp>

Public Functions

pu(std::size_t id = invalid_pu_id, core *core = nullptr, std::size_t thread_occupancy = 0)

std::size_t id() const

Private Functions

std::vector<pu> pus_sharing_core()

std::vector<pu> pus_sharing_numa_domain()

Private Members

std::size_t id_

core *core_

std::size_t thread_occupancy_

std::size_t thread_occupancy_count_

Private Static Attributes

const std::size_t invalid_pu_id = std::size_t(-1)

Friends

friend hpx::resource::pu::core

friend hpx::resource::pu::numa_domain

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

template<>
typedef parallel_task_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

template<>
typedef sequenced_task_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

typedef parallel_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

typedef sequenced_task_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

typedef sequenced_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

template<>
typedef parallel_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

template<>
typedef sequenced_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

template <typename Executor_, typename Parameters_>
struct rebind

#include <execution_policy.hpp>

Rebind the type of executor used by this execution policy. The execution category of Executor shall not be weaker than that of this execution policy

Public Types

typedef parallel_task_policy_shim<Executor_, Parameters_> type

The type of the rebound execution policy.

struct sequenced_execution_tag

#include <execution_fwd.hpp>

Function invocations executed by a group of sequential execution agents execute in sequential order.

struct sequenced_executor

#include <sequenced_executor.hpp>

A sequential_executor creates groups of sequential execution agents which execute in the calling thread. The sequential order is given by the lexicographical order of indices in the index space.

struct sequenced_policy

#include <execution_policy.hpp>

The class sequenced_policy is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and require that a parallel algorithm’s execution may not be parallelized.

Subclassed by hpx::parallel::execution::sequenced_policy_shim< Executor, Parameters >

Public Types

typedef sequenced_executor executor_type

The type of the executor associated with this execution policy.

typedef execution::extract_executor_parameters<executor_type>::type executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef sequenced_execution_tag execution_category

The category of the execution agents created by this execution policy.

Public Functions

sequenced_task_policy operator()(task_policy_tag) const

Create a new sequenced_task_policy.

Return

The new sequenced_task_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor>
rebind_executor<sequenced_policy, Executor, executor_parameters_type>::type on(Executor &&exec) const

Create a new sequenced_policy from the given executor

Note

Requires: is_executor<Executor>::value is true

Return

The new sequenced_policy

Template Parameters

• Executor: The type of the executor to associate with this execution policy.

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with.

template <typename... Parameters, typename ParametersType = typename executor_parameters_join<Parameters...>::type>
rebind_executor<sequenced_policy, executor_type, ParametersType>::type with(Parameters&&... params) const

Create a new sequenced_policy from the given execution parameters

Note

Requires: all parameters are executor_parameters, different parameter types can’t be duplicated

Return

The new sequenced_policy

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

executor_type &executor()

Return the associated executor object. Return the associated executor object.

executor_type const &executor() const

Return the associated executor object.

executor_parameters_type &parameters()

Return the associated executor parameters object.

executor_parameters_type const &parameters() const

Return the associated executor parameters object.

Private Functions

template <typename Archive>
void serialize(Archive &ar, const unsigned int version)

Private Members

executor_type exec_

executor_parameters_type params_

Friends

friend hpx::parallel::execution::sequenced_policy::hpx::serialization::access

template <typename Executor, typename Parameters>
struct sequenced_policy_shim : public hpx::parallel::execution::sequenced_policy

#include <execution_policy.hpp>

The class sequenced_policy is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and require that a parallel algorithm’s execution may not be parallelized.

Public Types

typedef Executor executor_type

The type of the executor associated with this execution policy.

typedef Parameters executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef hpx::traits::executor_execution_category<executor_type>::type execution_category

The category of the execution agents created by this execution policy.

Public Functions

sequenced_task_policy_shim<Executor, Parameters> operator()(task_policy_tag tag) const

Create a new sequenced_task_policy.

Return

The new sequenced_task_policy_shim

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor_>
rebind_executor<sequenced_policy_shim, Executor_, executor_parameters_type>::type on(Executor_ &&exec) const

Create a new sequenced_policy from the given executor

Note

Requires: is_executor<Executor>::value is true

Return

The new sequenced_policy

Template Parameters

• Executor: The type of the executor to associate with this execution policy.

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with.

template <typename... Parameters_, typename ParametersType = typename executor_parameters_join<Parameters_...>::type>
rebind_executor<sequenced_policy_shim, executor_type, ParametersType>::type with(Parameters_&&... params) const

Create a new sequenced_policy_shim from the given execution parameters

Note

Requires: all parameters are executor_parameters, different parameter types can’t be duplicated

Return

The new sequenced_policy_shim

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

Executor &executor()

Return the associated executor object.

Executor const &executor() const

Return the associated executor object.

Parameters &parameters()

Return the associated executor parameters object.

Parameters const &parameters() const

Return the associated executor parameters object.

struct sequenced_task_policy

#include <execution_policy.hpp>

Extension: The class sequenced_task_policy is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may not be parallelized (has to run sequentially).

The algorithm returns a future representing the result of the corresponding algorithm when invoked with the sequenced_policy.

Subclassed by hpx::parallel::execution::sequenced_task_policy_shim< Executor, Parameters >

Public Types

typedef sequenced_executor executor_type

The type of the executor associated with this execution policy.

typedef execution::extract_executor_parameters<executor_type>::type executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef sequenced_execution_tag execution_category

The category of the execution agents created by this execution policy.

Public Functions

sequenced_task_policy operator()(task_policy_tag) const

Create a new sequenced_task_policy from itself

Return

The new sequenced_task_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor>
rebind_executor<sequenced_task_policy, Executor, executor_parameters_type>::type on(Executor &&exec) const

Create a new sequenced_task_policy from the given executor

Note

Requires: is_executor<Executor>::value is true

Return

The new sequenced_task_policy

Template Parameters

• Executor: The type of the executor to associate with this execution policy.

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with.

template <typename... Parameters, typename ParametersType = typename executor_parameters_join<Parameters...>::type>
rebind_executor<sequenced_task_policy, executor_type, ParametersType>::type with(Parameters&&... params) const

Create a new sequenced_task_policy from the given execution parameters

Note

Requires: all parameters are executor_parameters, different parameter types can’t be duplicated

Return

The new sequenced_task_policy

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

executor_type &executor()

Return the associated executor object.

executor_type const &executor() const

Return the associated executor object.

executor_parameters_type &parameters()

Return the associated executor parameters object.

executor_parameters_type const &parameters() const

Return the associated executor parameters object.

Private Functions

template <typename Archive>
void serialize(Archive &ar, const unsigned int version)

Private Members

executor_type exec_

executor_parameters_type params_

Friends

friend hpx::parallel::execution::sequenced_task_policy::hpx::serialization::access

template <typename Executor, typename Parameters>
struct sequenced_task_policy_shim : public hpx::parallel::execution::sequenced_task_policy

#include <execution_policy.hpp>

Extension: The class sequenced_task_policy_shim is an execution policy type used as a unique type to disambiguate parallel algorithm overloading based on combining a underlying sequenced_task_policy and an executor and indicate that a parallel algorithm’s execution may not be parallelized (has to run sequentially).

The algorithm returns a future representing the result of the corresponding algorithm when invoked with the sequenced_policy.

Public Types

typedef Executor executor_type

The type of the executor associated with this execution policy.

typedef Parameters executor_parameters_type

The type of the associated executor parameters object which is associated with this execution policy

typedef hpx::traits::executor_execution_category<executor_type>::type execution_category

The category of the execution agents created by this execution policy.

Public Functions

sequenced_task_policy_shim const &operator()(task_policy_tag tag) const

Create a new sequenced_task_policy from itself

Return

The new sequenced_task_policy

Parameters

• tag: [in] Specify that the corresponding asynchronous execution policy should be used

template <typename Executor_>
rebind_executor<sequenced_task_policy_shim, Executor_, executor_parameters_type>::type on(Executor_ &&exec) const

Create a new sequenced_task_policy from the given executor

Note

Requires: is_executor<Executor>::value is true

Return

The new sequenced_task_policy

Template Parameters

• Executor: The type of the executor to associate with this execution policy.

Parameters

• exec: [in] The executor to use for the execution of the parallel algorithm the returned execution policy is used with.

template <typename... Parameters_, typename ParametersType = typename executor_parameters_join<Parameters_...>::type>
rebind_executor<sequenced_task_policy_shim, executor_type, ParametersType>::type with(Parameters_&&... params) const

Create a new sequenced_task_policy_shim from the given execution parameters

Note

Requires: all parameters are executor_parameters, different parameter types can’t be duplicated

Return

The new sequenced_task_policy_shim

Template Parameters

• Parameters: The type of the executor parameters to associate with this execution policy.

Parameters

• params: [in] The executor parameters to use for the execution of the parallel algorithm the returned execution policy is used with.

Executor &executor()

Return the associated executor object.

Executor const &executor() const

Return the associated executor object.

Parameters &parameters()

Return the associated executor parameters object.

Parameters const &parameters() const

Return the associated executor parameters object.

struct static_chunk_size

#include <static_chunk_size.hpp>

Loop iterations are divided into pieces of size chunk_size and then assigned to threads. If chunk_size is not specified, the iterations are evenly (if possible) divided contiguously among the threads.

Note

This executor parameters type is equivalent to OpenMP’s STATIC scheduling directive.

Public Functions

static_chunk_size()

Construct a static_chunk_size executor parameters object

Note

By default the number of loop iterations is determined from the number of available cores and the overall number of loop iterations to schedule.

static_chunk_size(std::size_t chunk_size)

Construct a static_chunk_size executor parameters object

Parameters

• chunk_size: [in] The optional chunk size to use as the number of loop iterations to run on a single thread.

template <typename ExPolicy = parallel::execution::parallel_policy>
class task_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.

A task_block

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>
void run(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, typename F, typename ... Ts>
void run(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.

Private Members

mutex_type mtx_

std::vector<hpx::future<void>> tasks_

parallel::exception_list errors_

threads::thread_id_type id_

ExPolicy policy_

class task_canceled_exception : public hpx::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()

struct thread_interrupted : public exception

#include <exception.hpp>

A hpx::thread_interrupted is the exception type used by HPX to interrupt a running HPX thread.

The hpx::thread_interrupted type is the exception type used by HPX to interrupt a running thread.

A running thread can be interrupted by invoking the interrupt() member function of the corresponding hpx::thread object. When the interrupted thread next executes one of the specified interruption points (or if it is currently blocked whilst executing one) with interruption enabled, then a hpx::thread_interrupted exception will be thrown in the interrupted thread. If not caught, this will cause the execution of the interrupted thread to terminate. As with any other exception, the stack will be unwound, and destructors for objects of automatic storage duration will be executed.

If a thread wishes to avoid being interrupted, it can create an instance of hpx::this_thread::disable_interruption. Objects of this class disable interruption for the thread that created them on construction, and restore the interruption state to whatever it was before on destruction.

void f()
{
    // interruption enabled here
    {
        hpx::this_thread::disable_interruption di;
        // interruption disabled
        {
            hpx::this_thread::disable_interruption di2;
            // interruption still disabled
        } // di2 destroyed, interruption state restored
        // interruption still disabled
    } // di destroyed, interruption state restored
    // interruption now enabled
}

The effects of an instance of hpx::this_thread::disable_interruption can be temporarily reversed by constructing an instance of hpx::this_thread::restore_interruption, passing in the hpx::this_thread::disable_interruption object in question. This will restore the interruption state to what it was when the hpx::this_thread::disable_interruption object was constructed, and then disable interruption again when the hpx::this_thread::restore_interruption object is destroyed.

void g()
{
    // interruption enabled here
    {
        hpx::this_thread::disable_interruption di;
        // interruption disabled
        {
            hpx::this_thread::restore_interruption ri(di);
            // interruption now enabled
        } // ri destroyed, interruption disable again
    } // di destroyed, interruption state restored
    // interruption now enabled
}

At any point, the interruption state for the current thread can be queried by calling hpx::this_thread::interruption_enabled().

class thread_pool_base : public manage_executor

#include <thread_pool_base.hpp>

The base class used to manage a pool of OS threads.

Public Functions

virtual hpx::future<void> resume() = 0

Resumes the thread pool. When the all OS threads on the thread pool have been resumed the returned future will be ready.

Note

Can only be called from an HPX thread. Use resume_cb or resume_direct to suspend the pool from outside HPX.

Return

A future<void> which is ready when the thread pool has been resumed.

Exceptions

• hpx::exception: if called from outside the HPX runtime.

virtual void resume_cb(std::function<void(void)> callback, error_code &ec = throws, ) = 0

Resumes the thread pool. Takes a callback as a parameter which will be called when all OS threads on the thread pool have been resumed.

Parameters

• callback: [in] called when the thread pool has been resumed.
• 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.

virtual void resume_direct(error_code &ec = throws) = 0

Resumes the thread pool. Blocks until all OS threads on the thread pool have been resumed.

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.

virtual hpx::future<void> suspend() = 0

Suspends the thread pool. When the all OS threads on the thread pool have been suspended the returned future will be ready.

Note

Can only be called from an HPX thread. Use suspend_cb or suspend_direct to suspend the pool from outside HPX. A thread pool cannot be suspended from an HPX thread running on the pool itself.

Return

A future<void> which is ready when the thread pool has been suspended.

Exceptions

• hpx::exception: if called from outside the HPX runtime.

virtual void suspend_cb(std::function<void(void)> callback, error_code &ec = throws, ) = 0

Suspends the thread pool. Takes a callback as a parameter which will be called when all OS threads on the thread pool have been suspended.

Note

A thread pool cannot be suspended from an HPX thread running on the pool itself.

Parameters

• callback: [in] called when the thread pool has been suspended.
• 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.

Exceptions

• hpx::exception: if called from an HPX thread which is running on the pool itself.

virtual void suspend_direct(error_code &ec = throws) = 0

Suspends the thread pool. Blocks until all OS threads on the thread pool have been suspended.

Note

A thread pool cannot be suspended from an HPX thread running on the pool itself.

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.

Exceptions

• hpx::exception: if called from an HPX thread which is running on the pool itself.

virtual hpx::future<void> suspend_processing_unit(std::size_t virt_core) = 0

Suspends the given processing unit. When the processing unit has been suspended the returned future will be ready.

Note

Can only be called from an HPX thread. Use suspend_processing_unit_cb or to suspend the processing unit from outside HPX. Requires that the pool has threads::policies::enable_elasticity set.

Return

A future<void> which is ready when the given processing unit has been suspended.

Parameters

• virt_core: [in] The processing unit on the the pool to be suspended. The processing units are indexed starting from 0.

Exceptions

• hpx::exception: if called from outside the HPX runtime.

virtual void suspend_processing_unit_cb(std::function<void(void)> callback, std::size_t virt_core, error_code &ec = throws, ) = 0

Suspends the given processing unit. Takes a callback as a parameter which will be called when the processing unit has been suspended.

Note

Requires that the pool has threads::policies::enable_elasticity set.

Parameters

• callback: [in] Callback which is called when the processing unit has been suspended.
• virt_core: [in] The processing unit to suspend.
• 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.

virtual hpx::future<void> resume_processing_unit(std::size_t virt_core) = 0

Resumes the given processing unit. When the processing unit has been resumed the returned future will be ready.

Note

Can only be called from an HPX thread. Use resume_processing_unit_cb or to resume the processing unit from outside HPX. Requires that the pool has threads::policies::enable_elasticity set.

Return

A future<void> which is ready when the given processing unit has been resumed.

Parameters

• virt_core: [in] The processing unit on the the pool to be resumed. The processing units are indexed starting from 0.

virtual void resume_processing_unit_cb(std::function<void(void)> callback, std::size_t virt_core, error_code &ec = throws, ) = 0

Resumes the given processing unit. Takes a callback as a parameter which will be called when the processing unit has been resumed.

Note

Requires that the pool has threads::policies::enable_elasticity set.

Parameters

• callback: [in] Callback which is called when the processing unit has been suspended.
• virt_core: [in] The processing unit to resume.
• 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.

struct thread_schedule_hint

#include <thread_enums.hpp>

Public Functions

thread_schedule_hint()

thread_schedule_hint(std::int16_t thread_hint)

thread_schedule_hint(thread_schedule_hint_mode mode, std::int16_t hint)

Public Members

thread_schedule_hint_mode mode

std::int16_t hint

struct unsequenced_execution_tag

#include <execution_fwd.hpp>

Function invocations executed by a group of vector execution agents are permitted to execute in unordered fashion when executed in different threads, and un-sequenced with respect to one another when executed in the same thread.

Note

unsequenced_execution_tag is weaker than parallel_execution_tag.

struct unwrap

#include <unwrap.hpp>

A helper function object for functionally invoking hpx::util::unwrap. For more information please refer to its documentation.

struct unwrap_all

#include <unwrap.hpp>

A helper function object for functionally invoking hpx::util::unwrap_all. For more information please refer to its documentation.

template <std::size_t Depth>
struct unwrap_n

#include <unwrap.hpp>

A helper function object for functionally invoking hpx::util::unwrap_n. For more information please refer to its documentation.

template <typename Sequence>
struct when_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

std::size_t index

The index of a future which has become ready.

Sequence futures

The sequence of futures as passed to hpx::when_any.

template <typename Sequence>
struct when_some_result

#include <when_some.hpp>

Result type for when_some, contains a sequence of futures and indices pointing to ready futures.

Public Members

std::vector<std::size_t> indices

List of indices of futures which became ready.

Sequence futures

The sequence of futures as passed to hpx::when_some.

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.

namespace hpx

Unnamed Group

error_code make_error_code(error e, throwmode mode = plain)

Returns a new error_code constructed from the given parameters.

error_code make_error_code(error e, char const *func, char const *file, long line, throwmode mode = plain)

error_code make_error_code(error e, char const *msg, throwmode mode = plain)

Returns error_code(e, msg, mode).

error_code make_error_code(error e, char const *msg, char const *func, char const *file, long line, throwmode mode = plain)

error_code make_error_code(error e, std::string const &msg, throwmode mode = plain)

Returns error_code(e, msg, mode).

error_code make_error_code(error e, std::string const &msg, char const *func, char const *file, long line, throwmode mode = plain)

error_code make_error_code(std::exception_ptr const &e)

Typedefs

typedef util::function_nonser<void(boost::system::error_code const&, parcelset::parcel const&)> parcel_write_handler_type

The type of a function which can be registered as a parcel write handler using the function hpx::set_parcel_write_handler.

Note

A parcel write handler is a function which is called by the parcel layer whenever a parcel has been sent by the underlying networking library and if no explicit parcel handler function was specified for the parcel.

typedef util::unique_function_nonser<void()> shutdown_function_type

The type of a function which is registered to be executed as a shutdown or pre-shutdown function.

typedef util::unique_function_nonser<void()> startup_function_type

The type of a function which is registered to be executed as a startup or pre-startup function.

Enums

enum error

Possible error conditions.

This enumeration lists all possible error conditions which can be reported from any of the API functions.

Values:

success = 0

The operation was successful.

no_success = 1

The operation did failed, but not in an unexpected manner.

not_implemented = 2

The operation is not implemented.

out_of_memory = 3

The operation caused an out of memory condition.

bad_action_code = 4

bad_component_type = 5

The specified component type is not known or otherwise invalid.

network_error = 6

A generic network error occurred.

version_too_new = 7

The version of the network representation for this object is too new.

version_too_old = 8

The version of the network representation for this object is too old.

version_unknown = 9

The version of the network representation for this object is unknown.

unknown_component_address = 10

duplicate_component_address = 11

The given global id has already been registered.

invalid_status = 12

The operation was executed in an invalid status.

bad_parameter = 13

One of the supplied parameters is invalid.

internal_server_error = 14

service_unavailable = 15

bad_request = 16

repeated_request = 17

lock_error = 18

duplicate_console = 19

There is more than one console locality.

no_registered_console = 20

There is no registered console locality available.

startup_timed_out = 21

uninitialized_value = 22

bad_response_type = 23

deadlock = 24

assertion_failure = 25

null_thread_id = 26

Attempt to invoke a API function from a non-HPX thread.

invalid_data = 27

yield_aborted = 28

The yield operation was aborted.

dynamic_link_failure = 29

commandline_option_error = 30

One of the options given on the command line is erroneous.

serialization_error = 31

There was an error during serialization of this object.

unhandled_exception = 32

An unhandled exception has been caught.

kernel_error = 33

The OS kernel reported an error.

broken_task = 34

The task associated with this future object is not available anymore.

task_moved = 35

The task associated with this future object has been moved.

task_already_started = 36

The task associated with this future object has already been started.

future_already_retrieved = 37

The future object has already been retrieved.

promise_already_satisfied = 38

The value for this future object has already been set.

future_does_not_support_cancellation = 39

The future object does not support cancellation.

future_can_not_be_cancelled = 40

The future can’t be canceled at this time.

no_state = 41

The future object has no valid shared state.

broken_promise = 42

The promise has been deleted.

thread_resource_error = 43

future_cancelled = 44

thread_cancelled = 45

thread_not_interruptable = 46

duplicate_component_id = 47

The component type has already been registered.

unknown_error = 48

An unknown error occurred.

bad_plugin_type = 49

The specified plugin type is not known or otherwise invalid.

filesystem_error = 50

The specified file does not exist or other filesystem related error.

bad_function_call = 51

equivalent of std::bad_function_call

task_canceled_exception = 52

parallel::v2::task_canceled_exception

task_block_not_active = 53

task_region is not active

out_of_range = 54

Equivalent to std::out_of_range.

length_error = 55

Equivalent to std::length_error.

enum throwmode

Encode error category for new error_code.

Values:

plain = 0

rethrow = 1

lightweight = 0x80

enum runtime_mode

A HPX runtime can be executed in two different modes: console mode and worker mode.

Values:

runtime_mode_invalid = -1

runtime_mode_console = 0

The runtime is the console locality.

runtime_mode_worker = 1

The runtime is a worker locality.

runtime_mode_connect = 2

The runtime is a worker locality connecting late

runtime_mode_default = 3

The runtime mode will be determined based on the command line arguments

runtime_mode_last

Functions

int init(util::function_nonser<int(boost::program_options::variables_map &vm)> const &f, boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> const &cfg, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main entry point for launching the HPX runtime system.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. This overload will not call hpx_main.

Return

The function returns the value, which has been returned from the user supplied f.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(int (*f)(boost::program_options::variables_map &vm), boost::program_options::options_description const &desc_cmdline, int argc, char **argv, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main entry point for launching the HPX runtime system.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. This overload will not call hpx_main.

Return

The function returns the value, which has been returned from the user supplied f.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> const &cfg, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(int argc, char **argv, std::vector<std::string> const &cfg, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, hpx::runtime_mode mode)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

If the parameter mode is runtime_mode_default, the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> const &cfg, hpx::runtime_mode mode)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

If the parameter mode is runtime_mode_default, the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(std::string const &app_name, int argc = 0, char **argv = nullptr, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• app_name: [in] The name of the application.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(int argc = 0, char **argv = nullptr, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. If not command line arguments are passed, console mode is assumed.

Note

If no command line arguments are passed the HPX runtime system will not support any of the default command line options as described in the section ‘HPX Command Line Options’.

Parameters

• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(std::vector<std::string> const &cfg, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. If not command line arguments are passed, console mode is assumed.

Note

If no command line arguments are passed the HPX runtime system will not support any of the default command line options as described in the section ‘HPX Command Line Options’.

Parameters

• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(int (*f)(boost::program_options::variables_map &vm), std::string const &app_name, int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will schedule the function given by f as a HPX thread. This overload will not call hpx_main.

Return

The function returns the value, which has been returned from the user supplied function f.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• app_name: [in] The name of the application.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(int (*f)(boost::program_options::variables_map &vm), int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will schedule the function given by f as a HPX thread. This overload will not call hpx_main.

Return

The function returns the value, which has been returned from the user supplied function f.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(util::function_nonser<int(int, char **)> const &f, std::string const &app_name, int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will schedule the function given by f as a HPX thread. This overload will not call hpx_main.

Return

The function returns the value, which has been returned from the user supplied function f.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• app_name: [in] The name of the application.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(util::function_nonser<int(int, char **)> const &f, int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will schedule the function given by f as a HPX thread. This overload will not call hpx_main.

Return

The function returns the value, which has been returned from the user supplied function f.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int init(util::function_nonser<int(int, char **)> const &f, int argc, char **argv, std::vector<std::string> const &cfg, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will schedule the function given by f as a HPX thread. This overload will not call hpx_main.

Return

The function returns the value, which has been returned from the user supplied function f.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(util::function_nonser<int(boost::program_options::variables_map &vm)> const &f, boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> const &cfg, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main non-blocking entry point for launching the HPX runtime system.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will not call hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(int (*f)(boost::program_options::variables_map &vm), boost::program_options::options_description const &desc_cmdline, int argc, char **argv, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main non-blocking entry point for launching the HPX runtime system.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will not call hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> const &cfg, startup_function_type startup = startup_function_type(), shutdown_function_type shutdown = shutdown_function_type(), hpx::runtime_mode mode = hpx::runtime_mode_default)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• startup: [in] A function to be executed inside a HPX thread before f is called. If this parameter is not given no function will be executed.
• shutdown: [in] A function to be executed inside an HPX thread while hpx::finalize is executed. If this parameter is not given no function will be executed.
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(int argc, char **argv, std::vector<std::string> const &cfg, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is runtime_mode_default, the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, hpx::runtime_mode mode)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is runtime_mode_default, the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(boost::program_options::options_description const &desc_cmdline, int argc, char **argv, std::vector<std::string> const &cfg, hpx::runtime_mode mode)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

In console mode it will execute the user supplied function hpx_main, in worker mode it will execute an empty hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is runtime_mode_default, the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

• desc_cmdline: [in] This parameter may hold the description of additional command line arguments understood by the application. These options will be prepended to the default command line options understood by hpx::init (see description below).
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(std::string const &app_name, int argc = 0, char **argv = nullptr, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• app_name: [in] The name of the application.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(int argc = 0, char **argv = nullptr, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. If not command line arguments are passed, console mode is assumed.

Note

If no command line arguments are passed the HPX runtime system will not support any of the default command line options as described in the section ‘HPX Command Line Options’.

Parameters

• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(std::vector<std::string> const &cfg, hpx::runtime_mode mode = hpx::runtime_mode_default)

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. If not command line arguments are passed, console mode is assumed.

Note

If no command line arguments are passed the HPX runtime system will not support any of the default command line options as described in the section ‘HPX Command Line Options’.

Parameters

• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(int (*f)(boost::program_options::variables_map &vm), std::string const &app_name, int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will schedule the function given by f as a HPX thread. It will not call hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application.
• app_name: [in] The name of the application.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(util::function_nonser<int(int, char **)> const &f, std::string const &app_name, int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will schedule the function given by f as a HPX thread. It will not call hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• app_name: [in] The name of the application.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(int (*f)(boost::program_options::variables_map &vm), int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will schedule the function given by f as a HPX thread. It will not call hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(util::function_nonser<int(int, char **)> const &f, int argc, char **argv, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will schedule the function given by f as a HPX thread. It will not call hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

bool start(util::function_nonser<int(int, char **)> const &f, int argc, char **argv, std::vector<std::string> const &cfg, hpx::runtime_mode mode = hpx::runtime_mode_default, )

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will schedule the function given by f as a HPX thread. It will not call hpx_main.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv.

Parameters

• f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
• argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
• argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
• cfg: A list of configuration settings which will be added to the system configuration before the runtime instance is run. Each of the entries in this list must have the format of a fully defined key/value pair from an ini-file (for instance ‘hpx.component.enabled=1’)
• mode: [in] The mode the created runtime environment should be initialized in. There has to be exactly one locality in each HPX application which is executed in console mode (hpx::runtime_mode_console), all other localities have to be run in worker mode (hpx::runtime_mode_worker). Normally this is set up automatically, but sometimes it is necessary to explicitly specify the mode.

int finalize(double shutdown_timeout, double localwait = -1.0, error_code &ec = throws)

Main function to gracefully terminate the HPX runtime system.

The function hpx::finalize is the main way to (gracefully) exit any HPX application. It should be called from one locality only (usually the console) and it will notify all connected localities to finish execution. Only after all other localities have exited this function will return, allowing to exit the console locality as well.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on all localities.

The default value (

-1.0) will try to find a globally set timeout value (can be set as the configuration parameter hpx.shutdown_timeout), and if that is not set or -1.0 as well, it will disable any timeout, each connected locality will wait for all existing HPX-threads to terminate.

Parameters

• shutdown_timeout: This parameter allows to specify a timeout (in microseconds), specifying how long any of the connected localities should wait for pending tasks to be executed. After this timeout, all suspended HPX-threads will be aborted. Note, that this function will not abort any running HPX-threads. In any case the shutdown will not proceed as long as there is at least one pending/running HPX-thread.

The default value (

-1.0) will try to find a globally set wait time value (can be set as the configuration parameter “hpx.finalize_wait_time”), and if this is not set or -1.0 as well, it will disable any addition local wait time before proceeding.

Parameters

• localwait: This parameter allows to specify a local wait time (in microseconds) before the connected localities will be notified and the overall shutdown process starts.

This function will block and wait for all connected localities to exit before returning to the caller. It should be the last HPX-function called by any application.

Return

This function will always return zero.

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

• 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.

Using this function is an alternative to hpx::disconnect, these functions do not need to be called both.

int finalize(error_code &ec = throws)

Main function to gracefully terminate the HPX runtime system.

The function hpx::finalize is the main way to (gracefully) exit any HPX application. It should be called from one locality only (usually the console) and it will notify all connected localities to finish execution. Only after all other localities have exited this function will return, allowing to exit the console locality as well.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on all localities.

This function will block and wait for all connected localities to exit before returning to the caller. It should be the last HPX-function called by any application.

Return

This function will always return zero.

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

• 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.

Using this function is an alternative to hpx::disconnect, these functions do not need to be called both.

HPX_NORETURN void hpx::terminate()

Terminate any application non-gracefully.

The function hpx::terminate is the non-graceful way to exit any application immediately. It can be called from any locality and will terminate all localities currently used by the application.

Note

This function will cause HPX to call std::terminate() on all localities associated with this application. If the function is called not from an HPX thread it will fail and return an error using the argument ec.

int disconnect(double shutdown_timeout, double localwait = -1.0, error_code &ec = throws)

Disconnect this locality from the application.

The function hpx::disconnect can be used to disconnect a locality from a running HPX application.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on this locality.

The default value (

-1.0) will try to find a globally set timeout value (can be set as the configuration parameter “hpx.shutdown_timeout”), and if that is not set or -1.0 as well, it will disable any timeout, each connected locality will wait for all existing HPX-threads to terminate.

Parameters

• shutdown_timeout: This parameter allows to specify a timeout (in microseconds), specifying how long this locality should wait for pending tasks to be executed. After this timeout, all suspended HPX-threads will be aborted. Note, that this function will not abort any running HPX-threads. In any case the shutdown will not proceed as long as there is at least one pending/running HPX-thread.

The default value (

-1.0) will try to find a globally set wait time value (can be set as the configuration parameter hpx.finalize_wait_time), and if this is not set or -1.0 as well, it will disable any addition local wait time before proceeding.

Parameters

• localwait: This parameter allows to specify a local wait time (in microseconds) before the connected localities will be notified and the overall shutdown process starts.

This function will block and wait for this locality to finish executing before returning to the caller. It should be the last HPX-function called by any locality being disconnected.

Return

This function will always return zero.

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

• 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.

int disconnect(error_code &ec = throws)

Disconnect this locality from the application.

The function hpx::disconnect can be used to disconnect a locality from a running HPX application.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on this locality.

This function will block and wait for this locality to finish executing before returning to the caller. It should be the last HPX-function called by any locality being disconnected.

Return

This function will always return zero.

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

• 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.

int stop(error_code &ec = throws)

Stop the runtime system.

This function will block and wait for this locality to finish executing before returning to the caller. It should be the last HPX-function called on every locality. This function should be used only if the runtime system was started using

hpx::start.

Return

The function returns the value, which has been returned from the user supplied main HPX function (usually hpx_main).

int suspend(error_code &ec = throws)

Suspend the runtime system.

The function hpx::suspend is used to suspend the HPX runtime system. It can only be used when running HPX on a single locality. It will block waiting for all thread pools to be empty. This function only be called when the runtime is running, or already suspended in which case this function will do nothing.

Return

This function will always return zero.

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

• 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.

int resume(error_code &ec = throws)

Resume the HPX runtime system.

The function hpx::resume is used to resume the HPX runtime system. It can only be used when running HPX on a single locality. It will block waiting for all thread pools to be resumed. This function only be called when the runtime suspended, or already running in which case this function will do nothing.

Return

This function will always return zero.

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

• 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.

boost::system::error_category const &get_hpx_category()

Returns generic HPX error category used for new errors.

boost::system::error_category const &get_hpx_rethrow_category()

Returns generic HPX error category used for errors re-thrown after the exception has been de-serialized.

error_code make_success_code(throwmode mode = plain)

Returns error_code(hpx::success, “success”, mode).

std::string diagnostic_information(exception_info const &xi)

Extract the diagnostic information embedded in the given exception and return a string holding a formatted message.

The function hpx::diagnostic_information can be used to extract all diagnostic information stored in the given exception instance as a formatted string. This simplifies debug output as it composes the diagnostics into one, easy to use function call. This includes 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.

Return

The formatted string holding all of the available diagnostic information stored in the given exception instance.

See

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(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for all diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if any of the required allocation operations fail)

std::string get_error_what(exception_info const &xi)

Return the error message of the thrown exception.

The function hpx::get_error_what can be used to extract the diagnostic information element representing the error message as stored in the given exception instance.

Return

The error message stored in the exception If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), 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() hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

std::uint32_t get_error_locality_id(hpx::exception_info const &xi)

Return the locality id where the exception was thrown.

The function hpx::get_error_locality_id can be used to extract the diagnostic information element representing the locality id as stored in the given exception instance.

Return

The locality id of the locality where the exception was thrown. If the exception instance does not hold this information, the function will return hpx::naming::invalid_locality_id.

See

hpx::diagnostic_information(), 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(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• nothing:

error get_error(hpx::exception const &e)

Return the locality id where the exception was thrown.

The function hpx::get_error can be used to extract the diagnostic information element representing the error value code as stored in the given exception instance.

Return

The error value code of the locality where the exception was thrown. If the exception instance does not hold this information, the function will return hpx::naming::invalid_locality_id.

See

hpx::diagnostic_information(), 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(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• e: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception, hpx::error_code, or std::exception_ptr.

Exceptions

• nothing:

error get_error(hpx::error_code const &e)

Return the locality id where the exception was thrown.

The function hpx::get_error can be used to extract the diagnostic information element representing the error value code as stored in the given exception instance.

Return

The error value code of the locality where the exception was thrown. If the exception instance does not hold this information, the function will return hpx::naming::invalid_locality_id.

See

hpx::diagnostic_information(), 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(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• e: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception, hpx::error_code, or std::exception_ptr.

Exceptions

• nothing:

std::string get_error_host_name(hpx::exception_info const &xi)

Return the hostname of the locality where the exception was thrown.

The function hpx::get_error_host_name can be used to extract the diagnostic information element representing the host name as stored in the given exception instance.

Return

The hostname of the locality where the exception was thrown. If the exception instance does not hold this information, the function will return and empty string.

See

hpx::diagnostic_information() 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() hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

std::int64_t get_error_process_id(hpx::exception_info const &xi)

Return the (operating system) process id of the locality where the exception was thrown.

The function hpx::get_error_process_id can be used to extract the diagnostic information element representing the process id as stored in the given exception instance.

Return

The process id of the OS-process which threw the exception If the exception instance does not hold this information, the function will return 0.

See

hpx::diagnostic_information(), hpx::get_error_host_name(), 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(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• nothing:

std::string get_error_env(hpx::exception_info const &xi)

Return the environment of the OS-process at the point the exception was thrown.

The function hpx::get_error_env can be used to extract the diagnostic information element representing the environment of the OS-process collected at the point the exception was thrown.

Return

The environment from the point the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), 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(), hpx::get_error_backtrace(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

std::string get_error_function_name(hpx::exception_info const &xi)

Return the function name from which the exception was thrown.

The function hpx::get_error_function_name can be used to extract the diagnostic information element representing the name of the function as stored in the given exception instance.

Return

The name of the function from which the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), hpx::get_error_host_name(), hpx::get_error_process_id() 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(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

std::string get_error_backtrace(hpx::exception_info const &xi)

Return the stack backtrace from the point the exception was thrown.

The function hpx::get_error_backtrace can be used to extract the diagnostic information element representing the stack backtrace collected at the point the exception was thrown.

Return

The stack back trace from the point the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), 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(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

std::string get_error_file_name(hpx::exception_info const &xi)

Return the (source code) file name of the function from which the exception was thrown.

The function hpx::get_error_file_name can be used to extract the diagnostic information element representing the name of the source file as stored in the given exception instance.

Return

The name of the source file of the function from which the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), hpx::get_error_host_name(), hpx::get_error_process_id(), hpx::get_error_function_name(), hpx::get_error_line_number(), hpx::get_error_os_thread(), hpx::get_error_thread_id(), hpx::get_error_thread_description(), hpx::get_error(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

long get_error_line_number(hpx::exception_info const &xi)

Return the line number in the (source code) file of the function from which the exception was thrown.

The function hpx::get_error_line_number can be used to extract the diagnostic information element representing the line number as stored in the given exception instance.

Return

The line number of the place where the exception was thrown. If the exception instance does not hold this information, the function will return -1.

See

hpx::diagnostic_information(), hpx::get_error_host_name(), hpx::get_error_process_id(), hpx::get_error_function_name(), hpx::get_error_file_name() hpx::get_error_os_thread(), hpx::get_error_thread_id(), hpx::get_error_thread_description(), hpx::get_error(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• nothing:

std::size_t get_error_os_thread(hpx::exception_info const &xi)

Return the sequence number of the OS-thread used to execute HPX-threads from which the exception was thrown.

The function hpx::get_error_os_thread can be used to extract the diagnostic information element representing the sequence number of the OS-thread as stored in the given exception instance.

Return

The sequence number of the OS-thread used to execute the HPX-thread from which the exception was thrown. If the exception instance does not hold this information, the function will return std::size(-1).

See

hpx::diagnostic_information(), 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_thread_id(), hpx::get_error_thread_description(), hpx::get_error(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• nothing:

std::size_t get_error_thread_id(hpx::exception_info const &xi)

Return the unique thread id of the HPX-thread from which the exception was thrown.

The function hpx::get_error_thread_id can be used to extract the diagnostic information element representing the HPX-thread id as stored in the given exception instance.

Return

The unique thread id of the HPX-thread from which the exception was thrown. If the exception instance does not hold this information, the function will return std::size_t(0).

See

hpx::diagnostic_information(), 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_description(), hpx::get_error(), hpx::get_error_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• nothing:

std::string get_error_thread_description(hpx::exception_info const &xi)

Return any additionally available thread description of the HPX-thread from which the exception was thrown.

The function hpx::get_error_thread_description can be used to extract the diagnostic information element representing the additional thread description as stored in the given exception instance.

Return

Any additionally available thread description of the HPX-thread from which the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), 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_backtrace(), hpx::get_error_env(), hpx::get_error(), hpx::get_error_state(), hpx::get_error_what(), hpx::get_error_config()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

std::string get_error_config(hpx::exception_info const &xi)

Return the HPX configuration information point from which the exception was thrown.

The function hpx::get_error_config can be used to extract the HPX configuration information element representing the full HPX configuration information as stored in the given exception instance.

Return

Any additionally available HPX configuration information the point from which the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), 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_backtrace(), hpx::get_error_env(), hpx::get_error(), hpx::get_error_state() hpx::get_error_what(), hpx::get_error_thread_description()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

std::string get_error_state(hpx::exception_info const &xi)

Return the HPX runtime state information at which the exception was thrown.

The function hpx::get_error_state can be used to extract the HPX runtime state information element representing the state the runtime system is currently in as stored in the given exception instance.

Return

The point runtime state at the point at which the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

See

hpx::diagnostic_information(), 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_backtrace(), hpx::get_error_env(), hpx::get_error(), hpx::get_error_what(), hpx::get_error_thread_description()

Parameters

• xi: The parameter e will be inspected for the requested diagnostic information elements which have been stored at the point where the exception was thrown. This parameter can be one of the following types: hpx::exception_info, hpx::error_code, std::exception, or std::exception_ptr.

Exceptions

• std::bad_alloc: (if one of the required allocations fails)

bool register_thread(runtime *rt, char const *name, error_code &ec = throws)

Register the current kernel thread with HPX, this should be done once for each external OS-thread intended to invoke HPX functionality. Calling this function more than once will silently fail.

void unregister_thread(runtime *rt)

Unregister the thread from HPX, this should be done once in the end before the external thread exists.

naming::gid_type const &get_locality()

The function get_locality returns a reference to the locality prefix.

std::size_t get_runtime_instance_number()

The function get_runtime_instance_number returns a unique number associated with the runtime instance the current thread is running in.

bool register_on_exit(util::function_nonser<void()> const&)

Register a function to be called during system shutdown.

bool is_starting()

Test whether the runtime system is currently being started.

This function returns whether the runtime system is currently being started or not, e.g. whether the current state of the runtime system is hpx::state_startup

Note

This function needs to be executed on a HPX-thread. It will return false otherwise.

bool tolerate_node_faults()

Test if HPX runs in fault-tolerant mode.

This function returns whether the runtime system is running in fault-tolerant mode

bool is_running()

Test whether the runtime system is currently running.

This function returns whether the runtime system is currently running or not, e.g. whether the current state of the runtime system is hpx::state_running

Note

This function needs to be executed on a HPX-thread. It will return false otherwise.

bool is_stopped()

Test whether the runtime system is currently stopped.

This function returns whether the runtime system is currently stopped or not, e.g. whether the current state of the runtime system is hpx::state_stopped

Note

This function needs to be executed on a HPX-thread. It will return false otherwise.

bool is_stopped_or_shutting_down()

Test whether the runtime system is currently being shut down.

This function returns whether the runtime system is currently being shut down or not, e.g. whether the current state of the runtime system is hpx::state_stopped or hpx::state_shutdown

Note

This function needs to be executed on a HPX-thread. It will return false otherwise.

std::size_t get_num_worker_threads()

Return the number of worker OS- threads used to execute HPX threads.

This function returns the number of OS-threads used to execute HPX threads. If the function is called while no HPX runtime system is active, it will return zero.

std::uint64_t get_system_uptime()

Return the system uptime measure on the thread executing this call.

This function returns the system uptime measured in nanoseconds for the thread executing this call. If the function is called while no HPX runtime system is active, it will return zero.

void start_active_counters(error_code &ec = throws)

Start all active performance counters, optionally naming the section of code.

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

The active counters are those which have been specified on the command line while executing the application (see command line option –hpx:print-counter)

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.

void reset_active_counters(error_code &ec = throws)

Resets all active performance counters.

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

The active counters are those which have been specified on the command line while executing the application (see command line option –hpx:print-counter)

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.

void reinit_active_counters(bool reset = true, error_code &ec = throws)

Re-initialize all active performance counters.

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

The active counters are those which have been specified on the command line while executing the application (see command line option –hpx:print-counter)

Parameters

• reset: [in] Reset the current values before re-initializing counters (default: true)
• 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.

void stop_active_counters(error_code &ec = throws)

Stop all active performance counters.

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

The active counters are those which have been specified on the command line while executing the application (see command line option –hpx:print-counter)

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.

void evaluate_active_counters(bool reset = false, char const *description = nullptr, error_code &ec = throws)

Evaluate and output all active performance counters, optionally naming the point in code marked by this function.

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

The output generated by this function is redirected to the destination specified by the corresponding command line options (see –hpx:print-counter-destination).

Note

The active counters are those which have been specified on the command line while executing the application (see command line option –hpx:print-counter)

Parameters

• reset: [in] this is an optional flag allowing to reset the counter value after it has been evaluated.
• description: [in] this is an optional value naming the point in the code marked by the call to this function.
• 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.

serialization::binary_filter *create_binary_filter(char const *binary_filter_type, bool compress, serialization::binary_filter *next_filter = nullptr, error_code &ec = throws)

Create an instance of a binary filter plugin.

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

• binary_filter_type: [in] The type of the binary filter to create
• compress: [in] The created filter should support compression
• next_filter: [in] Use this as the filter to dispatch the invocation into.
• 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<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 = ~0U)

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 = ~0U)

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 = ~0U)

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, typename Stub>
hpx::future<bool> register_with_basename(std::string base_name, components::client_base<Client, Stub> &client, std::size_t sequence_nr = ~0U)

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 = ~0U)

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

hpx::find_all_localities(), hpx::find_locality()

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

hpx::find_all_localities(), hpx::find_locality()

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

hpx::find_here(), hpx::find_locality()

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

hpx::find_here(), hpx::find_locality()

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

hpx::find_here(), hpx::find_locality()

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

hpx::find_here(), hpx::find_locality()

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

hpx::find_here(), hpx::find_all_localities()

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

hpx::get_colocation_id()

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.

template <typename Component>
hpx::future<std::shared_ptr<Component>> get_ptr(naming::id_type const &id)

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.

template <typename Derived, typename Stub>
hpx::future<std::shared_ptr<typename components::client_base<Derived, Stub>::server_component_type>> get_ptr(components::client_base<Derived, Stub> const &c)

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.

template <typename Component>
std::shared_ptr<Component> get_ptr(launch::sync_policy p, naming::id_type const &id, error_code &ec = throws)

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.

template <typename Derived, typename Stub>
std::shared_ptr<typename components::client_base<Derived, Stub>::server_component_type> get_ptr(launch::sync_policy p, components::client_base<Derived, Stub> const &c, error_code &ec = throws)

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::uint32_t get_locality_id(error_code &ec = throws)

Return the number of the locality this function is being called from.

This function returns the id of the current locality.

Note

The returned value is zero based and its maximum value is smaller than the overall number of localities the current application is running on (as returned by get_num_localities()).

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 needs to be executed on a HPX-thread. It will fail otherwise (it will return -1).

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::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

std::uint32_t get_initial_num_localities()

Return the number of localities which were registered at startup for the running application.

The function get_initial_num_localities returns the number of localities which were connected to the console at application startup.

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

hpx::find_all_localities, hpx::get_num_localities

lcos::future<std::uint32_t> get_num_localities()

Asynchronously return the number of localities which are currently registered for the running application.

The function get_num_localities asynchronously returns the number of localities currently connected to the console. The returned future represents the actual result.

Note

This function will return meaningful results only if called from an HPX-thread. It will return 0 otherwise.

See

hpx::find_all_localities, hpx::get_num_localities

std::uint32_t get_num_localities(launch::sync_policy, error_code &ec = throws)

Return the number of localities which are currently registered for the running application.

The function get_num_localities returns the number of localities currently connected to the console.

Note

This function will return meaningful results only if called from an HPX-thread. It will return 0 otherwise.

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

hpx::find_all_localities, hpx::get_num_localities

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.

lcos::future<std::uint32_t> get_num_localities(components::component_type t)

Asynchronously return the number of localities which are currently registered for the running application.

The function get_num_localities asynchronously returns the number of localities currently connected to the console which support the creation of the given component type. The returned future represents the actual result.

Note

This function will return meaningful results only if called from an HPX-thread. It will return 0 otherwise.

See

hpx::find_all_localities, hpx::get_num_localities

Parameters

• t: The component type for which the number of connected localities should be retrieved.

std::uint32_t get_num_localities(launch::sync_policy, components::component_type t, error_code &ec = throws)

Synchronously return the number of localities which are currently registered for the running application.

The function get_num_localities returns the number of localities currently connected to the console which support the creation of the given component type. The returned future represents the actual result.

Note

This function will return meaningful results only if called from an HPX-thread. It will return 0 otherwise.

See

hpx::find_all_localities, hpx::get_num_localities

Parameters

• t: The component type for which the number of connected localities 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::size_t get_os_thread_count()

Return the number of OS-threads running in the runtime instance the current HPX-thread is associated with.

std::size_t get_os_thread_count(threads::executor const &exec)

Return the number of worker OS- threads used by the given executor to execute HPX threads.

This function returns the number of cores used to execute HPX threads for the given executor. If the function is called while no HPX runtime system is active, it will return zero. If the executor is not valid, this function will fall back to retrieving the number of OS threads used by HPX.

Parameters

• exec: [in] The executor to be used.

std::string get_thread_name()

Return the name of the calling thread.

This function returns the name of the calling thread. This name uniquely identifies the thread in the context of HPX. If the function is called while no HPX runtime system is active, the result will be “<unknown>”.

std::size_t get_worker_thread_num()

Return the number of the current OS-thread running in the runtime instance the current HPX-thread is executed with.

This function returns the zero based index of the OS-thread which executes the current HPX-thread.

Note

The returned value is zero based and its maximum value is smaller than the overall number of OS-threads executed (as returned by get_os_thread_count().

Note

This function needs to be executed on a HPX-thread. It will fail otherwise (it will return -1).

std::size_t get_worker_thread_num(error_code &ec)

Return the number of the current OS-thread running in the runtime instance the current HPX-thread is executed with.

This function returns the zero based index of the OS-thread which executes the current HPX-thread.

Note

The returned value is zero based and its maximum value is smaller than the overall number of OS-threads executed (as returned by get_os_thread_count(). It will return -1 if the current thread is not a known thread or if the runtime is not in running state.

Note

This function needs to be executed on a HPX-thread. It will fail otherwise (it will return -1).

Parameters

• ec: [in,out] this represents the error status on exit.

void report_error(std::size_t num_thread, std::exception_ptr const &e)

The function report_error reports the given exception to the console.

void report_error(std::exception_ptr const &e)

The function report_error reports the given exception to the console.

char const *get_runtime_mode_name(runtime_mode state)

Get the readable string representing the name of the given runtime_mode constant.

runtime_mode get_runtime_mode_from_name(std::string const &mode)

Get the internal representation (runtime_mode constant) from the readable string representing the name.

parcel_write_handler_type set_parcel_write_handler(parcel_write_handler_type const &f)

Set the default parcel write handler which is invoked once a parcel has been sent if no explicit write handler was specified.

Return

The function returns the parcel write handler which was installed before this function was called.

Note

If no parcel handler function is registered by the user the system will call a default parcel handler function which is not performing any actions. However, this default function will terminate the application in case of any errors detected during preparing or sending the parcel.

Parameters

• f: The new parcel write handler to use from this point on

void register_pre_shutdown_function(shutdown_function_type f)

Add a function to be executed by a HPX thread during hpx::finalize() but guaranteed before any shutdown function is executed (system-wide)

Any of the functions registered with register_pre_shutdown_function are guaranteed to be executed by an HPX thread during the execution of hpx::finalize() before any of the registered shutdown functions are executed (see: hpx::register_shutdown_function()).

Note

If this function is called while the pre-shutdown functions are being executed, or after that point, it will raise a invalid_status exception.

See

hpx::register_shutdown_function()

Parameters

• f: [in] The function to be registered to run by an HPX thread as a pre-shutdown function.

void register_shutdown_function(shutdown_function_type f)

Add a function to be executed by a HPX thread during hpx::finalize() but guaranteed after any pre-shutdown function is executed (system-wide)

Any of the functions registered with register_shutdown_function are guaranteed to be executed by an HPX thread during the execution of hpx::finalize() after any of the registered pre-shutdown functions are executed (see: hpx::register_pre_shutdown_function()).

Note

If this function is called while the shutdown functions are being executed, or after that point, it will raise a invalid_status exception.

See

hpx::register_pre_shutdown_function()

Parameters

• f: [in] The function to be registered to run by an HPX thread as a shutdown function.

void register_pre_startup_function(startup_function_type f)

Add a function to be executed by a HPX thread before hpx_main but guaranteed before any startup function is executed (system-wide).

Any of the functions registered with register_pre_startup_function are guaranteed to be executed by an HPX thread before any of the registered startup functions are executed (see hpx::register_startup_function()).

This function is one of the few API functions which can be called before the runtime system has been fully initialized. It will automatically stage the provided startup function to the runtime system during its initialization (if necessary).

Note

If this function is called while the pre-startup functions are being executed or after that point, it will raise a invalid_status exception.

Parameters

• f: [in] The function to be registered to run by an HPX thread as a pre-startup function.

See

hpx::register_startup_function()

void register_startup_function(startup_function_type f)

Add a function to be executed by a HPX thread before hpx_main but guaranteed after any pre-startup function is executed (system-wide).

Any of the functions registered with register_startup_function are guaranteed to be executed by an HPX thread after any of the registered pre-startup functions are executed (see: hpx::register_pre_startup_function()), but before hpx_main is being called.

This function is one of the few API functions which can be called before the runtime system has been fully initialized. It will automatically stage the provided startup function to the runtime system during its initialization (if necessary).

Note

If this function is called while the startup functions are being executed or after that point, it will raise a invalid_status exception.

Parameters

• f: [in] The function to be registered to run by an HPX thread as a startup function.

See

hpx::register_pre_startup_function()

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>
void set_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>::type set_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>::type set_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>
void set_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>::type set_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>::type set_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>::value evaluates 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>::value evaluates 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>::value evaluates 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>::value evaluates 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 funtion 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>::value evaluates 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>::value evaluates 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 create
• 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, 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>::value evaluates 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>::value evaluates 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>::value evaluates 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>::value evaluates 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 create
• 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 ... 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:

tuple<future<void> > split_future(future<tuple<> > && f);
array<future<void>, 1> split_future(future<array<T, 0> > && f);

here the returned futures are directly representing the futures which were passed to the function.

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 InputIter>
void wait_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>
void wait_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_t N>
void wait_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>
void wait_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>
InputIter wait_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 InputIter, typename Container = 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, typename Container = 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 InputIter>
void wait_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>
void wait_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 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>
void wait_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>
void wait_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>
InputIter wait_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 InputIter, typename Container = 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, typename Container = 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 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>
void wait_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_t N>
void wait_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>
void wait_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>
InputIter wait_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 InputIter, typename Container = 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, typename Container = 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 F, typename Future>
void wait_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, typename Iterator>
void wait_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>
void wait_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, typename Iterator>
void wait_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 F, typename Future>
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, typename Iterator>
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, typename Iterator>
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.

Variables

error_code throws

Predefined error_code object used as “throw on error” tag.

The predefined hpx::error_code object hpx::throws is supplied for use as a “throw on error” tag.

Functions that specify an argument in the form ‘error_code& ec=throws’ (with appropriate namespace qualifiers), have the following error handling semantics:

If &ec != &throws and an error occurred: ec.value() returns the implementation specific error number for the particular error that occurred and ec.category() returns the error_category for ec.value().

If &ec != &throws and an error did not occur, ec.clear().

If an error occurs and &ec == &throws, the function throws an exception of type hpx::exception or of a type derived from it. The exception’s get_errorcode() member function returns a reference to an hpx::error_code object with the behavior as specified above.

namespace actions

namespace applier

Functions

applier &get_applier()

The function get_applier returns a reference to the (thread specific) applier instance.

applier *get_applier_ptr()

The function get_applier returns a pointer to the (thread specific) applier instance. The returned pointer is NULL if the current thread is not known to HPX or if the runtime system is not active.

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, typename Stub>
Derived migrate_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 copy
• target_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, typename Stub>
Derived copy(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 copy
• target_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, typename DistPolicy>
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, typename Stub, typename DistPolicy>
Derived migrate(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, typename Stub>
Derived migrate(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.

namespace lcos

Functions

template <typename Action, typename ArgN, ...>
hpx::future<std::vector<decltype(Action(hpx::id_type, ArgN, ...))>> 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