When is @uncheckedVariance needed in Scala, and why is it used in GenericTraversableTemplate?

Question

@uncheckedVariance can be used to bridge the gap between Scala's declaration site variance annotations and Java's invariant generics.

scala> import java.util.Comparator     import java.util.Comparator  scala> trait Foo[T] extends Comparator[T] defined trait Foo  scala> trait Foo[-T] extends Comparator[T]      <console>:5: error: contravariant type T occurs in invariant position in type [-T]java.lang.Object with java.util.Comparator[T] of trait Foo        trait Foo[-T] extends Comparator[T]              ^  scala> import annotation.unchecked._     import annotation.unchecked._  scala> trait Foo[-T] extends Comparator[T @uncheckedVariance]     defined trait Foo 

This says that java.util.Comparator is naturally contra-variant, that is the type parameter T appears in parameters and never in a return type.

This raises the question: why is it also used in the Scala collections library which doesn't extends from Java interfaces?

trait GenericTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBuilder[A, CC[A] @uncheckedVariance] 

What are the valid uses for this annotation?

Answer 1

The problem is that GenericTraversableTemplate is used twice: once for mutable collections (where its type parameter should be invariant), and once for immutable collections (where covariance is invariably king).

GenericTraversableTemplate's typechecks assuming either covariance or invariance for the A type parameter. However, when we inherit it in a mutable trait, we have to pick invariance. Conversely, we'd like covariance in an immutable subclass.

Since we can't abstract over the variance annotation (yet ;-)) in GenericTraversableTemplate, so that we could have instantiated it to either one depending on the subclass, we have to resort to casting (@uncheckVariance is essentially a kind-cast). For further reading, I recommend my dissertation (sorry ;-)) or our recent bitrot paper