test

ToolTalk User's Guide

ToolTalk Message Delivery Algorithm

To help you further understand how the ToolTalk service determines message recipients, this section describes the creation and delivery of both process-oriented messages and object-oriented messages.

Process-Oriented Message Delivery

For some process-oriented messages, the sending application knows the ptype or the procid of the process that should handle the message. For other messages, the ToolTalk service can determine the handler from the operation and arguments of the message.

  1. Initialize.

    The sender obtains a message handle and fills in the address, scope, and class attributes.

    The sender fills in the operation and arguments attributes.

    If the sender has declared only one ptype, the ToolTalk service fills in sender_ptype by default; otherwise, the sender must fill it in.

    If the scope is TT_FILE, the file name must be filled in or defaulted. If the scope is TT_SESSION, the session name must be filled in or defaulted. If the scope is TT_BOTH or TT_FILE_IN_SESSION, both the file name and session name must be filled in or defaulted.

    Note -

    The set of patterns checked for delivery depends on the scope of the message. If the scope is TT_SESSION, only patterns for processes in the same session are checked. If the scope is TT_FILE, patterns for all processes observing the file are checked. If the scope is TT_FILE_IN_SESSION or TT_BOTH, both sets of processes are checked.

    The sender may fill in the handler_ptype if known. However, this greatly reduces flexibility because it does not allow processes of one ptype to substitute for another. Also, the disposition attribute must be specified by the sender in this case.

  2. Dispatch to handler.

    The ToolTalk service compares the address, scope, message class, operation, and argument modes and types to all signatures in the Handle section of each ptype.

    Only one ptype will usually contain a message pattern that matches the operation and arguments and specifies a handle. If a handler ptype is found, then the ToolTalk service fills in opnum, handler_ptype, and disposition from the ptype message pattern.

    If the address is TT_HANDLER, the ToolTalk service looks for the specified procid and adds the message to the handler's message queue. TT_HANDLER messages cannot be observed because no pattern matching is done.

  3. Dispatch to observers.

    The ToolTalk service compares the scope, class, operation, and argument types to all message patterns in the Observe section of each ptype.

    For all observe signatures that match the message and specify TT_QUEUE or TT_START, the ToolTalk service attaches a record (called an "observe promise") to the message that specifies the ptype and the queue or start options. The ToolTalk service then adds the ptype to its internal ObserverPtypeList.

  4. Deliver to handler.

    If a running process has a registered handler message pattern that matches the message, the ToolTalk service delivers the message to the process; otherwise, the ToolTalk service honors the disposition (start or queue) options.

    If more than one process has registered a dynamic pattern that matches the handler information, the more specific pattern (determined by counting the number of non-wildcard matches) is given preference. If two patterns are equally specific, the choice of handler is arbitrary.

  5. Deliver to observers.

    The ToolTalk service delivers the message to all running processes that have registered Observer patterns that match the message. As each delivery is made, the ToolTalk service checks off any observe promise for the ptype of the observer. After this process is completed and there are observe promises left unfulfilled, the ToolTalk service honors the start and queue options in the promises.

Example

In this example, a debugger uses an editor to display the source around a breakpoint through ToolTalk messages.

The editor has the following Handle pattern in its ptype:

(HandlerPtype: TextEditor;
  Op: ShowLine;
  Scope: TT_SESSION;
  Session: my_session_id;
  File: /home/butterfly/astrid/src/ebe.c)

  1. When the debugger reaches a breakpoint, it sends a message that contains the op (ShowLine), argument (the line number), file (the file name), session (the current session id), and scope (TT_SESSION) attributes.

  2. The ToolTalk service matches this message against all registered patterns and finds the pattern registered by the editor.

  3. The ToolTalk service delivers the message to the editor.

  4. The editor then scrolls to the line indicated in the argument.

Object-Oriented Message Delivery

Many messages handled by the ToolTalk service are directed at objects but are actually delivered to the process that manages the object. The message signatures in an otype, which include the ptype of the process that can handle each specific message, help the ToolTalk service determine process to which it should deliver an object-oriented message.

  1. Initialize.

    The sender fills in the class, operation, arguments, and the target objid attributes.

    The sender attribute is automatically filled in by the ToolTalk service. The sender can either fill in the sender_ptype and session attributes or allow the ToolTalk service to fill in the default values.

    If the scope is TT_FILE, the file name must be filled in or defaulted. If the scope is TT_SESSION, the session name must be filled in or defaulted. If the scope is TT_BOTH or TT_FILE_IN_SESSION, both the file name and session name must be filled in or defaulted.

    Note -

    The set of patterns checked for delivery depends on the scope of the message. If the scope is TT_SESSION, only patterns for processes in the same session are checked. If the scope is TT_FILE, patterns for all processes observing the file are checked. If the scope is TT_FILE_IN_SESSION or TT_BOTH, both sets of processes are checked.

  2. Resolve.

    The ToolTalk service looks up the objid in the ToolTalk database and fills in the otype and file attributes.

  3. Dispatch to handler.

    The ToolTalk service searches through the otype definitions for Handler message patterns that match the message's operation and arguments attributes. When a match is found, the ToolTalk service fills in scope, opnum, handler_ptype, and disposition from the otype message pattern.

  4. Dispatch to object-oriented observers.

    The ToolTalk service compares the message's class, operation, and argument attributes against all Observe message patterns of the otype. When a match is found, if the message pattern specifies TT_QUEUE or TT_START, the ToolTalk service attaches a record (called an "observe promise") to the message that specifies the ptype and the queue or start options.

  5. Dispatch to procedural observers.

    The ToolTalk service continues to match the message's class, operation, and argument attributes against all Observe message patterns of all ptypes. When a match is found, if the signature specifies TT_QUEUE or TT_START, the ToolTalk service attaches an observe promise record to the message, specifying the ptype and the queue or start options.

  6. Deliver to handler.

    If a running process has a registered Handler pattern that matches the message, the ToolTalk service delivers the message to the process; otherwise, the ToolTalk service honors the disposition (queue or start) options.

    If more than one process has registered a dynamic pattern that matches the handler information, the more specific pattern (determined by counting the number of non-wildcard matches) is given preference. If two patterns are equally specific, the choice of handler is arbitrary.

  7. Deliver to observers.

    The ToolTalk service delivers the message to all running processes that have registered Observer patterns that match the message. As each delivery is made, the ToolTalk service checks off any observe promise for the ptype of the observer. After this process is completed and there are observe promises left unfulfilled, the ToolTalk service honors the disposition (queue or start) options in the promises.

Example

In this example, a hypothetical spreadsheet application named FinnogaCalc is integrated with the ToolTalk service.

  1. FinnogaCalc starts and registers with the ToolTalk service by declaring its ptype, FinnogaCalc, and joining its default session.

  2. FinnogaCalc loads a worksheet, hatsize.wks, and tells the ToolTalk service it is observing the worksheet by joining the worksheet file.

  3. A second instance of FinnogaCalc (called FinnogaCalc2) starts, loads a worksheet, wardrobe.wks, and registers with the ToolTalk service in the same way.

  4. The user assigns the value of cell B2 in hatsize.wks to also appear in cell C14 of wardrobe.wks.

  5. So that FinnogaCalc can send the value to FinnogaCalc2, FinnogaCalc2 creates an object spec for cell C14 by calling a ToolTalk function. This object is identified by an objid.

  6. FinnogaCalc2 then gives this objid to FinnogaCalc (for example, through the clipboard).

  7. FinnogaCalc remembers that its cell B2 should appear in the object identified by this objid and sends a message that contains the value.

  8. ToolTalk routes the message. To deliver the message, the ToolTalk service:

    1. Examines the spec associated with the objid and finds that the type of the objid is FinnogaCalc_cell and that the corresponding object is in the file wardrobe.wks.

    2. Consults the otype definition for FinnogaCalc_cell. From the otype, the ToolTalk service determines that this message is observed by processes of ptype FinnogaCalc and that the scope of the message should be TT_FILE.

    3. Matches the message against registered patterns and locates all processes of this ptype that are observing the proper file. FinnogaCalc2 matches, but FinnogaCalc does not.

    4. Delivers the message to FinnogaCalc2.

  9. FinnogaCalc2 recognizes that the message contains an object that corresponds to cell C14. FinnogaCalc2 updates the value in wardrobe.wks and displays the new value.

Otype Addressing

Sometimes you may need to send an object-oriented message without knowing the objid. To handle these cases, the ToolTalk service provides otype addressing. This addressing mode requires the sender to specify the operation, arguments, scope, and otype. The ToolTalk service looks in the specified otype definition for a message pattern that matches the message's operation and arguments to locate handling and observing processes. The dispatch and delivery then proceed as in messages to specific objects.