This README file corresponds to the alpha version of the Task Control
Architecture (TCA), version 7, released November 1992.  

This file describes changes to TCA in Version 7.  The changes consist of added
functionality and changes to the existing system.  All changes are upward
compatible with version 6: while the changes affect the behavior of some
functions, the interfaces to those functions are unaffected.

1. CONSTRAINT CLASS MESSAGES:
   a. These have been renamed "Inform" class messages -- the word "constraint"
      was a historical misnomer.  One should make the following replacements:
        ConstraintClass =>              InformClass
        tcaRegisterConstraintMessage => tcaRegisterInformMessage
        tcaAddConstraint =>             tcaInform

      For compatibility with earlier versions of TCA, the old names are still
      defined, but users should switch to using the new "inform" names, since
      this compatibility might not be extended to subsequent versions of TCA. 

   b. Handlers of Inform (Constraint) class messages now automatically issue a
      response to the central server.  Previously, the central server did not
      know when constraint messages had completed.  This sometimes led to
      situations in which constraints were handled out of order, and it even
      caused the server to hang processing new messages.  THIS CHANGE IS
      TRANSPARENT TO THE USER'S PROGRAMS.  The response is issued automatically 
      within tcaModuleListen or tcaHandleMessage.  While this may degrade
      performance slightly (an extra few bytes is sent to central), it should
      increase system reliability immensely.

2. BROADCAST MESSAGES
   Two new message classes were added to add a "broadcast" capability.
   a. BroadcastClass messages:
      Provides one-way broadcast capability.
      Use "tcaRegisterBroadcastMessage(name, format)" to register a
      BroadcastClass message.

      When a broadcast message is sent by a module (using "tcaBroadcast(name,
      data)"), *every* handler that is registered to handle that broadcast
      message (using "tcaRegisterHandler") will receive a copy of the message.
      Broadcast messages are analogous to inform (constraint) messages -- the
      handlers do not issue any response (although TCA will now issue one
      automatically, as described above). 

   b. MultiQueryClass messages:
      Provides a method for multiple handlers to work on the same query
      simultaneously, and for the querying module to receive multiple replies.
      Use "tcaRegisterMultiQueryMessage(name, queryFormat, replyFormat)" to
      register a MultiQueryClass message.

      A module sends a multi-query using "tcaMultiQuery(name, query, max, refPtr)",
        "name" is the message name,
	"query" is the query data,
	"max" is the maximum number of responses requested, and
	"refPtr", a pointer to a variable of type TCA_REF_PTR, is set to an
        identifier to be used with a corresponding tcaMultiReceive.

      When a multi-query message is sent, every handler that is registered to 
      handle that multi-query (using "tcaRegisterHandler") will receive a
      copy of the query message.  Multi-query messages are handled analogously
      to regular query messages -- the handlers issue a reply using "tcaReply".

      To get responses to a multi-query, use "tcaMultiReceive(ref, reply, timeout)"
	"ref" is the TCA_REF_PTR gotten from the corresponding tcaMultiQuery call,
	"reply" is a pointer to a structure to hold the reply data (analogous to
          that used in tcaQuery),
	"timeout" is a long int indicating the number of seconds to wait for a
          reply before returning.  If no message is received in that time, the
          return value of tcaMultiReceive is "TimeOut".  The defined value
	  WAITFOREVER will wait indefinitely for a response.

      Responses to a multi-query are received on an as-handled basis.  The user
      program should sit in a loop until all responses are received.  When no
      more responses will be forthcoming, the return value of tcaMultiReceive is
      "NullReply".  Thus, the following code example receives all responses:

	  TCA_REF_PTR mqRef;
	  tcaMultiQuery("mquery", &data, 3, &mqRef);
	  while (tcaMultiReceive(mqRef, WAITFOREVER, &reply) != NullReply) {
	    /* -- Process and/or save reply data here -- */
            }

      Note that while the maximum number of responses received will be the "max"
      given in the tcaMultiQuery call, fewer responses may in fact be received
      if fewer than "max" handlers were registered for that message.  Thus, the
      user's code should not depend on "max" replies being received.

3. WIRETAP CONDITIONS
   Two new message wiretap conditions were added: "WhenSuccess" and "WhenFailure".
   These are analogous to the "WhenAchieved", in that they delay temporally
   successive messages from firing until the listening message is achieved.
   The difference is that the wiretaps are specific to the success or
   failure of the tapped message.


4. TASK TREE MANIPULATION
   Several fundamental bugs affecting killing and retrying of task tree nodes
   have been repaired.  In particular, "tcaRetry" is much more robust, and
   comments in earlier manuals warning against its use are no longer applicable.


For queries, comments, or bug reports, contact Reid Simmons
(reids@cs.cmu.edu, 412-268-2621).
