< prev index next >

src/java.base/share/classes/java/nio/channels/SelectionKey.java

Print this page


   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


< prev index next >