[concurrency-interest] Javadoc for offer method in ConcurrentLinkedQueue

David Holmes dholmes@dltech.com.au
Fri, 12 Sep 2003 09:29:16 +1000

> Actually I'm looking at the current version.

Well now I'm really confused. The online docs give the following for

public boolean offer(E o)
  Adds the specified element to this queue.
Specified by:
  offer in interface Queue
  o - the element to add.
  true (as per the general contract of Queue.offer).
  NullPointerException - if the specified element is null

And this is what I referred to yesterday.

But my cvs copy does not contain this. Doug?

> 2. Btw: Why do some of the queues throw IllegalStateException (if
> queue is full) on add() when it can just return false?
> The contract of Collection.add says
>  Returns:
>    true if this collection changed as a result of the call
> So I can't see why we just can't indicate that a queue is full by
> returning false.

The contract for Collection.add also states:

"If a collection refuses to add a particular element for any reason
other than that it already contains the element, it *must* throw an
exception (rather than returning false). This preserves the invariant
that a collection always contains the specified element after this
call returns."

Hence it cannot return false on full.

David Holmes