mirror of
https://github.com/freebsd/freebsd-src.git
synced 2024-12-04 12:28:58 +00:00
360 lines
14 KiB
HTML
360 lines
14 KiB
HTML
<html>
|
|
<head>
|
|
<title> libsm : Assert and Abort </title>
|
|
</head>
|
|
<body>
|
|
|
|
<a href="index.html">Back to libsm overview</a>
|
|
|
|
<center>
|
|
<h1> libsm : Assert and Abort </h1>
|
|
<br> $Id: assert.html,v 1.6 2001/08/27 21:47:03 ca Exp $
|
|
</center>
|
|
|
|
<h2> Introduction </h2>
|
|
|
|
This package contains abstractions
|
|
for assertion checking and abnormal program termination.
|
|
|
|
<h2> Synopsis </h2>
|
|
|
|
<pre>
|
|
#include <sm/assert.h>
|
|
|
|
/*
|
|
** abnormal program termination
|
|
*/
|
|
|
|
void sm_abort_at(char *filename, int lineno, char *msg);
|
|
typedef void (*SM_ABORT_HANDLER)(char *filename, int lineno, char *msg);
|
|
void sm_abort_sethandler(SM_ABORT_HANDLER);
|
|
void sm_abort(char *fmt, ...)
|
|
|
|
/*
|
|
** assertion checking
|
|
*/
|
|
|
|
SM_REQUIRE(expression)
|
|
SM_ASSERT(expression)
|
|
SM_ENSURE(expression)
|
|
|
|
extern SM_DEBUG_T SmExpensiveRequire;
|
|
extern SM_DEBUG_T SmExpensiveAssert;
|
|
extern SM_DEBUG_T SmExpensiveEnsure;
|
|
|
|
#if SM_CHECK_REQUIRE
|
|
#if SM_CHECK_ASSERT
|
|
#if SM_CHECK_ENSURE
|
|
|
|
cc -DSM_CHECK_ALL=0 -DSM_CHECK_REQUIRE=1 ...
|
|
</pre>
|
|
|
|
<h2> Abnormal Program Termination </h2>
|
|
|
|
The functions sm_abort and sm_abort_at are used to report a logic
|
|
bug and terminate the program. They can be invoked directly,
|
|
and they are also used by the assertion checking macros.
|
|
|
|
<dl>
|
|
<dt>
|
|
void sm_abort_at(char *filename, int lineno, char *msg)
|
|
<dd>
|
|
This is the low level interface for causing abnormal program
|
|
termination. It is intended to be invoked from a
|
|
macro, such as the assertion checking macros.
|
|
|
|
If filename != NULL then filename and lineno specify the line
|
|
of source code on which the logic bug is detected. These
|
|
arguments are normally either set to __FILE__ and __LINE__
|
|
from an assertion checking macro, or they are set to NULL and 0.
|
|
|
|
The default action is to print an error message to smioerr
|
|
using the arguments, and then call abort(). This default
|
|
behaviour can be changed by calling sm_abort_sethandler.
|
|
<p>
|
|
<dt>
|
|
void sm_abort_sethandler(SM_ABORT_HANDLER handler)
|
|
<dd>
|
|
Install 'handler' as the callback function that is invoked
|
|
by sm_abort_at. This callback function is passed the same
|
|
arguments as sm_abort_at, and is expected to log an error
|
|
message and terminate the program. The callback function should
|
|
not raise an exception or perform cleanup: see Rationale.
|
|
|
|
sm_abort_sethandler is intended to be called once, from main(),
|
|
before any additional threads are created: see Rationale.
|
|
You should not use sm_abort_sethandler to
|
|
switch back and forth between several handlers;
|
|
this is particularly dangerous when there are
|
|
multiple threads, or when you are in a library routine.
|
|
<p>
|
|
<dt>
|
|
void sm_abort(char *fmt, ...)
|
|
<dd>
|
|
This is the high level interface for causing abnormal program
|
|
termination. It takes printf arguments. There is no need to
|
|
include a trailing newline in the format string; a trailing newline
|
|
will be printed if appropriate by the handler function.
|
|
</dl>
|
|
|
|
<h2> Assertions </h2>
|
|
|
|
The assertion handling package
|
|
supports a style of programming in which assertions are used
|
|
liberally throughout the code, both as a form of documentation,
|
|
and as a way of detecting bugs in the code by performing runtime checks.
|
|
<p>
|
|
There are three kinds of assertion:
|
|
<dl>
|
|
<dt>
|
|
SM_REQUIRE(expr)
|
|
<dd>
|
|
This is an assertion used at the beginning of a function
|
|
to check that the preconditions for calling the function
|
|
have been satisfied by the caller.
|
|
<p>
|
|
<dt>
|
|
SM_ENSURE(expr)
|
|
<dd>
|
|
This is an assertion used just before returning from a function
|
|
to check that the function has satisfied all of the postconditions
|
|
that it is required to satisfy by its contract with the caller.
|
|
<p>
|
|
<dt>
|
|
SM_ASSERT(expr)
|
|
<dd>
|
|
This is an assertion that is used in the middle of a function,
|
|
to check loop invariants, and for any other kind of check that is
|
|
not a "require" or "ensure" check.
|
|
</dl>
|
|
If any of the above assertion macros fail, then sm_abort_at
|
|
is called. By default, a message is printed to stderr and the
|
|
program is aborted. For example, if SM_REQUIRE(arg > 0) fails
|
|
because arg <= 0, then the message
|
|
<blockquote><pre>
|
|
foo.c:47: SM_REQUIRE(arg > 0) failed
|
|
</pre></blockquote>
|
|
is printed to stderr, and abort() is called.
|
|
You can change this default behaviour using sm_abort_sethandler.
|
|
|
|
<h2> How To Disable Assertion Checking At Compile Time </h2>
|
|
|
|
You can use compile time macros to selectively enable or disable
|
|
each of the three kinds of assertions, for performance reasons.
|
|
For example, you might want to enable SM_REQUIRE checking
|
|
(because it finds the most bugs), but disable the other two types.
|
|
<p>
|
|
By default, all three types of assertion are enabled.
|
|
You can selectively disable individual assertion types
|
|
by setting one or more of the following cpp macros to 0
|
|
before <sm/assert.h> is included for the first time:
|
|
<blockquote>
|
|
SM_CHECK_REQUIRE<br>
|
|
SM_CHECK_ENSURE<br>
|
|
SM_CHECK_ASSERT<br>
|
|
</blockquote>
|
|
Or, you can define SM_CHECK_ALL as 0 to disable all assertion
|
|
types, then selectively define one or more of SM_CHECK_REQUIRE,
|
|
SM_CHECK_ENSURE or SM_CHECK_ASSERT as 1. For example,
|
|
to disable all assertions except for SM_REQUIRE, you can use
|
|
these C compiler flags:
|
|
<blockquote>
|
|
-DSM_CHECK_ALL=0 -DSM_CHECK_REQUIRE=1
|
|
</blockquote>
|
|
|
|
After <sm/assert.h> is included, the macros
|
|
SM_CHECK_REQUIRE, SM_CHECK_ENSURE and SM_CHECK_ASSERT
|
|
are each set to either 0 or 1.
|
|
|
|
<h2> How To Write Complex or Expensive Assertions </h2>
|
|
|
|
Sometimes an assertion check requires more code than a simple
|
|
boolean expression.
|
|
For example, it might require an entire statement block
|
|
with its own local variables.
|
|
You can code such assertion checks by making them conditional on
|
|
SM_CHECK_REQUIRE, SM_CHECK_ENSURE or SM_CHECK_ASSERT,
|
|
and using sm_abort to signal failure.
|
|
<p>
|
|
Sometimes an assertion check is significantly more expensive
|
|
than one or two comparisons.
|
|
In such cases, it is not uncommon for developers to comment out
|
|
the assertion once the code is unit tested.
|
|
Please don't do this: it makes it hard to turn the assertion
|
|
check back on for the purposes of regression testing.
|
|
What you should do instead is make the assertion check conditional
|
|
on one of these predefined debug objects:
|
|
<blockquote>
|
|
SmExpensiveRequire<br>
|
|
SmExpensiveAssert<br>
|
|
SmExpensiveEnsure
|
|
</blockquote>
|
|
By doing this, you bring the cost of the assertion checking code
|
|
back down to a single comparison, unless expensive assertion checking
|
|
has been explicitly enabled.
|
|
By the way, the corresponding debug category names are
|
|
<blockquote>
|
|
sm_check_require<br>
|
|
sm_check_assert<br>
|
|
sm_check_ensure
|
|
</blockquote>
|
|
What activation level should you check for?
|
|
Higher levels correspond to more expensive assertion checks.
|
|
Here are some basic guidelines:
|
|
<blockquote>
|
|
level 1: < 10 basic C operations<br>
|
|
level 2: < 100 basic C operations<br>
|
|
level 3: < 1000 basic C operations<br>
|
|
...
|
|
</blockquote>
|
|
|
|
<p>
|
|
Here's a contrived example of both techniques:
|
|
<blockquote><pre>
|
|
void
|
|
w_munge(WIDGET *w)
|
|
{
|
|
SM_REQUIRE(w != NULL);
|
|
#if SM_CHECK_REQUIRE
|
|
/*
|
|
** We run this check at level 3 because we expect to check a few hundred
|
|
** table entries.
|
|
*/
|
|
|
|
if (sm_debug_active(&SmExpensiveRequire, 3))
|
|
{
|
|
int i;
|
|
|
|
for (i = 0; i < WIDGET_MAX; ++i)
|
|
{
|
|
if (w[i] == NULL)
|
|
sm_abort("w_munge: NULL entry %d in widget table", i);
|
|
}
|
|
}
|
|
#endif /* SM_CHECK_REQUIRE */
|
|
</pre></blockquote>
|
|
|
|
<h2> Other Guidelines </h2>
|
|
|
|
You should resist the urge to write SM_ASSERT(0) when the code has
|
|
reached an impossible place. It's better to call sm_abort, because
|
|
then you can generate a better error message. For example,
|
|
<blockquote><pre>
|
|
switch (foo)
|
|
{
|
|
...
|
|
default:
|
|
sm_abort("impossible value %d for foo", foo);
|
|
}
|
|
</pre></blockquote>
|
|
Note that I did not bother to guard the default clause of the switch
|
|
statement with #if SM_CHECK_ASSERT ... #endif, because there is
|
|
probably no performance gain to be had by disabling this particular check.
|
|
<p>
|
|
Avoid including code that has side effects inside of assert macros,
|
|
or inside of SM_CHECK_* guards. You don't want the program to stop
|
|
working if assertion checking is disabled.
|
|
|
|
<h2> Rationale for Logic Bug Handling </h2>
|
|
|
|
When a logic bug is detected, our philosophy is to log an error message
|
|
and terminate the program, dumping core if possible.
|
|
It is not a good idea to raise an exception, attempt cleanup,
|
|
or continue program execution. Here's why.
|
|
<p>
|
|
First of all, to facilitate post-mortem analysis, we want to dump core
|
|
on detecting a logic bug, disturbing the process image as little as
|
|
possible before dumping core. We don't want to raise an exception
|
|
and unwind the stack, executing cleanup code, before dumping core,
|
|
because that would obliterate information we need to analyze the cause
|
|
of the abort.
|
|
<p>
|
|
Second, it is a bad idea to raise an exception on an assertion failure
|
|
because this places unacceptable restrictions on code that uses
|
|
the assertion macros.
|
|
The reason is this: the sendmail code must be written so that
|
|
anywhere it is possible for an assertion to be raised, the code
|
|
will catch the exception and clean up if necessary, restoring
|
|
data structure invariants and freeing resources as required.
|
|
If an assertion failure was signalled by raising an exception,
|
|
then every time you added an assertion, you would need to check
|
|
both the function containing the assertion and its callers to see
|
|
if any exception handling code needed to be added to clean up properly
|
|
on assertion failure. That is far too great a burden.
|
|
<p>
|
|
It is a bad idea to attempt cleanup upon detecting a logic bug
|
|
for several reasons:
|
|
<ul>
|
|
<li>If you need to perform cleanup actions in order to preserve the
|
|
integrity of the data that the program is handling, then the
|
|
program is not fault tolerant, and needs to be redesigned.
|
|
There are several reasons why a program might be terminated unexpectedly:
|
|
the system might crash, the program might receive a signal 9,
|
|
the program might be terminated by a memory fault (possibly as a
|
|
side effect of earlier data structure corruption), and the program
|
|
might detect a logic bug and terminate itself. Note that executing
|
|
cleanup actions is not feasible in most of the above cases.
|
|
If the program has a fault tolerant design, then it will not lose
|
|
data even if the system crashes in the middle of an operation.
|
|
<p>
|
|
<li>If the cause of the logic bug is earlier data structure corruption,
|
|
then cleanup actions intended to preserve the integrity of the data
|
|
that the program is handling might cause more harm than good: they
|
|
might cause information to be corrupted or lost.
|
|
<p>
|
|
<li>If the program uses threads, then cleanup is much more problematic.
|
|
Suppose that thread A is holding some locks, and is in the middle of
|
|
modifying a shared data structure. The locks are needed because the
|
|
data structure is currently in an inconsistent state. At this point,
|
|
a logic bug is detected deep in a library routine called by A.
|
|
How do we get all of the running threads to stop what they are doing
|
|
and perform their thread-specific cleanup actions before terminating?
|
|
We may not be able to get B to clean up and terminate cleanly until
|
|
A has restored the invariants on the data structure it is modifying
|
|
and releases its locks. So, we raise an exception and unwind the stack,
|
|
restoring data structure invariants and releasing locks at each level
|
|
of abstraction, and performing an orderly shutdown. There are certainly
|
|
many classes of error conditions for which using the exception mechanism
|
|
to perform an orderly shutdown is appropriate and feasible, but there
|
|
are also classes of error conditions for which exception handling and
|
|
orderly shutdown is dangerous or impossible. The abnormal program
|
|
termination system is intended for this second class of error conditions.
|
|
If you want to trigger orderly shutdown, don't call sm_abort:
|
|
raise an exception instead.
|
|
</ul>
|
|
<p>
|
|
Here is a strategy for making sendmail fault tolerant.
|
|
Sendmail is structured as a collection of processes. The "root" process
|
|
does as little as possible, except spawn children to do all of the real
|
|
work, monitor the children, and act as traffic cop.
|
|
We use exceptions to signal expected but infrequent error conditions,
|
|
so that the process encountering the exceptional condition can clean up
|
|
and keep going. (Worker processes are intended to be long lived, in
|
|
order to minimize forking and increase performance.) But when a bug
|
|
is detected in a sendmail worker process, the worker process does minimal
|
|
or no cleanup and then dies. A bug might be detected in several ways:
|
|
the process might dereference a NULL pointer, receive a signal 11,
|
|
core dump and die, or an assertion might fail, in which case the process
|
|
commits suicide. Either way, the root process detects the death of the
|
|
worker, logs the event, and spawns another worker.
|
|
|
|
<h2> Rationale for Naming Conventions </h2>
|
|
|
|
The names "require" and "ensure" come from the writings of Bertrand Meyer,
|
|
a prominent evangelist for assertion checking who has written a number of
|
|
papers about the "Design By Contract" programming methodology,
|
|
and who created the Eiffel programming language.
|
|
Many other assertion checking packages for C also have "require" and
|
|
"ensure" assertion types. In short, we are conforming to a de-facto
|
|
standard.
|
|
<p>
|
|
We use the names <tt>SM_REQUIRE</tt>, <tt>SM_ASSERT</tt>
|
|
and <tt>SM_ENSURE</tt> in preference to to <tt>REQUIRE</tt>,
|
|
<tt>ASSERT</tt> and <tt>ENSURE</tt> because at least two other
|
|
open source libraries (libisc and libnana) define <tt>REQUIRE</tt>
|
|
and <tt>ENSURE</tt> macros, and many libraries define <tt>ASSERT</tt>.
|
|
We want to avoid name conflicts with other libraries.
|
|
|
|
</body>
|
|
</html>
|