6.2 Exceptional–condition object–type descriptors

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

Struct Typedef: cce_descriptor_t

Structure type representing exceptional–condition object–type descriptors; it holds a table of function pointers to handle exceptional–condition objects. It has the following fields:

cce_descriptor_t const * parent

Pointer to the descriptor that is parent of this one in the tree hierarchy. This pointer is set to NULL only for the root condition descriptor, See Predefined root condition descriptor.

cce_condition_final_fun_t * delete

Pointer to function releasing the exceptional–condition object’s memory block itself. This pointer can be NULL, meaning that: the object is statically allocated.

cce_condition_final_fun_t * final

Pointer to function releasing all the dynamic resources associated to the exceptional–condition object. This pointer can be NULL, meaning that: there are no dynamic resources.

cce_condition_static_message_fun_t * static_message

Pointer to function returning a statically allocated ASCIIZ string describing the exceptional–condition.

Function Prototype: void cce_condition_final_fun_t (cce_condition_t * C)

Release all the dynamic resources associated to C; leave untouched the memory block holding the cce_condition_t instance itself.

Function Prototype: void cce_condition_delete_fun_t (cce_condition_t * C)

Release the memory block referenced by C, if appropriate. If the structure is allocated with malloc(), the delete function can just be:

void
my_condition_delete_stuff (my_condition_stuff_t * C)
{
  free(C);
}

Function Prototype: char const * cce_condition_static_message_fun_t (cce_condition_t const * C)

Return a statically allocated ASCIIZ string describing the exceptional–condition. A static message must always be defined; another client–defined function can build a dynamic and more descriptive message.

For example, an instance of this function can be:

char const *
my_condition_static_message_stuff (my_condition_stuff_t const * C)
{
  return "error doing stuff";
}

Function: bool cce_descriptor_child_and_ancestor (cce_descriptor_t const * child, cce_descriptor_t const * ancestor)

Establish if two condition descriptors are child and ancestor. Return true if child is equal to ancestor or ancestor is in the hierarchy of child’s ancestors; otherwise return false.

Generic Macro: cce_descriptor_t * cce_descriptor (X)

This generic macro dispatches its expansion according to its argument’s type:

• Given a pointer to condition object: retrieve the pointer to its descriptor and cast it to a pointer to cce_descriptor_t.
• Given a pointer to condition descriptor: cast it to a pointer to cce_descriptor_t.

This generic macro performs compile–time type–checking so that the cast operation is applied only on values of suitable types; we can apply this macro to pointers to all the types defined by CCExceptions for which it makes sense.

Macro: cce_descriptor_set_parent_to (TYPE)

Expand into the name of a function that we can use to set the parent of a descriptor to the given TYPE descriptor.

Macro: cce_descriptor_pointer (EXCEPTIONAL_CONDITION_DESCRIPTOR_VARIABLE)

Expand into:

&((EXCEPTIONAL_CONDITION_DESCRIPTOR_VARIABLE).descriptor)

Given an exceptional-condition descriptor struct defined as:

typedef struct descr_t  descr_t;

struct descr_t {
  cce_descriptor_t      descriptor;
};

descr_t my_descriptor_descr = { ... };

this macro is used as:

cce_descriptor_pointer(my_descriptor_descr)

to expand into:

&((my_descriptor_descr).descriptor)

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