1 /*
2 * Copyright (c) 2000, 2019, 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
56 * #interestOps(int)} method. </p></li>
57 *
58 * <li><p> The <i>ready set</i> identifies the operation categories for which
59 * the key's channel has been detected to be ready by the key's selector.
60 * The ready set is initialized to zero when the key is created; it may later
61 * be updated by the selector during a selection operation, but it cannot be
62 * updated directly. </p></li>
63 *
64 * </ul>
65 *
66 * <p> That a selection key's ready set indicates that its channel is ready for
67 * some operation category is a hint, but not a guarantee, that an operation in
68 * such a category may be performed by a thread without causing the thread to
69 * block. A ready set is most likely to be accurate immediately after the
70 * completion of a selection operation. It is likely to be made inaccurate by
71 * external events and by I/O operations that are invoked upon the
72 * corresponding channel.
73 *
74 * <p> This class defines all known operation-set bits, but precisely which
75 * bits are supported by a given channel depends upon the type of the channel.
76 * Each subclass of {@link SelectableChannel} defines an {@link
77 * SelectableChannel#validOps() validOps()} method which returns a set
78 * identifying just those operations that are supported by the channel. An
79 * attempt to set or test an operation-set bit that is not supported by a key's
80 * channel will result in an appropriate run-time exception.
81 *
82 * <p> It is often necessary to associate some application-specific data with a
83 * selection key, for example an object that represents the state of a
84 * higher-level protocol and handles readiness notifications in order to
85 * implement that protocol. Selection keys therefore support the
86 * <i>attachment</i> of a single arbitrary object to a key. An object can be
87 * attached via the {@link #attach attach} method and then later retrieved via
88 * the {@link #attachment() attachment} method.
89 *
90 * <p> Selection keys are safe for use by multiple concurrent threads. A
91 * selection operation will always use the interest-set value that was current
92 * at the moment that the operation began. </p>
93 *
94 *
95 * @author Mark Reinhold
96 * @author JSR-51 Expert Group
273 * <p> It is guaranteed that the returned set will only contain operation
274 * bits that are valid for this key's channel. </p>
275 *
276 * @return This key's ready-operation set
277 *
278 * @throws CancelledKeyException
279 * If this key has been cancelled
280 */
281 public abstract int readyOps();
282
283
284 // -- Operation bits and bit-testing convenience methods --
285
286 /**
287 * Operation-set bit for read operations.
288 *
289 * <p> Suppose that a selection key's interest set contains
290 * {@code OP_READ} at the start of a <a
291 * href="Selector.html#selop">selection operation</a>. If the selector
292 * detects that the corresponding channel is ready for reading, has reached
293 * end-of-stream, has been remotely shut down for further reading, or has
294 * an error pending, then it will add {@code OP_READ} to the key's
295 * ready-operation set. </p>
296 */
297 public static final int OP_READ = 1 << 0;
298
299 /**
300 * Operation-set bit for write operations.
301 *
302 * <p> Suppose that a selection key's interest set contains
303 * {@code OP_WRITE} at the start of a <a
304 * href="Selector.html#selop">selection operation</a>. If the selector
305 * detects that the corresponding channel is ready for writing, has been
306 * remotely shut down for further writing, or has an error pending, then it
307 * will add {@code OP_WRITE} to the key's ready set. </p>
308 */
309 public static final int OP_WRITE = 1 << 2;
310
311 /**
312 * Operation-set bit for socket-connect operations.
313 *
314 * <p> Suppose that a selection key's interest set contains
315 * {@code OP_CONNECT} at the start of a <a
316 * href="Selector.html#selop">selection operation</a>. If the selector
317 * detects that the corresponding socket channel is ready to complete its
318 * connection sequence, or has an error pending, then it will add
319 * {@code OP_CONNECT} to the key's ready set. </p>
320 */
321 public static final int OP_CONNECT = 1 << 3;
322
323 /**
324 * Operation-set bit for socket-accept operations.
325 *
326 * <p> Suppose that a selection key's interest set contains
|
1 /*
2 * Copyright (c) 2000, 2020, 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
56 * #interestOps(int)} method. </p></li>
57 *
58 * <li><p> The <i>ready set</i> identifies the operation categories for which
59 * the key's channel has been detected to be ready by the key's selector.
60 * The ready set is initialized to zero when the key is created; it may later
61 * be updated by the selector during a selection operation, but it cannot be
62 * updated directly. </p></li>
63 *
64 * </ul>
65 *
66 * <p> That a selection key's ready set indicates that its channel is ready for
67 * some operation category is a hint, but not a guarantee, that an operation in
68 * such a category may be performed by a thread without causing the thread to
69 * block. A ready set is most likely to be accurate immediately after the
70 * completion of a selection operation. It is likely to be made inaccurate by
71 * external events and by I/O operations that are invoked upon the
72 * corresponding channel.
73 *
74 * <p> This class defines all known operation-set bits, but precisely which
75 * bits are supported by a given channel depends upon the type of the channel.
76 * Each subclass of {@link SelectableChannel} defines a {@link
77 * SelectableChannel#validOps() validOps()} method which returns a set
78 * identifying just those operations that are supported by the channel. An
79 * attempt to set or test an operation-set bit that is not supported by a key's
80 * channel will result in an appropriate run-time exception.
81 *
82 * <p> It is often necessary to associate some application-specific data with a
83 * selection key, for example an object that represents the state of a
84 * higher-level protocol and handles readiness notifications in order to
85 * implement that protocol. Selection keys therefore support the
86 * <i>attachment</i> of a single arbitrary object to a key. An object can be
87 * attached via the {@link #attach attach} method and then later retrieved via
88 * the {@link #attachment() attachment} method.
89 *
90 * <p> Selection keys are safe for use by multiple concurrent threads. A
91 * selection operation will always use the interest-set value that was current
92 * at the moment that the operation began. </p>
93 *
94 *
95 * @author Mark Reinhold
96 * @author JSR-51 Expert Group
273 * <p> It is guaranteed that the returned set will only contain operation
274 * bits that are valid for this key's channel. </p>
275 *
276 * @return This key's ready-operation set
277 *
278 * @throws CancelledKeyException
279 * If this key has been cancelled
280 */
281 public abstract int readyOps();
282
283
284 // -- Operation bits and bit-testing convenience methods --
285
286 /**
287 * Operation-set bit for read operations.
288 *
289 * <p> Suppose that a selection key's interest set contains
290 * {@code OP_READ} at the start of a <a
291 * href="Selector.html#selop">selection operation</a>. If the selector
292 * detects that the corresponding channel is ready for reading, has reached
293 * end-of-stream, has been remotely shut down for further writing, or has
294 * an error pending, then it will add {@code OP_READ} to the key's
295 * ready-operation set. </p>
296 */
297 public static final int OP_READ = 1 << 0;
298
299 /**
300 * Operation-set bit for write operations.
301 *
302 * <p> Suppose that a selection key's interest set contains
303 * {@code OP_WRITE} at the start of a <a
304 * href="Selector.html#selop">selection operation</a>. If the selector
305 * detects that the corresponding channel is ready for writing, has been
306 * remotely shut down for further reading, or has an error pending, then it
307 * will add {@code OP_WRITE} to the key's ready set. </p>
308 */
309 public static final int OP_WRITE = 1 << 2;
310
311 /**
312 * Operation-set bit for socket-connect operations.
313 *
314 * <p> Suppose that a selection key's interest set contains
315 * {@code OP_CONNECT} at the start of a <a
316 * href="Selector.html#selop">selection operation</a>. If the selector
317 * detects that the corresponding socket channel is ready to complete its
318 * connection sequence, or has an error pending, then it will add
319 * {@code OP_CONNECT} to the key's ready set. </p>
320 */
321 public static final int OP_CONNECT = 1 << 3;
322
323 /**
324 * Operation-set bit for socket-accept operations.
325 *
326 * <p> Suppose that a selection key's interest set contains
|