|
GEF is a general exception-handling and contract-programming facility for C programmers. With GEF, its special control macros, and other support functions, you can separate the main purpose of a function from its exception-handling, contract-validation, and resource-reclamation code.
November 01, 1998
URL:http://www.drdobbs.com/cpp/the-gef-general-exception-handling-libra/184410715
Bruce is a software developer for Xerox. He can be contacted at bbigby@alum .MIT.edu.
GEF is a general exception-handling and contract-programming facility for C programmers. GEF, with its special control macros, and other support functions, allows you to separate the main purpose of a function from its exception-handling, contract-validation, and resource-reclamation code. GEF even lets you isolate cleanup code to its own block -- just like Java.
In addition, GEF is also thread safe. GEF supports the 1003.1c specification of PosixThreads and UNIX signals. However, you must ensure that the PosixThreads API function (pthread_getspecific) is async-safe for your platform. If you are not using GEF to handle asynchronous operating-system signals, you need not be concerned with the issue of async safety.
I developed GEF on a Linux 2.x system, using the LinuxThreads PosixThreads-compatible library for thread support. Later, I ported GEF to a Sun Ultra1, running Solaris 2.5.1. With little effort, you should be able to port GEF to other C-development platforms as well. GEF source code and related files are available electronically from DDJ (see "Resource Center," page 3) or at http://home .rochester.rr.com/bigbyofrocny/. Also available electronically are sample programs that demonstrate the use of the GEF library.
GEF provides seven control keyword macros: gef_try, gef_invariants, gef_preconditions, gef_catch, gef_postconditions, gef_finally, and gef_end. If you are familiar with Java or C++, you'll notice that these keywords are identical to those of the other languages, except GEF qualifies keywords with the prefix, "gef." This prevents code that uses GEF from conflicting with C++ exception handling. In fact, the names of all of GEF keywords and functions have either "gef" or "GEF" as a prefix. Control macros use the lowercase prefix, while initialization functions use uppercase.
The gef_try keyword macro introduces an exception-handling block, after which you can include the main body of your code. It is analogous to the C++ and Java try blocks. You can place any legal C statement after this block, and just like an if statement, if you are including more than one statement after the gef_try, you need to enclose the statements within braces.
GEF supports a number of control blocks that let you establish and enforce the requirements of using a function. A function may specify its contract of use via the exception-handler blocks, gef_invariant, gef_preconditions, and gef_postconditions.
GEF provides the gef_invariants block to let you specify the conditions of a function that must hold true immediately before the function begins to execute and after the function returns. In Listing One (at the end of this article), AddHighInt is a function that adds an integer i to the top end of a dynamic array. The lower and upper bounds of any dynamic array may be negative or positive integers. However, at any point in time, the upper bound of an array minus its lower bound plus one must be equal to its size. This condition is an invariant, because the condition must be true at all times.
The function also states, as a precondition, that before the function executes, the value of the array's data pointer must not be NULL. This precondition guards against the problem of trying to store a value into an unallocated memory space. As a postcondition, the new upper bound of the array must be equal to its previous value plus one.
Together, gef_invariants, gef_preconditions, and gef_postconditions specify the contract to which the function, and its clients, must adhere to ensure proper operation.
Listing One simply illustrates how to use GEF's features. If you think that a routine, such as AddHighInt, will be called frequently, then you may consider implementing it in a more efficient but equally robust manner to avoid having to use the gef_try statement, which can be relatively expensive.
My measurements have revealed that the overhead of executing a gef_try/gef_end block with nothing in it except a counter, requires about 2.6 msec on a P5 133-MHz PC, running Linux 2.0.30. On a 143-MHz Ultra-1 running under Solaris 2.5.1, the cost is between 2.9 msec and 3.3 msec.
I obtained these timings by executing in a loop a gef_try/gef_end block that was relatively empty except for the existence of a counter that increments continuously for 1 second.
I computed the iterations per second, and, based on the clock speed of the machine, computed a rough estimate of the number of instructions. The overhead of entering and exiting a gef_try/gef_end block can be from 2.6 to 2.9 msec. This is not terrible, but if you are implementing a low-level routine whose clients will invoke it many times, you may want to consider explicitly checking for assertion violations via if-else statements and throw an exception when necessary.
GEF supports a number of control statements for dealing with exceptions: gef_throw, gef_retry, and gef_break. The names are consistent with Java and C++, with the exception of the gef_break control statement. Although the gef_retry and gef_break statements must appear within the scope of a gef_try/gef_end pair, the gef_throw statement may appear anywhere in your program.
You can use the gef_throw control statement to raise an exception and transfer control to the appropriate gef_catch block. GEF automatically raises an exception when an assertion violation occurs. If you do not specify a callback function for assertion violations, GEF throws its own predefined exception; otherwise, GEF invokes your handler function. In such a case, GEF reports the line number and a string that represents the path to the source file in which the assertion violation occurred.
You can also register functions that GEF will call when operating-system signals occur. GEF will only handle those OS signals that you specify during initialization. Signals that GEF can handle include UNIX's SIGALRM, SIGFPE, and SIGQUIT, among others. You must be careful when using GEF to handle asynchronous signals (such as SIGALRM) in a multithreaded program.
However, you may use GEF to handle synchronous operating-system signals without concern. For example, you may use GEF to catch floating-point errors on UNIX systems. Simply register the SIGFPE signal with GEF, and, if the signal occurs, GEF catches and delivers the signal to the appropriate exception handler in your program.
Typically, you will want to correct a problem that occurs during the execution of a function and retry the main body of code. The gef_retry statement lets you unconditionally transfer control to the gef_try block.
On occasion, a thread may reach a success point while executing within a gef_catch block. In such a case, you may use the gef_break statement to transfer control to the statement that appears immediately after the nearest gef_end.
Unlike GEF, the Eiffel programming language does not support a break statement for exception handlers. Eiffel's designers preferred that all operations terminate via the try block. As a result, Eiffel programmers often have to resort to setting and testing a Boolean to determine when to actually retry a block of code or to exit. I found this restriction to be unnecessary, because what you end up implicitly implementing is a kind of break for an exception handler.
Listing Two illustrates how you might use exception handling instead of contracts. The SquareRoot function returns the square root of a number, provided that its value is not less than zero. If the value of the number is less than zero, then the SquareRoot function throws an EXCEPT_ARITHMETIC_VIOLATION exception. Actually, SquareRoot does not need to throw an exception if the number argument is less than 0.0. SquareRoot can rely upon the math library to call the global matherr function, which throws the proper exception if an arithmetic violation occurs.
The main function catches any exceptions and reports the error, if any, or the result to the console.
Unlike C++ and Java, if a thread reaches the end of a gef_catch block without handling an exception, GEF automatically rethrows the exception. In this respect, the gef_catch block is consistent with the rescue block of Eiffel. However, the difference between GEF's gef_catch and Eiffel's rescue is that Eiffel does not have the capability to report a specific error. In Eiffel, functions either succeed or fail.
The gef_finally block is simply a cleanup block. GEF always executes this block, regardless of whether an exception occurs. Listing Three, for example, illustrates the use of the gef_finally block. The function, PrintConcatenation, accepts two strings (s1 and s2) and a pointer to a FILE stream (fp). The function first acquires the memory (via malloc) into which it will store the concatenated string. It asserts that the resulting memory address not be NULL. The function continues by copying s1 to the result and then concatenating s2 to the result. The function subsequently prints a message to the specified stream (fp).
The last thing the function does is return the unneeded memory to heap storage in the gef_finally block. The code only frees the memory if the result is not NULL.
As a precondition, the function must ensure that result is NULL and that s1 and s2 are not NULL. Since the function relies upon a NULL test to determine when to free memory, the initial value of result must be NULL, indicating that it does not point to heap memory.
Every exception-handling block must end with a gef_end statement. The semicolon after the gef_end statement exists to ensure that syntax-aware editors (such as Emacs) will format your C code properly. However, it is not necessary.
Table 1 lists the current GEF statements and functions. For example, you may specify a callback function that GEF will use to delete exception objects. You will likely take advantage of this feature if your code is object oriented in nature.
For example, you may create an exception object in the heap and throw it, and, as soon as a function handles the exception, GEF will call your callback routine to dispose of the exception.
GEF disposes of exception objects when executing the gef_retry and gef_break statements from within a gef_catch block. Currently, GEF's default callback for deleting exception objects is a function that does nothing and returns. Listing Two does not make use of this feature because it passes exceptions around as integers.
You must be careful when you use the C language break and return statements. GEF maintains a parallel stack of checkpoints that enable it to perform nonlocal jumps when you throw an exception. If you exit the scope of an exception handler without passing through the gef_end code, GEF will become unsynchronized with your program, and your program will likely experience a most untidy fault. To avoid this problem, get in the habit of returning from a function at its end.
If you must use the C return statement, make sure that it is not within the scope of an exception handler. However, you need not worry about exception handlers of calling functions -- only the exception handlers in which you will be returning a value.
Likewise, also be careful when you use the C break statement. You may use the break statement, but make sure it doesn't transfer control of your program to a statement which resides outside of a gef_end statement. Substituting a C break statement for GEF's gef_break statement will frequently suffice. Make sure that what you are doing is safe and makes sense.
GEF is stable, mature, and flexible. I welcome suggestions on how to further increase its performance. Currently, however, the overhead of 2.6 msec is not bad for most applications. At the least, if you are writing C code that is not speed sensitive, you can utilize GEF to write more elegant and fault-tolerant C code.
DDJ
typedef struct { int lowbound;
int highbound;
int size;
int **data;
int numberOfSlots;
} *ArrayOfInt_t;
static
void
AddHighInt(ArrayOfInt_t self, int i) {
int old_highbound = self->highbound;
gef_try {
self->data[size++] = i;
self->highbound++;
} gef_invariants {
gef_assert(self->highbound - self->lowbound + 1 == self->size);
} gef_preconditions {
gef_assert(self->data != NULL);
gef_assert(self->numberOfSlots > self->size);
} gef_postconditions {
gef_assert(self->highbound == old_highbound + 1);
} gef_end;
}
#include <stdio.h>#include <stdlib.h>
#include <math.h>
#include <signal.h>
#include <GEF.h>
/* Define exception values for program */
#define EXCEPT_FAILURE 0 /* This should never occur! */
#define EXCEPT_OS_VIOLATION 1
#define EXCEPT_INSUFFICIENT_MEMORY 2
#define EXCEPT_ASSERTION_VIOLATION 3
#define EXCEPT_ARITHMETIC_VIOLATION 4
static
void
InsufficientMemory() {
gef_throw((void*) EXCEPT_INSUFFICIENT_MEMORY);
}
static
void
AssertionViolation(char* fileName, int lineNumber) {
/* Can only transfer fileName and lineNumber info via a pointer to a */
/* structure. For now, simply throw the integer value, */
gef_throw((void*) EXCEPT_ASSERTION_VIOLATION);
}
static
void
UnhandledException(void* exceptionID) {
fprintf(stderr, "\tUnhandled exception, %d, occurred, while executing
process, %d.\n",((int) exceptionID), (int) getpid());
}
static
void*
OSSignalToException(int signum) {
switch(signum) {
case SIGFPE:
return((void*) EXCEPT_ARITHMETIC_VIOLATION);
default:
return((void*) EXCEPT_OS_VIOLATION);
}
}
int
matherr(struct exception* e) {
/* This handler will catch all IEEE math violations */
gef_throw((void*) EXCEPT_ARITHMETIC_VIOLATION);
}
static
double
SquareRoot(double number) {
/* Check for number < 0.0 for demonstration only. If math error occurs */
/* math library will call matherr, which will throw exception anyway. */
if (number < 0.0) gef_throw((void*) EXCEPT_ARITHMETIC_VIOLATION);
return(sqrt(number));
}
int
main(int argc, char** argv) {
double number, answer;
int exitCode = 0;
sigset_t osSignalSet;
GEFAttr_t gefAttrs;
if (argc != 2) {
fprintf(stderr, "Usage: %s decimal\n", argv[0]);
exit(1);
}
/* Configure GEF for process. */
sigemptyset(&osSignalSet); sigaddset(&osSignalSet, SIGFPE);
GEFInitialize(osSignalSet);
/* Configure GEF for thread */
GEFAttr_Init(&gefAttrs);
GEFAttr_SetAssertionViolation(&gefAttrs, AssertionViolation);
GEFAttr_SetUnhandledException(&gefAttrs, UnhandledException);
GEFAttr_SetOutOfMemory(&gefAttrs, InsufficientMemory);
GEFAttr_SetOSSignalToException(&gefAttrs, OSSignalToException);
GEFInitializeThread(gefAttrs);
gef_enable_assertions;
gef_try {
number = atof(argv[1]);
answer = SquareRoot(number);
printf("%f\n", answer);
} gef_preconditions {
gef_assert(argc == 2);
} gef_catch(exception) {
switch((int) exception) {
case EXCEPT_ARITHMETIC_VIOLATION:
fprintf(stderr,"%s: Cannot take square root of %f!\n",argv[0],number);
exitCode = 1;
gef_break;
default: break;
}
} gef_end;
GEFTerminate();
exit(exitCode);
}
voidPrintConcatenation(char* s1, char* s2, FILE* fp) {
char* result = NULL;
gef_try {
result = malloc(strlen(s1) + strlen(s2) + 1);
gef_assert(result != NULL);
strcpy(result, s1);
strcat(result, s2);
fprintf(fp, "Concatenation of %s and %s is %s!\n", s1, s2, result);
} gef_preconditions {
gef_assert(result == NULL);
gef_assert(s1 != NULL);
gef_assert(s2 != NULL);
} gef_finally {
if (result != NULL) free((void*) result);
result = NULL;
} gef_end;
}
Dr. Dobb's Journal November 1998
Eiffel is a programming language that champions the "programming by contract" paradigm, an alternate approach for dealing with exceptional conditions. In such a paradigm, your function specifies the specific conditions, in the form of assertions, that must hold true before a client may execute your function. In addition, your function may also specify any conditions that must hold true after it completes its operation.
For example, a function that computes the square root of a number may require that its input be nonnegative. This is a precondition. In addition, the function may, as part of its contract, guarantee that the absolute value of the difference between the number and the square of the answer not exceed 0.0001. This is a postcondition.
Another aspect of a contract is the invariant -- a condition that must be true at the beginning of a function's execution and hold true after it returns, as well.
For example, imagine that you created a dynamic array data structure in C, whose lower and upper bounds could change dynamically, increasing or decreasing, depending upon whether you added elements to the top of the array, or to the bottom of the array, or removed elements from the top of the array, or from the bottom. A condition that would always hold true, regardless of the operation, is that the upper bound of the array minus its lower bound plus 1 would always be equal to its size. This is an invariant. For example, an array whose size is 0 might have a lower bound of 0 and an upper bound of -1. This would satisfy the invariant, since the upper bound, -1, minus the lower bound, 0, plus 1 would be equal to the size of the array, 0. The existence of invariant, precondition, and postcondition statements can make your program very robust.
-- B.B.
Dr. Dobb's Journal November 1998
Terms of Service | Privacy Statement | Copyright © 2024 UBM Tech, All rights reserved.