Create Phase Protocols

[Sven Thommesen]

In my quest for Swarm enlightenment, I have come to the point 
of trying to understand how Create-Phase Protocols work. 

Having looked at the Swarm documentation and some of the 
source code, I believe it would be of great benefit to 
everyone if the documentation were beefed up to include a 
listing of all objects that use C-P-P and a description of the 
messages required by the proto-objects in order for them to 
successfully create the final objects.

However, I know that documentation is a task that is 
invariably put off till the last minute on any programming 
project. (Users are always clamoring for more functionality -- 
and programmers usually find documenting stuff crushingly 
boring ... :-> )

Perhaps in the interim Roger or Manor could provide some quick 
answers to the specific questions below ? (Please, please ...)

1. My understanding is that the 'createBegin' message is sent 
to a proto-object, that this proto-object creates a final 
object tailored to the user's specifications as determined by 
messages sent (i.e. parameters passed) to the proto-object, 
and that the final user object is returned by the 'createEnd' 
method. Correct?

2. Documentation suggests that messages to the proto-object be 
defined between +createBegin and -createEnd in the Interface 
definition. Is this only for the benefit of human readers, or 
is there 'magic' going on behind the scenes, so that the order 
of things in the .h file has special significance to the 
compiler? (The Heatbug.h file says that "as a *convention* we 
define createEnd here" ...)

3. Do implementations of methods in the .m file have to occur 
in the same order as defined in the .h file, or is order in 
the .m file irrelevant?

4. Although "Objective-C Swarm Style" says that "the actual 
subclassing of objects which actively use the createPhase 
stuff ... is not well supported" we do not seem to have much 
choice when it comes to Swarms, GUISwarms and SwarmObjects 
(agents). 

Looking at the examples provided by Heatbugs, there is some 
cause for confusion:

while HeatbugObserverSwarm and HeatbugModelSwarm both define 
+createBegin and -createEnd methods, HeatbugBatchSwarm defines 
only +createBegin, the Heatbug agent defines only -createEnd, 
and HeatSpace defines neither! So: 

(a) are createBegin and createEnd not strictly necessary, or 
do these objects work only because the missing methods are 
defined in superclasses?

(b) is it ever a problem if we define a +createBegin method 
whose only action is [super createBegin] ?

(c) is it ever a problem if we define a -createEnd method 
whose only action is return [super createEnd]?

Doing so, even if not strictly necessary, would seem to help 
remind ourselves what kind of objects we're dealing with.

5. There is conceptually a distinction to be made between (a) 
parameters that the *proto-object* needs to have in order to 
know what kind of final object to create (e.g. desired access 
methods for a List), and (b) parameters that the *final 
object* needs to have before *it* will function properly (e.g. 
Heatbug needs to know the size of the World.) 

The logic of C-P-P seems to require only that the first 
category of parameters be set between +createBegin and 
-createEnd. However, "Objective-C Swarm Style" suggests that 
we put methods there "which are supposed to be sent only once 
in the lifetime of an object", and that seems to encompass the 
second category as well.

In fact, -createEnd in Heatbug tests that it has valid 
pointers to World and Heat, which are both of that second 
category. 

So: should we make this distinction between the two categories 
of parameters (messages), or not?

6. A suggestion: that proto objects be named as such, i.e. 
"ProtoValue2dDisplay" or "Value2dDisplayFactory", since this 
would signal the special nature of the objects in question.

7. Rather than "re-assigning" objects during creation, e.g. in 
this case:

        heatDisplay = [Value2dDisplay createBegin: aZone];
          [heatDisplay setParameter: parameterValue];
        heatDisplay = [heatDisplay createEnd];

I'd prefer to code things this way:

        tempObj = [ProtoValue2dDisplay createBegin: aZone];
          [tempObj setParameter: parameterValue];
        heatDisplay = [tempObj createEnd];

This would make it much more transparent what is going on, and 
not require us to assign two different object types to the 
same name ...

I realize that those last 2 points would require a bit of 
re-coding on our part (more than on Manor's part, for sure), 
but I feel the conceptual clarity would make it worth it.

But perhaps other users out there have a different view?

Sven Thommesen
School of Human Sciences, Auburn University
Center for Computable Economics, UCLA