Checks

Much of the CGAL code contains checks. For example, all checks used in the kernel code are prefixed by CGAL_KERNEL. Other packages have their own prefixes, as documented in the corresponding chapters. Some are there to check if the kernel behaves correctly, others are there to check if the user calls kernel routines in an acceptable manner.

There are four types of checks. The first three are errors and lead to a halt of the program if they fail. The last only leads to a warning.

By default, all of these checks are performed. It is however possible to turn them off through the use of compile time switches. For example, for the checks in the kernel code, these switches are the following: CGAL_KERNEL_NO_PRECONDITIONS, CGAL_KERNEL_NO_POSTCONDITIONS, CGAL_KERNEL_NO_ASSERTIONS and CGAL_KERNEL_NO_WARNINGS. So, in order to compile the file foo.C with the postcondition checks off, you should do:
CC -DCGAL_KERNEL_NO_POSTCONDITIONS foo.C

Not all checks are on by default. All four types of checks can be marked as expensive or exactness checks (or both). These checks need to be turned on explicitly by supplying one or both of the compile time switches CGAL_KERNEL_CHECK_EXPENSIVE and CGAL_KERNEL_CHECK_EXACTNESS.

Expensive checks are, as the word says, checks that take a considerable time to compute. Considerable is an imprecise phrase. Checks that add less than 10 percent to the execution time of the routine they are in are not expensive. Checks that can double the execution time are. Somewhere in between lies the border line. Checks that increase the asymptotic running time of an algorithm are always considered expensive. Exactness checks are checks that rely on exact arithmetic. For example, if the intersection of two lines is computed, the postcondition of this routine may state that the intersection point lies on both lines. However, if the computation is done with doubles as number type, this may not be the case, due to round off errors. So, exactness checks should only be turned on if the computation is done with some exact number type.

2.1 Altering the failure behaviour

As stated above, if a postcondition, precondition or assertion is violated, the program will abort (stop and produce a core dump). This behaviour can be changed by means of the following function.

enum Failure_behaviour { ABORT , EXIT , EXIT_WITH_SUCCESS , CONTINUE };

The first value is the default. If the EXIT value is set, the program will stop and return a value indicating failure, but not dump the core. The last value tells the checks to go on after diagnosing the error.

advanced

If the EXIT_WITH_SUCCESS value is set, the program will stop and return a value corresponding to successful execution and not dump the core.

advanced

The value that is returned by set_error_behaviour is the value that was in use before.

For warnings there is a separate routine, which works in the same way. The only difference is that for warnings the default value is CONTINUE.

2.2 Control at a finer granularity

The compile time flags as described up to now all operate on the whole library. Sometimes you may want to have a finer control. CGAL offers the possibility to turn checks on and off with a bit finer granularity, namely the module in which the routines are defined. The name of the module is to be appended directly after the CGAL prefix. So, the flag CGAL_KERNEL_NO_ASSERTIONS switches off assertions in the kernel only, the flag CGAL_CH_CHECK_EXPENSIVE turns on expensive checks in the convex hull module. The name of a particular module is documented with that module.

advanced

2.3 Customising how errors are reported

Normally, error messages are written to the standard error output. It is possible to do something different with them. To that end you can register your own handler. This function should be declared as follows.

void
my_failure_function (
const char *type,
const char *expression,
const char *file,
int line,
const char *explanation)

Your failure function will be called with the following parameters. type is a string that contains one of the words precondition, postcondition, assertion or warning. The parameter expression contains the expression that was violated. file and line contain the place where the check was made. The explanation parameter contains an explanation of what was checked. It can be NULL, in which case the expression is thought to be descriptive enough.

There are several things that you can do with your own handler. You can display a diagnostic message in a different way, for instance in a pop up window or to a log file (or a combination). You can also implement a different policy on what to do after an error. For instance, you can throw an exception or ask the user in a dialogue whether to abort or to continue. If you do this, it is best to set the error behaviour to CONTINUE, so that it does not interfere with your policy.

You can register two handlers, one for warnings and one for errors. Of course, you can use the same function for both if you want. When you set a handler, the previous handler is returned, so you can restore it if you want.

#include <CGAL/assertions.h>

Failure_function set_error_handler ( Failure_function handler)

Failure_function set_warning_handler ( Failure_function handler)

Example

#include <CGAL/assertions.h>

void my_failure_handler(
    const char *type,
    const char *expr,
    const char* file,
    int line,
    const char* msg)
{
    /* report the error in some way. */
}

void foo()
{
    CGAL::Failure_function prev;
    prev = CGAL::set_error_handler(my_failure_handler);
    /* call some routines. */
    CGAL::set_error_handler(prev);
}

end of advanced section advanced

Failure_function	set_error_handler ( Failure_function handler)
Failure_function	set_warning_handler ( Failure_function handler)

Chapter 2Checks

2.1 Altering the failure behaviour

2.2 Control at a finer granularity

2.3 Customising how errors are reported

Example

Chapter 2
Checks