runtime_distributed¶

The contents of this module can be included with the header hpx/modules/runtime_distributed.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/runtime_distributed.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx

Functions

bool tolerate_node_faults()¶

class runtime_distributed : public runtime ¶

#include <runtime_distributed.hpp>

The runtime class encapsulates the HPX runtime system in a simple to use way. It makes sure all required parts of the HPX runtime system are properly initialized.

Public Functions

runtime_distributed(util::runtime_configuration &rtcfg)¶

Construct a new HPX runtime instance

Parameters

locality_mode: [in] This is the mode the given runtime instance should be executed in.

~runtime_distributed()¶: The destructor makes sure all HPX runtime services are properly shut down before exiting.

int start(util::function_nonser<hpx_main_function_type> const &func, bool blocking = false)¶

Start the runtime system.

Return

If a blocking is a true, this function will return the value as returned as the result of the invocation of the function object given by the parameter func. Otherwise it will return zero.

Parameters

func: [in] This is the main function of an HPX application. It will be scheduled for execution by the thread manager as soon as the runtime has been initialized. This function is expected to expose an interface as defined by the typedef hpx_main_function_type.
blocking: [in] This allows to control whether this call blocks until the runtime system has been stopped. If this parameter is true the function runtime::start will call runtime::wait internally.

int start(bool blocking = false)¶

Start the runtime system.

Return

If a blocking is a true, this function will return the value as returned as the result of the invocation of the function object given by the parameter func. Otherwise it will return zero.

Parameters

blocking: [in] This allows to control whether this call blocks until the runtime system has been stopped. If this parameter is true the function runtime::start will call runtime::wait internally .

int wait()¶

Wait for the shutdown action to be executed.

Return: This function will return the value as returned as the result of the invocation of the function object given by the parameter func.

void stop(bool blocking = true)¶

Initiate termination of the runtime system.

Parameters

blocking: [in] This allows to control whether this call blocks until the runtime system has been fully stopped. If this parameter is false then this call will initiate the stop action but will return immediately. Use a second call to stop with this parameter set to true to wait for all internal work to be completed.

int finalize(double shutdown_timeout)¶

void stop_helper(bool blocking, std::condition_variable &cond, std::mutex &mtx)¶

Stop the runtime system, wait for termination.

Parameters

blocking: [in] This allows to control whether this call blocks until the runtime system has been fully stopped. If this parameter is false then this call will initiate the stop action but will return immediately. Use a second call to stop with this parameter set to true to wait for all internal work to be completed.

int suspend()¶: Suspend the runtime system.

int resume()¶: Resume the runtime system.

bool report_error(std::size_t num_thread, std::exception_ptr const &e, bool terminate_all = true)¶

Report a non-recoverable error to the runtime system.

Parameters

num_thread: [in] The number of the operating system thread the error has been detected in.
e: [in] This is an instance encapsulating an exception which lead to this function call.
terminate_all: [in] Kill all localities attached to the currently running application (default: true)

bool report_error(std::exception_ptr const &e, bool terminate_all = true)¶

Report a non-recoverable error to the runtime system.

Note

This function will retrieve the number of the current shepherd thread and forward to the report_error function above.

Parameters

e: [in] This is an instance encapsulating an exception which lead to this function call.
terminate_all: [in] Kill all localities attached to the currently running application (default: true)

int run(util::function_nonser<hpx_main_function_type> const &func)¶

Run the HPX runtime system, use the given function for the main thread and block waiting for all threads to finish.

Note

The parameter func is optional. If no function is supplied, the runtime system will simply wait for the shutdown action without explicitly executing any main thread.

Return

This function will return the value as returned as the result of the invocation of the function object given by the parameter func.

Parameters

func: [in] This is the main function of an HPX application. It will be scheduled for execution by the thread manager as soon as the runtime has been initialized. This function is expected to expose an interface as defined by the typedef hpx_main_function_type. This parameter is optional and defaults to none main thread function, in which case all threads have to be scheduled explicitly.

int run()¶

Run the HPX runtime system, initially use the given number of (OS) threads in the thread-manager and block waiting for all threads to finish.

Return: This function will always return 0 (zero).

bool is_networking_enabled()¶

template<typename F> components::server::console_error_dispatcher::sink_type set_error_sink(F &&sink)¶

performance_counters::registry &get_counter_registry()¶: Allow access to the registry counter registry instance used by the HPX runtime.

performance_counters::registry const &get_counter_registry() const¶: Allow access to the registry counter registry instance used by the HPX runtime.

void register_counter_types()¶: Install all performance counters related to this runtime instance.

void register_query_counters(std::shared_ptr<util::query_counters> const &active_counters)¶

void start_active_counters(error_code &ec = throws)¶

void stop_active_counters(error_code &ec = throws)¶

void reset_active_counters(error_code &ec = throws)¶

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

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

void stop_evaluating_counters(bool terminate = false)¶

naming::resolver_client &get_agas_client()¶: Allow access to the AGAS client instance used by the HPX runtime.

hpx::threads::threadmanager &get_thread_manager()¶: Allow access to the thread manager instance used by the HPX runtime.

applier::applier &get_applier()¶: Allow access to the applier instance used by the HPX runtime.

std::string here() const¶: Returns a string of the locality endpoints (usable in debug output)

std::uint64_t get_runtime_support_lva() const¶

naming::gid_type get_next_id(std::size_t count = 1)¶

util::unique_id_ranges &get_id_pool()¶

void add_pre_startup_function(startup_function_type f)¶

Add a function to be executed inside a HPX thread before hpx_main but guaranteed to be executed before any startup function registered with add_startup_function.

Note

The difference to a startup function is that all pre-startup functions will be (system-wide) executed before any startup function.

Parameters

f: The function ‘f’ will be called from inside a HPX thread before hpx_main is executed. This is very useful to setup the runtime environment of the application (install performance counters, etc.)

void add_startup_function(startup_function_type f)¶

Add a function to be executed inside a HPX thread before hpx_main

Parameters

f: The function ‘f’ will be called from inside a HPX thread before hpx_main is executed. This is very useful to setup the runtime environment of the application (install performance counters, etc.)

void add_pre_shutdown_function(shutdown_function_type f)¶

Add a function to be executed inside a HPX thread during hpx::finalize, but guaranteed before any of the shutdown functions is executed.

Note

The difference to a shutdown function is that all pre-shutdown functions will be (system-wide) executed before any shutdown function.

Parameters

f: The function ‘f’ will be called from inside a HPX thread while hpx::finalize is executed. This is very useful to tear down the runtime environment of the application (uninstall performance counters, etc.)

void add_shutdown_function(shutdown_function_type f)¶

Add a function to be executed inside a HPX thread during hpx::finalize

Parameters

f: The function ‘f’ will be called from inside a HPX thread while hpx::finalize is executed. This is very useful to tear down the runtime environment of the application (uninstall performance counters, etc.)

hpx::util::io_service_pool *get_thread_pool(char const *name)¶: Access one of the internal thread pools (io_service instances) HPX is using to perform specific tasks. The three possible values for the argument name are “main_pool”, “io_pool”, “parcel_pool”, and “timer_pool”. For any other argument value the function will return zero.

bool register_thread(char const *name, std::size_t num = 0, bool service_thread = true, error_code &ec = throws)¶: Register an external OS-thread with HPX.

notification_policy_type get_notification_policy(char const *prefix, runtime_local::os_thread_type type)¶: Generate a new notification policy instance for the given thread name prefix

std::uint32_t get_locality_id(error_code &ec) const¶

std::size_t get_num_worker_threads() const¶

std::uint32_t get_num_localities(hpx::launch::sync_policy, error_code &ec) const¶

std::uint32_t get_initial_num_localities() const¶

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

std::uint32_t get_num_localities(hpx::launch::sync_policy, components::component_type type, error_code &ec) const¶

lcos::future<std::uint32_t> get_num_localities(components::component_type type) const¶

std::uint32_t assign_cores(std::string const &locality_basename, std::uint32_t num_threads)¶

std::uint32_t assign_cores()¶

Private Types

using used_cores_map_type = std::map<std::string, std::uint32_t>¶

Private Functions

runtime_distributed *This()¶

threads::thread_result_type run_helper(util::function_nonser<runtime::hpx_main_function_type> const &func, int &result)¶

void wait_helper(std::mutex &mtx, std::condition_variable &cond, bool &running)¶

void init_tss_helper(char const *context, runtime_local::os_thread_type type, std::size_t local_thread_num, std::size_t global_thread_num, char const *pool_name, char const *postfix, bool service_thread)¶

void deinit_tss_helper(char const *context, std::size_t num)¶

void init_tss_ex(std::string const &locality, char const *context, runtime_local::os_thread_type type, std::size_t local_thread_num, std::size_t global_thread_num, char const *pool_name, char const *postfix, bool service_thread, error_code &ec)¶

Private Members

runtime_mode mode_¶

util::unique_id_ranges id_pool_¶

naming::resolver_client agas_client_¶

applier::applier applier_¶

used_cores_map_type used_cores_map_¶

std::unique_ptr<components::server::runtime_support> runtime_support_¶

std::shared_ptr<util::query_counters> active_counters_¶

Private Static Functions

static void default_errorsink(std::string const&)¶

namespace hpx

Functions

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

namespace hpx

Functions

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.