[drmaa-wg] Cosmetic changes

Sun Apr 23 17:11:02 CDT 2006

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 at 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.