1.3. The hooks

The before and after trace hooks only exists to be able to generate a report at the end of a trace computation. The effective computation is done by the event hooks.

These hooks does particular computation on data arriving as argument, a call_data. The type of the call_data, when a hook is called during the trace read, is a traceset context. It contains all the necessary information about the read in progress. This is the base class from which inherits trace set state, and trace set/trace/tracefile state is the base classe of trace set/trace/tracefile statistics. All these types can be casted to another without problem (a TracesetState, for example, can be casted to a TracesetContext, but it's not true for the casting between a TraceContext and a TracesetContext, see the chapter "How to use the trace reading context" for details). They offer the input data and they give a container (the attributes of the trace set/trace/tracefile statistics) to write the output of this hook.

The idea behind writing in the attributes container is to provide an extensible way of storing any type of information. For example, a specific module that adds statistics to a trace can store them there, and the statistic printout will automatically include the results produced by the specific module.

Output data does not necessarily need to be stored in such a global container though. If we think of data of which we need to keed track during the execution, an event counter for example, we should create our own data structure that contains this counter, and pass the address of the allocated structure as the hook_data parameter of the hook list creation function. That way, the hook will be called with its hook_data as first parameter, which it can read and write. We can think of this structure as the data related to the function that persists between each call to the hook. You must make sure that you cast the hook_data to the type of the structure before you use it in the hook function.

The detail about how to access the different fields of the reading context (the hook's call_data) will be discussed in the chapter "How to use the trace reading context".