Why does Double.valueof javadoc say that it caches values ​​when it is not?

Question

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 usually be used in preference to the Double (double) constructor, since this method can significantly improve the performance of space and time by caching frequently requested values.

Here is the actual code:

 public static Double valueOf(double d) { return new Double(d); } 

Cache is a lie! What's going on here?

Answer 1

The method exists for many types: Integer , Long , BigDecimal and others, and the documentation is always the same: in some circumstances (which are not defined), the method can return the same result.

AFAIK, caching is implemented only for integer types and returns cached instances for values ​​from -128 to 127 (the most common values). For BigDecimal cache currently works for values ​​from 0 to 10.

Later versions of Java may extend this behavior to other values ​​/ more types. Therefore, today it is very useful to use this code, because it can make your code faster tomorrow (and the code today will not be slower).

The Java compiler, for example, uses this API when generating code for autoboxing.

Answer 2

There is nothing wrong with the API document:

This method is likely to give ...

That is, implementations are allowed to do caching here, which is simply not possible with the constructor. However, this is not required. But, since there is a chance that you have a caching implementation, this method should be preferable to using a constructor.

Answer 3

From Java 1.5+, the JVM / JIT guarantees Integer -127 caching to 127. Therefore, for Integer preferred approach is to use valueOf . Usually you should use valueOf with the constructor for double , because JIT can optimize your code as you see fit. For example, consider the following loop:

 for (Object o: objectList) { o.setValue(Double.valueOf(0.0)); } 

In this case, the JIT can pre-compute the double object and reassign the same value at each iteration of the loop, whereas if you were to use new Double(0.0); , he could not do that.

Answer 4

The API designers probably did not want to limit the alternative implementation. Now you can add caching to the Double class.

Answer 5

These valueOf() methods exist in every numeric type to support caching. In fact, for Double it does not use cache, but for Integer and Long .

Answer 6

Remember that the JVM was created to reduce the code size for embedded devices (mostly) - it is an operating system with a prefix. I worked on several built-in java platforms, and in cases where the value of valueOf would be more obvious, in some cases this will save a little space.

Basically, the method exists because the “new” can never use cached instances. valueOf MAY be implemented to use cached instances (otherwise you will always use the new one) and probably does everything that saves time.

If they (or you) replaced this method with the one that really did the cache values, then all of your code could take advantage of this change, but without preparation using a method like "valueOf", this will never happen (well, almost never - you could tweak the compiler / bytecode executor to have "new" returned cached values, but I think this will break some contracts)

So cache is not a lie, but only a state of mind.