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)

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)
void set_notification_policies(notification_policy_type &&notifier, threads::detail::network_background_callback_type network_background_callback)
void init()

Common initialization for different constructors.

void init_global_data()
void deinit_global_data()
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()
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()