glib has a nice set of macros you can use to enforce invariants and preconditions in your code. GTK+ uses these liberally—one of the reasons it’s so stable and easy to use. They all disappear when you define G_DISABLE_CHECKS or G_DISABLE_ASSERT, so there’s no performance penalty in production code. Using these liberally is a very, very good idea. You’ll find bugs much faster if you do. You can even add assertions and checks whenever you find a bug to be sure the bug doesn’t reappear in future versions—this complements a regression suite. Checks are especially useful when the code you’re writing will be used as a black box by other programmers; users will immediately know when and how they’ve misused your code.
Of course you should be very careful to ensure your code isn’t subtly dependent on debug-only statements to function correctly. Statements that will disappear in pro- duction code should never have side effects.
[code lang=”cpp”]
#include <glib.h>
g_return_if_fail(condition);
g_return_val_if_fail(condition, retval);
[/code]
Figure 2-3. Precondition Checks
Figure 2-3 shows glib’s precondition checks. g_return_if_fail() prints a warning
and immediately returns from the current function if condition is FALSE. g_return_val_if_fail()
is similar but allows you to return some retval. These macros are incredibly useful—if
you use them liberally, especially in combination with GTK+’s runtime type check- ing, you’ll halve the time you spend looking for bad pointers and type errors.
Using these functions is simple; here’s an example from the glib hash table imple- mentation:
[code lang=”cpp”]
void
g_hash_table_foreach (GHashTable *hash_table,
GHFunc func,
gpointer user_data)
{
GHashNode *node;
gint i;
g_return_if_fail (hash_table != NULL);
g_return_if_fail (func != NULL);
for (i = 0; i < hash_table->size; i++)
for (node = hash_table->nodes[i]; node; node = node->next)
(* func) (node->key, node->value, user_data);
}
[/code]
Without the checks, passing NULL as a parameter to this function would result in a mysterious segmentation fault. The person using the library would have to figure out where the error occurred with a debugger, and maybe even dig in to the glib code to see what was wrong. With the checks, they’ll get a nice error message telling them that NULL arguments are not allowed.
[code lang=”cpp”]
#include <glib.h>
g_assert(condition);
g_assert_not_reached(void);
[/code]
Figure 2-4. Assertions
glib also has more traditional assertion macros, shown in Figure 2-4. g_assert() is basically identical to assert(), but responds to G_DISABLE_ASSERT and behaves consistently across all platforms. g_assert_not_reached() is also provided; this is
an assertion which always fails. Assertions call abort() to exit the program and (if your environment supports it) dump a core file for debugging purposes.
Fatal assertions should be used to check internal consistency of a function or library, while g_return_if_fail() is intended to ensure sane values are passed to the pub- lic interfaces of a program module. That is, if an assertion fails, you typically look for a bug in the module containing the assertion; if a g_return_if_fail() check fails, you typically look for the bug in the code which invokes the module.
This code from glib’s calendrical calculations module shows the difference:
[code lang=”cpp”]
GDate*
g_date_new_dmy (GDateDay day, GDateMonth m, GDateYear y)
{
GDate *d;
g_return_val_if_fail (g_date_valid_dmy (day, m, y), NULL);
d = g_new (GDate, 1);
d->julian = FALSE;
d->dmy = TRUE;
d->month = m;
d->day = day;
d->year = y;
g_assert (g_date_valid (d));
return d;
}
[/code]
The precondition check at the beginning ensures the user passes in reasonable values for the day, month and year; the assertion at the end ensures that glib constructed a sane object, given sane values.
g_assert_not_reached() should be used to mark “impossible” situations; a com- mon use is to detect switch statements that don’t handle all possible values of an enumeration:
[code lang=”cpp”]
switch (val)
{
case FOO_ONE:
break;
case FOO_TWO:
break;
default:
/* Invalid enumeration value */
g_assert_not_reached();
break;
}
[/code]
All of the debugging macros print a warning using glib’s g_log() facility, which means the warning includes the name of the originating application or library, and you can optionally install a replacement warning-printing routine. For example, you might send all warnings to a dialog box or log file instead of printing them on the console.
Source: Havoc Pennington. 1999. GTK Gnome Application Development. New York: New Riders Publishing