Additional runtime functions

Besides the runtime functions defined by the language standard, the C++ runtime system offers a number of useful functions with which programs can be made more reliable. Note, however, that programs which use these functions are not ANSI C++-compliant and are hence not portable.
The following additional functions are available: unwind_exit, get_caught_object_typeid, can_throw and can_rethrow.
These functions are all part of the _SNI_extensions namespace.

The EO_flag_set data type used for the arguments is also defined in the _SNI_extensions namespace.

Data Type EO_flag_set

The data type EO_flag_set is used to display properties of an exception object.

The definition of EO_flag_set in the language mode C++ V3 differs from the definition in language mode C++ 2017 or C++ 2020.

EO_flag_set in language mode C++ 2017 or C++ 2020

In the language mode C++ 2017 or C++ 2020 EO_flag_set is defined as follows:

namespace _SNI_extensions {
      typedef unsigned int EO_flag_set;
}

The following flag values are defined for data items of type EO_flag_set:

EO_NO_FLAGS             : not a pointer type / no flag set
EO_IS_POINTER           : pointer type
EO_POINTER_TO_CONST     : pointer to a constant object
EO_POINTER_TO_VOLATILE  : pointer to a volatile object
EO_LAST                 : last element of a flag array

EO_flag_set in language mode C++ V3

In the language mode C++ V3 EO_flag_set is defined as follows:

namespace _SNI_extensions {
      typedef unsigned char EO_flag_set;
}

The following flag values are defined for data items of type EO_flag_set:

EO_NO_FLAGS             : not a pointer type
EO_IS_POINTER           : pointer type
EO_POINTER_TO_CONST     : pointer to a constant object
EO_POINTER_TO_VOLATILE  : pointer to a volatile object

unwind_exit - Unwind stack before exiting program

The unwind_exit function, like exit, is used to terminate a program. In contrast to exit, however, a call to unwind_exit causes the following additional actions to be performed before the program is exited:

• All automatic objects on the runtime stack that have not yet been deleted are destroyed.

• All exception objects that have not been exited are destroyed.

This is followed by the destruction of global objects as in the case of exit.

Note that neither exit nor unwind_exit will destroy objects on the heap that have not been released.

If a destructor called by unwind_exit ends with an exception, terminate is called implicitly. It is therefore advisable to call unwind_exit in the terminate_handler as well. This will guarantee that the destructors for all automatic and exception objects are eventually called in any case. This cannot result in an endless loop.

The unwind_exit function can be called from any part of the program (like exit), especially from a terminate_handler. Like exit, it is supplied with an exit status as an argument (and with the same effect).

The prototype of the unwind_exit function is declared in the <exception> header:

#include <exception>
namespace _SNI_extensions {
      void unwind_exit(int status);
}

get_caught_object_typeid - Determine type of caught exception object

The function get_caught_object_typeid can be used to determine the type of a caught exception object. It returns the type of the exception object that was most recently caught and was not finished. If no caught and unfinished exception object exists, an exception of type bad_typeid is thrown.

The function get_caught_object_typeid can be called in any handler (terminate_handler, unexpected_handler, catch(...) {...}) to obtain information about the type of the caught exception object. This can be useful in diagnosing program runtime errors.

The type of the caught exception object is returned as a reference to a type_info object. The class type_info and the prototype of the function get_caught_object_typeid are declared in the <typeinfo> header:

The definition of the function get_caught_object_typeid in the language mode C++ V3 differs from the definition in language mode C++ 2017 or C++ 2020.

get_caught_object_typeid in language mode C++ 2017 or C++ 2020

The prototype of the function get_caught_object_typeid is declared in the header file <typeinfo> as follows

#include <typeinfo>
namespace _SNI_extensions {
      const type_info &get_caught_object_typeid(EO_flag_set *pflags, EO_flag_set **ppflags);
}

If the arguments to get_caught_object_typeid are non-zero, they are interpreted as addresses to receive information on whether the caught object is a pointer.

The behavior depends on whether the exception object is not a pointer, a simple pointer or a pointer to a pointer.

If the exception object is not a pointer, its type is returned as a reference to a type_info object. *pflags will be set to EO_NO_FLAGS. *ppflags will be set to zero.

If the exception object is a pointer to a non-pointer, the type pointed to is returned. *pflags will be set to EO_IS_POINTER, (EO_IS_POINTER | EO_POINTER_TO_CONST), (EO_IS_POINTER | EO_POINTER_TO_VOLATILE) or (EO_IS_POINTER | EO_POINTER_TO_CONST | EO_POINTER_TO_VOLATILE) depending on type attributes (const and/or volatile). *ppflags will be set to zero.

If the excpetion object is a pointer to a pointer, the first non-pointer type after the pointer chain is returned. *pflags will be set to EO_NO_FLAGS. An array is built to describe the attributes of each pointer in the chain. To indicate const the flag value EO_POINTER_TO_CONST is used, to indicate volatile the flag value EO_POINTER_TO_VOLATILE is used. The last element of the array has the additional flag value EO_LAST. *ppflags will be set to point to this array.

As an example: if the exception object is of type "volatile char * *const *" the array { EO_POINTER_TO_CONST, EO_NO_FLAGS, EO_POINTER_TO_VOLATILE|EO_LAST } is built.

get_caught_object_typeid in language mode C++ V3

The prototype of the function get_caught_object_typeid is declared in the header file <typeinfo> as follows

#include <typeinfo>
namespace _SNI_extensions {
      const type_info &get_caught_object_typeid(EO_flag_set *pflags);
}

If the exception object is not a pointer, its type is returned as a reference to a type_info object. If the exception object is a pointer, the type pointed to is returned. If the argument to get_caught_object_typeid is non-zero, it is interpreted as an address to receive information on whether the caught object is a pointer, and if it is, also the type attributes applicable to the object pointed to (values see above). As an example: when a const char * was thrown, the typeid of char will be returned and *pflags will be set to (EO_IS_POINTER | EO_POINTER_TO_CONST) .

can_throw - Check for terminate or unexpected on throwing an object

The function can_throw (predicate) checks whether an exception of the specified type can be thrown without resulting in a call to terminate or unexpected.

#include <typeinfo>
namespace _SNI_extensions {
    bool can_throw(const std::type_info &typeid_to_check,
                   EO_flag_set flags = EO_NO_FLAGS);
}

typeid_to_check must be a non-pointer type of an exception object.

flags can be used to specify whether the type of exception to be actually checked is a pointer or whether it is a const or volatile (values see above)

If the flags argument is not specified, EO_NO_FLAGS (not a pointer type) is set by default.

can_rethrow - Check for terminate or unexpected on rethrowing an object

The function can_rethrow (predicate) checks whether an exception can be rethrown (throw;) without resulting in a call to terminate or unexpected.

#include <typeinfo>
namespace _SNI_extensions {
    bool can_rethrow(void); 
}