1 /*
2 * Copyright (c) 2000, 2018, 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
26 package java.nio.channels;
27
28 import java.io.Closeable;
29 import java.io.IOException;
30 import java.nio.channels.spi.SelectorProvider;
31 import 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 set.
88 * All keys may be removed from the selected-key set by invoking the set's
89 * {@link java.util.Set#clear() clear} method. Keys may not be added directly
90 * to the selected-key set. </p>
91 *
92 * <a id="selop"></a>
93 * <h2>Selection</h2>
94 *
95 * <p> During each selection operation, keys may be added to and removed from a
96 * selector's selected-key set and may be removed from its key and
97 * cancelled-key sets. Selection is performed by the {@link #select()}, {@link
98 * #select(long)}, and {@link #selectNow()} methods, and involves three steps:
99 * </p>
100 *
101 * <ol>
102 *
103 * <li><p> Each key in the cancelled-key set is removed from each key set of
104 * which it is a member, and its channel is deregistered. This step leaves
105 * the cancelled-key set empty. </p></li>
106 *
107 * <li><p> The underlying operating system is queried for an update as to the
108 * readiness of each remaining channel to perform any of the operations
109 * identified by its key's interest set as of the moment that the selection
110 * operation began. For a channel that is ready for at least one such
111 * operation, one of the following two actions is performed: </p>
112 *
113 * <ol>
114 *
115 * <li><p> If the channel's key is not already in the selected-key set then
116 * it is added to that set and its ready-operation set is modified to
117 * identify exactly those operations for which the channel is now reported
118 * to be ready. Any readiness information previously recorded in the ready
119 * set is discarded. </p></li>
120 *
121 * <li><p> Otherwise the channel's key is already in the selected-key set,
122 * so its ready-operation set is modified to identify any new operations
123 * for which the channel is reported to be ready. Any readiness
124 * information previously recorded in the ready set is preserved; in other
125 * words, the ready set returned by the underlying system is
126 * bitwise-disjoined into the key's current ready set. </p></li>
127 *
128 * </ol>
129 *
130 * If all of the keys in the key set at the start of this step have empty
131 * interest sets then neither the selected-key set nor any of the keys'
132 * ready-operation sets will be updated.
133 *
134 * <li><p> If any keys were added to the cancelled-key set while step (2) was
135 * in progress then they are processed as in step (1). </p></li>
136 *
137 * </ol>
138 *
139 * <p> Whether or not a selection operation blocks to wait for one or more
140 * channels to become ready, and if so for how long, is the only essential
141 * difference between the three selection methods. </p>
142 *
143 *
144 * <h2>Concurrency</h2>
145 *
146 * <p> A Selector and its key set are safe for use by multiple concurrent
147 * threads. Its selected-key set and cancelled-key set, however, are not.
148 *
149 * <p> The selection operations synchronize on the selector itself, on the
150 * selected-key set, in that order. They also synchronize on the cancelled-key
151 * set during steps (1) and (3) above.
152 *
153 * <p> Changes made to the interest sets of a selector's keys while a
154 * selection operation is in progress have no effect upon that operation; they
155 * will be seen by the next selection operation.
156 *
157 * <p> Keys may be cancelled and channels may be closed at any time. Hence the
158 * presence of a key in one or more of a selector's key sets does not imply
159 * that the key is valid or that its channel is open. Application code should
160 * be careful to synchronize and check these conditions as necessary if there
161 * is any possibility that another thread will cancel a key or close a channel.
162 *
163 * <p> A thread blocked in one of the {@link #select()} or {@link
164 * #select(long)} methods may be interrupted by some other thread in one of
165 * three ways:
166 *
167 * <ul>
168 *
169 * <li><p> By invoking the selector's {@link #wakeup wakeup} method,
170 * </p></li>
171 *
172 * <li><p> By invoking the selector's {@link #close close} method, or
173 * </p></li>
174 *
175 * <li><p> By invoking the blocked thread's {@link
176 * java.lang.Thread#interrupt() interrupt} method, in which case its
177 * interrupt status will be set and the selector's {@link #wakeup wakeup}
178 * method will be invoked. </p></li>
179 *
180 * </ul>
181 *
182 * <p> The {@link #close close} method synchronizes on the selector and its
183 * selected-key set in the same order as in a selection operation.
184 *
185 * <a id="ksc"></a>
186 * <p> A Selector's key set is safe for use by multiple concurrent threads.
187 * Retrieval operations from the key set do not generally block and so may
188 * overlap with new registrations that add to the set, or with the cancellation
189 * steps of selection operations that remove keys from the set. Iterators and
190 * spliterators return elements reflecting the state of the set at some point at
191 * or since the creation of the iterator/spliterator. They do not throw
192 * {@link java.util.ConcurrentModificationException ConcurrentModificationException}.
193 *
194 * <a id="sksc"></a>
195 * <p> A selector's selected-key set is not, in general, safe for use by
196 * multiple concurrent threads. If such a thread might modify the set directly
197 * then access should be controlled by synchronizing on the set itself. The
198 * iterators returned by the set's {@link java.util.Set#iterator() iterator}
199 * methods are <i>fail-fast:</i> If the set is modified after the iterator is
200 * created, in any way except by invoking the iterator's own {@link
201 * java.util.Iterator#remove() remove} method, then a {@link
202 * java.util.ConcurrentModificationException} will be thrown. </p>
203 *
204 * @author Mark Reinhold
205 * @author JSR-51 Expert Group
206 * @since 1.4
207 *
208 * @see SelectableChannel
209 * @see SelectionKey
210 */
211
212 public abstract class Selector implements Closeable {
213
214 /**
215 * Initializes a new instance of this class.
216 */
217 protected Selector() { }
218
219 /**
220 * Opens a selector.
221 *
222 * <p> The new selector is created by invoking the {@link
223 * java.nio.channels.spi.SelectorProvider#openSelector openSelector} method
224 * of the system-wide default {@link
225 * java.nio.channels.spi.SelectorProvider} object. </p>
226 *
227 * @return A new selector
228 *
229 * @throws IOException
230 * If an I/O error occurs
231 */
232 public static Selector open() throws IOException {
233 return SelectorProvider.provider().openSelector();
234 }
235
236 /**
237 * Tells whether or not this selector is open.
238 *
239 * @return {@code true} if, and only if, this selector is open
240 */
241 public abstract boolean isOpen();
242
243 /**
244 * Returns the provider that created this channel.
245 *
246 * @return The provider that created this channel
247 */
248 public abstract SelectorProvider provider();
249
250 /**
251 * Returns this selector's key set.
252 *
253 * <p> The key set is not directly modifiable. A key is removed only after
254 * it has been cancelled and its channel has been deregistered. Any
255 * attempt to modify the key set will cause an {@link
256 * UnsupportedOperationException} to be thrown.
257 *
258 * <p> The set is <a href="#ksc">safe</a> for use by multiple concurrent
259 * threads. </p>
260 *
261 * @return This selector's key set
262 *
263 * @throws ClosedSelectorException
264 * If this selector is closed
265 */
266 public abstract Set<SelectionKey> keys();
267
268 /**
269 * Returns this selector's selected-key set.
270 *
271 * <p> Keys may be removed from, but not directly added to, the
272 * selected-key set. Any attempt to add an object to the key set will
273 * cause an {@link UnsupportedOperationException} to be thrown.
274 *
275 * <p> The selected-key set is <a href="#sksc">not thread-safe</a>. </p>
276 *
277 * @return This selector's selected-key set
278 *
279 * @throws ClosedSelectorException
280 * If this selector is closed
281 */
282 public abstract Set<SelectionKey> selectedKeys();
283
284 /**
285 * Selects a set of keys whose corresponding channels are ready for I/O
286 * operations.
287 *
288 * <p> This method performs a non-blocking <a href="#selop">selection
289 * operation</a>. If no channels have become selectable since the previous
290 * selection operation then this method immediately returns zero.
291 *
292 * <p> Invoking this method clears the effect of any previous invocations
293 * of the {@link #wakeup wakeup} method. </p>
294 *
295 * @return The number of keys, possibly zero, whose ready-operation sets
296 * were updated by the selection operation
297 *
298 * @throws IOException
299 * If an I/O error occurs
300 *
301 * @throws ClosedSelectorException
302 * If this selector is closed
303 */
304 public abstract int selectNow() throws IOException;
305
306 /**
307 * Selects a set of keys whose corresponding channels are ready for I/O
308 * operations.
309 *
310 * <p> This method performs a blocking <a href="#selop">selection
311 * operation</a>. It returns only after at least one channel is selected,
312 * this selector's {@link #wakeup wakeup} method is invoked, the current
313 * thread is interrupted, or the given timeout period expires, whichever
314 * comes first.
315 *
316 * <p> This method does not offer real-time guarantees: It schedules the
317 * timeout as if by invoking the {@link Object#wait(long)} method. </p>
318 *
319 * @param timeout If positive, block for up to {@code timeout}
320 * milliseconds, more or less, while waiting for a
321 * channel to become ready; if zero, block indefinitely;
322 * must not be negative
323 *
324 * @return The number of keys, possibly zero,
325 * whose ready-operation sets were updated
326 *
327 * @throws IOException
328 * If an I/O error occurs
329 *
330 * @throws ClosedSelectorException
331 * If this selector is closed
332 *
333 * @throws IllegalArgumentException
334 * If the value of the timeout argument is negative
335 */
336 public abstract int select(long timeout) throws IOException;
337
338 /**
339 * Selects a set of keys whose corresponding channels are ready for I/O
340 * operations.
341 *
342 * <p> This method performs a blocking <a href="#selop">selection
343 * operation</a>. It returns only after at least one channel is selected,
344 * this selector's {@link #wakeup wakeup} method is invoked, or the current
345 * thread is interrupted, whichever comes first. </p>
346 *
347 * @return The number of keys, possibly zero,
348 * whose ready-operation sets were updated
349 *
350 * @throws IOException
351 * If an I/O error occurs
352 *
353 * @throws ClosedSelectorException
354 * If this selector is closed
355 */
356 public abstract int select() throws IOException;
357
358 /**
359 * Causes the first selection operation that has not yet returned to return
360 * immediately.
361 *
362 * <p> If another thread is currently blocked in an invocation of the
363 * {@link #select()} or {@link #select(long)} methods then that invocation
364 * will return immediately. If no selection operation is currently in
365 * progress then the next invocation of one of these methods will return
366 * immediately unless the {@link #selectNow()} method is invoked in the
367 * meantime. In any case the value returned by that invocation may be
368 * non-zero. Subsequent invocations of the {@link #select()} or {@link
369 * #select(long)} methods will block as usual unless this method is invoked
370 * again in the meantime.
371 *
372 * <p> Invoking this method more than once between two successive selection
373 * operations has the same effect as invoking it just once. </p>
374 *
375 * @return This selector
376 */
377 public abstract Selector wakeup();
378
379 /**
380 * Closes this selector.
381 *
382 * <p> If a thread is currently blocked in one of this selector's selection
383 * methods then it is interrupted as if by invoking the selector's {@link
384 * #wakeup wakeup} method.
385 *
386 * <p> Any uncancelled keys still associated with this selector are
387 * invalidated, their channels are deregistered, and any other resources
388 * associated with this selector are released.
389 *
390 * <p> If this selector is already closed then invoking this method has no
391 * effect.
392 *
393 * <p> After a selector is closed, any further attempt to use it, except by
394 * invoking this method or the {@link #wakeup wakeup} method, will cause a
395 * {@link ClosedSelectorException} to be thrown. </p>
396 *
397 * @throws IOException
398 * If an I/O error occurs
399 */
400 public abstract void close() throws IOException;
401
402 }