Selector

Selector

java.nio.channels

---

Java 1.4

A Selector is an object that monitors multiple nonblocking SelectableChannel objects and (after blocking if necessary) "selects" the channel that is (or the channels that are) ready for I/O. Create a new Selector with the static open ( ) method. Next register the channels that it is to monitor: a channel is registered by passing the Selector to the register( ) method of the channel ( register( ) is defined by the abstract SelectableChannel class). In addition to the Selector you must also pass a bitmask that specifies which I/O operations (reading, writing, connecting, and accepting) that the Selector is to monitor for that channel. Each call to this register( ) method returns a SelectionKey object. (The SelectionKey class also defines the constants that are used to form the bitmask of I/O operations.) Note that before a SelectableChannel can be registered, it must be in nonblocking mode, which can be accomplished with the configureBlocking( ) method of SelectableChannel .

Once the channels are registered with the Selector , call select( ) to block until one or more of the channels is ready for I/O. One version of select( ) takes a timeout value and returns if the specified number of milliseconds elapses without any channels becoming ready for I/O. These methods also return if any of the channels is closed, if an error occurs on any channel, if the wakeup ( ) method of the Selector is called, or if the interrupt( ) method of the blocked thread is called. There is also a selectNow( ) method which is like select( ) except that it does not block: it simply polls each of the channels and determines which have become ready for I/O. The return value of selectNow( ) and of both select( ) methods is the number of channels ready for I/O. It is possible for this return value to be zero.

The select( ) and selectNow( ) methods returns the number of channels that are ready for I/O; they do not return the channels themselves . To obtain this information, you must call the selectedKeys( ) method, which returns a java.util.Set containing SelectionKey objects. After calling select( ) and selectedKeys( ) , applications typically obtain a java.util.Iterator for the Set and use it to loop through the SelectionKey objects that represent the channels that are ready for I/O. Use the channel( ) method of the SelectionKey to determine which channel is ready, and call readyOps( ) , isReadable( ) , isWritable( ) or related methods of the SelectionKey to determine what kind of I/O operation is ready on the channel. SelectionKey objects remain in the selectedKeys( ) set until explicitly removed, so after performing the I/O operation for a given SelectionKey , you should remove that key from the Set returned by selectedKeys( ) (use the remove( ) method of the Set of its Iterator ).

In addition to the selectedKeys( ) method, Selector also defines a keys( ) method, which also returns a Set of SelectionKey objects. This set represents the complete set of channels that are being monitored by the Selector and may not be modified, except by closing the channel or deregistring the channel by calling the cancel( ) method of the associated SelectionKey . Cancelled keys are removed from the keys( ) set on the next call to select( ) or selectNow( ) .

Call wakeup( ) to cause another thread blocked in a call to select( ) to wake up and return immediately. If wakeup( ) is called but no thread is currently blocked in a select( ) call, then the next call to select( ) or selectNow( ) will return immediately.

When a Selector object is no longer needed, close it by calling close( ) . If any thread is blocked in a select( ) call, it will return immediately as if wakeup( ) had been called. After calling close( ) , you should not call any other methods of a Selector . isOpen( ) returns true if a Selector is still open, and returns false if it has been closed.

The Selector class is thread-safe. Note, however, that the Set object returnd by selectedKeys( ) is not: it should be used by only one thread at a time.

 public abstract class  Selector  {  // Protected Constructors  protected  Selector  ( );  // Public Class Methods  public static Selector  open  ( ) throws java.io.IOException;  // Public Instance Methods  public abstract void  close  ( ) throws java.io.IOException;        public abstract boolean  isOpen  ( );        public abstract java.util.Set<SelectionKey>  keys  ( );        public abstract java.nio.channels.spi.SelectorProvider  provider  ( );        public abstract int  select  ( ) throws java.io.IOException;        public abstract int  select  (long  timeout  ) throws java.io.IOException;        public abstract java.util.Set<SelectionKey>  selectedKeys  ( );        public abstract int  selectNow  ( ) throws java.io.IOException;        public abstract Selector  wakeup  ( );   } 

Subclasses

java.nio.channels.spi.AbstractSelector

Passed To

SelectableChannel.{keyFor( ) , register( )} , java.nio.channels.spi.AbstractSelectableChannel.{keyFor( ) , register( )}

Returned By

SelectionKey.selector( )