Timeout values

[Alan Bateman]

Gili wrote:
> Did this message ever get accepted by the mailing list? I ask because
> http://n2.nabble.com/Timeout-values-td3093833.html seems to believe
> otherwise.
>
> Thanks,
> Gili
>   
Yes, I saw it, but didn't see any replies.

Just to re-cap, the methods that wait-with-timeout introduced by this 
API are:
  AsynchronousChannelGroup#awaitTermination(long, TimeUnit), and
  WatchService#poll(long, TimeUnit)

The timeouts in both cases are specified to be consistent with j.u.c. 
That is, a timeout of <= 0 means do not wait.

The only pre-existing method in this API that can wait-with-timeout is 
Selector's select(long) method. A timeout of 0 means wait indefinitely; 
a negative timeout is not allowed. To do a non-blocking select you use 
the selectNow() method. You are right that this is a bit inconsistent 
with j.u.c but I don't think anyone has complained. Personally, I think 
it's okay because blocking and non-blocking selects are used for 
different purposes. In any case, Selector was added in 1.4 and we can't 
change it.

Moving onto AsynchronousSocketChannel, which can optionally associate a 
timer with an I/O operation. Here, the timeout is to cause the I/O 
operation to fail if the I/O doesn't complete before the timeout 
expires. The timeout is not a wait timeout so different semantics to the 
above.

There are two sets of methods, depending on if you using a timeout or 
not. If you don't want a timeout then you will typically using the 
3-argument:
  read(ByteBuffer, Object, CompletionHandler)

whereas if you want a timeout then you will use the 5-parameter methods:
  read(ByteBuffer, long, TimeUnit, Object, CompletionHandler)

Your concern is with 5-parameter methods for cases where you don't want 
a timer. This usage will likely be rare (except for the scatter/gather 
case which don't have overloading for all cases). As specified now, you 
pass a timeout of 0L  to mean "no timeout". A negative timeout is not 
allowed (that was for consistency with Selector; another choice would be 
for <= 0 to mean no timeout and so IllegalArgumentException is not 
thrown if you pass a negative value).. If I recall correctly, you are 
suggesting that Long.MAX_VALUE would be a better choice. That is, change 
the wording slightly so that MAX_VALUE means an infinite timeout (so 
that the implementation doesn't need to start a timer).  I don't recall 
if you had a suggestion for <= 0 but in any case, I don't see a big 
motive to change this. There's nothing stopping you passing in MAX_VALUE 
now except that it's slightly less efficient than 0.

-Alan.