[concurrency-interest] Javadoc for offer method in ConcurrentLinkedQueue

Doug Lea dl@cs.oswego.edu
Thu, 11 Sep 2003 11:51:10 -0400


Methods add(x) and offer(x) differ in that the return values mean
different things. In add, a true return means that the collection
changed; in offer, it means thjat the element was added. The difference
IS somewhat subtle and confusing; suggestions for clarifying would
be welcome.

The return value for add(x) is only useful for Sets, where it tells
you whether an element was already present.  In a sequential program, it
is always the case that:
  c.add(x);
  assert(c.contains(x))
but only that
  if (c.offer(x)) 
    assert(c.contains(x))

And since add cannot "normally" refuse to add an element, it can
do so only by throwing an exception.

It might have been nice to somehow collapse these, but it cannot be done
without changing the specs for Collection.add, which could break
existing programs. (Interfaces are forever...)

-Doug