diff --git a/doc/macro_reference.qbk b/doc/macro_reference.qbk index 9bb3fa30..639093ac 100644 --- a/doc/macro_reference.qbk +++ b/doc/macro_reference.qbk @@ -1068,7 +1068,7 @@ used to create a mangled name in combination with a predefined macro such a ]] [[`BOOST_FORCEINLINE`][ This macro can be used in place of the `inline` keyword to instruct the compiler -that a function should always be inlined. +that the function should always be inlined. Overuse of this macro can lead to significant bloat, while good use can increase performance in certain cases, such as computation-intensive code built through generative programming techniques. @@ -1088,7 +1088,7 @@ able to debug errors more easily. ]] [[`BOOST_NOINLINE`][ This macro can be used in place of the `inline` keyword to instruct the compiler -that a function should never be inlined. One should typically use this macro +that the function should never be inlined. One should typically use this macro to mark functions that are unlikely to be called, such as error handling routines. Usage example: @@ -1099,6 +1099,26 @@ Usage example: } `` ]] +[[`BOOST_NORETURN`][ +This macro can be used before the function declaration or definition to instruct the compiler +that the function does not return normally (i.e. with a `return` statement or by leaving +the function scope, if the function return type is `void`). The macro can be used to mark +functions that always throw exceptions or terminate the application. Compilers that support +this markup may use this information to specifically organize the code surrounding calls to +this function and suppress warnings about missing `return` statements in the functions +enclosing such calls. + +Usage example: +`` + BOOST_NORETURN void on_error_occurred(const char* descr) + { + throw std::runtime_error(descr); + } +`` + +If the compiler does not support this markup, `BOOST_NORETURN` is defined empty and an +additional macro `BOOST_NO_NORETURN` is defined. +]] [[`BOOST_LIKELY(X)` `BOOST_UNLIKELY(X)`][ These macros communicate to the compiler that the conditional expression `X` is likely diff --git a/include/boost/config/suffix.hpp b/include/boost/config/suffix.hpp index 3bb325ed..a3fda525 100644 --- a/include/boost/config/suffix.hpp +++ b/include/boost/config/suffix.hpp @@ -603,6 +603,21 @@ namespace std{ using ::type_info; } # endif #endif +// BOOST_NORETURN ---------------------------------------------// +// Macro to use before a function declaration/definition to designate +// the function as not returning normally (i.e. with a return statement +// or by leaving the function scope, if the function return type is void). +#if !defined(BOOST_NORETURN) +# if defined(_MSC_VER) +# define BOOST_NORETURN __declspec(noreturn) +# elif defined(__GNUC__) +# define BOOST_NORETURN __attribute__ ((__noreturn__)) +# else +# define BOOST_NO_NORETURN +# define BOOST_NORETURN +# endif +#endif + // Branch prediction hints // These macros are intended to wrap conditional expressions that yield true or false //