32: Broadcasting Events

1. Overview
   1. Events allow one process (the source) to communicate with many other processes (its intended destinations) with a single action.
   2. Only processes defined using the EventProcess mix-in can broadcast and receive events.
   3. An event is broadcast from one process to its intended destination using a signal.
      1. A signal is an event that specifies the source process (the telename of the broadcasting process) and the time it was sent.
   4. An event process registers interest in receiving broadcasts by creating a set of event classes it will receive. Each item in the set is an event selector.
      1. Event type is determined by class (which must be a subclass of the class Event).
      2. Broadcast interest can be further refined by specifying a single process by telename so that only events broadcast from that process are received.
   5. When a process broadcasts a signal, the Telescript engine checks all event processes to see if they're interested in the signal. If so, the engine adds the signal to a FIFO stack maintained by the engine for the process. The process can retrieve the signal at its leisure.
2. Setting events to be received
   1. An event is simply a source (the telename of the sending process) and a time (the time the event was sent).
      1. The class of the event (a subclass of Event) is important information itself.
   2. An event process has a property that is a set of objects that are members of the class Event.
      1. Each object in this set is an event selector.
      2. Different event selectors are created by subclassing the class Event.
      3. An event selector specifies that the process can receive any signal carrying an event that is a member of the event selector's class.
         1. If the event selector contains a telename in its source attribute, the event selector specifies only events from that source.
         2. If the event selector contains a nil in its source attribute, it specifies events from any source.
   3. The disableEvents operation (on EventProcess) removes event selectors from the set.
   4. The enableEvents operation (on EventProcess) adds event selectors to the set.
3. Sending a signal
   1. The signalEvent operation (on EventProcess) accepts an event, sets its source and time attributes, and asks the engine to broadcast the event as a signal.
   2. The scope of intended destinations is set using these four identifiers:
      1. responder: broadcast this signal to the source alone (source-to-source broadcasting)
      2. responderDeep: broadcast this signal to the responder and, if the responder is a place, to all of its occupants and their occupants recursively
      3. occupants: broadcast this signal to the source's occupants, but not their occupants. If the source is not a place, don't broadcast at all.
      4. occupantsDeep: broadcast this signal to the source's occupants and their occupants recursively. If the source is not a place, don't broadcast at all.
   3. Note that events are broadcast only within an engine place; they cannot be broadcast between engine places. You can, however, send agents to different engine places to broadcast the same event.
4. Dealing with signals in the queue
   1. The engine maintains a FIFO stack of received signals (those that match an event selector in the process) for the life of the process
   2. Use the getEvent operation (on EventProcess) to check the queue and retrieve an event.
      1. With no specifications, this operation removes the first event from the stack and returns it.
      2. If you specify an event selector, this operation removes the first event of that kind from the stack and returns it.
      3. If you specify a waiting interval, this operation goes to the stack and--if it can't find the specified event--waits until the specified event arrives or the waiting intervale expires.
   3. Use the clearEvents operation to clear the queue of signals.

Generated by the sweat of Mike Boom's brow.