[drmaa-wg] Cosmetic changes

[Hrabri Rajic]

Dear all,

I have gone thru the list and made many changes.  It would be good for a
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 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.

In addition to the "cosmetic changes" the most recent, and attached DRMAA
spec contains the text update for Tracker 1793.


> -----Original Message-----
> From: owner-drmaa-wg at ggf.org [mailto:owner-drmaa-wg at ggf.org] On Behalf Of
> Peter Troeger
> Sent: Friday, April 21, 2006 3:18 AM
> To: DRMAA Working Group
> Subject: [drmaa-wg] Cosmetic changes
> 
> Hi,
> 
> here is the promised proposal of "cosmetic" changes for the latest
> version of the spec. Most of them fix an incorrect application of
> RFC-2119 keywords. It is much more then expected, but nothing critical
> regarding semantics or functionality.
> 
> 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.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: ggf-rec-drmaa-1_0-corrected.pdf
Type: application/pdf
Size: 378902 bytes
Desc: not available
Url : http://www.ogf.org/pipermail/drmaa-wg/attachments/20060423/ac955361/attachment.pdf