[Saga-devel] Adding a new (overloaded) method to an adaptor

[Hartmut Kaiser]

Paul,

> >As long as nobody comes up with a better compile time scheme of
> detecting
> >the implemented adaptor functionality the answer is a weak yes.
> 
> Could you explain this a little more?  I can't quite see what you're
> getting at.  Do you allow adaptors that don't implement everything
> specified by the package?  I'm fairly new to SAGA and still trying to
> learn its idiosyncrasies.

Yes, that's the point. An adaptor may implement just one or two functions of
the functionality exposed by a package. Or all of it, for that matter. It
may implement only the synchronous functions, or may decide just to provide
the asynchronous ones instead. The engine takes care of the rest. Either by
selecting a different adaptor, or by supplying the missing asynch/synch
functions, as required.

> >But I still
> >think it's not a big deal, as the adaptor interface isn't visible to
> the
> >user in the end. I don't expect to have to convey this subtlety to
> more than
> >a couple of people writing adaptors, so we're fine.
> 
> I think you've hit the nail right on the head.  I'm writing an adaptor
> and Steve is writing the design for Service Discovery.  If anyone else
> is going to write another Service Discovery adaptor then they are going
> to have to conform to Steve's Design (which specifies what the adaptor
> provides/should do) and an API for the package.  Our function name
> mapping if overloaded functions aren't allowed should be documented I
> suppose.  Currently there's an overloaded method in the design for
> Service Discovery.  I don't think the Java implementation of SAGA has
> this limitation and so the Service Discovery design becomes somewhat
> language specific.

This isn't anything language specific (i.e. no C++ vs. Java issue). This is
an implementation specific detail of our design resulting from the automatic
compile time based registration mechanism (merely, the non-perfect
implementation thereof).

> >But again, feel free to use function overloading. The gotcha I
> mentioned
> >didn't show up in real use cases yet, I just know it's there. So far
> >everything worked well even in the context of function overloading.
> 
> Do you have an example of this problem so that I can see if it's a
> problem for us and to keep clear of it?

The problem manifests itself if you have both, the synchronous and
asynchronous functions implemented, but not all of them. In this case an
adaptor might get selected to be in the set of considered adaptors even it
doesn't implement a certain function (a function gets registered as being
implemented even if it's not). Note, this is just a minor performance hit,
as the adaptor/cpi base class implements all functions, resulting in correct
behavior anyways. Those base functions generally just throw a NotImplemented
exception, essentially resulting in ignoring this particular adaptor.
Correct function registration just avoids this function call altogether,
skipping the exception handling.

So again: go ahead using overloaded function names. This works, even if some
optimizations might not get applied. In the worst case the cost is
neglectible, though: handling of one unnecessary exception per (API)
function call.

Now, as I think of it, I shouldn't even have mentioned this in the first
place :-P

> >Yep, I agree. Writing packages/adaptors isn't documented anywhere. I
> don't
> >like the macros either, but these save a lot of stupid typing. At some
> point
> >I tried to replace them with some template magic, but there are still
> things
> >you can't really implement using templates only, so we got stuck with
> what
> >we have.
> >
> >BTW, there is an adaptor writers guide in the beginnings, but this is
> mostly
> >work in progress. At least we can claim to see light at the end of the
> >tunnel (even if its red shifted).
> >
> >Even if the adaptor framework has a lot of functions implemented, I
> don't
> >think that to be a problem. Function overloading is discouraged from
> our end
> >for the functions exposing the adaptor functionality only. No other
> >restrictions apply.
> 
> I suppose that what I'm getting at is a list of method names, member
> variable names and namespace names that we shouldn't be using.  For
> example for a method called foo(), what methods/members are auto-
> magically created, (for either the package or adaptor)?  Would an
> internal member/method called something like foopriv, or sync_foo for
> example be a problem, depending upon namespace of course?

The only limitation you face is that you _should_ (note, I didn't say
_must_) avoid using function names similar to the functions exposed by the
adaptor. That's those starting with sync_... and async_... If you use those
it will just complicate your function registration code and _might_ result
in not applying the described optimization. 

But this is not a strict requirement. I hope this to be more transparent
now.

Everything else should be fine.

Regards Hartmut