hg: nio/nio/jdk: First installation of potential updates for M4

[libman at terabit.com.au]

Alan,
Please correct me, if I am  wrong.
Or may be my questions will help to fix doc:

from AsynchronousChannel doc
--------------------------------
Cancellation

The Future interface defines the cancel method to cancel execution of a task.

Where the cancel method is invoked with the mayInterruptIfRunning
parameter set to true then the I/O operation may be interrupted by closing
the channel. This will cause any other I/O operations outstanding on the
channel to complete with the exception AsynchronousCloseException.
-----------------------------------------------------------------------

So if mayInterruptIfRunning is true, what exception should be generated
for given operation:  Cancellation Exception or AsynchronousCloseException
or any of them is legal? I assumed that any of them is legal.
That is why you misunderstood me.
If my assumption is wrong, probably it would be good to state
explicitly in doc that given operation should finish with
only CancellationException.


from Future doc
--------------------------------
This attempt will fail if the task :
has already completed,
has already been cancelled,
or could not be cancelled for some other reason

Assuming that cancel(true) can produce  AsynchronousCloseException,
my example is legal:

cancel (boolean mayInterrupt)
{
   if (mayInterrupt) {
       // this will force all operations
       // including this operation
       // fail with  AsynchronousCloseException.
       // So operation failed, but not cancelled
       channel.close();
    }
    else {
       // we can not cancel opeartion
       //  "for some other reason"
    }
    return false;
}

If cancel(true) MUST NOT generate AsynchronousCloseException for THIS
operation (only for all others), than pseudo-code should work:

cancel (boolean mayInterrupt)
{
   if (mayInterrupt) {

       boolean rc = setAtomicallyStateToCancelIfNotDone...

       channel.close();

       // when operation will fail, channel implementation
       // a) will attempt to set Failed state
       //    with AsynchronousCloseException,
       //    but it will fail as we set already cancelled
       //
       // b) channel will notify waiters after
       //    setting completion state in a)
       //    in any case Failed or Cancelled

       // if we do not want return before actual
       // notification , wait on special condition
       // here.
       // This will allow to reuse buffers safely
       // on cancel return.
       // Do we need this?

       return rc;
    }

    // else we did not cancel "for some reasons"
    // and if anybody else cancelled, it was not our action
    // so:
    return false;
}

Alex