[drmaa-wg] Cosmetic changes

Sun Apr 23 18:58:09 CDT 2006

Hi all,

Great!  Let someone else just address this thread contested issues and we
are done.

Regards

	Hrabri

p.s. I have added the second address change - looks identical now :-)

> -----Original Message-----
> From: Peter Tröger [mailto:peter.troeger at hpi.uni-potsdam.de]
> Sent: Sunday, April 23, 2006 5:11 PM
> To: hrabri at sbcglobal.net
> Cc: DRMAA Working Group
> Subject: Re: [drmaa-wg] Cosmetic changes
> 
> 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.