# About the Event Broker

Working with an interactive device such as a controller pad poses a challenge to traditional I/O architectures; a user can change the device's state at any time, so a task working with a device must monitor it constantly. Successful device monitoring requires a task to run a loop that continually polls the interactive device, or requires the interactive device driver to accept an I/O request but does not respond until it detects a change in the device. In the first case, the polling task uses a lot of processor time. In the second case, a task has to have several IOReqs pending to avoid losing any device changes while the driver returns an IOReq. Portfolio provides the event broker, a solution to interactive device I/O that requires neither polling nor multiple IOReqs.

The event broker is a task that constantly monitors activity on attached interactive devices. Currently, interactive devices are attached only to the control port on the 3DO system. The event broker monitors the control port to see what the devices are doing.

Activities on interactive devices are called events. Events include joypad presses and releases, key strokes, mouse rolling, plugging a new control device into the control port, unplugging a device from the control port, and many others. Events can occur on any hardware device attached to the control port. A hardware device is called a pod. The event broker always identifies the pod in which an event occurs.

The event broker starts when the system starts up, and stands between user tasks and the interactive pods on the control port. To work with interactive devices, a user task connects to the event broker and registers itself as a listener. A listener is a task that connects to the event broker to receive event notification and to pass data to pods. To become a listener, a task creates a message port for communication with the event broker. Then the task communicates its requests to the event broker with messages; the event broker responds to these messages with its own messages. I/O operations through the event broker are carried out through messages instead of IOReqs.

## Specifying and Monitoring Events

The first message a listener task sends to the event broker contains two event masks. A listener task uses the first event mask to specify which of the 256 different event types it is interested in hearing about. This mask is the trigger mask; it lists all event types that can trigger an event message to the listener. The second event mask is the capture mask; it lists all event types for which the event broker must check status whenever it sends an event message.

In each video field the event broker checks pods for events, 60 times per second on NTSC systems, and 50 times per second on PAL systems. If any of the events it senses match an event in a listener task trigger mask, the event broker composes an event message to send to the listener. That event message contains a pointer to an accompanying data block that contains information about all event types that are specified in either the trigger mask or the capture mask.

The event broker takes a "snapshot" of the pods' states whenever a triggering event occurs. For example, a listener can specify "controller pad button down" as a trigger event and then specify "gunlike-device button pressed" and "keyboard key pressed" as capture events. Whenever a controller pad button is pressed down in a pod, the event broker is triggered to send an event message to the listener. The event message's data block contains the status of "controller pad button down" (true because it was the triggering event), the status of "gunlike-device button pressed" (true or false, depending on whether or not the button was pressed on any attached gunlike devices during the field), and the status of "keyboard key pressed" (true or false, depending on whether or not any keys were pressed on any attached keyboards). The listener task now knows that the controller pad button was pressed, and knows whether or not any keyboard keys or buttons on gunlike devices were pressed during the same video field. The listener can then take appropriate action.

Because the event broker notifies listeners of events via messages, a listener task can enter the wait state for an event broker message, just as a task waits for any other message. This allows synchronous I/O with interactive pods. A listener can also continue execution after sending an event broker message, which allows asynchronous I/O. In either case, whenever a listener task receives a message from the event broker, it must reply to the event broker and say the message is processed and can be reused. If the listener task does not reply, the event message queue can fill up, and it can lose events in which it was interested.

## Working With Input Focus

Input focus is an important concept to both 3DO users and 3DO tasks. When several tasks occupy the display at the same time, input focus determines which task should respond to the user's actions. For example, a pinball game occupies one part of the display, while a CD-ROM encyclopedia occupies another part. When the user presses the "left" direction of the controller pad's joypad, does the left pinball flipper flip, or does the reader for the encyclopedia move back a page? It depends on which program has the input focus. If the user chose the reader earlier (via menu selection, for example) so that the reader is now the active task, the reader holds the input focus and responds to the controller pad.

The event broker sends events to the appropriate focus holder-if connected tasks are set up to pay attention to focus. Whenever a task connects to the event broker, it can request to be one of three listener types:

- A focus-dependent listener, which only receives its specified events from the event broker when the event broker knows that the task has the input focus.

- A focus-independent listener, which receives all of its specified events from the event broker at all times.

- A focus-interested listener, which receives all of its specified events when it has the focus, and only non-user interface type events when it does not have the focus.

Tasks such as the encyclopedia reader and the pinball game mentioned above are usually focus-dependent listeners because they only respond when the user selects the task. Tasks that offer a program-selection menu to the user are usually focus-independent because they must respond at any time to user requests, even if they do not hold the focus.

## Reconfiguring or Disconnecting an Event Broker Connection

As a listener task works with the event broker, it can send a message requesting a new configuration at any time. The new configuration can reset the task's focus dependence, specify new capture and trigger events, set a new message port, or change other connection parameters. A listener task can also request to be disconnected from the event broker so that it will no longer be notified of interactive events.

## Other Event Broker Activities

Although the event broker's main activity is monitoring and reporting on interactive device events, it can also:

- Provide lists of connected devices and listener tasks
- Send and receive I/O data from interactive devices
- Send generic commands to interactive devices
- Notify a listener task of events occurring in other listener tasks