8.7 Signalling execution of unreachable code

We can use the unreachable code exceptional–condition object–type to signal the execution of unreachable code; this happens when we know that a function call must raise an exception, but it for some erroneous reason it does not. We can instantiate this type and also derive new types from it. To catch this exceptional condition we can do:

cce_location_t        L[1];

if (cce_location(L)) {
  if (cctests_condition_is_unreachable(cce_condition(L))) {
    CCTESTS_PC(cctests_condition_unreachable_t, C, cce_condition(L));
    do_something_with(C);
  }
  cce_run_catch_handlers_final(L);
} else {
  do_something(L);
  cce_run_body_handlers(L);
}

Struct Typedef: cctests_descriptor_unreachable_t

Type of data structure representing the exceptional–condition descriptor. It has the following public fields:

cce_descriptor_t descriptor

The condition descriptor’s base values.

The parent of this type descriptor is the one referenced by cctests_descriptor_failure_ptr, Signalling test failure.

Struct Typedef: cctests_condition_unreachable_t

Type of data structure representing the exceptional–condition object. It has the following public fields:

cctests_condition_failure_t failure

The condition object’s base values.

char const * filename

Pointer to a statically allocated ASCIIZ string representing the pathname of the source file in which the unreachable code is located. This value is meant to be generated with the preprocessor macro __FILE__.

char const * funcname

Pointer to a statically allocated ASCIIZ string representing the name of the function in which the unreachable code is located. This value is meant to be generated with the preprocessor macro __func__.

int linenum

The line number in the source file in which the unreachable code is located. This value is meant to be generated with the preprocessor macro __LINE__.

Function: void cce_descriptor_set_parent_to(cctests_condition_unreachable_t) (cce_descriptor_t * const D)

Set the parent of the descriptor referenced by D to the descriptor of the exceptional–condition object–type cctests_condition_unreachable_t.

Function: void cctests_condition_init_unreachable (cctests_condition_unreachable_t * C, char const * filename, char const * funcname, int linenum)

Initialisation function for the condition object. This function is meant to be called from the initialisation function of sub–types of cctests_condition_unreachable_t.

Function: cce_condition_t const * cctests_condition_new_unreachable (cce_destination_t L, char const * filename, char const * funcname, int linenum)

Return a pointer to exceptional condition object. If an error occurs building the instance: raise an exception by performing a non–local exit to L.

Function: bool cctests_condition_is_unreachable (cce_condition_t const * C)

Return true if C if of type cctests_condition_unreachable_t; otherwise return false.

Preprocessor Macro: cctests_raise_unreachable (cce_destination_t L)

Raise an exceptional condition of type cctests_condition_unreachable_t by expanding into:

cce_raise((L), cctests_condition_new_unreachable((L), __FILE__, __func__, __LINE__))

Sub–typing example

To define a sub–type of cctests_condition_unreachable_t we can copy the code in the files:

condition-unreachable-subtype.c
condition-unreachable-subtype-headear.h
condition-unreachable-subtype-body.c

under the tests directory of the source distribution; the code defines a new condition–object type my_condition_unreachable_subtype_t.

This document describes version 0.4.1-devel.1 of CCTests.