Re: Create Phase Protocols

[Roger M. Burkhart]

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

The most complete description of rules for the create phase protocols
is buried under defobj->Interface Reference->Create.  Check there if
you haven't already.

Meanwhile a few quick answers:

> 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?

In most cases, the final object is the same as the proto object, but
in the general case the final object can be different.  In any event
the createEnd message must be used before final phase messages are
used.  To protect against any change in library implementations,
calling code is required to assume that the final object might be
different.

> 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" ...)

The order in the .h file makes no difference.  It's just a convention
for now.

> 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?

Objective C imposes no requirements on the order of message declarations
in either the .h or .m files.  For one form of create-phase implementation,
however, the order of message in the .m file *does* make a difference;
classes are automatically generated that automatically split one class
into separate classes for each phase.  This technique is currently used
only in the defobj, collections, and activity library, and is not currently
supported for user-written libraries.  These split classes enforce the
restriction that only messages for the current phase of an object will
be recognized.

> 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). 

The statement is too general.  Subclassing is well supported for the
classes you list, which are specifically designed for use as superclasses.
There's nothing about create-phase protocols as such which makes
subclassing difficult.  It's only when alternate implementations are
selected at createEnd time that there's a problem.  These superclasses
perform no implementation switching.  They're just superstructure for you
to inherit from and then define whatever else you want.

The superclasses in defobj, collections, and activity that use the split
classes technique are the current ones for which subclassing is not
officially supported (though it does work).  The automatic phase splitting
will eventually be well defined for user subclasses as well, but because
the final class can still differ from the create-phase class, you'll still
have to decide for which phase or phases you're defining a custom subclass.

> 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?

They're in superclasses.

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

Not as long as you also return the value; the action should be
return [super createBegin: argZone].  But that's identical to
what it means to leave the method out entirely, since then you
just inherit the super method.

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

Not unless there's something about the createBegin: that requires
or assumes a createEnd to finish things up.

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

Whenever coding methods in a subclass, you're assuming a lot of
existing context.  Simple comments rather than hard methods might
be enough for a reminder.

> 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?

We lump everything in the create phase that can never be reset again,
because even if the kind of object created is not affected, there are
allocations or other supporting structure that can often be made once and
for all as a result of fixed settings.  It's also a way to document
that a value cannot be reset, and a way to check all parameter settings
for consistency with one another.

> 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.

Good idea to consider some naming conventions, especially that would
show up in debugging.  There's already a bit of this in split-phase
classes from defobj/collections/activity, but not recognizable as
a normal class name (the class name string ends in ".Creating").
But some recommended user conventions might be good as well.

> 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?

I understand this as an issue of coding style.  We went the other
way mostly to avoid having to declare extra temporary variables
every time when creating objects.  That's probably why we'll keep
the current style, but if there's any strong opinion I'd be glad
to hear it.

I've been somewhat sparsely in contact the last few weeks with travel
and other activities, so I may not keep up any quick response, but I
hope this helps to start answering your questions a little.

Roger Burkhart