Event Handling

The C Statistics API can be used to detect when certain events occur at the level of the ipqos module, and to return information about the event that has occurred. There are three ways to detect that an event has occurred:

• By using poll(2) or select(3c) to examine the file descriptor

• By enabling the device to send a signal directly to the user process

• By calling the function ba_get_next_event() to check for the next event

As events are buffered, if using poll(2) or select(3c), you must call ba_get_next_event() repeatedly in non-blocking mode to check that there are no outstanding events, to make sure that the next poll(2) works correctly.

Once you have detected that an event has occurred, for example, by using poll(2), call the function ba_get_next_event() to retrieve information about the event.

The C Statistics API provides the following functions for event handling:

• ba_set_event_mask() sets the event mask to indicate which of the events listed in Table 3-1 should be reported.

• ba_get_event_mask() retrieves the current event mask.

• ba_get_next_event() retrieves information about the most recent event that occurred.

• ba_enable_signal() enables the signalling mechanism so that the ipqos module can send a signal directly to the user process.

• ba_disable_signal() disables the signalling mechanism.

Table 3-1 lists the event types reported to the user process.

To limit the number of events held in the buffer, edit the environment variable BA_EVENTBUFSIZE in the /etc/default/ba_info file. To buffer an unlimited number of events, set this value to 0, but note that this will lead to kernel memory exhaustion if all events are not retrieved.