Event Processing

Overview

Interaction events are the mechanism that the HNM uses to notify clients about changes in the system. The HMI can subscribe to the HNM to receive these events, which can then be dispatched to the appropriate applications.

Interaction events live through two stages:
  • event generation—applications or services (including the HMI) create events for the HNM to manage
  • event processing—the HNM examines the priority of events to determine which ones to act upon
The process works essentially as follows:
  1. An application decides how a certain event should be handled. For example, if the app wants an event to trigger a notice to appear on the display, it will set up a display event for the HNM to handle.
  2. The HNM maps the received event to its policy configuration to determine the event's priority.
  3. The HNM then decides whether to preempt other events, based on their priority, and to activate the newly received event.
  4. To notify subscribers of any changes to its state, the HNM updates the PPS Status object (/pps/services/hmi-notification/Status).

Priorities

Applications can specify priorities in their policy configuration files by using integer values in the range 0 (lowest) to 7 (highest). The format for the configuration file's relevant section (called "event-priorities") looks like this: 
event-priorities {
        EventName = <priority_value>
        EventNameSpace {
                # This event's name will be prepended by the
                # 'EventNameSpace::' string, making it
                # distinct from the previous definition of
                # 'EventName'.
                EventName = <priority_value>
        }
}
For example, here's an excerpt from the event-priorities section of the configuration file for the VirtualMechanic plugin module: 
event-priorities {
				Caution {
					fuelLevel = 2
					washerFluidLevel = 1
					transmissionFluidLevel = 2
					coolantLevel = 2
					brakeFluidLevel = 2
					tirePressure = 1
					tireWear = 1
					brakePadWear = 1
					brakeAbs = 1
					engineOilPressure = 2
					engineOilLevel = 2
					rpm = 0
					#temperature = 2
					#clutch_wear = 2
					lightHead = 2
					lightTail = 2
				}

For more information on configuration files, see "Configuration" in this guide.

If a priority configuration isn't specified for a particular event in the configuration file, the HNM will assign a default value. The default priority will depend on the window type that's requested. Here are the window types and their default priorities:
Window type Default priority Description
Fullscreen 0 The notification takes up the whole window.
Growl 0 A subtle, transient notification.
Hidden 0 The notification isn't displayed.
Note: The Hidden window type is defined only for the sake of completeness—it shouldn't be used in practice.
Notification 0 The notification remains on the screen (e.g., a status bar).
Overlay 0 The notification appears in a popup overlay.

Priority scenarios

The HNM must handle three distinct priority scenarios when an application asks for an event to be processed:
  1. The event has a lower priority than the currently active event.
  2. The event has the same priority as the currently active event.
  3. The event has a higher priority than the currently active event.
These scenarios can be extended to accommodate the case where multiple asynchronous events can arrive simultaneously. Although queues are the ideal data structure to accommodate this workflow, not all interactions can be delayed. Therefore, events are handled according to the following rules:
  • If multiple events are received with varying priorities, the HNM will process each event, queuing the events with lower priority and handling only the highest-priority event.
  • If multiple events are received with the same priority, the HNM will queue those that can be queued and will process one of the remaining events, dropping the rest.

Event types

Events are categorized into classes that correspond to the interaction types (e.g., display, audio). A class of interaction events can have subtypes. For example, the display class has these subtypes:
display-start
An app creates this event to ask the HMI to display a window. If the event's priority value is greater than that of all active events, then the HNM will service the event. Otherwise, a fallback window type will be requested, causing the appraisal to repeat until no more fallback types are left to try. For example: 
event->window_type = HNM_WINDOW_NOTIFICATION ;
event->fallback_types[ 0 ] = HNM_WINDOW_GROWL ;
event->fallback_types[ 1 ] = HNM_WINDOW_HIDDEN ;
event->fallback_types[ 2 ] = HNM_WINDOW_HIDDEN ;
event->fallback_types[ 3 ] = HNM_WINDOW_HIDDEN ;
display-end
An app creates this event to ask the HMI to hide a window.

Sharing the display

Some apps may be willing to share the display with others. Although the HNM doesn't mandate how the display is physically shared, it must be aware of which applications can share the display (and under which circumstances) so it can decide whether to allow an app to display itself.

Apps can specify whether windows can share the display by setting one of the following display-control flags:
HNM_DISPLAY_SHARED
Indicates that the window type can share the display regardless of what is currently being displayed.
HNM_DISPLAY_EXCLUSIVE
Indicates that the window type can't share the display with any other exclusive window type.
HNM_DISPLAY_SEMI_EXCLUSIVE
Indicates that the window type can be shared with a predefined number of semi-exclusive windows, which depends on the number of available display slots (defined in the policy configuration).

These controls are specified in the window-types section of the policy.cfg file. For details, see "Window types" in the "Configuration" chapter.