[concurrency-interest] Javadoc for offer method in ConcurrentLinkedQueue

Kasper Nielsen kav@it.edu
Thu, 11 Sep 2003 14:55:30 +0200


Actually I'm looking at the current version.

1.
If offer() and add() doesn't differ for ConcurrentLinkedQueue I can't
see why the javadoc for offer() should be any different from add(), by
looking at offer() alone it sounds like it might fail under certain
circumstances "Adds the specified element to this queue, if possible...
Returns: true if it was possible to add the element to this queue, else
false" and that add() will allways succeed "Adds the specified element
to the tail of this queue... Returns true (as per the general contract
of Collection.add)"

I also think it should be explicitly indicated that they do the same
thing, two methods that do exactly the same thing is allways suspicious.

2.
Btw: Why do some of the queues throw IllegalStateException (if this
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.

- Kasper

> -----Original Message-----
> From: David Holmes [mailto:dholmes@dltech.com.au] 
> Sent: 11. september 2003 14:18
> To: Kasper Nielsen; concurrency-interest@altair.cs.oswego.edu
> Cc: Doug Lea
> Subject: RE: [concurrency-interest] Javadoc for offer method 
> in ConcurrentLinkedQueue
> 
> 
> I wrote:
> > I don't understand what you perceive as the problem. The 
> javadoc for 
> > offer() hasn't been copied, it's been redefined to indicate 
> that the 
> > offer can't fail (ie return false). For an unbounded collection 
> > offer() and add() have the same behaviour as they differ 
> only in the 
> > failure mode related to capacity restrictions.
> 
> 
> I just realized that Kasper may be looking at a packaged 
> version of the docs that has since been updated. The current 
> docs are online at:
> 
http://gee.cs.oswego.edu/dl/concurrent/dist/docs/index.html

Sorry for any confusion.

David Holmes