boost/contract/core/exception.hpp

   1
   2 #ifndef BOOST_CONTRACT_EXCEPTION_HPP_
   3 #define BOOST_CONTRACT_EXCEPTION_HPP_
   4
   5 // Copyright (C) 2008-2018 Lorenzo Caminiti
   6 // Distributed under the Boost Software License, Version 1.0 (see accompanying
   7 // file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt).
   8 // See: http://www.boost.org/doc/libs/release/libs/contract/doc/html/index.html
   9
  10 /** @file
  11 Handle contract assertion failures.
  12 */
  13
  14 // IMPORTANT: Included by contract_macro.hpp so trivial headers only.
  15 #include <boost/contract/core/config.hpp>
  16 #include <boost/contract/detail/declspec.hpp> // No compile-time overhead.
  17 #include <boost/function.hpp>
  18 #include <boost/config.hpp>
  19 #include <exception>
  20 #include <string>
  21
  22 // NOTE: This code should not change (not even its impl) based on the
  23 // CONTRACT_NO_... macros. For example, preconditions_failure() should still
  24 // all the set precondition failure handler even when NO_PRECONDITIONS is
  25 // #defined, because user code might explicitly call precondition_failure()
  26 // (for whatever reason...). Otherwise, the public API of this lib will change.
  27
  28 #ifdef BOOST_CONTRACT_DETAIL_DOXYGEN
  29 // Needed for `std::` prefix to show (but removed via `EXCLUDE_SYMBOLS=std`).
  30 namespace std {
  31     class exception {};
  32     class bad_cast {};
  33 }
  34 #endif
  35
  36 namespace boost { namespace contract {
  37
  38 /**
  39 Public base class for all exceptions directly thrown by this library.
  40
  41 This class does not inherit from @c std::exception because exceptions deriving
  42 from this class will do that (inheriting from @c std::exception,
  43 @c std::bad_cast, etc.).
  44
  45 @see    @RefClass{boost::contract::assertion_failure},
  46         @RefClass{boost::contract::bad_virtual_result_cast},
  47         etc.
  48 */
  49 class BOOST_CONTRACT_DETAIL_DECLSPEC exception {
  50 public:
  51     /**
  52     Destruct this object.
  53
  54     @b Throws: This is declared @c noexcept (or @c throw() before C++11).
  55     */
  56     virtual ~exception() /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */;
  57 };
  58
  59 #ifdef BOOST_MSVC
  60     #pragma warning(push)
  61     #pragma warning(disable: 4275) // Bases w/o DLL spec (bad_cast, etc).
  62     #pragma warning(disable: 4251) // Members w/o DLL spec (string for what_).
  63 #endif
  64
  65 /**
  66 Exception thrown when inconsistent return values are passed to overridden
  67 virtual public functions.
  68
  69 This exception is thrown when programmers pass to this library return value
  70 parameters for public function overrides in derived classes that are not
  71 consistent with the return type parameter passed for the virtual public function
  72 being overridden from the base classes.
  73 This allows this library to give more descriptive error messages in such cases
  74 of misuse.
  75
  76 This exception is internally thrown by this library and programmers should not
  77 need to throw it from user code.
  78
  79 @see    @RefSect{tutorial.public_function_overrides__subcontracting_,
  80         Public Function Overrides}
  81 */
  82 class BOOST_CONTRACT_DETAIL_DECLSPEC bad_virtual_result_cast : // Copy (as str).
  83         public std::bad_cast, public boost::contract::exception {
  84 public:
  85     /**
  86     Construct this object with the name of the from- and to- result types.
  87
  88     @param from_type_name Name of the from-type (source of the cast).
  89     @param to_type_name Name of the to-type (destination of the cast).
  90     */
  91     explicit bad_virtual_result_cast(char const* from_type_name,
  92             char const* to_type_name);
  93
  94     /**
  95     Destruct this object.
  96
  97     @b Throws: This is declared @c noexcept (or @c throw() before C++11).
  98     */
  99     virtual ~bad_virtual_result_cast()
 100             /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */;
 101
 102     /**
 103     Description for this error (containing both from- and to- type names).
 104
 105     @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 106     */
 107     virtual char const* what() const
 108             /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */;
 109
 110 /** @cond */
 111 private:
 112     std::string what_;
 113 /** @endcond */
 114 };
 115
 116 /**
 117 Exception typically used to report a contract assertion failure.
 118
 119 This exception is thrown by code expanded by @RefMacro{BOOST_CONTRACT_ASSERT}
 120 (but it can also be thrown by user code programmed manually without that macro).
 121 This exception is typically used to report contract assertion failures because
 122 it contains detailed information about the file name, line number, and source
 123 code of the asserted condition (so it can be used by this library to provide
 124 detailed error messages when handling contract assertion failures).
 125
 126 However, any other exception can be used to report a contract assertion failure
 127 (including user-defined exceptions).
 128 This library will call the appropriate contract failure handler function
 129 (@RefFunc{boost::contract::precondition_failure}, etc.) when this or any other
 130 exception is thrown while checking contracts (by default, these failure handler
 131 functions print an error message to @c std::cerr and terminate the program, but
 132 they can be customized to take any other action).
 133
 134 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 135         @RefSect{extras.no_macros__and_no_variadic_macros_, No Macros}
 136 */
 137 class BOOST_CONTRACT_DETAIL_DECLSPEC assertion_failure : // Copy (as str, etc.).
 138         public std::exception, public boost::contract::exception {
 139 public:
 140     /**
 141     Construct this object with file name, line number, and source code text of
 142     an assertion condition (all optional).
 143
 144     This constructor can also be used to specify no information (default
 145     constructor), or to specify only file name and line number but not source
 146     code text (because of the parameter default values).
 147
 148     @param file Name of the file containing the assertion (usually set using
 149                 <c>__FILE__</c>).
 150     @param line Number of the line containing the assertion (usually set using
 151                 <c>__LINE__</c>).
 152     @param code Text listing the source code of the assertion condition.
 153     */
 154     explicit assertion_failure(char const* file = "", unsigned long line = 0,
 155             char const* code = "");
 156
 157     /**
 158     Construct this object only with the source code text of the assertion
 159     condition.
 160     @param code Text listing the source code of the assertion condition.
 161     */
 162     explicit assertion_failure(char const* code);
 163
 164     /**
 165     Destruct this object.
 166
 167     @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 168     */
 169     virtual ~assertion_failure()
 170             /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */;
 171
 172     /**
 173     String describing the failed assertion.
 174
 175     @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 176
 177     @return A string formatted similarly to the following:
 178       <c>assertion "`code()`" failed: file "`file()`", line \`line()\`</c>
 179             (where `` indicate execution quotes).
 180             File, line, and code will be omitted from this string if they were
 181             not specified when constructing this object.
 182     */
 183     virtual char const* what() const
 184             /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */;
 185
 186     /**
 187     Name of the file containing the assertion.
 188
 189     @return File name as specified at construction (or @c "" if no file was
 190             specified).
 191     */
 192     char const* file() const;
 193
 194     /**
 195     Number of the line containing the assertion.
 196
 197     @return Line number as specified at construction (or @c 0 if no line number
 198             was specified).
 199     */
 200     unsigned long line() const;
 201
 202     /**
 203     Text listing the source code of the assertion condition.
 204
 205     @return Assertion condition source code as specified at construction (or
 206             @c "" if no source code text was specified).
 207     */
 208     char const* code() const;
 209
 210 /** @cond */
 211 private:
 212     void init();
 213
 214     char const* file_;
 215     unsigned long line_;
 216     char const* code_;
 217     std::string what_;
 218 /** @endcond */
 219 };
 220
 221 #ifdef BOOST_MSVC
 222     #pragma warning(pop)
 223 #endif
 224
 225 /**
 226 Indicate the kind of operation where the contract assertion failed.
 227
 228 This is passed as a parameter to the assertion failure handler functions.
 229 For example, it might be necessary to know in which operation an assertion
 230 failed to make sure exceptions are never thrown from destructors, not even
 231 when contract failure handlers are programmed by users to throw exceptions
 232 instead of terminating the program.
 233
 234 @see @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure}
 235 */
 236 enum from {
 237     /** Assertion failed when checking contracts for constructors. */
 238     from_constructor,
 239
 240     /** Assertion failed when checking contracts for destructors . */
 241     from_destructor,
 242
 243     /**
 244     Assertion failed when checking contracts for functions (members or not,
 245     public or not).
 246     */
 247     from_function
 248 };
 249
 250 /**
 251 Type of assertion failure handler functions (with @c from parameter).
 252
 253 Assertion failure handler functions specified by this type must be functors
 254 returning @c void and taking a single parameter of type
 255 @RefEnum{boost::contract::from}.
 256 For example, this is used to specify contract failure handlers for class
 257 invariants, preconditions, postconditions, and exception guarantees.
 258
 259 @see @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure}
 260 */
 261 typedef boost::function<void (from)> from_failure_handler;
 262
 263 /**
 264 Type of assertion failure handler functions (without @c from parameter).
 265
 266 Assertion failure handler functions specified by this type must be nullary
 267 functors returning @c void.
 268 For example, this is used to specify contract failure handlers for
 269 implementation checks.
 270
 271 @see @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure}
 272 */
 273 typedef boost::function<void ()> failure_handler;
 274
 275 /** @cond */
 276 namespace exception_ {
 277     // Check failure.
 278
 279     BOOST_CONTRACT_DETAIL_DECLSPEC
 280     failure_handler const& set_check_failure_unlocked(failure_handler const& f)
 281             BOOST_NOEXCEPT_OR_NOTHROW;
 282     BOOST_CONTRACT_DETAIL_DECLSPEC
 283     failure_handler const& set_check_failure_locked(failure_handler const& f)
 284             BOOST_NOEXCEPT_OR_NOTHROW;
 285
 286     BOOST_CONTRACT_DETAIL_DECLSPEC
 287     failure_handler get_check_failure_unlocked() BOOST_NOEXCEPT_OR_NOTHROW;
 288     BOOST_CONTRACT_DETAIL_DECLSPEC
 289     failure_handler get_check_failure_locked() BOOST_NOEXCEPT_OR_NOTHROW;
 290
 291     BOOST_CONTRACT_DETAIL_DECLSPEC
 292     void check_failure_unlocked() /* can throw */;
 293     BOOST_CONTRACT_DETAIL_DECLSPEC
 294     void check_failure_locked() /* can throw */;
 295
 296     // Precondition failure.
 297
 298     BOOST_CONTRACT_DETAIL_DECLSPEC
 299     from_failure_handler const& set_pre_failure_unlocked(
 300             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 301     BOOST_CONTRACT_DETAIL_DECLSPEC
 302     from_failure_handler const& set_pre_failure_locked(
 303             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 304
 305     BOOST_CONTRACT_DETAIL_DECLSPEC
 306     from_failure_handler get_pre_failure_unlocked() BOOST_NOEXCEPT_OR_NOTHROW;
 307     BOOST_CONTRACT_DETAIL_DECLSPEC
 308     from_failure_handler get_pre_failure_locked() BOOST_NOEXCEPT_OR_NOTHROW;
 309
 310     BOOST_CONTRACT_DETAIL_DECLSPEC
 311     void pre_failure_unlocked(from where) /* can throw */;
 312     BOOST_CONTRACT_DETAIL_DECLSPEC
 313     void pre_failure_locked(from where) /* can throw */;
 314
 315     // Postcondition failure.
 316
 317     BOOST_CONTRACT_DETAIL_DECLSPEC
 318     from_failure_handler const& set_post_failure_unlocked(
 319             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 320     BOOST_CONTRACT_DETAIL_DECLSPEC
 321     from_failure_handler const& set_post_failure_locked(
 322             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 323
 324     BOOST_CONTRACT_DETAIL_DECLSPEC
 325     from_failure_handler get_post_failure_unlocked() BOOST_NOEXCEPT_OR_NOTHROW;
 326     BOOST_CONTRACT_DETAIL_DECLSPEC
 327     from_failure_handler get_post_failure_locked() BOOST_NOEXCEPT_OR_NOTHROW;
 328
 329     BOOST_CONTRACT_DETAIL_DECLSPEC
 330     void post_failure_unlocked(from where) /* can throw */;
 331     BOOST_CONTRACT_DETAIL_DECLSPEC
 332     void post_failure_locked(from where) /* can throw */;
 333
 334     // Except failure.
 335
 336     BOOST_CONTRACT_DETAIL_DECLSPEC
 337     from_failure_handler const& set_except_failure_unlocked(
 338             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 339     BOOST_CONTRACT_DETAIL_DECLSPEC
 340     from_failure_handler const& set_except_failure_locked(
 341             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 342
 343     BOOST_CONTRACT_DETAIL_DECLSPEC
 344     from_failure_handler get_except_failure_unlocked()
 345             BOOST_NOEXCEPT_OR_NOTHROW;
 346     BOOST_CONTRACT_DETAIL_DECLSPEC
 347     from_failure_handler get_except_failure_locked() BOOST_NOEXCEPT_OR_NOTHROW;
 348
 349     BOOST_CONTRACT_DETAIL_DECLSPEC
 350     void except_failure_unlocked(from where) /* can throw */;
 351     BOOST_CONTRACT_DETAIL_DECLSPEC
 352     void except_failure_locked(from where) /* can throw */;
 353
 354     // Old-copy failure.
 355
 356     BOOST_CONTRACT_DETAIL_DECLSPEC
 357     from_failure_handler const& set_old_failure_unlocked(
 358             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 359     BOOST_CONTRACT_DETAIL_DECLSPEC
 360     from_failure_handler const& set_old_failure_locked(
 361             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 362
 363     BOOST_CONTRACT_DETAIL_DECLSPEC
 364     from_failure_handler get_old_failure_unlocked() BOOST_NOEXCEPT_OR_NOTHROW;
 365     BOOST_CONTRACT_DETAIL_DECLSPEC
 366     from_failure_handler get_old_failure_locked() BOOST_NOEXCEPT_OR_NOTHROW;
 367
 368     BOOST_CONTRACT_DETAIL_DECLSPEC
 369     void old_failure_unlocked(from where) /* can throw */;
 370     BOOST_CONTRACT_DETAIL_DECLSPEC
 371     void old_failure_locked(from where) /* can throw */;
 372
 373     // Entry invariant failure.
 374
 375     BOOST_CONTRACT_DETAIL_DECLSPEC
 376     from_failure_handler const& set_entry_inv_failure_unlocked(
 377             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 378     BOOST_CONTRACT_DETAIL_DECLSPEC
 379     from_failure_handler const& set_entry_inv_failure_locked(
 380             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 381
 382     BOOST_CONTRACT_DETAIL_DECLSPEC
 383     from_failure_handler get_entry_inv_failure_unlocked()
 384             BOOST_NOEXCEPT_OR_NOTHROW;
 385     BOOST_CONTRACT_DETAIL_DECLSPEC
 386     from_failure_handler get_entry_inv_failure_locked()
 387             BOOST_NOEXCEPT_OR_NOTHROW;
 388
 389     BOOST_CONTRACT_DETAIL_DECLSPEC
 390     void entry_inv_failure_unlocked(from where) /* can throw */;
 391     BOOST_CONTRACT_DETAIL_DECLSPEC
 392     void entry_inv_failure_locked(from where) /* can throw */;
 393
 394     // Exit invariant failure.
 395
 396     BOOST_CONTRACT_DETAIL_DECLSPEC
 397     from_failure_handler const& set_exit_inv_failure_unlocked(
 398             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 399     BOOST_CONTRACT_DETAIL_DECLSPEC
 400     from_failure_handler const&set_exit_inv_failure_locked(
 401             from_failure_handler const& f) BOOST_NOEXCEPT_OR_NOTHROW;
 402
 403     BOOST_CONTRACT_DETAIL_DECLSPEC
 404     from_failure_handler get_exit_inv_failure_unlocked()
 405             BOOST_NOEXCEPT_OR_NOTHROW;
 406     BOOST_CONTRACT_DETAIL_DECLSPEC
 407     from_failure_handler get_exit_inv_failure_locked()
 408             BOOST_NOEXCEPT_OR_NOTHROW;
 409
 410     BOOST_CONTRACT_DETAIL_DECLSPEC
 411     void exit_inv_failure_unlocked(from where) /* can throw */;
 412     BOOST_CONTRACT_DETAIL_DECLSPEC
 413     void exit_inv_failure_locked(from where) /* can throw */;
 414 }
 415 /** @endcond */
 416
 417 } } // namespace
 418
 419 /** @cond */
 420 #ifdef BOOST_CONTRACT_HEADER_ONLY
 421     // NOTE: This header must be included in the middle of this file (because
 422     // its impl depends on both from and assert_failure types). This is not
 423     // ideal, but it is better than splitting this file into multiple
 424     // independent ones because all content in this file is logically related
 425     // from the user prospective.
 426     #include <boost/contract/detail/inlined/core/exception.hpp>
 427 #endif
 428 /** @endcond */
 429
 430 namespace boost { namespace contract {
 431
 432 // Following must be inline for static linkage (no DYN_LINK and no HEADER_ONLY).
 433
 434 /**
 435 Set failure handler for implementation checks.
 436
 437 Set a new failure handler and returns it.
 438
 439 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 440
 441 @param f New failure handler functor to set.
 442
 443 @return Same failure handler functor @p f passed as parameter (e.g., for
 444         concatenating function calls).
 445
 446 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 447         @RefSect{advanced.implementation_checks, Implementation Checks}
 448 */
 449 inline failure_handler const& set_check_failure(failure_handler const& f)
 450         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 451     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 452         return exception_::set_check_failure_locked(f);
 453     #else
 454         return exception_::set_check_failure_unlocked(f);
 455     #endif
 456 }
 457
 458 /**
 459 Return failure handler currently set for implementation checks.
 460
 461 This is often called only internally by this library.
 462
 463 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 464
 465 @return A copy of the failure handler currently set.
 466
 467 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 468         @RefSect{advanced.implementation_checks, Implementation Checks}
 469 */
 470 inline failure_handler get_check_failure()
 471         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 472     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 473         return exception_::get_check_failure_locked();
 474     #else
 475         return exception_::get_check_failure_unlocked();
 476     #endif
 477 }
 478
 479 /**
 480 Call failure handler for implementation checks.
 481
 482 This is often called only internally by this library.
 483
 484 @b Throws:  This can throw in case programmers specify a failure handler that
 485             throws exceptions on implementation check failures (not the
 486             default).
 487
 488 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 489         @RefSect{advanced.implementation_checks, Implementation Checks}
 490 */
 491 inline void check_failure() /* can throw */ {
 492     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 493         exception_::check_failure_locked();
 494     #else
 495         exception_::check_failure_unlocked();
 496     #endif
 497 }
 498
 499 /**
 500 Set failure handler for preconditions.
 501
 502 Set a new failure handler and returns it.
 503
 504 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 505
 506 @param f New failure handler functor to set.
 507
 508 @return Same failure handler functor @p f passed as parameter (e.g., for
 509         concatenating function calls).
 510
 511 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 512         @RefSect{tutorial.preconditions, Preconditions}
 513 */
 514 inline from_failure_handler const& set_precondition_failure(from_failure_handler
 515         const& f) /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 516     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 517         return exception_::set_pre_failure_locked(f);
 518     #else
 519         return exception_::set_pre_failure_unlocked(f);
 520     #endif
 521 }
 522
 523 /**
 524 Return failure handler currently set for preconditions.
 525
 526 This is often called only internally by this library.
 527
 528 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 529
 530 @return A copy of the failure handler currently set.
 531
 532 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 533         @RefSect{tutorial.preconditions, Preconditions}
 534 */
 535 inline from_failure_handler get_precondition_failure()
 536         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 537     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 538         return exception_::get_pre_failure_locked();
 539     #else
 540         return exception_::get_pre_failure_unlocked();
 541     #endif
 542 }
 543
 544 /**
 545 Call failure handler for preconditions.
 546
 547 This is often called only internally by this library.
 548
 549 @b Throws:  This can throw in case programmers specify a failure handler that
 550             throws exceptions on contract assertion failures (not the default).
 551
 552 @param where    Operation that failed the contract assertion (when this function
 553                 is called by this library, this parameter will never be
 554                 @c from_destructor because destructors do not have
 555                 preconditions).
 556
 557 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 558         @RefSect{tutorial.preconditions, Preconditions}
 559 */
 560 inline void precondition_failure(from where) /* can throw */ {
 561     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 562         exception_::pre_failure_locked(where);
 563     #else
 564         exception_::pre_failure_unlocked(where);
 565     #endif
 566 }
 567
 568 /**
 569 Set failure handler for postconditions.
 570
 571 Set a new failure handler and returns it.
 572
 573 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 574
 575 @param f New failure handler functor to set.
 576
 577 @return Same failure handler functor @p f passed as parameter (e.g., for
 578         concatenating function calls).
 579
 580 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 581         @RefSect{tutorial.postconditions, Postconditions}
 582 */
 583 inline from_failure_handler const& set_postcondition_failure(
 584     from_failure_handler const& f
 585 ) /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 586     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 587         return exception_::set_post_failure_locked(f);
 588     #else
 589         return exception_::set_post_failure_unlocked(f);
 590     #endif
 591 }
 592
 593 /**
 594 Return failure handler currently set for postconditions.
 595
 596 This is often called only internally by this library.
 597
 598 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 599
 600 @return A copy of the failure handler currently set.
 601
 602 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 603         @RefSect{tutorial.postconditions, Postconditions}
 604 */
 605 inline from_failure_handler get_postcondition_failure()
 606         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 607     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 608         return exception_::get_post_failure_locked();
 609     #else
 610         return exception_::get_post_failure_unlocked();
 611     #endif
 612 }
 613
 614 /**
 615 Call failure handler for postconditions.
 616
 617 This is often called only internally by this library.
 618
 619 @b Throws:  This can throw in case programmers specify a failure handler that
 620             throws exceptions on contract assertion failures (not the default).
 621
 622 @param where    Operation that failed the contract assertion (e.g., this might
 623                 be useful to program failure handler functors that never throw
 624                 from destructors, not even when they are programmed by users to
 625                 throw exceptions instead of terminating the program).
 626
 627 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 628         @RefSect{tutorial.postconditions, Postconditions}
 629 */
 630 inline void postcondition_failure(from where) /* can throw */ {
 631     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 632         exception_::post_failure_locked(where);
 633     #else
 634         exception_::post_failure_unlocked(where);
 635     #endif
 636 }
 637
 638 /**
 639 Set failure handler for exception guarantees.
 640
 641 Set a new failure handler and returns it.
 642
 643 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 644
 645 @param f New failure handler functor to set.
 646
 647 @return Same failure handler functor @p f passed as parameter (e.g., for
 648         concatenating function calls).
 649
 650 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 651         @RefSect{tutorial.exception_guarantees, Exception Guarantees}
 652 */
 653 inline from_failure_handler const& set_except_failure(from_failure_handler
 654         const& f) /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 655     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 656         return exception_::set_except_failure_locked(f);
 657     #else
 658         return exception_::set_except_failure_unlocked(f);
 659     #endif
 660 }
 661
 662 /**
 663 Return failure handler currently set for exception guarantees.
 664
 665 This is often called only internally by this library.
 666
 667 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 668
 669 @return A copy of the failure handler currently set.
 670
 671 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 672         @RefSect{tutorial.exception_guarantees, Exception Guarantees}
 673 */
 674 inline from_failure_handler get_except_failure()
 675         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 676     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 677         return exception_::get_except_failure_locked();
 678     #else
 679         return exception_::get_except_failure_unlocked();
 680     #endif
 681 }
 682
 683 /**
 684 Call failure handler for exception guarantees.
 685
 686 This is often called only internally by this library.
 687
 688 @b Throws:  This can throw in case programmers specify a failure handler that
 689             throws exceptions on contract assertion failures (not the default),
 690             however:
 691
 692 @warning    When this failure handler is called there is already an active
 693             exception (the one that caused the exception guarantees to be
 694             checked in the first place).
 695             Therefore, programming this failure handler to throw yet another
 696             exception will force C++ to automatically terminate the program.
 697
 698 @param where Operation that failed the contract assertion.
 699
 700 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 701         @RefSect{tutorial.exception_guarantees, Exception Guarantees}
 702 */
 703 inline void except_failure(from where) /* can throw */ {
 704     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 705         exception_::except_failure_locked(where);
 706     #else
 707         exception_::except_failure_unlocked(where);
 708     #endif
 709 }
 710
 711 /**
 712 Set failure handler for old values copied at body.
 713
 714 Set a new failure handler and returns it.
 715
 716 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 717
 718 @param f New failure handler functor to set.
 719
 720 @return Same failure handler functor @p f passed as parameter (e.g., for
 721         concatenating function calls).
 722
 723 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 724         @RefSect{advanced.old_values_copied_at_body, Old Values Copied at Body}
 725 */
 726 inline from_failure_handler const& set_old_failure(from_failure_handler const&
 727         f) /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 728     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 729         return exception_::set_old_failure_locked(f);
 730     #else
 731         return exception_::set_old_failure_unlocked(f);
 732     #endif
 733 }
 734
 735 /**
 736 Return failure handler currently set for old values copied at body.
 737
 738 This is often called only internally by this library.
 739
 740 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 741
 742 @return A copy of the failure handler currently set.
 743
 744 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 745         @RefSect{advanced.old_values_copied_at_body, Old Values Copied at Body}
 746 */
 747 inline from_failure_handler get_old_failure()
 748         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 749     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 750         return exception_::get_old_failure_locked();
 751     #else
 752         return exception_::get_old_failure_unlocked();
 753     #endif
 754 }
 755
 756 /**
 757 Call failure handler for old values copied at body.
 758
 759 This is often called only internally by this library.
 760
 761 @b Throws:  This can throw in case programmers specify a failure handler that
 762             throws exceptions on contract assertion failures (not the default).
 763
 764 @param where    Operation that failed the old value copy (e.g., this might
 765                 be useful to program failure handler functors that never throw
 766                 from destructors, not even when they are programmed by users to
 767                 throw exceptions instead of terminating the program).
 768
 769 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 770         @RefSect{advanced.old_values_copied_at_body, Old Values Copied at Body}
 771 */
 772 inline void old_failure(from where) /* can throw */ {
 773     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 774         exception_::old_failure_locked(where);
 775     #else
 776         exception_::old_failure_unlocked(where);
 777     #endif
 778 }
 779
 780 /**
 781 Set failure handler for class invariants at entry.
 782
 783 Set a new failure handler and returns it.
 784
 785 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 786
 787 @param f New failure handler functor to set.
 788
 789 @return Same failure handler functor @p f passed as parameter (e.g., for
 790         concatenating function calls).
 791
 792 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 793         @RefSect{tutorial.class_invariants, Class Invariants},
 794         @RefSect{extras.volatile_public_functions,
 795         Volatile Public Functions}
 796 */
 797 inline from_failure_handler const& set_entry_invariant_failure(
 798     from_failure_handler const& f
 799 )/** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 800     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 801         return exception_::set_entry_inv_failure_locked(f);
 802     #else
 803         return exception_::set_entry_inv_failure_unlocked(f);
 804     #endif
 805 }
 806
 807 /**
 808 Return failure handler currently set for class invariants at entry.
 809
 810 This is often called only internally by this library.
 811
 812 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 813
 814 @return A copy of the failure handler currently set.
 815
 816 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 817         @RefSect{tutorial.class_invariants, Class Invariants},
 818         @RefSect{extras.volatile_public_functions,
 819         Volatile Public Functions}
 820 */
 821 inline from_failure_handler get_entry_invariant_failure()
 822         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 823     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 824         return exception_::get_entry_inv_failure_locked();
 825     #else
 826         return exception_::get_entry_inv_failure_unlocked();
 827     #endif
 828 }
 829
 830 /**
 831 Call failure handler for class invariants at entry.
 832
 833 This is often called only internally by this library.
 834
 835 @b Throws:  This can throw in case programmers specify a failure handler that
 836             throws exceptions on contract assertion failures (not the default).
 837
 838 @param where    Operation that failed the contract assertion (e.g., this might
 839                 be useful to program failure handler functors that never throw
 840                 from destructors, not even when they are programmed by users to
 841                 throw exceptions instead of terminating the program).
 842
 843 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 844         @RefSect{tutorial.class_invariants, Class Invariants},
 845         @RefSect{extras.volatile_public_functions,
 846         Volatile Public Functions}
 847 */
 848 inline void entry_invariant_failure(from where) /* can throw */ {
 849     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 850         return exception_::entry_inv_failure_locked(where);
 851     #else
 852         return exception_::entry_inv_failure_unlocked(where);
 853     #endif
 854 }
 855
 856 /**
 857 Set failure handler for class invariants at exit.
 858
 859 Set a new failure handler and returns it.
 860
 861 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 862
 863 @param f New failure handler functor to set.
 864
 865 @return Same failure handler functor @p f passed as parameter (e.g., for
 866         concatenating function calls).
 867
 868 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 869         @RefSect{tutorial.class_invariants, Class Invariants},
 870         @RefSect{extras.volatile_public_functions,
 871         Volatile Public Functions}
 872 */
 873 inline from_failure_handler const& set_exit_invariant_failure(
 874     from_failure_handler const& f
 875 ) /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 876     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 877         return exception_::set_exit_inv_failure_locked(f);
 878     #else
 879         return exception_::set_exit_inv_failure_unlocked(f);
 880     #endif
 881 }
 882
 883 /**
 884 Return failure handler currently set for class invariants at exit.
 885
 886 This is often called only internally by this library.
 887
 888 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 889
 890 @return A copy of the failure handler currently set.
 891
 892 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 893         @RefSect{tutorial.class_invariants, Class Invariants},
 894         @RefSect{extras.volatile_public_functions,
 895         Volatile Public Functions}
 896 */
 897 inline from_failure_handler get_exit_invariant_failure()
 898         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */ {
 899     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 900         return exception_::get_exit_inv_failure_locked();
 901     #else
 902         return exception_::get_exit_inv_failure_unlocked();
 903     #endif
 904 }
 905
 906 /**
 907 Call failure handler for class invariants at exit.
 908
 909 This is often called only internally by this library.
 910
 911 @b Throws:  This can throw in case programmers specify a failure handler that
 912             throws exceptions on contract assertion failures (not the default).
 913
 914 @param where    Operation that failed the contract assertion (e.g., this might
 915                 be useful to program failure handler functors that never throw
 916                 from destructors, not even when they are programmed by users to
 917                 throw exceptions instead of terminating the program).
 918
 919 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 920         @RefSect{tutorial.class_invariants, Class Invariants},
 921         @RefSect{extras.volatile_public_functions,
 922         Volatile Public Functions}
 923 */
 924 inline void exit_invariant_failure(from where) /* can throw */ {
 925     #ifndef BOOST_CONTRACT_DISABLE_THREADS
 926         exception_::exit_inv_failure_locked(where);
 927     #else
 928         exception_::exit_inv_failure_unlocked(where);
 929     #endif
 930 }
 931
 932 /**
 933 Set failure handler for class invariants (at both entry and exit).
 934
 935 This is provided for convenience and it is equivalent to call both
 936 @RefFunc{boost::contract::set_entry_invariant_failure} and
 937 @RefFunc{boost::contract::set_exit_invariant_failure} with the same functor
 938 parameter @p f.
 939
 940 @b Throws: This is declared @c noexcept (or @c throw() before C++11).
 941
 942 @param f New failure handler functor to set for both entry and exit invariants.
 943
 944 @return Same failure handler functor @p f passed as parameter (e.g., for
 945         concatenating function calls).
 946
 947 @see    @RefSect{advanced.throw_on_failures__and__noexcept__, Throw on Failure},
 948         @RefSect{tutorial.class_invariants, Class Invariants},
 949         @RefSect{extras.volatile_public_functions,
 950         Volatile Public Functions}
 951 */
 952 /** @cond */ BOOST_CONTRACT_DETAIL_DECLSPEC /** @endcond */
 953 from_failure_handler const& set_invariant_failure(from_failure_handler const& f)
 954         /** @cond */ BOOST_NOEXCEPT_OR_NOTHROW /** @endcond */;
 955
 956 } } // namespace
 957
 958 #endif // #include guard
 959