init_runtime¶

The contents of this module can be included with the header hpx/modules/init_runtime.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/init_runtime.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx

Functions

int finalize(double shutdown_timeout, double localwait = -1.0, error_code &ec = throws)¶

Main function to gracefully terminate the HPX runtime system.

The function hpx::finalize is the main way to (gracefully) exit any HPX application. It should be called from one locality only (usually the console) and it will notify all connected localities to finish execution. Only after all other localities have exited this function will return, allowing to exit the console locality as well.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on all localities.

The default value (

-1.0) will try to find a globally set timeout value (can be set as the configuration parameter hpx.shutdown_timeout), and if that is not set or -1.0 as well, it will disable any timeout, each connected locality will wait for all existing HPX-threads to terminate.

Parameters

shutdown_timeout: This parameter allows to specify a timeout (in microseconds), specifying how long any of the connected localities should wait for pending tasks to be executed. After this timeout, all suspended HPX-threads will be aborted. Note, that this function will not abort any running HPX-threads. In any case the shutdown will not proceed as long as there is at least one pending/running HPX-thread.

The default value (

-1.0) will try to find a globally set wait time value (can be set as the configuration parameter “hpx.finalize_wait_time”), and if this is not set or -1.0 as well, it will disable any addition local wait time before proceeding.

Parameters

localwait: This parameter allows to specify a local wait time (in microseconds) before the connected localities will be notified and the overall shutdown process starts.

This function will block and wait for all connected localities to exit before returning to the caller. It should be the last HPX-function called by any application.

Return

This function will always return zero.

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.

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.

Using this function is an alternative to hpx::disconnect, these functions do not need to be called both.

int finalize(error_code &ec = throws)¶

Main function to gracefully terminate the HPX runtime system.

The function hpx::finalize is the main way to (gracefully) exit any HPX application. It should be called from one locality only (usually the console) and it will notify all connected localities to finish execution. Only after all other localities have exited this function will return, allowing to exit the console locality as well.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on all localities.

This function will block and wait for all connected localities to exit before returning to the caller. It should be the last HPX-function called by any application.

Return

This function will always return zero.

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.

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.

Using this function is an alternative to hpx::disconnect, these functions do not need to be called both.

HPX_NORETURN void hpx::terminate()

Terminate any application non-gracefully.

The function hpx::terminate is the non-graceful way to exit any application immediately. It can be called from any locality and will terminate all localities currently used by the application.

Note: This function will cause HPX to call std::terminate() on all localities associated with this application. If the function is called not from an HPX thread it will fail and return an error using the argument ec.

int disconnect(double shutdown_timeout, double localwait = -1.0, error_code &ec = throws)¶

Disconnect this locality from the application.

The function hpx::disconnect can be used to disconnect a locality from a running HPX application.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on this locality.

The default value (

-1.0) will try to find a globally set timeout value (can be set as the configuration parameter “hpx.shutdown_timeout”), and if that is not set or -1.0 as well, it will disable any timeout, each connected locality will wait for all existing HPX-threads to terminate.

Parameters

shutdown_timeout: This parameter allows to specify a timeout (in microseconds), specifying how long this locality should wait for pending tasks to be executed. After this timeout, all suspended HPX-threads will be aborted. Note, that this function will not abort any running HPX-threads. In any case the shutdown will not proceed as long as there is at least one pending/running HPX-thread.

The default value (

-1.0) will try to find a globally set wait time value (can be set as the configuration parameter hpx.finalize_wait_time), and if this is not set or -1.0 as well, it will disable any addition local wait time before proceeding.

Parameters

localwait: This parameter allows to specify a local wait time (in microseconds) before the connected localities will be notified and the overall shutdown process starts.

This function will block and wait for this locality to finish executing before returning to the caller. It should be the last HPX-function called by any locality being disconnected.

Return

This function will always return zero.

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.

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.

int disconnect(error_code &ec = throws)¶

Disconnect this locality from the application.

The function hpx::disconnect can be used to disconnect a locality from a running HPX application.

During the execution of this function the runtime system will invoke all registered shutdown functions (see hpx::init) on this locality.

This function will block and wait for this locality to finish executing before returning to the caller. It should be the last HPX-function called by any locality being disconnected.

Return

This function will always return zero.

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.

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.

int stop(error_code &ec = throws)¶

Stop the runtime system.

This function will block and wait for this locality to finish executing before returning to the caller. It should be the last HPX-function called on every locality. This function should be used only if the runtime system was started using

hpx::start.

Return: The function returns the value, which has been returned from the user supplied main HPX function (usually hpx_main).

namespace hpx

Functions

int init(std::function<int(hpx::program_options::variables_map&)> f, int argc, char **argv, init_params const &params = init_params(), )¶

Main entry point for launching the HPX runtime system.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. This overload will not call hpx_main.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread.

Return

The function returns the value, which has been returned from the user supplied f.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::init function (See documentation of hpx::init_params)

int init(std::function<int(int, char**)> f, int argc, char **argv, init_params const &params = init_params(), )¶

Main entry point for launching the HPX runtime system.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. This overload will not call hpx_main.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread.

Return

The function returns the value, which has been returned from the user supplied f.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::init function (See documentation of hpx::init_params)

int init(int argc, char **argv, init_params const &params = init_params())¶

Main entry point for launching the HPX runtime system.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. This overload will not call hpx_main.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread.

Return

The function returns the value, which has been returned from the user supplied f.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::init function (See documentation of hpx::init_params)

int init(std::nullptr_t f, int argc, char **argv, init_params const &params = init_params())¶

Main entry point for launching the HPX runtime system.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. This overload will not call hpx_main.

This is the main entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread.

Return

The function returns the value, which has been returned from the user supplied f.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::init function (See documentation of hpx::init_params)

int init(init_params const &params = init_params())¶

Main entry point for launching the HPX runtime system.

This is a simplified main entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings).

Return

The function returns the value, which has been returned from hpx_main (or 0 when executed in worker mode).

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. If not command line arguments are passed, console mode is assumed.

Note

If no command line arguments are passed the HPX runtime system will not support any of the default command line options as described in the section ‘HPX Command Line Options’.

Parameters

params: [in] The parameters to the hpx::init function (See documentation of hpx::init_params)

namespace hpx

struct init_params¶

#include <hpx_init_params.hpp>

Parameters used to initialize the HPX runtime through hpx::init and hpx::start.

Public Members

std::reference_wrapper<hpx::program_options::options_description const> desc_cmdline = detail::default_desc¶

std::vector<std::string> cfg¶

startup_function_type startup¶

shutdown_function_type shutdown¶

hpx::runtime_mode mode = ::hpx::runtime_mode::default_¶

hpx::resource::partitioner_mode rp_mode = ::hpx::resource::mode_default ¶

hpx::resource::rp_callback_type rp_callback¶

namespace hpx

Functions

bool start(std::function<int(hpx::program_options::variables_map&)> f, int argc, char **argv, init_params const &params = init_params(), )¶

Main non-blocking entry point for launching the HPX runtime system.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will not call hpx_main.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as an HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::start function (See documentation of hpx::init_params)

bool start(std::function<int(int, char**)> f, int argc, char **argv, init_params const &params = init_params(), )¶

Main non-blocking entry point for launching the HPX runtime system.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will not call hpx_main.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as an HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::start function (See documentation of hpx::init_params)

bool start(int argc, char **argv, init_params const &params = init_params())¶

Main non-blocking entry point for launching the HPX runtime system.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will not call hpx_main.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as an HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::start function (See documentation of hpx::init_params)

bool start(std::nullptr_t f, int argc, char **argv, init_params const &params = init_params())¶

Main non-blocking entry point for launching the HPX runtime system.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users main() function. It will set up the HPX runtime environment and schedule the function given by f as a HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution. This overload will not call hpx_main.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as an HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

If the parameter mode is not given (defaulted), the created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. Otherwise it will be executed as specified by the parametermode.

Parameters

f: [in] The function to be scheduled as an HPX thread. Usually this function represents the main entry point of any HPX application. If f is nullptr the HPX runtime environment will be started without invoking f.
argc: [in] The number of command line arguments passed in argv. This is usually the unchanged value as passed by the operating system (to main()).
argv: [in] The command line arguments for this application, usually that is the value as passed by the operating system (to main()).
params: [in] The parameters to the hpx::start function (See documentation of hpx::init_params)

bool start(init_params const &params = init_params())¶

Main non-blocking entry point for launching the HPX runtime system.

This is a simplified main, non-blocking entry point, which can be used to set up the runtime for an HPX application (the runtime system will be set up in console mode or worker mode depending on the command line settings). It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

This is the main, non-blocking entry point for any HPX application. This function (or one of its overloads below) should be called from the users

main() function. It will set up the HPX runtime environment and schedule the function given by f as an HPX thread. It will return immediately after that. Use hpx::wait and hpx::stop to synchronize with the runtime system’s execution.

Return

The function returns true if command line processing succeeded and the runtime system was started successfully. It will return false otherwise.

Note

The created runtime system instance will be executed in console or worker mode depending on the command line arguments passed in argc/argv. If not command line arguments are passed, console mode is assumed.

Note

If no command line arguments are passed the HPX runtime system will not support any of the default command line options as described in the section ‘HPX Command Line Options’.

Parameters

params: [in] The parameters to the hpx::start function (See documentation of hpx::init_params)

namespace hpx

Functions

int suspend(error_code &ec = throws)¶

Suspend the runtime system.

The function hpx::suspend is used to suspend the HPX runtime system. It can only be used when running HPX on a single locality. It will block waiting for all thread pools to be empty. This function only be called when the runtime is running, or already suspended in which case this function will do nothing.

Return

This function will always return zero.

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.

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.

int resume(error_code &ec = throws)¶

Resume the HPX runtime system.

The function hpx::resume is used to resume the HPX runtime system. It can only be used when running HPX on a single locality. It will block waiting for all thread pools to be resumed. This function only be called when the runtime suspended, or already running in which case this function will do nothing.

Return

This function will always return zero.

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.

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_startup¶

Functions

std::vector<std::string> user_main_config(std::vector<std::string> const &cfg)¶

Variables

std::vector<std::string> (*user_main_config_function)(std::vector<std::string> const&)¶