Hi,
I have gone thru the list and made many changes. It would be good for a
Looks very good.
third party person (Andreas, Roger, Dan) to go over the proposed changes and make comments wherever I am disagreeing with Peter, unless Peter agrees with me or presents more compelling arguments.
I agree to whatever you decided, since I only wanted to apply the RFC-2119 keyword semantics in a more strict manner. Most of your counter-arguments say that the semantics of the particular sentence would be changed - this should NOT be the case.
I would advise that we leave the knotty stuff as is. It is there for a reason and redoing it at 5 to 12 is not advisable.
As I said, totally agreed. Finally, someone else should now do a last review ... Peter. P.S.: The newline in the address of my institute is still missing.
Author list: - Hrabri occurs twice, Dan is missing, Peter might get a star symbol attached to his name
Maintainer and author are two different roles. Makes sense both ways - changed to combine. I still prefer the old way ...
Section 1.2: - Replace "Interface Definition Language (IDL) - like" with "C - like"
Left as is. This is what was meant.
Section 2, second sentence: - Replace "SHOULD" with "should"
OK.
Section 2.1: - First sentence: Replace "COULD" with "could" - Second sentence: Replace "COULD" with "MAY" - Third sentence: Replace "COULD" with "SHOULD be able to"
Sounds good. Done.
Section 2.2: - First sentence: Replace "it is RECOMMENDED a DRMAA library be thread-safe" with "a DRMAA library SHOULD be thread-safe" - Second sentence: Replace "It is RECOMMENDED that the DRMAA implementers label" with "DRMAA implementers SHOULD label"
Based on the implementation record so far this makes sense. It tightens the spec and increases the implementation entry bar. ***Need a second opinion.***
I have added sentence: "The initialization routine is the only routine that MAY not be thread reentrant to still allow the implementers to call their implementation thread-safe."
Section 2.3: - Replace "Unix and Windows" with "operating system"
Agree.
Section 2.4: - Replace "MAY" with "may"
OK.
Section 2.4.1: - 4. paragraph: Replace "MAY" with "may", replace "SHALL" with "can"
OK.
Section 2.4.2, last paragraph: - Replace "is assumed" with "SHOULD"
This is a too strong statement. It could be very tricky, so we originally wanted reduced expetations.
Section 2.5.2: - join_files attribute is missing in the list
Added.
Section 2.5.4: - Remove "(this is a useful synchronization mechanism)" - Replace "on all job Id's in the current process" with "on all job Id's in the current session"
OK
- The following sentence sounds very strange: "The Unix and Windows signals are replaced with the job control routines that have counterparts in DRMS." What does that mean ? The Win32 subsystem has no signalling, but an exception concept. Signals are not really 'replaced' by the control routines, do they ?
No, there are not. It was alluded to suspending and killing jobs. Unix and Windows replaced with Unix like.
- We have no state expressing "System and user suspended simultaneously"
Correct. We talked about adding it and did only few steps in that direction ... Deleted.
Section 3: - Replace "IDL-like" with "C-like"
Skipped. Same as above for consistency.
Section 3.1: - Replace "drmaa." with "drmaa_".
Left as is. It is way English is used ...
Section 3.1.1: - Remove "(except those that return already allocated sclar or vector values and cannot fail)" OK.
- Replace "Successful return is indicated" by "Successful return SHALL be indicated" OK.
- Replace "An invalid argument is flagged" by "An invalid argument SHALL be flagged" OK.
- Replace "The error code MAY be provided" with "The error code can be provided"
MAY is better here. May was the intent.
- Replace "error string that MAY be used in addition" with "error string that can be used in addition"
MAY is better here. May was the intent.
Section 3.1.2: - Replace "NOT RECOMMENDED" by "SHOULD NOT be possible". - Replace "It is RECOMMENDED that the DRMAA library SHALL free" with "The DRMAA library SHOULD free"
- Replace "so it is RECOMMENDED that old session resources not be used later" with "so old session resources SHOULD NOT be usable later by the application." - Replace "It is RECOMMENDED that restartable applications make" with "Restartable applications SHOULD make"
These change the meaning of what was intended (quality of implementation to differentiate) and requires us to test for this - I recommend we leave this for later versions, especially since we might want the opposite behavior.
- Replace "drmaa_synchronize" with "drmaa_synchronize()" - Replace "calls will make them" with "calls will make job id's"
Good catch.
Section 3.1.4: I am not able to catch what the first three sentences want to explain. How can programmatically changed attrivutes be set at compile time ?
Even if you make them dependent on run time or something you set them deterministically at compile time - and you would want that behavior to override native specification if set accidentally or trump job categories. This is in collision how things should work: developer vs end user vs admin We have debated how to set the precedence rules for those three ways of attribute setting and have found no satisfactory answer. The wording reflects this w/o going in every possible situation. Much more work is needed here, unless someone has already solved that in other GGF groups.
Section 3.1.5: - Replace "The following are RECOMMENDED" with "The following are recommended"
I am not sure about this one.
Section 3.2.1: - Replace "drmaa_init() SHOULD be called by only one of the threads. The main thread is RECOMMENDED." with "drmaa_init() SHOULD be called by only one of the threads, which SHOULD be the main application thread."
In a threaded application where DRMAA job submissions are not done in the primary thread this would require adjusting the application logic. Do we really want to test for this in DRMAA library?
Section 3.2.2, description of drmaa_get_attribute(): - Replace "otherwise, NULL is returned" with "otherwise, NULL MUST be returned."
OK.
Section 3.2.2, description of drmaa_get_vector_attribute(): - Replace "the values of 'name' are returned; otherwise, NULL is returned" with "the values of 'name' SHALL be returned; otherwise, NULL MUST be returned"
Good.
Section 3.2.3, first paragraph: - Replace "reserved attribute names" with "reserved attributes"
OK.
Section 3.2.3, description of job start time parameter: - Replace "when the job MAY be eligible" with "when the job may be eligible"
Good!
Section 3.2.3, description of transfer files parameter: - Replace "MAY be specified" with "can be specified".
I prefer to leave the old wording.
Section 3.2.5, description of drmaa_synchronize: - Second sentence: Replace "SHOULD" with "SHALL" - Third sentence: Replace "then this routine waits for all" with "then this routine SHALL wait for all"
OK both.
- 4. sentence: Replace "the routine SHOULD immediately return" with "the routine SHALL return" - Replace "the caller MAY use timeout specifying" with "the caller can use the timeout parameter specifying"
Section 3.2.5, description of drmaa_wait: - Third sentence: Replace "SHOULD" with "MUST" - 4. sentence: Replace "SHOULD" with "MUST" - Replace "so any subsequent calls to drmaa_wait SHOULD fail" with "so any subsequent calls to drmaa_wait SHALL fail" - Replace "DRMAA_ERRNO_INVALID_ARGUMENT SHOULD be thrown" with "DRMAA_ERRNO_INVALID_ARGUMENT SHALL be returned"
All done.
Section 3.2.5, description of drmaa_wifsignaled: - Replace "returned in signaled indicates" with "returned in the 'signaled' parameter indicates"
OK.
Section 3.2.5, description of drmaa_job_ps: - drmaa_context_error_buf must be flagged as "OUT" in the signature
Yes.
Section 3.2.6, description of drmaa_strerror: - Replace signature "error_string drmaa_strerror( errno )" with "drmaa_strerror( IN errno, OUT error_string )" - Replace "RETURNS" with "OUT error_string"
Done.
Section 3.2.6: - Add "OUT" keyword to the parameters in the signature of the following functions: drmaa_get_contact, drmaa_version, drmaa_get_DRM_system, drmaa_get_DRMAA_implementation
Yes.
Section 3.3, description of DRMAA_ERRNO_NO_DEFAULT_CONTACT_STRING_SELECTED: - Replace "multiple DRMAA implementation contained in the binary module" with "multiple available DRMAA implementations"
Better wording, same implied meaning - done.
Section 3.3, description of DRMAA_ERRNO_CONFLICTING_ATTRIBUTE_VALUES: - Replace "attributes" with "attribute"
Plural was meant.
Section 5: - Add Dan - Write Peter's address in the following way (missing newline): Peter Tröger peter.troeger@hpi.uni-potsdam.de Hasso-Plattner-Institute at University of Potsdam Prof.-Dr.-Helmert-Str. 2-3 D-14482 Potsdam Germany
Done.
Section 8+: - List of references is missing (relates only to [RFC2119])
Done. Look how GGF prefers to reference RFC2119.
Do we want to thank some contributors at the end of the document ?
I have added such sections. Hope all people are properly acknowledged.
The best
Hrabri
Best regards, Peter.