A selector may be created by invoking the {@link #open open} method of * this class, which will use the system's default {@link * java.nio.channels.spi.SelectorProvider selector provider} to * create a new selector. A selector may also be created by invoking the * {@link java.nio.channels.spi.SelectorProvider#openSelector openSelector} * method of a custom selector provider. A selector remains open until it is * closed via its {@link #close close} method. * * * *
A selectable channel's registration with a selector is represented by a * {@link SelectionKey} object. A selector maintains three sets of selection * keys: * *
The key set contains the keys representing the current * channel registrations of this selector. This set is returned by the * {@link #keys() keys} method.
The selected-key set is the set of keys such that each * key's channel was detected to be ready for at least one of the operations * identified in the key's interest set during a prior selection operation. * This set is returned by the {@link #selectedKeys() selectedKeys} method. * The selected-key set is always a subset of the key set.
The cancelled-key set is the set of keys that have been * cancelled but whose channels have not yet been deregistered. This set is * not directly accessible. The cancelled-key set is always a subset of the * key set.
All three sets are empty in a newly-created selector. * *
A key is added to a selector's key set as a side effect of registering a * channel via the channel's {@link SelectableChannel#register(Selector,int) * register} method. Cancelled keys are removed from the key set during * selection operations. The key set itself is not directly modifiable. * *
A key is added to its selector's cancelled-key set when it is cancelled, * whether by closing its channel or by invoking its {@link SelectionKey#cancel * cancel} method. Cancelling a key will cause its channel to be deregistered * during the next selection operation, at which time the key will removed from * all of the selector's key sets. * *
Keys are added to the selected-key set by selection * operations. A key may be removed directly from the selected-key set by * invoking the set's {@link java.util.Set#remove(java.lang.Object) remove} * method or by invoking the {@link java.util.Iterator#remove() remove} method * of an {@link java.util.Iterator iterator} obtained from the * set. Keys are never removed from the selected-key set in any other way; * they are not, in particular, removed as a side effect of selection * operations. Keys may not be added directly to the selected-key set.
* * * *During each selection operation, keys may be added to and removed from a * selector's selected-key set and may be removed from its key and * cancelled-key sets. Selection is performed by the {@link #select()}, {@link * #select(long)}, and {@link #selectNow()} methods, and involves three steps: *
* *Each key in the cancelled-key set is removed from each key set of * which it is a member, and its channel is deregistered. This step leaves * the cancelled-key set empty.
The underlying operating system is queried for an update as to the * readiness of each remaining channel to perform any of the operations * identified by its key's interest set as of the moment that the selection * operation began. For a channel that is ready for at least one such * operation, one of the following two actions is performed:
* *If the channel's key is not already in the selected-key set then * it is added to that set and its ready-operation set is modified to * identify exactly those operations for which the channel is now reported * to be ready. Any readiness information previously recorded in the ready * set is discarded.
Otherwise the channel's key is already in the selected-key set, * so its ready-operation set is modified to identify any new operations * for which the channel is reported to be ready. Any readiness * information previously recorded in the ready set is preserved; in other * words, the ready set returned by the underlying system is * bitwise-disjoined into the key's current ready set.
If any keys were added to the cancelled-key set while step (2) was * in progress then they are processed as in step (1).
Whether or not a selection operation blocks to wait for one or more * channels to become ready, and if so for how long, is the only essential * difference between the three selection methods.
* * *Selectors are themselves safe for use by multiple concurrent threads; * their key sets, however, are not. * *
The selection operations synchronize on the selector itself, on the key * set, and on the selected-key set, in that order. They also synchronize on * the cancelled-key set during steps (1) and (3) above. * *
Changes made to the interest sets of a selector's keys while a * selection operation is in progress have no effect upon that operation; they * will be seen by the next selection operation. * *
Keys may be cancelled and channels may be closed at any time. Hence the * presence of a key in one or more of a selector's key sets does not imply * that the key is valid or that its channel is open. Application code should * be careful to synchronize and check these conditions as necessary if there * is any possibility that another thread will cancel a key or close a channel. * *
A thread blocked in one of the {@link #select()} or {@link * #select(long)} methods may be interrupted by some other thread in one of * three ways: * *
By invoking the selector's {@link #wakeup wakeup} method, *
By invoking the selector's {@link #close close} method, or *
By invoking the blocked thread's {@link * java.lang.Thread#interrupt() interrupt} method, in which case its * interrupt status will be set and the selector's {@link #wakeup wakeup} * method will be invoked.
The {@link #close close} method synchronizes on the selector and all * three key sets in the same order as in a selection operation. * * * *
A selector's key and selected-key sets are not, in general, safe for use * by multiple concurrent threads. If such a thread might modify one of these * sets directly then access should be controlled by synchronizing on the set * itself. The iterators returned by these sets' {@link * java.util.Set#iterator() iterator} methods are fail-fast: If the set * is modified after the iterator is created, in any way except by invoking the * iterator's own {@link java.util.Iterator#remove() remove} method, then a * {@link java.util.ConcurrentModificationException} will be thrown.
* * * @author Mark Reinhold * @author JSR-51 Expert Group * @since 1.4 * * @see SelectableChannel * @see SelectionKey */ public abstract class Selector implements Closeable { /** * Initializes a new instance of this class. */ protected Selector() { } /** * Opens a selector. * *The new selector is created by invoking the {@link * java.nio.channels.spi.SelectorProvider#openSelector openSelector} method * of the system-wide default {@link * java.nio.channels.spi.SelectorProvider} object.
* * @return A new selector * * @throws IOException * If an I/O error occurs */ public static Selector open() throws IOException { return SelectorProvider.provider().openSelector(); } /** * Tells whether or not this selector is open. * * @return true if, and only if, this selector is open */ public abstract boolean isOpen(); /** * Returns the provider that created this channel. * * @return The provider that created this channel */ public abstract SelectorProvider provider(); /** * Returns this selector's key set. * *The key set is not directly modifiable. A key is removed only after * it has been cancelled and its channel has been deregistered. Any * attempt to modify the key set will cause an {@link * UnsupportedOperationException} to be thrown. * *
The key set is not thread-safe.
* * @return This selector's key set * * @throws ClosedSelectorException * If this selector is closed */ public abstract SetKeys may be removed from, but not directly added to, the * selected-key set. Any attempt to add an object to the key set will * cause an {@link UnsupportedOperationException} to be thrown. * *
The selected-key set is not thread-safe.
* * @return This selector's selected-key set * * @throws ClosedSelectorException * If this selector is closed */ public abstract SetThis method performs a non-blocking selection * operation. If no channels have become selectable since the previous * selection operation then this method immediately returns zero. * *
Invoking this method clears the effect of any previous invocations * of the {@link #wakeup wakeup} method.
* * @return The number of keys, possibly zero, whose ready-operation sets * were updated by the selection operation * * @throws IOException * If an I/O error occurs * * @throws ClosedSelectorException * If this selector is closed */ public abstract int selectNow() throws IOException; /** * Selects keys whose corresponding channels are ready for I/O * operations and passes them to the provided consumer. * *This method performs a non-blocking selection * operation. If no channels have become selectable since the previous * selection operation then this method immediately returns zero. * *
The difference between this method and {@link #selectNow()} is that * this method immediately passes the {@link java.nio.channels.SelectionKey} objects * to its handler, rather than updating the key set.
* *Invoking this method clears the effect of any previous invocations * of the {@link #wakeup wakeup} method.
* * @return The number of keys, possibly zero, whose ready-operation sets * were updated by the selection operation * * @param handler A handler function which is invoked with new SelectionKey * objects When an selection operation occurs. It is called * the same number of times as the return value. * * @throws java.lang.NullPointerException * if the handler is null. * * @throws IOException * If an I/O error occurs * * @throws ClosedSelectorException * If this selector is closed */ public abstract int selectNow(ConsumerThis method performs a blocking selection * operation. It returns only after at least one channel is selected, * this selector's {@link #wakeup wakeup} method is invoked, the current * thread is interrupted, or the given timeout period expires, whichever * comes first. * *
This method does not offer real-time guarantees: It schedules the * timeout as if by invoking the {@link Object#wait(long)} method.
* * @param timeout If positive, block for up to timeout * milliseconds, more or less, while waiting for a * channel to become ready; if zero, block indefinitely; * must not be negative * * @return The number of keys, possibly zero, * whose ready-operation sets were updated * * @throws IOException * If an I/O error occurs * * @throws ClosedSelectorException * If this selector is closed * * @throws IllegalArgumentException * If the value of the timeout argument is negative */ public abstract int select(long timeout) throws IOException; /** * Selects keys whose corresponding channels are ready for I/O * operations and passes them to the provided consumer. * *This method performs a blocking selection * operation. It returns only after at least one channel is selected, * this selector's {@link #wakeup wakeup} method is invoked, the current * thread is interrupted, or the given timeout period expires, whichever * comes first. * *
The difference between this method and {@link #select(long)} is that * this method immediately passes the {@link java.nio.channels.SelectionKey} objects * to its handler, rather than updating the key set.
* *This method does not offer real-time guarantees: It schedules the * timeout as if by invoking the {@link Object#wait(long)} method.
* * @param handler A handler function which is invoked with new SelectionKey * objects When an selection operation occurs. It is called * the same number of times as the return value. * * @param timeout If positive, block for up to timeout * milliseconds, more or less, while waiting for a * channel to become ready; if zero, block indefinitely; * must not be negative * * @return The number of keys, possibly zero, * whose ready-operation sets were updated * * @throws IOException * If an I/O error occurs * * @throws ClosedSelectorException * If this selector is closed * * @throws IllegalArgumentException * If the value of the timeout argument is negative */ public abstract int select(ConsumerThis method performs a blocking selection * operation. It returns only after at least one channel is selected, * this selector's {@link #wakeup wakeup} method is invoked, or the current * thread is interrupted, whichever comes first.
* * @return The number of keys, possibly zero, * whose ready-operation sets were updated * * @throws IOException * If an I/O error occurs * * @throws ClosedSelectorException * If this selector is closed */ public abstract int select() throws IOException; /** * Causes the first selection operation that has not yet returned to return * immediately. * *If another thread is currently blocked in an invocation of the * {@link #select()} or {@link #select(long)} methods then that invocation * will return immediately. If no selection operation is currently in * progress then the next invocation of one of these methods will return * immediately unless the {@link #selectNow()} method is invoked in the * meantime. In any case the value returned by that invocation may be * non-zero. Subsequent invocations of the {@link #select()} or {@link * #select(long)} methods will block as usual unless this method is invoked * again in the meantime. * *
Invoking this method more than once between two successive selection * operations has the same effect as invoking it just once.
* * @return This selector */ public abstract Selector wakeup(); /** * Closes this selector. * *If a thread is currently blocked in one of this selector's selection * methods then it is interrupted as if by invoking the selector's {@link * #wakeup wakeup} method. * *
Any uncancelled keys still associated with this selector are * invalidated, their channels are deregistered, and any other resources * associated with this selector are released. * *
If this selector is already closed then invoking this method has no * effect. * *
After a selector is closed, any further attempt to use it, except by * invoking this method or the {@link #wakeup wakeup} method, will cause a * {@link ClosedSelectorException} to be thrown.
* * @throws IOException * If an I/O error occurs */ public abstract void close() throws IOException; }