search

ensoft-xx / google-collections

Automatically exported from code.google.com/p/google-collections
Apache License 2.0
0 stars 0 forks source link

Enhance the JavaDoc for MapMaker.makeComputingMap #183

Closed GoogleCodeExporter closed 8 years ago

GoogleCodeExporter commented 8 years ago 
In a discussion with a colleague a vagueness was expressed around the
javadoc of the MapMaker.makeComputingMap function.  Most of this was around
the line "Only one value will be computed for each key at a given time."

Joshua Bloch's presentation "The Collections Connection, Gala Tenth
Edition" at javaone has the following code segment:

final AtomicInteger counter = new AtomicInteger(0);
uids = new MapMaker().weakKeys().makeComputingMap(
  new Function<Object, Integer>() {
    public Integer apply(Object from) {
      return counter.getAndIncrement(); }});

The question was asked, "why the AtomicInteger?"  The way the doc is
written there is an ambiguity around how many concurrent calls will happen
to apply().

The following explanation for the atomic int was given:

The reason why is that the function will only be called sync per "from" so
if there are two requests for keyA and keyB at the same time and
!keyA.equals(keyB) then the function will be called concurrently for both
keyA and keyB.  This is why there is an atomic int and why this is better
then just locking on the map.  You can compute multiple values at the same
time and know that all the computations going on are also unique (no
duplicated effort).

I hope this helps show where the javadoc could use some more precision and
how it might be read two ways.

~Brian

Original issue reported on code.google.com by nairb...@gmail.com on 5 Jun 2009 at 4:30

GoogleCodeExporter commented 8 years ago 
I don't see any ambiguity in the Javadoc.

I think that you are confusing the fact that MapMaker itself will only compute 
a single value for a given key, but 
that doesn't have any implications for code _outside_ of Mapmaker, e.g. the 
AtomicInteger, or the method in 
which it lies.

More specifically, the AtomicInteger is necessary because it can be 
concurrently accessed by multiple MapMaker 
computations on _different keys_.

Original comment by f...@google.com on 5 Jun 2009 at 7:21

GoogleCodeExporter commented 8 years ago 
a few words and a few minutes' time can probably make the doc clearer.

Original comment by kevin...@gmail.com on 15 Jun 2009 at 5:40

GoogleCodeExporter commented 8 years ago

Original comment by kevin...@gmail.com on 17 Sep 2009 at 5:45

GoogleCodeExporter commented 8 years ago

Original comment by kevin...@gmail.com on 17 Sep 2009 at 5:46

GoogleCodeExporter commented 8 years ago

Original comment by kevin...@gmail.com on 17 Sep 2009 at 5:59

GoogleCodeExporter commented 8 years ago 
doc is improved for rc3.

Original comment by kevin...@gmail.com on 17 Sep 2009 at 7:24