6.12 The unreachable code exceptional–condition object

We can use the unreachable code exceptional–condition object–type to signal the execution of unreachable code.

All the following definitions are accessible from the header file ccexceptions.h.

Struct Typedef: cce_descriptor_unreachable_t

Structure type representing the exceptional–condition object–type descriptor. This descriptor has the descriptor cce_descriptor_logic_error_t as parent. It has the following public fields:

cce_descriptor_t descriptor

Core values of the exceptional–condition object–type descriptor.

Struct Typedef: cce_condition_unreachable_t

Structure type representing the unreachable code exceptional–condition object. It has the following public fields:

cce_condition_logic_error_t logic_error

Core values of the exceptional–condition object–type descriptor.

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: cce_condition_t const * cce_condition_new_unreachable (cce_destination_t L, char const * filename, char const * funcname, int linenum)

Return a pointer to a newly built exceptional–condition object of type cce_condition_unreachable_t. If an error occurs: raise an exception by performing a non–local exit to L.

Preprocessor Macro: void cce_raise_unreachable (cce_destination_t L)

If the preprocessor symbol CCEXCEPTIONS_EXCLUDE_UNREACHABLE is not defined: raise an exceptional condition of type cce_condition_unreachable_t by expanding into:

cce_raise((L),
  cce_condition_new_unreachable((L),
    __FILE__, __func__, __LINE__));

If the preprocessor symbol CCEXCEPTIONS_EXCLUDE_UNREACHABLE is defined: expand to nothing. By default CCEXCEPTIONS_EXCLUDE_UNREACHABLE is not defined.

Function: bool cce_condition_is_unreachable (cce_condition_t const * C)

Return true if the exceptional–condition object referenced by C is of type cce_condition_unreachable_t or it is derived from it; otherwise return false.

Facilities to derive an exceptional–condition object subtype

When deriving a subtype from cce_condition_unreachable_t we need the following functions.

Function: void cce_descriptor_set_parent_to(cce_descriptor_unreachable_t) (cce_descriptor_t * D)

Mutate the exceptional–condition object–type descriptor referenced by D so that its parent is the descriptor of cce_descriptor_unreachable_t. We should call this function in the initialisation module of the derived type.

Function: void cce_condition_init_unreachable (cce_condition_unreachable_t * C, char const * filename, char const * funcname, int linenum)

Initialise an already allocated exceptional–condition object. We should call this function from the initialisation function of the derived type.

Subtyping example

To define a subtype of cce_condition_unreachable_t we can copy the code in the files:

condition-subtyping-unreachable.c
condition-subtyping-unreachable-header.h
condition-subtyping-unreachable-body.c

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

This document describes version 0.9.0-devel.3 of CCExceptions.