[drmaa-wg] Cosmetic changes

[Andreas Haas]

I went through the newest document and reviewed all changes.

Good work!

Regards,
Andreas

On Sun, 23 Apr 2006, Hrabri Rajic wrote:

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