runtime_local.hpp#

See Public API for a list of names and headers that are part of the public HPX API.

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

explicit 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(hpx::function<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(hpx::function<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.

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.
Returns: This function will return the value as returned as the result of the invocation of the function object given by the parameter func.

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.

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

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

virtual int start(hpx::function<hpx_main_function_type> const &func, bool blocking = false)#

Start the runtime system.

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.

Returns

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.

virtual int start(bool blocking = false)#

Start the runtime system.

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

virtual int wait()#

Wait for the shutdown action to be executed.

Returns: 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)#

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:

Note

This function should be called for each thread exactly once. It will fail if it is called more than once.

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.

Returns

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

Returns: 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(hpx::function<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 hpx::future<std::uint32_t> get_num_localities() const#

virtual std::string get_locality_name() const#

inline virtual std::uint32_t assign_cores(std::string const&, std::uint32_t)#

inline 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<hpx::function<void()>>#

Protected Functions

explicit 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(hpx::function<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_#

mutable 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

static 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)#