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 */
set_check_failure(failure_handler const & f)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 */
get_check_failure()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 */
check_failure()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 */
set_precondition_failure(from_failure_handler const & f)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 */
get_precondition_failure()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 */
precondition_failure(from where)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 */
set_postcondition_failure(from_failure_handler const & f)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 */
get_postcondition_failure()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 */
postcondition_failure(from where)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 */
set_except_failure(from_failure_handler const & f)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 */
get_except_failure()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 */
except_failure(from where)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 */
set_old_failure(from_failure_handler const & f)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 */
get_old_failure()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 */
old_failure(from where)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 */
set_entry_invariant_failure(from_failure_handler const & f)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 */
get_entry_invariant_failure()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 */
entry_invariant_failure(from where)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 */
set_exit_invariant_failure(from_failure_handler const & f)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 */
get_exit_invariant_failure()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 */
exit_invariant_failure(from where)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
960