A DESCRIPTION OF THE REQUEST :
The documentation describes the blocking behavior of interestOps() as arbitrary and dependent on the implementation.

JUSTIFICATION :
The very loose guarantees about whether or not interestOps() will block forces authors to jump through all sorts of hoops to insure that a call to interestOps() will not block the application logic from continuing.

Currently, there are two real solutions:
1. Since I have only observed interestOps() blocking when a select() is also blocked, one can simply use select() with a timeout and hope that the interestOps() completes before the selection thread loops back around to the select() and blocks again.

2. Build a queue of runnables that do the appropriate interestOps() operations and then wakeup() the selector.

Both workarounds work, but are either clunky or not 100% safe.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
interestOps(), with and without arguments, should not ever block. In addition, the documentation should make a guarantee about whether or not wakeup() needs to be called for a possibly in-progress selectoin operation will notice the updated interest set.
ACTUAL -
I'm not sure of what situations interestOps() will block in, but since the API documentation mentions it, I'm guessing there is an implementation where interestOps() does block...

Also, in the event that interestOps() does not block, a note should be made about whether in-progress selection operations will notice interest ops update (they currently do not--wakeup() must be explicitly called).

CUSTOMER SUBMITTED WORKAROUND :
Two workarounds have been mentioned earlier.

The first is using select() with a timeout and hoping the thread blocked on interestOps() makes progress when select() times out.

The other is building a queue of Runnables to update the interest sets and then calling wakeup() on the selector. This is somewhat clunky.