From 1502bf03fdf8255d4673cc529e02ad69cef9995d Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Thu, 7 Sep 2017 09:31:30 -0400 Subject: Add a module comment to util_bug.h Closes ticket 22824. --- src/common/util_bug.h | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'src') diff --git a/src/common/util_bug.h b/src/common/util_bug.h index de39317d1c..ce6565d92d 100644 --- a/src/common/util_bug.h +++ b/src/common/util_bug.h @@ -5,6 +5,32 @@ /** * \file util_bug.h + * + * \brief Macros to manage assertions, fatal and non-fatal. + * + * Guidelines: All the different kinds of assertion in this file are for + * bug-checking only. Don't write code that can assert based on bad inputs. + * + * We provide two kinds of assertion here: "fatal" and "nonfatal". Use + * nonfatal assertions for any bug you can reasonably recover from -- and + * please, try to recover! Many severe bugs in Tor have been caused by using + * a regular assertion when a nonfatal assertion would have been better. + * + * If you need to check a condition with a nonfatal assertion, AND recover + * from that same condition, consider using the BUG() macro inside a + * conditional. For example: + * + * + * // wrong -- use tor_assert_nonfatal() if you just want an assertion. + * BUG(ptr == NULL); + * + * // okay, but needlessly verbose + * tor_assert_nonfatal(ptr != NULL); + * if (ptr == NULL) { ... } + * + * // this is how we do it: + * if (BUG(ptr == NULL)) { ... } + * **/ #ifndef TOR_UTIL_BUG_H -- cgit v1.2.3-54-g00ecf