errors

The contents of this module can be included with the header hpx/modules/errors.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/errors.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

Enums

enum error

Possible error conditions.

This enumeration lists all possible error conditions which can be reported from any of the API functions.

Values:

success = 0

The operation was successful.

no_success = 1

The operation did failed, but not in an unexpected manner.

not_implemented = 2

The operation is not implemented.

out_of_memory = 3

The operation caused an out of memory condition.

bad_action_code = 4

bad_component_type = 5

The specified component type is not known or otherwise invalid.

network_error = 6

A generic network error occurred.

version_too_new = 7

The version of the network representation for this object is too new.

version_too_old = 8

The version of the network representation for this object is too old.

version_unknown = 9

The version of the network representation for this object is unknown.

unknown_component_address = 10

duplicate_component_address = 11

The given global id has already been registered.

invalid_status = 12

The operation was executed in an invalid status.

bad_parameter = 13

One of the supplied parameters is invalid.

internal_server_error = 14

service_unavailable = 15

bad_request = 16

repeated_request = 17

lock_error = 18

duplicate_console = 19

There is more than one console locality.

no_registered_console = 20

There is no registered console locality available.

startup_timed_out = 21

uninitialized_value = 22

bad_response_type = 23

deadlock = 24

assertion_failure = 25

null_thread_id = 26

Attempt to invoke a API function from a non-HPX thread.

invalid_data = 27

yield_aborted = 28

The yield operation was aborted.

dynamic_link_failure = 29

commandline_option_error = 30

One of the options given on the command line is erroneous.

serialization_error = 31

There was an error during serialization of this object.

unhandled_exception = 32

An unhandled exception has been caught.

kernel_error = 33

The OS kernel reported an error.

broken_task = 34

The task associated with this future object is not available anymore.

task_moved = 35

The task associated with this future object has been moved.

task_already_started = 36

The task associated with this future object has already been started.

future_already_retrieved = 37

The future object has already been retrieved.

promise_already_satisfied = 38

The value for this future object has already been set.

future_does_not_support_cancellation = 39

The future object does not support cancellation.

future_can_not_be_cancelled = 40

The future can’t be canceled at this time.

no_state = 41

The future object has no valid shared state.

broken_promise = 42

The promise has been deleted.

thread_resource_error = 43

future_cancelled = 44

thread_cancelled = 45

thread_not_interruptable = 46

duplicate_component_id = 47

The component type has already been registered.

unknown_error = 48

An unknown error occurred.

bad_plugin_type = 49

The specified plugin type is not known or otherwise invalid.

filesystem_error = 50

The specified file does not exist or other filesystem related error.

bad_function_call = 51

equivalent of std::bad_function_call

task_canceled_exception = 52

parallel::v2::task_canceled_exception

task_block_not_active = 53

task_region is not active

out_of_range = 54

Equivalent to std::out_of_range.

length_error = 55

Equivalent to std::length_error.

migration_needs_retry = 56

migration failed because of global race, retry

namespace hpx

Unnamed Group

error_code make_error_code(error e, throwmode mode = plain)

Returns a new error_code constructed from the given parameters.

error_code make_error_code(error e, char const *func, char const *file, long line, throwmode mode = plain)

error_code make_error_code(error e, char const *msg, throwmode mode = plain)

Returns error_code(e, msg, mode).

error_code make_error_code(error e, char const *msg, char const *func, char const *file, long line, throwmode mode = plain)

error_code make_error_code(error e, std::string const &msg, throwmode mode = plain)

Returns error_code(e, msg, mode).

error_code make_error_code(error e, std::string const &msg, char const *func, char const *file, long line, throwmode mode = plain)

error_code make_error_code(std::exception_ptr const &e)

Functions

std::error_category const &get_hpx_category()

Returns generic HPX error category used for new errors.

std::error_category const &get_hpx_rethrow_category()

Returns generic HPX error category used for errors re-thrown after the exception has been de-serialized.

error_code make_success_code(throwmode mode = plain)

Returns error_code(hpx::success, “success”, mode).

class error_code : public error_code

#include <error_code.hpp>

A hpx::error_code represents an arbitrary error condition.

The class hpx::error_code describes an object used to hold error code values, such as those originating from the operating system or other low-level application program interfaces.

Note

Class hpx::error_code is an adjunct to error reporting by exception

Public Functions

error_code(throwmode mode = plain)

Construct an object of type error_code.

Parameters

• mode: The parameter mode specifies whether the constructed 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).

Exceptions

• nothing:

error_code(error e, throwmode mode = plain)

Construct an object of type error_code.

Parameters

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

• mode: The parameter mode specifies whether the constructed 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).

Exceptions

• nothing:

error_code(error e, char const *func, char const *file, long line, throwmode mode = plain)

Construct an object of type error_code.

Parameters

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

• func: The name of the function where the error was raised.

• file: The file name of the code where the error was raised.

• line: The line number of the code line where the error was raised.

• mode: The parameter mode specifies whether the constructed 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).

Exceptions

• nothing:

error_code(error e, char const *msg, throwmode mode = plain)

Construct an object of type error_code.

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

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

error_code(error e, char const *msg, char const *func, char const *file, long line, throwmode mode = plain)

Construct an object of type error_code.

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.

• func: The name of the function where the error was raised.

• file: The file name of the code where the error was raised.

• line: The line number of the code line where the error was raised.

• mode: The parameter mode specifies whether the constructed 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).

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

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

Construct an object of type error_code.

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

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

error_code(error e, std::string const &msg, char const *func, char const *file, long line, throwmode mode = plain)

Construct an object of type error_code.

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.

• func: The name of the function where the error was raised.

• file: The file name of the code where the error was raised.

• line: The line number of the code line where the error was raised.

• mode: The parameter mode specifies whether the constructed 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).

Exceptions

• std::bad_alloc: (if allocation of a copy of the passed string fails).

std::string get_message() const

Return a reference to the error message stored in the hpx::error_code.

Exceptions

• nothing:

void clear()

Clear this error_code object. The postconditions of invoking this method are.

• value() == hpx::success and category() == hpx::get_hpx_category()

error_code(error_code const &rhs)

Copy constructor for error_code

Note

This function maintains the error category of the left hand side if the right hand side is a success code.

error_code &operator=(error_code const &rhs)

Assignment operator for error_code

Note

This function maintains the error category of the left hand side if the right hand side is a success code.

Private Functions

error_code(int err, hpx::exception const &e)

error_code(std::exception_ptr const &e)

Private Members

std::exception_ptr exception_

Friends

friend hpx::exception

error_code make_error_code(std::exception_ptr const &e)

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.

Return

The error message stored in the exception 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_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.

Exceptions

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

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.

Return

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.

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

Exceptions

• nothing:

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.

Return

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.

See

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.

Exceptions

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

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.

Return

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.

See

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.

Exceptions

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

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.

Return

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.

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

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

exception(error e = success)

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

Parameters

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

exception(std::system_error const &e)

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

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 = 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 = 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()

Destruct a hpx::exception

Exceptions

• nothing:

error get_error() const

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.

Exceptions

• nothing:

error_code get_error_code(throwmode mode = plain) const

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

namespace hpx

Enums

enum throwmode

Encode error category for new error_code.

Values:

plain = 0

rethrow = 1

lightweight = 0x80

Variables

error_code throws

Predefined error_code object used as “throw on error” tag.

The predefined hpx::error_code object hpx::throws is supplied for use as a “throw on error” tag.

Functions that specify an argument in the form ‘error_code& ec=throws’ (with appropriate namespace qualifiers), have the following error handling semantics:

If &ec != &throws and an error occurred: ec.value() returns the implementation specific error number for the particular error that occurred and ec.category() returns the error_category for ec.value().

If &ec != &throws and an error did not occur, ec.clear().

If an error occurs and &ec == &throws, the function throws an exception of type hpx::exception or of a type derived from it. The exception’s get_errorcode() member function returns a reference to an hpx::error_code object with the behavior as specified above.

Defines

HPX_DEFINE_ERROR_INFO(NAME, TYPE)

namespace hpx

Functions

template<typename E>HPX_NORETURN void hpx::throw_with_info(E && e, exception_info  && xi = exception_info ())

template<typename E>HPX_NORETURN void hpx::throw_with_info(E && e, exception_info  const & xi)

template<typename E>
exception_info *get_exception_info(E &e)

template<typename E>
exception_info const *get_exception_info(E const &e)

template<typename E, typename F>
auto invoke_with_exception_info(E const &e, F &&f)

template<typename F>
auto invoke_with_exception_info(std::exception_ptr const &p, F &&f)

template<typename F>
auto invoke_with_exception_info(hpx::error_code const &ec, F &&f)

template<typename Tag, typename Type>
struct error_info

Public Types

template<>
using tag = Tag

template<>
using type = Type

Public Functions

error_info(Type const &value)

error_info(Type &&value)

Public Members

Type _value

class exception_info

Subclassed by hpx::detail::exception_with_info_base

Public Functions

exception_info()

exception_info(exception_info const &other)

exception_info(exception_info &&other)

exception_info &operator=(exception_info const &other)

exception_info &operator=(exception_info &&other)

virtual ~exception_info()

template<typename ...ErrorInfo>
exception_info &set(ErrorInfo&&... tagged_values)

template<typename Tag>
Tag::type const *get() const

Private Types

using node_ptr = std::shared_ptr<detail::exception_info_node_base>

Private Members

node_ptr _data

namespace hpx

class exception_list : public hpx::exception

#include <exception_list.hpp>

The class exception_list is a container of exception_ptr objects parallel algorithms may use to communicate uncaught exceptions encountered during parallel execution to the caller of the algorithm

The type exception_list::const_iterator fulfills the requirements of a forward iterator.

Public Types

using iterator = exception_list_type::const_iterator

bidirectional iterator

Public Functions

std::size_t size() const

The number of exception_ptr objects contained within the exception_list.

Note

Complexity: Constant time.

exception_list_type::const_iterator begin() const

An iterator referring to the first exception_ptr object contained within the exception_list.

exception_list_type::const_iterator end() const

An iterator which is the past-the-end value for the exception_list.

Defines

HPX_THROW_EXCEPTION(errcode, f, ...)

Throw a hpx::exception initialized from the given parameters.

The macro HPX_THROW_EXCEPTION can be used to throw a hpx::exception. The purpose of this macro is to prepend the source file name and line number of the position where the exception is thrown to the error message. Moreover, this associates additional diagnostic information with the exception, such as file name and line number, locality id and thread id, and stack backtrace from the point where the exception was thrown.

The parameter errcode holds the hpx::error code the new exception should encapsulate. The parameter f is expected to hold the name of the function exception is thrown from and the parameter msg holds the error message the new exception should encapsulate.

void raise_exception()
{
    // Throw a hpx::exception initialized from the given parameters.
    // Additionally associate with this exception some detailed
    // diagnostic information about the throw-site.
    HPX_THROW_EXCEPTION(hpx::no_success, "raise_exception", "simulated error");
}

Example:

HPX_THROWS_IF(ec, errcode, f, ...)

Either throw a hpx::exception or initialize hpx::error_code from the given parameters.

The macro HPX_THROWS_IF can be used to either throw a hpx::exception or to initialize a hpx::error_code from the given parameters. If &ec == &hpx::throws, the semantics of this macro are equivalent to HPX_THROW_EXCEPTION. If &ec != &hpx::throws, the hpx::error_code instance ec is initialized instead.

The parameter errcode holds the hpx::error code from which the new exception should be initialized. The parameter f is expected to hold the name of the function exception is thrown from and the parameter msg holds the error message the new exception should encapsulate.