Safe Varargs

[Joe Darcy]

Hi Neal.

On 12/13/2010 8:30 PM, Neal Gafter wrote:
> This documentation uses the phrase "potentially unsafe operations"
> without defining it.  Presumably such unsafe operations include an
> assignment to a variable of the same type (i.e. allowing the varargs
> parameter to escape).

Yes, we choosing at this time to not precisely define the full set of 
safe or unsafe operations on the parameter.

Not aliasing the parameter, only reading from the parameter, and 
treating the parameter in an invariant sense would generally be safe.

-Joe

> On Monday, December 13, 2010, Joe Darcy<joe.darcy at oracle.com>  wrote:
>> Greetings.
>>
>> Following up on earlier work, the javac team has pushed a new
>> implementation of Project Coin's simplified varargs method invocation
>> feature. [1] The changes are scheduled to appear in the promotion of JDK
>> 7 b123.
>>
>> As envisioned previously, a new @Documented annotation type,
>> java.lang.SafeVararags, can be used to suppress warnings related to
>> unchecked warnings, both the new mandatory warnings at the declaration
>> site of a varargs method/constructor with a non-reifiable element type
>> and the existing unchecked warnings at the call sites of such methods. A
>> systematic application of this annotation to appropriate declarations in
>> the JDK libraries will follow as future work.
>>
>> Since new unchecked warnings are being introduced, those diligently
>> compiling with options like "-Xlint:unchecked -Werror" will see a build
>> error under JDK 7 if any of the suspicious varargs method declarations
>> are found. To address this, the @SafeVarargs annotation can be applied
>> to the declarations, if appropriate, or the
>> @SuppressWarnings({"unchecked", "varargs"}) annotation can be applied.
>> Unlike @SafeVarargs, the @SuppressWarnings annotation will not squelch
>> unchecked warnings at the call site of the annotated method.
>>
>> The specification of the new SafeVarargs annotation type is below.
>>
>> -Joe
>>
>> [1] http://hg.openjdk.java.net/jdk7/tl/jdk/rev/78885e69c42c
>> http://hg.openjdk.java.net/jdk7/tl/langtools/rev/7b99f98b3035
>>
>> -=-=-=-=-=-=-
>>
>> Annotation Type SafeVarargs
>>
>>      @Documented
>>      @Retention(value=RUNTIME)
>>      @Target(value={CONSTRUCTOR,METHOD})
>>      public @interface SafeVarargs
>>
>> A programmer assertion that the body of the annotated method or
>> constructor does not perform potentially unsafe operations on its
>> varargs parameter. Applying this annotation to a method or constructor
>> suppresses unchecked warnings about a non-reifiable variable-arity
>> (vararg) type and suppresses unchecked warnings about parameterized
>> array creation at call sites.
>>
>> In addition to the usage restrictions imposed by its @Target
>> meta-annotation, compilers are required to implement additional usage
>> restrictions on this annotation type; it is a compile-time error if a
>> method or constructor declaration is annotated with a @SafeVarargs
>> annotation, and either:
>>
>>          * the declaration is a fixed-arity method or constructor
>>          * the declaration is a variable-arity method that is neither
>> static nor final.
>>
>> Compilers are encouraged to issue warnings when this annotation type is
>> applied to a method or constructor declaration where:
>>
>>          * The variable-arity parameter has a reifiable element type,
>> which includes primitive types, Object, and String. (The unchecked
>> warnings this annotation type suppresses already do not occur for a
>> reifiable element type.)
>>          * The body of the method or constructor declaration performs
>> potentially unsafe operations, such as an assignment to an element of
>> the variable-arity parameter's array that generates an unchecked warning.
>>
>>            Future versions of the platform may mandate compiler errors
>> for such unsafe operations.
>>
>>
>>
>>