[saga-rg] Re: comment on SAGA strawman doc.

[Andre Merzky]

Quoting [Peter Kunszt] (Jul 21 2005):
> 
> hello andre
> 
> maybe the doc we were looking at was not the latest one..
> where is the one that is the current reference? we got our
> copy from gridforge..

The latest version is at our wiki: http://wiki.cct.lsu.edu/saga/

On GridForge was a good version as well, the one we wanted
to have reviews for.  So the excuse of having given you an
old copy does not work it seems ;-)



> >>>  - The examples are sometimes more misleading than
> >>>  useful...
> >
> >Hmm, we are not sure why that is.  Are they too complex?
> >Not focused enough?
> 
> our (certainly subjective) impression was that they are
> too simplistic and not enough explanations are given.
> specifying most possible errors would be also quite useful
> and a motivation what problem the example at hand is
> supposed to solve. maybe again it was an early document.

Point taken I think.  Currently the examples are pretty much
just pieces of C++ code which are supposed to illustrate the
useage of parts of the API.  Seems to work well for the
authors, but not so well for the reader.  Ok, thanks.



> >>>  - Interface NSDir: what are the semantics of the copy
> >>>  method? of getName and getURL?
> >
> > Hmm, we actually hoped that the semantics is well
> > defined.  If the copy call returns w/o error, a copy of a
> > file will exist on the target location.
> 
> in the doc we had, it was just listed, no extra text was
> there stating what happens if something goes wrong...

For example for copy, the current version says (the flags
are defined elsewhere):

-------------------------------------------------------------
  Methods for operation on namespace entities:
  - copy
    Purpose: copy the entry to another part of the namespace
    Format:  void copy          (in  string         source,
                                 in  string         target,
                                 in  array<copyFlags,1> 
                                                    flags);
    Inputs:  source:             name to copy
             target:             name to copy to
             flags:              flags defining the operation 
                                 modus
    Outputs: none               
    Throws:  BadParameter:       name(s) and/or flags are 
                                 invalid
             NoSuchFile:         name(s) do(es) not exist
             NoSuccess:          flags inhibited successful
                                 operation
    Notes:   - if the target is a directory the source entry 
               is copied into the directory
             - it is an error if the source is a directory 
               and the 'Recursive' flag is not set.  
             - if the target already exists, it will be 
               overwritten if the 'Overwrite' flag is set, 
               otherwise it is an error
             - default flags set is 
               {NoOverwrite, NoRecursive}
             - Overwrite and NoOverwrite cannot be specified 
               at the same time
             - Recursive and NoRecursive cannot be specified 
               at the same time
             - similar to the 'cp' command in Unix shells, 
               as defined by POSIX
-------------------------------------------------------------
         
The old version should have been similar I think (have to
check).  It does indeed not tell you much about consistency,
only refers to POSIX shell cp. 

About consistency we had a lengthy discussion, with the
aggreement that the consistency model is to be defined and
documented by the implementation.  The API spec itself does
not assume any specific consistency model, as we feel that
(a) POSIX consistency is not achievable within reasonable
effort/performance, (b) if the user assumes the worst (no
consistency), he will still be able to make good use of the
API, and (c) reality will be somewhere in the middle.

Would you see problems with that approach?

Cheers, Andre.




-- 
+-----------------------------------------------------------------+
| Andre Merzky                      | phon: +31 - 20 - 598 - 7759 |
| Vrije Universiteit Amsterdam (VU) | fax : +31 - 20 - 598 - 7653 |
| Dept. of Computer Science         | mail: merzky at cs.vu.nl       |
| De Boelelaan 1083a                | www:  http://www.merzky.net |
| 1081 HV Amsterdam, Netherlands    |                             |
+-----------------------------------------------------------------+