[Ns-developers] ns-3-object proposed for merge

[Gustavo Carneiro]

On 30/01/2008, craigdo at ee.washington.edu <craigdo at ee.washington.edu> wrote:
>
>
> > Functional semantics aren't conveyed by JUST the name of a
> > method, but also
> > by its parameter list and return type.  If you told me that I can use
> > something like GetObject(TypeId), I'd ask you immediately "what if two
> > aggregated objects have the same TypeId, what is the
> > behavior?"  If you gave
> > no reply, after a few seconds I'd probably think "either it
> > returns a list
> > of ALL matching Objects, or it is disallowed to have multiple
> > Objects of the
> > same TypeId".  Then I'd look at the return type and see that
> > it returns only
> > a single Ptr to the type, and I'd conclude that it is in fact
> > disallowed to
> > have multiple Objects of the same type aggregated.
> > The semantics are correctly implied by the function
> > signature, and most
> > people would realize what is going on from this and the name.  If our
> > aggregation had generic container semantics, it might look like
> > GetObject(objectName) or GetObject(objectIndex); but it
> > doesn't, so I don't
> > think there is a problem.
>
> I'm not so sure.  If you take a few steps back, what does,
>
>   Ptr<ClassName> p = GetObject<OtherClassName> ();
>
> really tell you if you don't know most of the answer a priori?  Without
> understanding what is going on, is this really clear?  I tend to think not
> very.  You can infer that there is a method that looks something like,
>
> template<typename T>
> Ptr<T>
> GetObject (void)
> {
> // yadda yadda black box
>   return Ptr<T> yadda;
> }
>
> I think maybe you can puzzle out what "yadda yadda black box" does so
> easily
> because you already know the answer :-)
>
> On the other hand, what does
>
>   void AddObject (Ptr<Object> other);
>
> tell you about what is going on?  Not much.
>
> Adding enough context to make the answer to the puzzle relatively obvious
> for someone who really doesn't understand what is really happening yet
> makes
> the method names (in both the adding and getting parts) very long and
> somewhat redundant.
>
>   node->AggregateSingleObjectOfUniqueType<SomeClass> (Ptr<Object> object);
>   p = node->InAggregationFindSingleObjectOfUniqueType<SomeClass> ();
>
> But you still probably have to go RTFM to figure out about aggregations,
> and
> objects of classes, and what this is all really about and why you are
> doing
> this anyway; so at some level, a longer name just becomes a longer hint
> for
> people who already know but rarely use the system -- and mostly just a
> pain
> to type for, well, us.  On the other hand, I may be doing the same thing
> you
> did and thinking that this is more clear because I already know the answer
> and what an aggregation is.  In the asymptotic limit, the name of the
> method
> approaches the tutorial chapter on the method name ;-)
>
> That said, Gustavo's point that QueryInterface will provide lots of
> context
> is a good one.  If you've heard of QI, or google it, you will find out all
> about aggregation of Interfaces and Interface discovery.  you'll even find
> hundreds of books.  That's one of the main reasons I suggested "just use
> COM" about a year ago -- so we don't have to write the book.
>
> The problem is, in ns-3 today, after reading the COM book, you'll start
> looking for Interfaces and GUIDs, etc. -- and you won't find them.  So,
> Joe's point is a good one.  You may be mislead and find the system harder
> to
> understand if you are sent off to a referent like COM by the term
> QueryInterface, or to Java by the term Interface -- only to later find out
> that ns-3 is not COM or Java, and there are no Interfaces even though we
> implied there were.
>
> So, I don't think it's a big deal what we call it, just so long as it's
> not
> too long or too misleading.  I'm more concerned about being misleading
> than
> leading at this point in the discussion.  As I said, I'm not too excited
> about it, though.  I don't think there's an obvious right answer for what
> the names are, and we can go round-and-round about it (and have).
>
> There is already a big section in the tutorial to try and explain what all
> of this means (right now it includes lots of words telling you about what
> object interfaces are, and how interfaces and components work, and how
> aggregation and discovery works (our version of the COM book); but that
> you
> should NOT think about COM Interfaces when you see the QueryInterface
> method).
>
> AggregateObject seems just fine to me.  The referent is in the ns-3 manual
> and tutorial.
> GetObject seems just fine to me.  The referent is in the ns-3 manual and
> tutorial.


I could suggest another alternative: AddInterfaceObject and
QueryInterfaceObject...  Yes, a bit more verbose, I know :P

I should also point out that we could probably use a new API for generic
object aggregation.  You will ask why.  I will answer that we do not
currently have the equivalent of a "process" in NS-3.  I am currently
getting by with the OLSR agent by, well, defining an OlsrAgent
interface/implementation and attaching it to a Node object via
AddInterface.  You will ask, why do I need to attach the OlsrAgent to the
Node object, to which I will answer that I want to bind the life cycle of
the OlsrAgent to the Node in which it is "running".  By using AddInterface I
can release my own reference to it and still be sure that the OlsrAgent
instance will be released when the node is released, but not sooner.

For some time now I have wished for a more generic "process" API.  It does
not have to be put in the base Object class, but maybe it belongs in Node.
It should allow a Node instance to manage a set of objects, regardless of
type (allowing even multiple objects of the same type to be attached).  Now
_that API_, should we ever add it, will be a _real_ object aggregation.  And
if we start using AggregateObject/AddObject now then it would be very
confusing later if we add another type of aggregation.  Of course if such a
generic object aggregation API is out of the question then this argument is
void.

Sorry for extending this thread, but I just want the full implications of
choosing these new names to be clear to all.

Cheers.

-- 
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert