swarm.objectbase.sgml.reference.html

set for Swarm2.1是圣菲研究院的开发人员对Swarm的特性及其使用描述的最为完备的指南性文档。从这里可以获得最细致的平台说明。

>Next come the message prototypes to which this agent will
        respond.  And it is worth noting again that these are
        <I
CLASS="EMPHASIS"
>in addition to</I
> those declared in the
        <I
CLASS="EMPHASIS"
>SwarmObject</I
> superclass.  So, not only
        will other objects be able to send messages to this agent that
        are declared here, but other objects will be able to send all
        the messages declared in the
        <TT
CLASS="LITERAL"
>objectbase/SwarmObject.h</TT
> imported
        previously.  The messages prototyped here will dictate what
        the compiler thinks this object can respond to.  Hence, if any
        part of any of these prototypes differs from the corresponding
        function definition in the <TT
CLASS="LITERAL"
>Heatbug.m</TT
> file,
        then the compiler will say something like <TT
CLASS="LITERAL"
>Object:
        aHeatbug does not respond to xyz</TT
>, where "xyz" is the
        name of the message that is being sent to the
        <TT
CLASS="LITERAL"
>Heatbug</TT
>.  A script is provided with the
        Swarm distribution that fixes header file prototypes to match
        the message declarations in the corresponding ".m" file.  This
        script should be in the <TT
CLASS="LITERAL"
>$SWARMHOME/bin</TT
>
        directory and is called <TT
CLASS="LITERAL"
>m2h</TT
>.
      </P
><P
>One more thing to notice about these prototypes is that
        some of them are duplicates of what appears in the
        <TT
CLASS="LITERAL"
>objectbase/SwarmObject.h</TT
> file.  This means
        that when the message is called on a
        <I
CLASS="EMPHASIS"
>Heatbug</I
> object, it will execute the
        method defined here and not the one in the
        <I
CLASS="EMPHASIS"
>SwarmObject</I
> class.  In the
        <I
CLASS="EMPHASIS"
>objectbase</I
> library, the following
        messages are intended to be overridden, as necessry:
        <TT
CLASS="LITERAL"
>create:, createBegin:, createEnd, customizeBegin:,
        customizeEnd, customizeCopy:, describe:, and
        getInstanceName.</TT
> Each of these messages do specific
        things that may change from subclass to subclass of
        <I
CLASS="EMPHASIS"
>SwarmObject</I
>.  In this case, however,
        we're only overriding <TT
CLASS="LITERAL"
>createEnd</TT
>.  The
        differences between we implement it in
        <I
CLASS="EMPHASIS"
>Heatbugs</I
> and the default is not that
        significant.  But, it should be pointed out that when
        overriding certain messages, like
        <TT
CLASS="LITERAL"
>createBegin:</TT
> and
        <TT
CLASS="LITERAL"
>createEnd</TT
>, the new method should call the
        superclass' version of the message, as well.  This is done
        using the default pointer to the superclass, designated
        <I
CLASS="EMPHASIS"
>super</I
>.  The syntax in the
        <I
CLASS="EMPHASIS"
>Heatbugs</I
> case is:

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>[super createEnd];</PRE
></TD
></TR
></TABLE
>

      </P
><P
>The reasons for doing this are related to the object phase
        protocols used by <I
CLASS="EMPHASIS"
>defobj</I
>.  If you would
        like more info on that, see the <A
HREF="http://www.swarm.org"
TARGET="_top"
><I
CLASS="CITETITLE"
>Swarm User Guide</I
></A
>.
      </P
><P
>Finally, the <TT
CLASS="LITERAL"
>@end</TT
> keyword signifies the
        end of the interface definition.  GNU Objective C allows one
        to leave this off; but, it is not good practice.</P
><P
>And that's it.  Of course, there're a few tricky aspects
        to using the <I
CLASS="EMPHASIS"
>objectbase</I
> library that
        weren't mentioned here.  Some of them will be mentioned in the
        <A
HREF="swarm.objectbase.sgml.reference.html#SWARM.OBJECTBASE.SGML.SECT1.ADVUSAGE"
>Advanced Usage
        Notes</A
> and the <A
HREF="swarm.objectbase.sgml.reference.html#SWARM.OBJECTBASE.SGML.SECT1.IMPL"
>Implementation
        Notes</A
>; but, the best way to learn is to examine the way
        the demo applications do it and try to make some changes
        yourself.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN11368"
>3.3. Subclassing from <I
CLASS="EMPHASIS"
>Swarm</I
></A
></H2
><P
>Subclassing from the <I
CLASS="EMPHASIS"
>Swarm</I
> class
        works very similar to subclassing from
        <I
CLASS="EMPHASIS"
>SwarmObject</I
>.
      </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN11374"
>3.4. ActivityControl</A
></H2
><P
>The <I
CLASS="EMPHASIS"
>ActivityControl</I
> object provides
        much more finely grained control over the execution of an
        interactive simulation.  It addresses both the problems of not
        being able to stop the simulation at any given point in any
        given activity and provides an initial step towards a Swarm
        debugger.
      </P
><P
>An activity controller can be attached to
        <I
CLASS="EMPHASIS"
>any</I
> activity that is created in a Swarm
        simulation, including those that are created for use only by
        the Swarm kernel.  The controller then provides the basic
        activity manipulation messages on that activity, which are:
        <TT
CLASS="LITERAL"
>run, stop, next, step, stepUntil,</TT
> and
        <TT
CLASS="LITERAL"
>terminate</TT
>.
      </P
><P
>The presence of the <I
CLASS="EMPHASIS"
>ActivityControl</I
>
        object might cause some confusion about what role the
        <I
CLASS="EMPHASIS"
>ControlPanel</I
> should play in the
        controlled execution of the various schedules.  The
        <I
CLASS="EMPHASIS"
>ControlPanel</I
> should still be used for the
        top-level control of any simulation that is running in a
        context where <I
CLASS="EMPHASIS"
>random</I
> interference is expected
        (like under a GUISwarm where the user may click a button at
        any time).  The reason this is true is because the
        <I
CLASS="EMPHASIS"
>ControlPanel</I
> sends pseudo-interrupts to
        the infinite loop we use to perpetuate execution of the top
        level Swarm (which can only be seen in the form of the
        <TT
CLASS="LITERAL"
>go</TT
> message on a
        <I
CLASS="EMPHASIS"
>GUISwarm</I
> at present).  <I
CLASS="EMPHASIS"
>This type
        of control may change in the future!</I
> But, for now, it
        is how we monitor the control state of the simulation.
      </P
><P
>Now, having said that, the
        <I
CLASS="EMPHASIS"
>ControlPanel</I
> should no longer be used to
        run the simulation.  It should only be used to instantiate the
        control context and quit the entire simulation.  That means
        that sometime in the future, the <TT
CLASS="LITERAL"
>Go</TT
> and the
        <TT
CLASS="LITERAL"
>Stop</TT
> buttons will be removed from the
        <I
CLASS="EMPHASIS"
>ControlPanel</I
> display.  They have been
        left in for backwards compatibility so that applications that
        do not use the new <I
CLASS="EMPHASIS"
>ActivityControl</I
> will
        retain their (albeit handicapped) controllability.  Also, the
        current <TT
CLASS="LITERAL"
>Time Step</TT
> button will be renamed to
        <TT
CLASS="LITERAL"
>Start</TT
> to be consistent with it's new
        purpose.
      </P
><P
>In order to use the new control mechanism, you must place
        code like the following in the top-level Swarm.  (This code
        was taken from a modified mousetrap demo app.)
        
      </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>observerActCont = [ActivityControl createBegin: [self getZone]];
observerActCont = [observerActCont createEnd];
[observerActCont attachToActivity: [self getSwarmActivity]];
[probeDisplayManager createProbeDisplayFor: observerActCont];</PRE
></TD
></TR
></TABLE
><P
>This creates an <I
CLASS="EMPHASIS"
>ActivityControl</I
> and
        attaches it to the top-level activity (in this case an
        <TT
CLASS="LITERAL"
>observerSwarm</TT
>).  It also creates a display
        for the controller. (The probe map for the
        <I
CLASS="EMPHASIS"
>ActivityControl</I
> class is designed within
        the <I
CLASS="EMPHASIS"
>ActivityControl</I
>, itself.  This is
        done because all of these objects are expected to look the
        same to any outside object.)  With this activity controller,
        you will then be able to <TT
CLASS="LITERAL"
>run, stop, next, step,
        stepUntil,</TT
> and <TT
CLASS="LITERAL"
>terminate</TT
> that
        activity.
      </P
><P
>There are some tricky aspects to successfully using an
        <I
CLASS="EMPHASIS"
>ActivityControl</I
> object that the <A
HREF="swarm.objectbase.sgml.reference.html#SWARM.OBJECTBASE.SGML.SECT1.ADVUSAGE"
> Advanced Usage
        Notes</A
> will cover.
      </P
></DIV
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SWARM.OBJECTBASE.SGML.SECT1.ADVUSAGE"
>4. Advanced Usage Guide</A
></H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN11413"
>4.1. ProbeMap design</A
></H2
><P
>When designing a <I
CLASS="EMPHASIS"
>ProbeMap</I
> for a given
        (subclass of) <I
CLASS="EMPHASIS"
>SwarmObject</I
>, inclusion of
        instance variables or messages defined in the super class
        might be desirable.  The normal <I
CLASS="EMPHASIS"
>ProbeMap</I
>
        design code might look like (this code was taken from the
        tutorial app called "hello-world"):
      </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>probeMap = [CustomProbeMap createBegin: [self getZone]];
[probeMap setProbedClass: [person class]];
probeMap = [probeMap createEnd];
[probeMap addProbe: [probeLibrary getProbeForVariable: "room"
  				 inClass: [person class]]];
[probeMap addProbe: [probeLibrary getProbeForVariable: "party"
  				 inClass: [person class]]];
[probeMap addProbe: [probeLibrary getProbeForVariable: "name"
  				 inClass: [person class]]];
[probeMap addProbe: [probeLibrary getProbeForVariable: "stillhere"
  				 inClass: [person class]]];
[probeMap addProbe: [probeLibrary getProbeForVariable: "listOfFriends"
  				 inClass: [person class]]];
[probeMap addProbe: [probeLibrary getProbeForVariable: "myColor"
  				 inClass: [person class]]];
[probeLibrary setProbeMap: probeMap For: [person class]];
[probeDisplayManager createProbeDisplayFor: person];</PRE
></TD
></TR
></TABLE
><P
>where <TT
CLASS="LITERAL"
>room, party, name, stillhere,
          listOfFriends,</TT
> and <TT
CLASS="LITERAL"
>myColor</TT
> are
          instance variables declared in the interface to the
          <I
CLASS="EMPHASIS"
>Person</I
> subclass.  And
          <I
CLASS="EMPHASIS"
>Person</I
> is a subclass of
          <I
CLASS="EMPHASIS"
>Agent2d</I
>, which is a subclass of
          <I
CLASS="EMPHASIS"
>SwarmObject</I
>.
      </P
><P
>Now let's say that there are two variables declared in
        <I
CLASS="EMPHASIS"
>Agent2d</I
> that you want to put into this
        custom probe in addition to the ones you've picked out of
        <I
CLASS="EMPHASIS"
>Person</I
>.  Call them <TT
CLASS="LITERAL"
>x</TT
>
        and <TT
CLASS="LITERAL"
>y</TT
>.  The way to add them to the
        <TT
CLASS="LITERAL"
>probeMap</TT
> is to add the following two lines
        of code to the above.
      </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>[probeMap addProbe: [probeLibrary getProbeForVariable: "x"
  				 inClass: [Agent2d class]]];
[probeMap addProbe: [probeLibrary getProbeForVariable: "y"
					 inClass: [Agent2d class]]];</PRE
></TD
></TR
></TABLE
><P
>And that's it!  The two superclass-declared variables,
        which are, in fact, instance variables of the instance of the
        subclass, are now included in the probe.
      </P
><P
>In addition, a convenience message has been added to the
        <I
CLASS="EMPHASIS"
>CustomProbeMap</I
> interface to compress the
        above rather cluttered mechanism into one message.  This
        convenience message can be used in the usual case where a
        <I
CLASS="EMPHASIS"
>ProbeMap</I
> will consist of variables and
        messages from the same class.  For example, the first part of
        the custom probe creation above can be shortened to:

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>probeMap = [CustomProbeMap create: [self getZone] forClass: [person class]
      withIdentifiers: "room", "party", "name", "stillhere",
                       "listOfFriends", "myColor", NULL];</PRE
></TD
></TR
></TABLE
>

        And if the user wanted messages in the probe as well, it could
        be extended to:

<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>probeMap = [CustomProbeMap create: [self getZone] 
                          forClass: [person class]
                   withIdentifiers: "room", "party", "name",
                       "stillhere", "listOfFriends", "myColor", 
                       ":",
                       "setWorld:Room:Party:",
                       "setPerson:Topic_array:ShowSpeech:",
                       NULL];</PRE
></TD
></TR
></TABLE
>

      </P
><P
>At present, this message doesn't search the superclasses
        for the message names listed here.  But, that will soon be
        rectified.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN11441"
>4.2. ActivityControl Issues</A