Timeout values

[Doug Lea]

> 
> 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.

BTW, besides conforming to common sense, the main reason for this is
to make waits composable. As in:
   void composite(timeLimit) {
      ...
      step1(timeLimit);
      ...
      step2(timeLimit - elapsed);
   }
which otherwise can surprisingly misbehave if timeLimit - elapsed
happens to be 0.

> 
> 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.

It was done this way in nio because the above arguments were
not enough to convince those people accustomed to C select/poll
APIs, especially since TimeUnit had not yet been introduced,
and without it there was no good alternative convention to point to.

> 
> 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". 

I agree that this should be changed. Any method taking a TimeUnit
should obey j.u.c conventions. Which means separating out the
no-timeout case as another method. Which would be a minor
nuisance to carry out but will probably result in fewer
usage errors.

-Doug