1 /*
2 * Copyright (c) 2000, 2008, 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.spi;
27
28 import java.io.IOException;
29 import java.nio.channels.SelectionKey;
30 import java.nio.channels.Selector;
31 import java.util.HashSet;
32 import java.util.Set;
33 import sun.nio.ch.Interruptible;
34 import java.util.concurrent.atomic.AtomicBoolean;
35
36
37 /**
38 * Base implementation class for selectors.
39 *
40 * <p> This class encapsulates the low-level machinery required to implement
41 * the interruption of selection operations. A concrete selector class must
42 * invoke the {@link #begin begin} and {@link #end end} methods before and
43 * after, respectively, invoking an I/O operation that might block
44 * indefinitely. In order to ensure that the {@link #end end} method is always
45 * invoked, these methods should be used within a
46 * <tt>try</tt> ... <tt>finally</tt> block: <a name="be">
47 *
48 * <blockquote><pre>
49 * try {
50 * begin();
51 * // Perform blocking I/O operation here
52 * ...
53 * } finally {
54 * end();
55 * }</pre></blockquote>
56 *
57 * <p> This class also defines methods for maintaining a selector's
58 * cancelled-key set and for removing a key from its channel's key set, and
59 * declares the abstract {@link #register register} method that is invoked by a
60 * selectable channel's {@link AbstractSelectableChannel#register register}
61 * method in order to perform the actual work of registering a channel. </p>
62 *
63 *
64 * @author Mark Reinhold
65 * @author JSR-51 Expert Group
66 * @since 1.4
67 */
68
69 public abstract class AbstractSelector
70 extends Selector
71 {
72
73 private AtomicBoolean selectorOpen = new AtomicBoolean(true);
74
75 // The provider that created this selector
76 private final SelectorProvider provider;
77
78 /**
79 * Initializes a new instance of this class. </p>
80 */
81 protected AbstractSelector(SelectorProvider provider) {
82 this.provider = provider;
83 }
84
85 private final Set<SelectionKey> cancelledKeys = new HashSet<SelectionKey>();
86
87 void cancel(SelectionKey k) { // package-private
88 synchronized (cancelledKeys) {
89 cancelledKeys.add(k);
90 }
91 }
92
93 /**
94 * Closes this selector.
95 *
96 * <p> If the selector has already been closed then this method returns
97 * immediately. Otherwise it marks the selector as closed and then invokes
98 * the {@link #implCloseSelector implCloseSelector} method in order to
99 * complete the close operation. </p>
100 *
101 * @throws IOException
102 * If an I/O error occurs
103 */
104 public final void close() throws IOException {
105 boolean open = selectorOpen.getAndSet(false);
106 if (!open)
107 return;
108 implCloseSelector();
109 }
110
111 /**
112 * Closes this selector.
113 *
114 * <p> This method is invoked by the {@link #close close} method in order
115 * to perform the actual work of closing the selector. This method is only
116 * invoked if the selector has not yet been closed, and it is never invoked
117 * more than once.
118 *
119 * <p> An implementation of this method must arrange for any other thread
120 * that is blocked in a selection operation upon this selector to return
121 * immediately as if by invoking the {@link
122 * java.nio.channels.Selector#wakeup wakeup} method. </p>
123 *
124 * @throws IOException
125 * If an I/O error occurs while closing the selector
126 */
127 protected abstract void implCloseSelector() throws IOException;
128
129 public final boolean isOpen() {
130 return selectorOpen.get();
131 }
132
133 /**
134 * Returns the provider that created this channel.
135 *
136 * @return The provider that created this channel
137 */
138 public final SelectorProvider provider() {
139 return provider;
140 }
141
142 /**
143 * Retrieves this selector's cancelled-key set.
144 *
145 * <p> This set should only be used while synchronized upon it. </p>
146 *
147 * @return The cancelled-key set
148 */
149 protected final Set<SelectionKey> cancelledKeys() {
150 return cancelledKeys;
151 }
152
153 /**
154 * Registers the given channel with this selector.
155 *
156 * <p> This method is invoked by a channel's {@link
157 * AbstractSelectableChannel#register register} method in order to perform
158 * the actual work of registering the channel with this selector. </p>
159 *
160 * @param ch
161 * The channel to be registered
162 *
163 * @param ops
164 * The initial interest set, which must be valid
165 *
166 * @param att
167 * The initial attachment for the resulting key
168 *
169 * @return A new key representing the registration of the given channel
170 * with this selector
171 */
172 protected abstract SelectionKey register(AbstractSelectableChannel ch,
173 int ops, Object att);
174
175 /**
176 * Removes the given key from its channel's key set.
177 *
178 * <p> This method must be invoked by the selector for each channel that it
179 * deregisters. </p>
180 *
181 * @param key
182 * The selection key to be removed
183 */
184 protected final void deregister(AbstractSelectionKey key) {
185 ((AbstractSelectableChannel)key.channel()).removeKey(key);
186 }
187
188
189 // -- Interruption machinery --
190
191 private Interruptible interruptor = null;
192
193 /**
194 * Marks the beginning of an I/O operation that might block indefinitely.
195 *
196 * <p> This method should be invoked in tandem with the {@link #end end}
197 * method, using a <tt>try</tt> ... <tt>finally</tt> block as
198 * shown <a href="#be">above</a>, in order to implement interruption for
199 * this selector.
200 *
201 * <p> Invoking this method arranges for the selector's {@link
202 * Selector#wakeup wakeup} method to be invoked if a thread's {@link
203 * Thread#interrupt interrupt} method is invoked while the thread is
204 * blocked in an I/O operation upon the selector. </p>
205 */
206 protected final void begin() {
207 if (interruptor == null) {
208 interruptor = new Interruptible() {
209 public void interrupt(Thread ignore) {
210 AbstractSelector.this.wakeup();
211 }};
212 }
213 AbstractInterruptibleChannel.blockedOn(interruptor);
214 Thread me = Thread.currentThread();
215 if (me.isInterrupted())
216 interruptor.interrupt(me);
217 }
218
219 /**
220 * Marks the end of an I/O operation that might block indefinitely.
221 *
222 * <p> This method should be invoked in tandem with the {@link #begin begin}
223 * method, using a <tt>try</tt> ... <tt>finally</tt> block as
224 * shown <a href="#be">above</a>, in order to implement interruption for
225 * this selector. </p>
226 */
227 protected final void end() {
228 AbstractInterruptibleChannel.blockedOn(null);
229 }
230
231 }