hpx/runtime_local/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.
Public Functions
-
virtual notification_policy_type
get_notification_policy
(char const *prefix, runtime_local::os_thread_type type)¶
-
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
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¶
-
util::thread_mapper &
get_thread_mapper
()¶ Return a reference to the internal PAPI thread manager.
-
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.
- 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 int
start
(hpx::function<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
(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::uint32_t
get_num_localities
(hpx::launch::sync_policy, error_code &ec) const¶
Public Static Functions
Protected Functions
-
runtime
(hpx::util::runtime_configuration &rtcfg)¶
-
void
set_notification_policies
(notification_policy_type &¬ifier, 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)¶
Protected Attributes
-
on_exit_type
on_exit_functions_
¶
-
hpx::util::runtime_configuration
rtcfg_
¶
-
long
instance_number_
¶
-
std::unique_ptr<util::thread_mapper>
thread_support_
¶
-
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_
¶
-
notification_policy_type
main_pool_notifier_
¶
-
util::io_service_pool
main_pool_
¶
-
notification_policy_type
notifier_
¶
-
std::unique_ptr<hpx::threads::threadmanager>
thread_manager_
¶
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
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_
¶
-
using
-
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
-
char const *
-
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)¶
-
bool
-
void