Next: , Previous: , Up: Instruction Meta-class Definition   [Contents][Index]


4.3.2 Event Handling

The event handler function of an instruction meta-class can process the types of events, which are represented by macros listed below. The type of event is passed to the event handler function via the argument qsmm_evt.

Macro: QSMM_EVT_ENT_INIT

Instruction meta-class initialization. This event is sent by the function qsmm_reg_instr_meta_class called to register the instruction meta-class.

You may put initial assignments to variables and allocation of resources, which are used by the instruction meta-class, in a block of code that handles this event, together with other user code associated with the instruction meta-class.

Macro: QSMM_EVT_ENT_DONE

Instruction meta-class uninitialization. This event is sent to all registered instruction meta-class event handlers by the function qsmm_destroy called to destroy the multinode model.

In a block of code, which handles the event, resources could be freed that were allocated when processing event QSMM_EVT_ENT_INIT.

Macro: QSMM_EVT_INSTR_CLASS_INIT

Instruction class initialization. This event is sent by the function qsmm_reg_instr_class called to register an instruction class which is a subclass of the instruction meta-class. The function qsmm_reg_instr_class is usually called from the event handler function of an instruction class set during processing event QSMM_EVT_ENT_INIT for the instruction class set, and the instruction class is registered as belonging to that instruction class set.

A block of code, which handles the event, typically performs the following operations:

The functions mentioned above are described in detail further on in this section.

Macro: QSMM_EVT_INSTR_CLASS_DONE

Instruction class uninitialization. This event is sent for registered instruction classes upon uninitialization of the instruction meta-class or an instruction class set that contains them, which is currently performed during destruction of multinode model by the function qsmm_destroy.

In a block of code, which handles the event, a binary representation of instruction class parameters (see further on in this subsection) could be uninitialized, and additional resources associated with the instruction class, which were allocated while processing event QSMM_EVT_INSTR_CLASS_INIT, could be freed.

Macro: QSMM_EVT_ENGINE_INIT

Initialization of the model instance. This event is sent to all registered instruction meta-class event handlers (in lexicographical order of names of instruction meta-classes) by the function qsmm_engine_create, called to create the model instance, at the end of execution of that function.

In a block of code, which handles the event, initial assignments to user variables specific to the model instance could be made, and additional resources specific to the model instance could be allocated.

Macro: QSMM_EVT_ENGINE_DONE

Uninitialization of the model instance. This event is sent by the function qsmm_engine_destroy to all registered instruction meta-class event handlers at the beginning of execution of that function in order, which is reverse for order, in which event QSMM_EVT_ENGINE_INIT was sent. The function qsmm_engine_destroy can be called explicitly, but is also called automatically when recreating the model instance by the function qsmm_engine_create and when destroying the multinode model by the function qsmm_destroy.

In a block of code, which handles the event, additional resources could be freed that were allocated when processing event QSMM_EVT_ENGINE_INIT.

Macro: QSMM_EVT_ACTIVATE

Instruction invocation. A block of code, which handles the event, performs custom actions associated with the instruction class that change system or environment state. In that block of code, the outcome of the instruction can be set using the function qsmm_set_instr_outcome. See Handling Instruction Invocation, for more information.

Upon successful completion, the event handler function must return a non-negative value. Specific non-negative value will have no effect on system operation. On error, the event handler function should return a negative value. Such negative value will cause a model error handler to be invoked if it is set.

An instruction class may have parameters associated with it. Instruction class parameters have two forms: binary and text. A text form is derived from a binary form. Instruction class parameters in text form are printed after an instruction meta-class name and together they make up the whole instruction class name. Instruction class parameters in binary form can be specified when registering the instruction class by the function qsmm_reg_instr_class. The purpose of the following function is to fetch binary instruction class parameters to a buffer, which could be a variable or a structure instance, in the event handler function of instruction meta-class.

Function: int qsmm_get_eh_instr_param (qsmm_t model, int bufsz, void *bufp)

This function fetches a binary representation of parameters of an instruction class associated with an event being processed. The binary representation is copied to buffer bufp of size bufsz bytes. The function can only be called from the event handler function of an instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE. Handle model specifies a multinode model the instruction meta-class belongs to.

Size bufsz of the buffer must be greater than or equal to the size of the binary representation of instruction class parameters specified when registering the instruction class using the function qsmm_reg_instr_class. If bufsz is greater than the size of the binary representation of the instruction class parameters, then remaining contents of buffer bufp will be left intact.

On success, the function returns a non-negative number equal to the size in bytes of the binary representation of instruction class parameters copied to buffer bufp. On failure, a negative error code is returned. Currently, the following error codes can be returned.

QSMM_ERR_UNTIMELY

The function was not called from the event handler function of instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE.

QSMM_ERR_INVAL

The value of bufsz is less than the size of the binary representation of instruction class parameters specified when registering the instruction class using the function qsmm_reg_instr_class.

Because a binary representation of instruction class parameters is needed when processing several types of events, it is reasonable to fetch the parameters at the beginning of the event handler function when processing those types of events. To prevent raising error QSMM_ERR_UNTIMELY and possible invocation of model error handler because of an inappropriate event type, the following macro can be used to check whether the type of event is appropriate to call the function qsmm_get_eh_instr_param.

Macro: QSMM_HAS_INSTR_CLASS (evt)

This macro is expanded to:

((evt)==QSMM_EVT_INSTR_CLASS_INIT ||
 (evt)==QSMM_EVT_INSTR_CLASS_DONE ||
 (evt)==QSMM_EVT_ACTIVATE)

This macro is intended for checking whether an instruction class is associated with type evt of an event processed by the event handler function, and it is safe to call the function qsmm_get_eh_instr_param and other functions that use instruction class context.

For example, to fetch a binary representation of instruction class parameters at the beginning of the event handler function of instruction meta-class ‘move’, the instruction meta-class definition may be written as follows:

static QSMM_INSTR_META_CLASS(move) {
    enum direct_e direct=0;
    if (QSMM_HAS_INSTR_CLASS(qsmm_evt))
        qsmm_get_eh_instr_param(qsmm,sizeof(direct),&direct);
    ...
}

To get the name of an instruction class set to which an instruction class belongs, a function described below can be called when processing an event by the event handler function of instruction meta-class. The described function can also be used to get the name of an instruction class set when processing an event by the event handler function of the instruction class set.

Function: int qsmm_get_eh_instr_class_set_name (qsmm_t model, const char **instr_class_set_name_pp)

This function retrieves the name of an instruction class set that corresponds to an event being processed by an event handler function of a multinode model specified by handle model. If instr_class_set_name_pp is not NULL, then the function will set *instr_class_set_name_pp to the name of that instruction class set. If this function is called from the event handler function of an instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE, then it will retrieve the name of an instruction class set that contains an instruction class associated with the event. If this function is called from the event handler function of an instruction class set, then it will retrieve the name of that instruction class set.

On success, the function returns a non-negative value. If the function is not called from the event handler function of instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE, and is not called from the event handler function of instruction class set, then negative error code QSMM_ERR_UNTIMELY will be returned.


Next: , Previous: , Up: Instruction Meta-class Definition   [Contents][Index]