hpx::exception#

Defined in header hpx/exception.hpp.

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

namespace hpx

Typedefs

using custom_exception_info_handler_type = std::function<hpx::exception_info(std::string const&, std::string const&, long, std::string const&)>#
using pre_exception_handler_type = std::function<void()>#

Functions

void set_custom_exception_info_handler(custom_exception_info_handler_type f)#
void set_pre_exception_handler(pre_exception_handler_type f)#
std::string get_error_what(exception_info const &xi)#

Return the error message of the thrown exception.

The function hpx::get_error_what can be used to extract the diagnostic information element representing the error message as stored in the given exception instance.

See also

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

Throws

std::bad_alloc – (if one of the required allocations fails)

Returns

The error message stored in the exception If the exception instance does not hold this information, the function will return an empty string.

error get_error(hpx::exception const &e)#

Return the error code value of the exception thrown.

The function hpx::get_error can be used to extract the diagnostic information element representing the error value code as stored in the given exception instance.

See also

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_backtrace(), hpx::get_error_env(), hpx::get_error_what(), hpx::get_error_config(), hpx::get_error_state()

Parameters

e – 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, hpx::error_code, or std::exception_ptr.

Throws

nothing

Returns

The error value code 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.

error get_error(hpx::error_code const &e)#
std::string get_error_function_name(hpx::exception_info const &xi)#

Return the function name from which the exception was thrown.

The function hpx::get_error_function_name can be used to extract the diagnostic information element representing the name of the function as stored in the given exception instance.

See also

hpx::diagnostic_information(), hpx::get_error_host_name(), hpx::get_error_process_id() 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.

Throws

std::bad_alloc – (if one of the required allocations fails)

Returns

The name of the function from which the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

std::string get_error_file_name(hpx::exception_info const &xi)#

Return the (source code) file name of the function from which the exception was thrown.

The function hpx::get_error_file_name can be used to extract the diagnostic information element representing the name of the source file as stored in the given exception instance.

See also

hpx::diagnostic_information(), hpx::get_error_host_name(), hpx::get_error_process_id(), hpx::get_error_function_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.

Throws

std::bad_alloc – (if one of the required allocations fails)

Returns

The name of the source file of the function from which the exception was thrown. If the exception instance does not hold this information, the function will return an empty string.

long get_error_line_number(hpx::exception_info const &xi)#

Return the line number in the (source code) file of the function from which the exception was thrown.

The function hpx::get_error_line_number can be used to extract the diagnostic information element representing the line number as stored in the given exception instance.

See also

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

Throws

nothing

Returns

The line number of the place where the exception was thrown. If the exception instance does not hold this information, the function will return -1.

class exception : public system_error#
#include <exception.hpp>

A hpx::exception is the main exception type used by HPX to report errors.

The hpx::exception type is the main exception type used by HPX to report errors. Any exceptions thrown by functions in the HPX library are either of this type or of a type derived from it. This implies that it is always safe to use this type only in catch statements guarding HPX library calls.

Subclassed by hpx::exception_list

Public Functions

explicit exception(error e = hpx::error::success)#

Construct a hpx::exception from a hpx::error.

Parameters

e – The parameter e holds the hpx::error code the new exception should encapsulate.

explicit exception(std::system_error const &e)#

Construct a hpx::exception from a boost::system_error.

explicit exception(std::error_code const &e)#

Construct a hpx::exception from a boost::system::error_code (this is new for Boost V1.69). This constructor is required to compensate for the changes introduced as a resolution to LWG3162 (https://cplusplus.github.io/LWG/issue3162).

exception(error e, char const *msg, throwmode mode = throwmode::plain)#

Construct a hpx::exception from a hpx::error and an error message.

Parameters
  • e – The parameter e holds the hpx::error code the new exception should encapsulate.

  • msg – The parameter msg holds the error message the new exception should encapsulate.

  • mode – The parameter mode specifies whether the returned hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

exception(error e, std::string const &msg, throwmode mode = throwmode::plain)#

Construct a hpx::exception from a hpx::error and an error message.

Parameters
  • e – The parameter e holds the hpx::error code the new exception should encapsulate.

  • msg – The parameter msg holds the error message the new exception should encapsulate.

  • mode – The parameter mode specifies whether the returned hpx::error_code belongs to the error category hpx_category (if mode is plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

~exception() override#

Destruct a hpx::exception

Throws

nothing

error get_error() const noexcept#

The function get_error() returns the hpx::error code stored in the referenced instance of a hpx::exception. It returns the hpx::error code this exception instance was constructed from.

Throws

nothing

error_code get_error_code(throwmode mode = throwmode::plain) const noexcept#

The function get_error_code() returns a hpx::error_code which represents the same error condition as this hpx::exception instance.

Parameters

mode – The parameter mode specifies whether the returned hpx::error_code belongs to the error category hpx_category (if mode is throwmode::plain, this is the default) or to the category hpx_category_rethrow (if mode is rethrow).

struct thread_interrupted : public exception#
#include <exception.hpp>

A hpx::thread_interrupted is the exception type used by HPX to interrupt a running HPX thread.

The hpx::thread_interrupted type is the exception type used by HPX to interrupt a running thread.

A running thread can be interrupted by invoking the interrupt() member function of the corresponding hpx::thread object. When the interrupted thread next executes one of the specified interruption points (or if it is currently blocked whilst executing one) with interruption enabled, then a hpx::thread_interrupted exception will be thrown in the interrupted thread. If not caught, this will cause the execution of the interrupted thread to terminate. As with any other exception, the stack will be unwound, and destructors for objects of automatic storage duration will be executed.

If a thread wishes to avoid being interrupted, it can create an instance of hpx::this_thread::disable_interruption. Objects of this class disable interruption for the thread that created them on construction, and restore the interruption state to whatever it was before on destruction.

void f()
{
    // interruption enabled here
    {
        hpx::this_thread::disable_interruption di;
        // interruption disabled
        {
            hpx::this_thread::disable_interruption di2;
            // interruption still disabled
        } // di2 destroyed, interruption state restored
        // interruption still disabled
    } // di destroyed, interruption state restored
    // interruption now enabled
}

The effects of an instance of hpx::this_thread::disable_interruption can be temporarily reversed by constructing an instance of hpx::this_thread::restore_interruption, passing in the hpx::this_thread::disable_interruption object in question. This will restore the interruption state to what it was when the hpx::this_thread::disable_interruption object was constructed, and then disable interruption again when the hpx::this_thread::restore_interruption object is destroyed.

void g()
{
    // interruption enabled here
    {
        hpx::this_thread::disable_interruption di;
        // interruption disabled
        {
            hpx::this_thread::restore_interruption ri(di);
            // interruption now enabled
        } // ri destroyed, interruption disable again
    } // di destroyed, interruption state restored
    // interruption now enabled
}

At any point, the interruption state for the current thread can be queried by calling hpx::this_thread::interruption_enabled().