runtime_local¶

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

Defines

HPX_REGISTER_STARTUP_SHUTDOWN_REGISTRY(RegistryType, componentname)¶: This macro is used to register the given component factory with Hpx.Plugin. This macro has to be used for each of the components.

HPX_REGISTER_STARTUP_SHUTDOWN_REGISTRY_DYNAMIC(RegistryType, componentname)¶

HPX_REGISTER_STARTUP_SHUTDOWN_FUNCTIONS()¶: This macro is used to define the required Hpx.Plugin entry point for the startup/shutdown registry. This macro has to be used in not more than one compilation unit of a component module.

HPX_REGISTER_STARTUP_SHUTDOWN_FUNCTIONS_DYNAMIC()¶

namespace hpx

namespace components

struct component_startup_shutdown_base¶

#include <component_startup_shutdown_base.hpp>

The component_startup_shutdown_base has to be used as a base class for all component startup/shutdown registries.

Public Functions

virtual ~component_startup_shutdown_base()¶

virtual bool get_startup_function(startup_function_type &startup, bool &pre_startup) = 0¶

Return any startup function for this component.

Return

Returns true if the parameter startup has been successfully initialized with the startup function.

Parameters

startup: [in, out] The module is expected to fill this function object with a reference to a startup function. This function will be executed by the runtime system during system startup.

virtual bool get_shutdown_function(shutdown_function_type &shutdown, bool &pre_shutdown) = 0¶

Return any startup function for this component.

Return

Returns true if the parameter shutdown has been successfully initialized with the shutdown function.

Parameters

shutdown: [in, out] The module is expected to fill this function object with a reference to a startup function. This function will be executed by the runtime system during system startup.

namespace hpx

Functions

std::string get_config_entry(std::string const &key, std::string const &dflt)¶: Retrieve the string value of a configuration entry given by key.

std::string get_config_entry(std::string const &key, std::size_t dflt)¶: Retrieve the integer value of a configuration entry given by key.

void set_config_entry(std::string const &key, std::string const &value)¶: Set the string value of a configuration entry given by key.

void set_config_entry(std::string const &key, std::size_t value)¶: Set the integer value of a configuration entry given by key.

void set_config_entry_callback(std::string const &key, util::function_nonser<void(std::string const&, std::string const&)> const &callback)¶: Set the string value of a configuration entry given by key.

namespace hpx

Functions

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

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

namespace hpx

namespace util

Functions

void may_attach_debugger(std::string const &category)¶: Attaches a debugger if category is equal to the configuration entry hpx.attach-debugger.

namespace hpx

Functions

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.

namespace hpx

Functions

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)

namespace hpx

Functions

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.

namespace hpx

Functions

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.

namespace hpx

Functions

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

namespace hpx

namespace util

class interval_timer¶

Public Functions

HPX_NON_COPYABLE(interval_timer)¶

interval_timer()¶

interval_timer(util::function_nonser<bool()> const &fstd::int64_t microsecs, std::string const &description = "", bool pre_shutdown = false, )¶

interval_timer(util::function_nonser<bool()> const &futil::function_nonser<void()> const &on_termstd::int64_t microsecs, std::string const &description = "", bool pre_shutdown = false, )¶

interval_timer(util::function_nonser<bool()> const &fhpx::chrono::steady_duration const &rel_time, char const *description = "", bool pre_shutdown = false, )¶

interval_timer(util::function_nonser<bool()> const &futil::function_nonser<void()> const &on_termhpx::chrono::steady_duration const &rel_time, char const *description = "", bool pre_shutdown = false, )¶

~interval_timer()¶

bool start(bool evaluate = true)¶

bool stop(bool terminate = false)¶

bool restart(bool evaluate = true)¶

bool is_started() const¶

bool is_terminated() const¶

std::int64_t get_interval() const¶

void change_interval(std::int64_t new_interval)¶

void change_interval(hpx::chrono::steady_duration const &new_interval)¶

Private Members

std::shared_ptr<detail::interval_timer> timer_¶

namespace hpx

namespace runtime_local¶

Enums

enum os_thread_type¶

Types of kernel threads registered with the runtime.

Values:

unknown = -1¶

main_thread = 0¶: kernel thread represents main thread

worker_thread¶: kernel thread is used to schedule HPX threads

io_thread¶: kernel thread can be used for IO operations

timer_thread¶: kernel is used by timer operations

parcel_thread¶: kernel is used by networking operations

custom_thread¶: kernel is registered by the application

Functions

std::string get_os_thread_type_name(os_thread_type type)¶: Return a human-readable name representing one of the kernel thread types.

struct os_thread_data¶

#include <os_thread_type.hpp>

Registration data for kernel threads that is maintained by the runtime internally

Public Members

std::string label_¶: name used for thread registration

std::thread::id id_¶: thread id of corresponding kernel thread

std::uint64_t native_handle_¶: the threads native handle

os_thread_type type_¶: HPX thread type.

namespace hpx

namespace util

class pool_timer¶

Public Functions

HPX_NON_COPYABLE(pool_timer)¶

pool_timer()¶

pool_timer(util::function_nonser<bool()> const &futil::function_nonser<void()> const &on_termstd::string const &description = "", bool pre_shutdown = true, )¶

~pool_timer()¶

bool start(hpx::chrono::steady_duration const &time_duration, bool evaluate = false)¶

bool stop()¶

bool is_started() const¶

bool is_terminated() const¶

Private Members

std::shared_ptr<detail::pool_timer> timer_¶

namespace hpx

Functions

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.

namespace hpx

namespace threads

Functions

template<typename F, typename ...Ts> util::invoke_result<F, Ts...>::type run_as_hpx_thread(F const &f, Ts&&... vs)¶

namespace hpx

namespace threads

Functions

template<typename F, typename ...Ts> hpx::future<typename util::invoke_result<F, Ts...>::type> run_as_os_thread(F &&f, Ts&&... vs)¶

namespace hpx

Functions

void set_error_handlers()¶

class runtime¶

Public Types

using notification_policy_type = threads::policies::callback_notifier ¶: Generate a new notification policy instance for the given thread name prefix

using hpx_main_function_type = int()¶: The hpx_main_function_type is the default function type usable as the main HPX thread function.

using hpx_errorsink_function_type = void(std::uint32_t, std::string const&)¶

Public Functions

virtual notification_policy_type get_notification_policy(char const *prefix, runtime_local::os_thread_type type)¶

state get_state() const¶

void set_state(state s)¶

runtime(hpx::util::runtime_configuration &rtcfg, bool initialize = true)¶: Construct a new HPX runtime instance.

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

void on_exit(util::function_nonser<void()> const &f)¶: Manage list of functions to call on exit.

void starting()¶: Manage runtime ‘stopped’ state.

void stopping()¶: Call all registered on_exit functions.

bool stopped() const¶: This accessor returns whether the runtime instance has been stopped.

hpx::util::runtime_configuration &get_config()¶: access configuration information

hpx::util::runtime_configuration const &get_config() const¶

std::size_t get_instance_number() const¶

util::thread_mapper &get_thread_mapper()¶: Return a reference to the internal PAPI thread manager.

threads::topology const &get_topology() const¶

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

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

virtual void rethrow_exception()¶: Rethrow any stored exception (to be called after stop())

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

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

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

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

virtual int suspend()¶: Suspend the runtime system.

virtual int resume()¶: Resume the runtime system.

virtual int finalize(double)¶

virtual bool is_networking_enabled()¶: Return true if networking is enabled.

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

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

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

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

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

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

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

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

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

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

This function should be called from any OS-thread which is external to HPX (not created by HPX), but which needs to access HPX functionality, such as setting a value on a promise or similar.

‘main’, ‘io’, ‘timer’, ‘parcel’, ‘worker’

Note

The function will compose a thread name of the form ‘<name>-thread#<num>’ which is used to register the thread. It is the user’s responsibility to ensure that each (composed) thread name is unique. HPX internally uses the following names for the threads it creates, do not reuse those:

Parameters

name: [in] The name to use for thread registration.
num: [in] The sequence number to use for thread registration. The default for this parameter is zero.
service_thread: [in] The thread should be registered as a service thread. The default for this parameter is ‘true’. Any service threads will be pinned to cores not currently used by any of the HPX worker threads.

Note: This function should be called for each thread exactly once. It will fail if it is called more than once.
Return: This function will return whether the requested operation succeeded or not.

virtual bool unregister_thread()¶

Unregister an external OS-thread with HPX.

This function will unregister any external OS-thread from HPX.

Note: This function should be called for each thread exactly once. It will fail if it is called more than once. It will fail as well if the thread has not been registered before (see register_thread).
Return: This function will return whether the requested operation succeeded or not.

virtual runtime_local::os_thread_data get_os_thread_data(std::string const &label) const¶: Access data for a given OS thread that was previously registered by register_thread.

virtual bool enumerate_os_threads(util::function_nonser<bool(runtime_local::os_thread_data const&)> const &f) const¶: Enumerate all OS threads that have registered with the runtime.

notification_policy_type::on_startstop_type on_start_func() const¶

notification_policy_type::on_startstop_type on_stop_func() const¶

notification_policy_type::on_error_type on_error_func() const¶

notification_policy_type::on_startstop_type on_start_func(notification_policy_type::on_startstop_type&&)¶

notification_policy_type::on_startstop_type on_stop_func(notification_policy_type::on_startstop_type&&)¶

notification_policy_type::on_error_type on_error_func(notification_policy_type::on_error_type&&)¶

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

virtual std::size_t get_num_worker_threads() const¶

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

virtual std::uint32_t get_initial_num_localities() const¶

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

virtual std::string get_locality_name() const¶

virtual std::uint32_t assign_cores(std::string const&, std::uint32_t)¶

virtual std::uint32_t assign_cores()¶

Public Static Functions

static std::uint64_t get_system_uptime()¶: Return the system uptime measure on the thread executing this call.

Protected Types

using on_exit_type = std::vector<util::function_nonser<void()>>¶

Protected Functions

runtime(hpx::util::runtime_configuration &rtcfg, notification_policy_type &&notifier, notification_policy_type &&main_pool_notifier, threads::detail::network_background_callback_type network_background_callback, bool initialize)¶

void init()¶: Common initialization for different constructors.

void init_tss()¶

void deinit_tss()¶

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

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

Protected Attributes

on_exit_type on_exit_functions_¶

std::mutex mtx_¶

hpx::util::runtime_configuration rtcfg_¶

long instance_number_¶

std::unique_ptr<util::thread_mapper> thread_support_¶

threads::topology &topology_¶

std::atomic<state> state_¶

notification_policy_type::on_startstop_type on_start_func_¶

notification_policy_type::on_startstop_type on_stop_func_¶

notification_policy_type::on_error_type on_error_func_¶

int result_¶

std::exception_ptr exception_¶

notification_policy_type main_pool_notifier_¶

util::io_service_pool main_pool_¶

notification_policy_type notifier_¶

std::unique_ptr<hpx::threads::threadmanager> thread_manager_¶

Protected Static Attributes

std::atomic<int> instance_number_counter_¶

Private Functions

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

Helper function to stop the runtime.

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.

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

void init_tss_ex(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)¶

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 notify_finalize()¶

void wait_finalize()¶

runtime *This()¶

void call_startup_functions(bool pre_startup)¶

Private Members

std::list<startup_function_type> pre_startup_functions_¶

std::list<startup_function_type> startup_functions_¶

std::list<shutdown_function_type> pre_shutdown_functions_¶

std::list<shutdown_function_type> shutdown_functions_¶

bool stop_called_¶

bool stop_done_¶

std::condition_variable wait_condition_¶

namespace threads

Functions

char const *get_stack_size_name(std::ptrdiff_t size)¶

Returns the stack size name.

Get the readable string representing the given stack size constant.

Parameters

size: this represents the stack size

std::ptrdiff_t get_default_stack_size()¶

Returns the default stack size.

Get the default stack size in bytes.

std::ptrdiff_t get_stack_size(thread_stacksize)¶

Returns the stack size corresponding to the given stack size enumeration.

Get the stack size corresponding to the given stack size enumeration.

Parameters

size: this represents the stack size

namespace util

Functions

bool retrieve_commandline_arguments(hpx::program_options::options_description const &app_options, hpx::program_options::variables_map &vm)¶

bool retrieve_commandline_arguments(std::string const &appname, hpx::program_options::variables_map &vm)¶

namespace hpx

Functions

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 return false.

void unregister_thread(runtime *rt)¶: Unregister the thread from HPX, this should be done once in the end before the external thread exists.

runtime_local::os_thread_data get_os_thread_data(std::string const &label)¶: Access data for a given OS thread that was previously registered by register_thread. This function must be called from a thread that was previously registered with the runtime.

bool enumerate_os_threads(util::function_nonser<bool(os_thread_data const&)> const &f)¶: Enumerate all OS threads that have registered with the runtime.

std::size_t get_runtime_instance_number()¶: Return the runtime instance 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.

namespace hpx

namespace parallel

namespace execution

Enums

enum service_executor_type¶

Values:

io_thread_pool¶: Selects creating a service executor using the I/O pool of threads

parcel_thread_pool¶: Selects creating a service executor using the parcel pool of threads

timer_thread_pool¶: Selects creating a service executor using the timer pool of threads

main_thread¶: Selects creating a service executor using the main thread

struct io_pool_executor : public service_executor ¶

Public Functions

io_pool_executor()¶

struct main_pool_executor : public service_executor ¶

Public Functions

main_pool_executor()¶

struct parcel_pool_executor : public service_executor ¶

Public Functions

parcel_pool_executor(char const *name_suffix = "-tcp")¶

struct service_executor : public service_executor ¶

Public Functions

service_executor(service_executor_type t, char const *name_suffix = "")¶

struct timer_pool_executor : public service_executor ¶

Public Functions

timer_pool_executor()¶

namespace hpx

Typedefs

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.

Functions

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.

namespace hpx

Typedefs

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.

Functions

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

namespace hpx

namespace threads

Functions

bool threadmanager_is(state st)¶

bool threadmanager_is_at_least(state st)¶

namespace hpx

Functions

threads::policies::callback_notifier::on_startstop_type get_thread_on_start_func()¶

Retrieve the currently installed start handler function. This is a function that will be called by HPX for each newly created thread that is made known to the runtime. HPX stores exactly one such function reference, thus the caller needs to make sure any newly registered start function chains into the previous one (see register_thread_on_start_func).

Return: The currently installed error handler function.
Note: This function can be called before the HPX runtime is initialized.

threads::policies::callback_notifier::on_startstop_type get_thread_on_stop_func()¶

Retrieve the currently installed stop handler function. This is a function that will be called by HPX for each newly created thread that is made known to the runtime. HPX stores exactly one such function reference, thus the caller needs to make sure any newly registered stop function chains into the previous one (see register_thread_on_stop_func).

Return: The currently installed error handler function.
Note: This function can be called before the HPX runtime is initialized.

threads::policies::callback_notifier::on_error_type get_thread_on_error_func()¶

Retrieve the currently installed error handler function. This is a function that will be called by HPX for each newly created thread that is made known to the runtime. HPX stores exactly one such function reference, thus the caller needs to make sure any newly registered error function chains into the previous one (see register_thread_on_error_func).

Return: The currently installed error handler function.
Note: This function can be called before the HPX runtime is initialized.

threads::policies::callback_notifier::on_startstop_type register_thread_on_start_func(threads::policies::callback_notifier::on_startstop_type &&f)¶

Set the currently installed start handler function. This is a function that will be called by HPX for each newly created thread that is made known to the runtime. HPX stores exactly one such function reference, thus the caller needs to make sure any newly registered start function chains into the previous one (see get_thread_on_start_func).

Return

The previously registered function of this category. It is the user’s responsibility to call that function if the callback is invoked by HPX.

Note

This function can be called before the HPX runtime is initialized.

Parameters

f: The function to install as the new start handler.

threads::policies::callback_notifier::on_startstop_type register_thread_on_stop_func(threads::policies::callback_notifier::on_startstop_type &&f)¶

Set the currently installed stop handler function. This is a function that will be called by HPX for each newly created thread that is made known to the runtime. HPX stores exactly one such function reference, thus the caller needs to make sure any newly registered stop function chains into the previous one (see get_thread_on_stop_func).

Return

The previously registered function of this category. It is the user’s responsibility to call that function if the callback is invoked by HPX.

Note

This function can be called before the HPX runtime is initialized.

Parameters

f: The function to install as the new stop handler.

threads::policies::callback_notifier::on_error_type register_thread_on_error_func(threads::policies::callback_notifier::on_error_type &&f)¶

Set the currently installed error handler function. This is a function that will be called by HPX for each newly created thread that is made known to the runtime. HPX stores exactly one such function reference, thus the caller needs to make sure any newly registered error function chains into the previous one (see get_thread_on_error_func).

Return

The previously registered function of this category. It is the user’s responsibility to call that function if the callback is invoked by HPX.

Note

This function can be called before the HPX runtime is initialized.

Parameters

f: The function to install as the new error handler.

namespace hpx

namespace util

class thread_mapper¶

Public Types

using callback_type = detail::thread_mapper_callback_type¶

Public Functions

HPX_NON_COPYABLE(thread_mapper)¶

thread_mapper()¶

~thread_mapper()¶

std::uint32_t register_thread(char const *label, runtime_local::os_thread_type type)¶

bool unregister_thread()¶

std::uint32_t get_thread_index(std::string const &label) const¶

std::uint32_t get_thread_count() const¶

bool register_callback(std::uint32_t tix, callback_type const&)¶

bool revoke_callback(std::uint32_t tix)¶

std::thread::id get_thread_id(std::uint32_t tix) const¶

std::uint64_t get_thread_native_handle(std::uint32_t tix) const¶

std::string const &get_thread_label(std::uint32_t tix) const¶

runtime_local::os_thread_type get_thread_type(std::uint32_t tix) const¶

bool enumerate_os_threads(util::function_nonser<bool(os_thread_data const&)> const &f) const¶

os_thread_data get_os_thread_data(std::string const &label) const¶

Public Static Attributes

constexpr std::uint32_t invalid_index = std::uint32_t(-1)¶

constexpr std::uint64_t invalid_tid = std::uint64_t(-1)¶

Private Types

using mutex_type = hpx::lcos::local::spinlock ¶

using thread_map_type = std::vector<detail::os_thread_data>¶

using label_map_type = std::map<std::string, std::size_t>¶

Private Members

mutex_type mtx_¶

thread_map_type thread_map_¶

label_map_type label_map_¶

namespace hpx

namespace resource

Functions

std::size_t get_num_thread_pools()¶: Return the number of thread pools currently managed by the resource_partitioner

std::size_t get_num_threads()¶: Return the number of threads in all thread pools currently managed by the resource_partitioner

std::size_t get_num_threads(std::string const &pool_name)¶: Return the number of threads in the given thread pool currently managed by the resource_partitioner

std::size_t get_num_threads(std::size_t pool_index)¶: Return the number of threads in the given thread pool currently managed by the resource_partitioner

std::size_t get_pool_index(std::string const &pool_name)¶: Return the internal index of the pool given its name.

std::string const &get_pool_name(std::size_t pool_index)¶: Return the name of the pool given its internal index.

threads::thread_pool_base &get_thread_pool(std::string const &pool_name)¶: Return the name of the pool given its name.

threads::thread_pool_base &get_thread_pool(std::size_t pool_index)¶: Return the thread pool given its internal index.

bool pool_exists(std::string const &pool_name)¶: Return true if the pool with the given name exists.

bool pool_exists(std::size_t pool_index)¶: Return true if the pool with the given index exists.

namespace threads

Functions

std::int64_t get_thread_count(thread_schedule_state state = thread_schedule_state::unknown)¶

The function get_thread_count returns the number of currently known threads.

Note

If state == unknown this function will not only return the number of currently existing threads, but will add the number of registered task descriptions (which have not been converted into threads yet).

Parameters

state: [in] This specifies the thread-state for which the number of threads should be retrieved.

std::int64_t get_thread_count(thread_priority priority, thread_schedule_state state = thread_schedule_state::unknown)¶

The function get_thread_count returns the number of currently known threads.

Note

If state == unknown this function will not only return the number of currently existing threads, but will add the number of registered task descriptions (which have not been converted into threads yet).

Parameters

priority: [in] This specifies the thread-priority for which the number of threads should be retrieved.
state: [in] This specifies the thread-state for which the number of threads should be retrieved.

std::int64_t get_idle_core_count()¶: The function get_idle_core_count returns the number of currently idling threads (cores).

mask_type get_idle_core_mask()¶: The function get_idle_core_mask returns a bit-mask representing the currently idling threads (cores).

bool enumerate_threads(util::function_nonser<bool(thread_id_type)> const &f, thread_schedule_state state = thread_schedule_state::unknown, )¶

The function enumerate_threads will invoke the given function f for each thread with a matching thread state.

Parameters

f: [in] The function which should be called for each matching thread. Returning ‘false’ from this function will stop the enumeration process.
state: [in] This specifies the thread-state for which the threads should be enumerated.

namespace hpx

namespace util

namespace debug

Functions

std::vector<hpx::threads::thread_id_type> get_task_ids(hpx::threads::thread_schedule_state state = hpx::threads::thread_schedule_state::suspended)¶

std::vector<hpx::threads::thread_data*> get_task_data(hpx::threads::thread_schedule_state state = hpx::threads::thread_schedule_state::suspended)¶

std::string suspended_task_backtraces()¶