Why does the Double.valueof javadoc say it caches values, when it doesn't?
JavaJavadocJava Problem Overview
In OpenJDK, for the method:
public static Double valueOf(double d)
The javadoc says:
> Returns a Double instance representing the specified double value. If a new Double instance is not required, this method should generally be used in preference to the constructor Double(double), as this method is likely to yield significantly better space and time performance by caching frequently requested values.
Here's the actual code:
public static Double valueOf(double d) {
return new Double(d);
}
The cache is a lie! What's going on here?
Java Solutions
Solution 1 - Java
The method exists for many types: Integer
, Long
, BigDecimal
and others and the documentation is always the same: Under some circumstances (which aren't defined), the method can return the same result.
AFAIK, the caching is only implemented for integer types and it returns cached instances for values between -128 and 127 (most common values). For BigDecimal
, the cache currently works for values from 0 to 10.
Later versions of Java might extend this behavior to other values/more types. So it's smart to use this code today because it might make your code faster tomorrow (and the code won't be slower today).
The Java compiler, for example, uses this API when generating code for autoboxing.
Solution 2 - Java
There is nothing wrong with the API doc:
> This method is likely to yield...
That is, an implementation is allowed to do caching here, which is simply not possible with a constructor. However, it is not required to. But, since chances are that you have an implementation that performs caching, this method should be preferred over using a constructor.
Solution 3 - Java
From Java 1.5+, the JVM/JIT guarantees the caching of Integer
s -127 to 127. So that is why for Integer
the preferred approach is to use valueOf
. You should generally use valueOf
over using the constructor for double
because then the JIT is able to optimise your code as it sees fit. For example, consider the following loop:
for (Object o: objectList) {
o.setValue(Double.valueOf(0.0));
}
In this instance, the JIT can precalculate the double object and reassign the same value on each iteration of the loop, whereas if you were to use new Double(0.0);
it would not be able to do that.
Solution 4 - Java
The designers of the API probably didn’t want to restrict alternate implementation. Those are now free to add caching to the Double
class.
Solution 5 - Java
These valueOf()
methods exist in every numeric type for the purpose to support caching. In fact, for Double it does not use any cache but for Integer
and Long
.
Solution 6 - Java
Remember that the JVM was created to reduce code size for embedded devices (mostly)--it's a set-top box operating system. I've worked on a few embedded java platforms and on those the "value of" valueOf would be more obvious, it would save quite a bit of space in some cases.
Mostly the method exists because "new" cannot ever use cached instances. valueOf MAY be implemented to use cached instances (otherwise you would just always use new) and likely does wherever it proves to save time.
If they (or you) replaced that method with one that actually did cache values then all your code would gain the advantage of that change, but without preparing by providing a method like "valueOf" it could never happen (well, practically never--you could tweak the compiler/bytecode executor to have "new" return cached values but I think that would break some contracts)
So the cache isn't really a lie, just a state of mind.