1/*
2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package java.nio.channels;
27
28import java.io.Closeable;
29import java.io.IOException;
30import java.nio.channels.spi.SelectorProvider;
31import java.util.Set;
32
33
34/**
35 * A multiplexor of {@link SelectableChannel} objects.
36 *
37 * <p> A selector may be created by invoking the {@link #open open} method of
38 * this class, which will use the system's default {@link
39 * java.nio.channels.spi.SelectorProvider selector provider} to
40 * create a new selector.  A selector may also be created by invoking the
41 * {@link java.nio.channels.spi.SelectorProvider#openSelector openSelector}
42 * method of a custom selector provider.  A selector remains open until it is
43 * closed via its {@link #close close} method.
44 *
45 * <a id="ks"></a>
46 *
47 * <p> A selectable channel's registration with a selector is represented by a
48 * {@link SelectionKey} object.  A selector maintains three sets of selection
49 * keys:
50 *
51 * <ul>
52 *
53 *   <li><p> The <i>key set</i> contains the keys representing the current
54 *   channel registrations of this selector.  This set is returned by the
55 *   {@link #keys() keys} method. </p></li>
56 *
57 *   <li><p> The <i>selected-key set</i> is the set of keys such that each
58 *   key's channel was detected to be ready for at least one of the operations
59 *   identified in the key's interest set during a prior selection operation.
60 *   This set is returned by the {@link #selectedKeys() selectedKeys} method.
61 *   The selected-key set is always a subset of the key set. </p></li>
62 *
63 *   <li><p> The <i>cancelled-key</i> set is the set of keys that have been
64 *   cancelled but whose channels have not yet been deregistered.  This set is
65 *   not directly accessible.  The cancelled-key set is always a subset of the
66 *   key set. </p></li>
67 *
68 * </ul>
69 *
70 * <p> All three sets are empty in a newly-created selector.
71 *
72 * <p> A key is added to a selector's key set as a side effect of registering a
73 * channel via the channel's {@link SelectableChannel#register(Selector,int)
74 * register} method.  Cancelled keys are removed from the key set during
75 * selection operations.  The key set itself is not directly modifiable.
76 *
77 * <p> A key is added to its selector's cancelled-key set when it is cancelled,
78 * whether by closing its channel or by invoking its {@link SelectionKey#cancel
79 * cancel} method.  Cancelling a key will cause its channel to be deregistered
80 * during the next selection operation, at which time the key will removed from
81 * all of the selector's key sets.
82 *
83 * <a id="sks"></a><p> Keys are added to the selected-key set by selection
84 * operations.  A key may be removed directly from the selected-key set by
85 * invoking the set's {@link java.util.Set#remove(java.lang.Object) remove}
86 * method or by invoking the {@link java.util.Iterator#remove() remove} method
87 * of an {@link java.util.Iterator iterator} obtained from the
88 * set.  Keys are never removed from the selected-key set in any other way;
89 * they are not, in particular, removed as a side effect of selection
90 * operations.  Keys may not be added directly to the selected-key set. </p>
91 *
92 *
93 * <a id="selop"></a>
94 * <h2>Selection</h2>
95 *
96 * <p> During each selection operation, keys may be added to and removed from a
97 * selector's selected-key set and may be removed from its key and
98 * cancelled-key sets.  Selection is performed by the {@link #select()}, {@link
99 * #select(long)}, and {@link #selectNow()} methods, and involves three steps:
100 * </p>
101 *
102 * <ol>
103 *
104 *   <li><p> Each key in the cancelled-key set is removed from each key set of
105 *   which it is a member, and its channel is deregistered.  This step leaves
106 *   the cancelled-key set empty. </p></li>
107 *
108 *   <li><p> The underlying operating system is queried for an update as to the
109 *   readiness of each remaining channel to perform any of the operations
110 *   identified by its key's interest set as of the moment that the selection
111 *   operation began.  For a channel that is ready for at least one such
112 *   operation, one of the following two actions is performed: </p>
113 *
114 *   <ol>
115 *
116 *     <li><p> If the channel's key is not already in the selected-key set then
117 *     it is added to that set and its ready-operation set is modified to
118 *     identify exactly those operations for which the channel is now reported
119 *     to be ready.  Any readiness information previously recorded in the ready
120 *     set is discarded.  </p></li>
121 *
122 *     <li><p> Otherwise the channel's key is already in the selected-key set,
123 *     so its ready-operation set is modified to identify any new operations
124 *     for which the channel is reported to be ready.  Any readiness
125 *     information previously recorded in the ready set is preserved; in other
126 *     words, the ready set returned by the underlying system is
127 *     bitwise-disjoined into the key's current ready set. </p></li>
128 *
129 *   </ol>
130 *
131 *   If all of the keys in the key set at the start of this step have empty
132 *   interest sets then neither the selected-key set nor any of the keys'
133 *   ready-operation sets will be updated.
134 *
135 *   <li><p> If any keys were added to the cancelled-key set while step (2) was
136 *   in progress then they are processed as in step (1). </p></li>
137 *
138 * </ol>
139 *
140 * <p> Whether or not a selection operation blocks to wait for one or more
141 * channels to become ready, and if so for how long, is the only essential
142 * difference between the three selection methods. </p>
143 *
144 *
145 * <h2>Concurrency</h2>
146 *
147 * <p> Selectors are themselves safe for use by multiple concurrent threads;
148 * their key sets, however, are not.
149 *
150 * <p> The selection operations synchronize on the selector itself, on the key
151 * set, and on the selected-key set, in that order.  They also synchronize on
152 * the cancelled-key set during steps (1) and (3) above.
153 *
154 * <p> Changes made to the interest sets of a selector's keys while a
155 * selection operation is in progress have no effect upon that operation; they
156 * will be seen by the next selection operation.
157 *
158 * <p> Keys may be cancelled and channels may be closed at any time.  Hence the
159 * presence of a key in one or more of a selector's key sets does not imply
160 * that the key is valid or that its channel is open.  Application code should
161 * be careful to synchronize and check these conditions as necessary if there
162 * is any possibility that another thread will cancel a key or close a channel.
163 *
164 * <p> A thread blocked in one of the {@link #select()} or {@link
165 * #select(long)} methods may be interrupted by some other thread in one of
166 * three ways:
167 *
168 * <ul>
169 *
170 *   <li><p> By invoking the selector's {@link #wakeup wakeup} method,
171 *   </p></li>
172 *
173 *   <li><p> By invoking the selector's {@link #close close} method, or
174 *   </p></li>
175 *
176 *   <li><p> By invoking the blocked thread's {@link
177 *   java.lang.Thread#interrupt() interrupt} method, in which case its
178 *   interrupt status will be set and the selector's {@link #wakeup wakeup}
179 *   method will be invoked. </p></li>
180 *
181 * </ul>
182 *
183 * <p> The {@link #close close} method synchronizes on the selector and all
184 * three key sets in the same order as in a selection operation.
185 *
186 * <a id="ksc"></a>
187 *
188 * <p> A selector's key and selected-key sets are not, in general, safe for use
189 * by multiple concurrent threads.  If such a thread might modify one of these
190 * sets directly then access should be controlled by synchronizing on the set
191 * itself.  The iterators returned by these sets' {@link
192 * java.util.Set#iterator() iterator} methods are <i>fail-fast:</i> If the set
193 * is modified after the iterator is created, in any way except by invoking the
194 * iterator's own {@link java.util.Iterator#remove() remove} method, then a
195 * {@link java.util.ConcurrentModificationException} will be thrown. </p>
196 *
197 *
198 * @author Mark Reinhold
199 * @author JSR-51 Expert Group
200 * @since 1.4
201 *
202 * @see SelectableChannel
203 * @see SelectionKey
204 */
205
206public abstract class Selector implements Closeable {
207
208    /**
209     * Initializes a new instance of this class.
210     */
211    protected Selector() { }
212
213    /**
214     * Opens a selector.
215     *
216     * <p> The new selector is created by invoking the {@link
217     * java.nio.channels.spi.SelectorProvider#openSelector openSelector} method
218     * of the system-wide default {@link
219     * java.nio.channels.spi.SelectorProvider} object.  </p>
220     *
221     * @return  A new selector
222     *
223     * @throws  IOException
224     *          If an I/O error occurs
225     */
226    public static Selector open() throws IOException {
227        return SelectorProvider.provider().openSelector();
228    }
229
230    /**
231     * Tells whether or not this selector is open.
232     *
233     * @return {@code true} if, and only if, this selector is open
234     */
235    public abstract boolean isOpen();
236
237    /**
238     * Returns the provider that created this channel.
239     *
240     * @return  The provider that created this channel
241     */
242    public abstract SelectorProvider provider();
243
244    /**
245     * Returns this selector's key set.
246     *
247     * <p> The key set is not directly modifiable.  A key is removed only after
248     * it has been cancelled and its channel has been deregistered.  Any
249     * attempt to modify the key set will cause an {@link
250     * UnsupportedOperationException} to be thrown.
251     *
252     * <p> The key set is <a href="#ksc">not thread-safe</a>. </p>
253     *
254     * @return  This selector's key set
255     *
256     * @throws  ClosedSelectorException
257     *          If this selector is closed
258     */
259    public abstract Set<SelectionKey> keys();
260
261    /**
262     * Returns this selector's selected-key set.
263     *
264     * <p> Keys may be removed from, but not directly added to, the
265     * selected-key set.  Any attempt to add an object to the key set will
266     * cause an {@link UnsupportedOperationException} to be thrown.
267     *
268     * <p> The selected-key set is <a href="#ksc">not thread-safe</a>. </p>
269     *
270     * @return  This selector's selected-key set
271     *
272     * @throws  ClosedSelectorException
273     *          If this selector is closed
274     */
275    public abstract Set<SelectionKey> selectedKeys();
276
277    /**
278     * Selects a set of keys whose corresponding channels are ready for I/O
279     * operations.
280     *
281     * <p> This method performs a non-blocking <a href="#selop">selection
282     * operation</a>.  If no channels have become selectable since the previous
283     * selection operation then this method immediately returns zero.
284     *
285     * <p> Invoking this method clears the effect of any previous invocations
286     * of the {@link #wakeup wakeup} method.  </p>
287     *
288     * @return  The number of keys, possibly zero, whose ready-operation sets
289     *          were updated by the selection operation
290     *
291     * @throws  IOException
292     *          If an I/O error occurs
293     *
294     * @throws  ClosedSelectorException
295     *          If this selector is closed
296     */
297    public abstract int selectNow() throws IOException;
298
299    /**
300     * Selects a set of keys whose corresponding channels are ready for I/O
301     * operations.
302     *
303     * <p> This method performs a blocking <a href="#selop">selection
304     * operation</a>.  It returns only after at least one channel is selected,
305     * this selector's {@link #wakeup wakeup} method is invoked, the current
306     * thread is interrupted, or the given timeout period expires, whichever
307     * comes first.
308     *
309     * <p> This method does not offer real-time guarantees: It schedules the
310     * timeout as if by invoking the {@link Object#wait(long)} method. </p>
311     *
312     * @param  timeout  If positive, block for up to {@code timeout}
313     *                  milliseconds, more or less, while waiting for a
314     *                  channel to become ready; if zero, block indefinitely;
315     *                  must not be negative
316     *
317     * @return  The number of keys, possibly zero,
318     *          whose ready-operation sets were updated
319     *
320     * @throws  IOException
321     *          If an I/O error occurs
322     *
323     * @throws  ClosedSelectorException
324     *          If this selector is closed
325     *
326     * @throws  IllegalArgumentException
327     *          If the value of the timeout argument is negative
328     */
329    public abstract int select(long timeout)
330        throws IOException;
331
332    /**
333     * Selects a set of keys whose corresponding channels are ready for I/O
334     * operations.
335     *
336     * <p> This method performs a blocking <a href="#selop">selection
337     * operation</a>.  It returns only after at least one channel is selected,
338     * this selector's {@link #wakeup wakeup} method is invoked, or the current
339     * thread is interrupted, whichever comes first.  </p>
340     *
341     * @return  The number of keys, possibly zero,
342     *          whose ready-operation sets were updated
343     *
344     * @throws  IOException
345     *          If an I/O error occurs
346     *
347     * @throws  ClosedSelectorException
348     *          If this selector is closed
349     */
350    public abstract int select() throws IOException;
351
352    /**
353     * Causes the first selection operation that has not yet returned to return
354     * immediately.
355     *
356     * <p> If another thread is currently blocked in an invocation of the
357     * {@link #select()} or {@link #select(long)} methods then that invocation
358     * will return immediately.  If no selection operation is currently in
359     * progress then the next invocation of one of these methods will return
360     * immediately unless the {@link #selectNow()} method is invoked in the
361     * meantime.  In any case the value returned by that invocation may be
362     * non-zero.  Subsequent invocations of the {@link #select()} or {@link
363     * #select(long)} methods will block as usual unless this method is invoked
364     * again in the meantime.
365     *
366     * <p> Invoking this method more than once between two successive selection
367     * operations has the same effect as invoking it just once.  </p>
368     *
369     * @return  This selector
370     */
371    public abstract Selector wakeup();
372
373    /**
374     * Closes this selector.
375     *
376     * <p> If a thread is currently blocked in one of this selector's selection
377     * methods then it is interrupted as if by invoking the selector's {@link
378     * #wakeup wakeup} method.
379     *
380     * <p> Any uncancelled keys still associated with this selector are
381     * invalidated, their channels are deregistered, and any other resources
382     * associated with this selector are released.
383     *
384     * <p> If this selector is already closed then invoking this method has no
385     * effect.
386     *
387     * <p> After a selector is closed, any further attempt to use it, except by
388     * invoking this method or the {@link #wakeup wakeup} method, will cause a
389     * {@link ClosedSelectorException} to be thrown. </p>
390     *
391     * @throws  IOException
392     *          If an I/O error occurs
393     */
394    public abstract void close() throws IOException;
395
396}
397