[saga-rg] SAGA spec proof read

[Pascal Kleijer]

Hello,

* insert here 'late' apologies *

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?
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.
4. add_location can throw AlreadyExists but then tells in the notes that 
if the location exists in the set, no error is issued.
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).
2. “read” should add that it will read at least 1 byte from the stream. 
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.”
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.
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.
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.
6. In “Example for async stream server” the “my_cb” attribute ‘s’ is 
missing the underscore.
7. In the callback method there is an underscore to much.





-- 

Best regards,
Pascal Kleijer

----------------------------------------------------------------
   HPC Marketing Promotion Division, NEC Corporation
   1-10, Nisshin-cho, Fuchu, Tokyo, 183-8501, Japan.
   Tel: +81-(0)42/333.6389       Fax: +81-(0)42/333.6382

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 4385 bytes
Desc: S/MIME Cryptographic Signature
Url : http://www.ogf.org/pipermail/saga-rg/attachments/20060608/2ae83ff2/attachment-0003.bin