[saga-rg] SAGA spec proof read

[Andre Merzky]

Quoting [Pascal Kleijer] (Jun 08 2006):
> 
> Hello,
> 
> * insert here 'late' apologies *

:-D


> Well I did my job and proof read the specs assigned to me at least. I 
> have a couple of comments and changes:
> 
> Review of the straw man 1.4:
> 
> Logical files:
> 1. The summary is missing the enumeration of replica catalogs it wants 
> to run against. Is this still open or will this be shifted to the 
> language bindings?

We took the requirements mostly from a document from the
Persistent Archives WG, which collects and classifies the
functional requirements to a replica system.  That doc in
itself cites about 10 replica systems.  The doc is cited in
the req. document - you are right, it should also be cited
in the spec.


> 2. The open_flag enumeration falg ?Excel? is too cryptic. It must be 
> extended to its full meaning like the rest of the flags.
> 3. Constructor of logical files? notes: Excl should be replaced with 
> full name.

Agree.


> 4. add_location can throw AlreadyExists but then tells in the notes that 
> if the location exists in the set, no error is issued.

Nice catch!  I would propose to remove the exception - for
most app level use cases I can think of this would be
easier.


> 5. Example has a small typo 'std::cout << "sice of...' should be 
> 'std::cout << "size of...'

:-)


> Streams:
> 1. Note, the document does not specify if the following pattern is 
> allowed ?connect->close->connect?. If it is not stated we can assume 
> that a stream can be ?reopened? (have a loop in the state machine).

We should add a state diagram.  That should make clear that
loops are not possible.

Hmmm, on a second thought: re-open would be easy to
implement (does not need to be the same stream on
implementation level) - does it make sense for some use
cases?  

Please note that the proposed messageing API does not make
any assumption about the connection life time: that would
allow to implement the message API with
open/send/close/re-open/send/close ...


> 2. ?read? should add that it will read at least 1 byte
> from the stream. 

Hmm, read on a non-blocking stream might very well return
0 bytes, w/o meeting any error.

But the spec is confusing about the blocking issue: it says
read is blocking - but that refers to the read method.  The
stream the read occurs on might be a non-blocking stream
(see attribute 'blocking').

I'll clean that up.

For a blocking read on a blocking stream: I agree there
should be min 1 byte read.


> Some extensions:
> Purpose: ?Reads up to ?size? bytes of data from the stream into an array 
> of bytes. An attempt is made to read as many as ?size? bytes, but a 
> smaller number but may be read. The number of bytes actually read is 
> returned as ?nbytes?. If ?size? is zero, then no bytes are read and 
> nbytes is 0; otherwise, there is an attempt to read at least one byte.?

That should already be the case - that is why 'nbytes' is
returned, indicating the actual number of bytes copied.
nbytes can be smaller than size w/o posing an error
condition (as in POSIX).  Is that what you propose?


> 3. In this implementation we have no choice but to wait for an exception 
> to be thrown when the stream has dried up (use the read method). It 
> would be nice to have -1 set to nbytes to first time the end of stream 
> is reached (if applies), then the next call to read will throw an exception.

What is the error condition the exception is supposed to
catch:

  - stream died
  - no data available

The first one is available via the state of the stream.

The second one is what you refer to, right?  But I think
that this is not an error condition which should raise an
exception: data might be available again a second later.

If data availability poses an error condition or not should
be decided on application level IMHO.  

Am I missing something?


> 4. There is no way to check the size of the data waiting for read. It 
> would be nice if we can query the stream on how many bytes in the pipe 
> are waiting. This is important if the client must allocate a buffer to 
> read this data. So an additional method like ?available? should be 
> added. Note that this will slightly overlap with the ?wait? method for 
> ?read? or ?any? mask, but will return a more accurate figure. Another 
> solution is to extend the wait method.

I would have no idea how to implement that on a stream:
without an additional protocol, you have no chance to know
how many bytes will arrive.

However, that is one of the reasons why the message API was
proposed: that implies an additional protocol on the wire,
but will allow the application to query the message size
before performing the message read.


> 5. It is not stated in the document if the stream ensures direct writing 
> when ?write? is called. In the case there is an internal buffer is it up 
> to the implementation to ensure the flush or is it best to add a flush 
> method to the API? I would suggest adding a flush method which can be 
> explicitly called by the user?s code, even if the implementation ignores it.

There is an attribute 'nodelay' which requires the
implementation to avoid caching is possible.  That is
neccessary for remote shell type applications (the enter
after a command should be sent immediately, and not wait for
another 1023 bytes ;-)

I'll make the description of that attribute more clear.

> 6. In ?Example for async stream server? the ?my_cb? attribute ?s? is 
> missing the underscore.

Thanks.


> 7. In the callback method there is an underscore to much.

Thanks again :-)


Cheers, Andre.

-- 
"So much time, so little t  o do..."  -- Garfield