Runtime command-line deprecation (Was Re: RFR: 8066821(S) Enhance command line processing to manage deprecating and obsoleting -XX command line arguments

[Daniel D. Daugherty]

On 7/19/15 8:09 PM, David Holmes wrote:
> On 17/07/2015 11:29 PM, Daniel D. Daugherty wrote:
>> One tiny correction below...
>
> A correction to your correction ...
>
>> On 7/16/15 5:52 PM, David Holmes wrote:
>>> Aside: in the JDK deprecation has mostly been phase one only,
>>> unfortunately, with a handful of phase two. Alas no stage three.
>>
>> There's at least one stage 3 in the JDK:
>>
>> java.lang.Thread.suspend() throws UnsupportedOperationException
>> since JDK8-B96.
>
> I don't consider that a stage 3 - stage 3 would mean Thread.suspend 
> doesn't even exist in the API.

Your three stages from your original reply which you trimmed
from this reply:

 > I agree that in the worst-case there could well be a three phase process:
 >  - deprecate and handle
 >  - deprecate and ignore
 >  - remove (give error on use)

I was responding to the "give error on use" part and not so much
on the "remove" part.

Dan


>
> Cheers,
> David
>
>> https://bugs.openjdk.java.net/browse/JDK-7059085
>>
>> http://hg.openjdk.java.net/jdk9/dev/jdk/annotate/669be1677ab7/src/share/classes/java/lang/Thread.java#l848 
>>
>>
>>
>> Dan
>>
>>
>>>
>>> Cheers,
>>> David
>>> ------
>>>
>>>>>> The way I understand that we handle private -XX options today is a
>>>>>> 2-step removal: (obsolete_jvm_flags - where the
>>>>>> release number is in a table and could be undefined)
>>>>>>
>>>>>> Using your helpful taxonomy
>>>>>> fromhttps://bugs.openjdk.java.net/browse/JDK-806682:
>>>>>>
>>>>>> Today: private -XX options use 2-step removal (obsolete_jvm_flags)
>>>>>>      release 1: Deprecate & Obsolete - warn about the option but do
>>>>>> nothing with it (we can remove all code that supports it)
>>>>>>      release 2: Dead - unrecognized
>>>>>>    - the point of the 2-step is to give customers time to modify any
>>>>>> scripts they use
>>>>>>
>>>>>> I believe we have very rarely removed External flags - since
>>>>>> customers, licensees, etc. may expect them.
>>>>>>
>>>>>> Mini-proposal:
>>>>>> 1) I would recommend that we add a future set of changes to add
>>>>>> consistent handling for the External flags -
>>>>>> so that they would follow a three-step removal:
>>>>>>      release 1: Deprecate & Handle - warn and keep supporting
>>>>>>      release 2: Deprecate & Obsolete - warn and do nothing
>>>>>>      release 3: Dead - unrecognized
>>>>>>
>>>>>> 2) For the Internal flags - I think it would be kindest to customers
>>>>>> and not a huge amount of additional work if
>>>>>> we were to follow the Private model of using a 2 step.
>>>>>>
>>>>>> 3) leave the Private flags with the current 2-step removal
>>>>>
>>>>> Yes, this reflects our current model.
>>>>>> 4) add support for aliasing - for any of them
>>>>>>      So that if you are doing aliasing, you would follow the model
>>>>>> you are adding
>>>>>>       release 1: Deprecated & Handled - i.e. warn and still support
>>>>>> (and set the information for the new alias)
>>>>>>       release 2: Dead - unrecognized
>>>>>>
>>>>>> 5) Could we possibly take the two flags that followed a different
>>>>>> model already, i.e. moving to
>>>>>> Deprecated & Handled and handle those as mistakes rather than 
>>>>>> part of
>>>>>> a new general model?
>>>>>
>>>>> So this is my question which is around the code review in question.
>>>>> Note, Derek, can you resend the RFR to 
>>>>> hotspot-dev at openjdk.java.net so
>>>>> it gets to all of us (even the compiler team may want to share in the
>>>>> mechanism).
>>>>>
>>>>> Why are UseParNewGC and MaxGCMinorPauseMillis deprecated and handled
>>>>> and not deprecated and obsolete?  I don't actually see why have the
>>>>> distinction here?
>>>>>
>>>>> Did these flags follow the deprecation procedure below? Why not just
>>>>> make them obsolete, why have this other mechanism?  I may be asking
>>>>> the same question as Karen.
>>>>>
>>>>> I think the aliased flags could have a deprecate and handle model
>>>>> (where handle == alias) in which case you only need one table for the
>>>>> aliased flags, and you need to keep them in globals.hpp so they're
>>>>> parsed properly.
>>>>
>>>> The real reason I wrote the code that way is because I was supporting
>>>> the current policy (classic "mechanism not policy" checkin). I didn't
>>>> (and don't) have the history on how we got there. But after thinking
>>>> about it (see top post), I think there will be some cases where we'll
>>>> have handle options instead of ignoring them and vice verse. And the
>>>> final decision may come down to engineering, or customer, or partner
>>>> concerns, or management whimsy, or whatever the current fad is. We're
>>>> talking about code changes over multiple years here :-)
>>>>>> Or do you think we will see more cases other than aliasing in which
>>>>>> we would want to
>>>>>>      release 1: Deprecate & Handle and then release 2: Dead
>>>>>>      rather than release 1: Deprecate & Obsolete and then 2: Dead
>>>>>>      or rather than a 3 step like the External option proposal 
>>>>>> above?
>>>>>
>>>>> I think for the aliased flags you want the first option here
>>>>> (deprecate&handle), right?  But that's only because you need to keep
>>>>> the option in globals.hpp so it parses correctly, otherwise the 
>>>>> second
>>>>> option (deprecate&obsolete) would be the preference?
>>>>>
>>>>> The options in the GC that are being deprecated and handled have had
>>>>> warnings about them for a while, so making them obsolete doesn't feel
>>>>> too soon.
>>>>
>>>> Yes, but just went through the approval process.
>>>>>
>>>>> Also, I agree with Kim's comment below that your comment lines are 
>>>>> too
>>>>> long.  My fonts are too big to have windows this wide.
>>>>>
>>>>> thanks,
>>>>> Coleen
>>>>>> thanks,
>>>>>> Karen
>>>>>>
>>>>>> p.s. Note that all of the deprecation needs to
>>>>>> 1) work with licensee engineering to ensure we give licensee's a
>>>>>> head's up and get feedback
>>>>>> 2) file a change control request
>>>>>>
>>>>>> - we try to do these both as bulk requests to reduce the processing
>>>>>> overhead.
>>>>>>
>>>>>> p.p.s. Details
>>>>>>
>>>>>> 1.  Do the warnings print today or are they silent? Just want to 
>>>>>> make
>>>>>> sure we are conscious of how
>>>>>> those are handled if any of this moves to the new unified logging
>>>>>> mechanism for which the new default
>>>>>> for "warning" level is to print.
>>>> The deprecation messages go through warning(), which is controlled by
>>>> PrintWarnings (defaults to true). This is how the obsolete flag 
>>>> warnings
>>>> are printed. The new deprecation mechanism replaces a mishmash of 
>>>> calls
>>>> to jio_fprintf() and warning(), with a variety of different ways of
>>>> saying the same thing.
>>>>>> 2. "will likely be removed in a future release"? If we have already
>>>>>> set the release it will be removed - is this a bit
>>>>>> vague or did I not read closely enough?
>>>> That text came from some of the deprecated GC options. If removal has
>>>> been scheduled, we could say something more definite, or even the 
>>>> exact
>>>> release. We don't print the exact "death" release for obsolete options
>>>> currently though.
>>>>>>
>>>>>> On Feb 3, 2015, at 6:30 PM, Derek White wrote:
>>>>>>
>>>>>>> Request for review (again):
>>>>>>>
>>>>>>> - Updated with Kim's suggestion.
>>>>>>> - Stopped double-printing warnings in some cases.
>>>>>>> - Initial caps on warning() messages.
>>>>>>>
>>>>>>> Webrev:http://cr.openjdk.java.net/~drwhite/8066821/webrev.04/
>>>>>>> CR:https://bugs.openjdk.java.net/browse/JDK-8066821
>>>>>>> Tests:     jtreg, jprt
>>>>>>>
>>>>>>> Thanks for looking!
>>>>>>>
>>>>>>> - Derek
>>>>>>>
>>>>>>> On 1/28/15 3:47 PM, Kim Barrett wrote:
>>>>>>>
>>>> ...
>>
>
>