1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package org.jboss.netty.channel.socket.oio;
17
18 import org.jboss.netty.channel.Channel;
19 import org.jboss.netty.channel.ChannelPipeline;
20 import org.jboss.netty.channel.ChannelSink;
21 import org.jboss.netty.channel.group.ChannelGroup;
22 import org.jboss.netty.channel.socket.ServerSocketChannel;
23 import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
24 import org.jboss.netty.util.internal.ExecutorUtil;
25
26 import java.util.concurrent.Executor;
27 import java.util.concurrent.Executors;
28 import java.util.concurrent.RejectedExecutionException;
29
30 /**
31 * A {@link ServerSocketChannelFactory} which creates a server-side blocking
32 * I/O based {@link ServerSocketChannel}. It utilizes the good old blocking
33 * I/O API which is known to yield better throughput and latency when there
34 * are relatively small number of connections to serve.
35 *
36 * <h3>How threads work</h3>
37 * <p>
38 * There are two types of threads in a {@link OioServerSocketChannelFactory};
39 * one is boss thread and the other is worker thread.
40 *
41 * <h4>Boss threads</h4>
42 * <p>
43 * Each bound {@link ServerSocketChannel} has its own boss thread.
44 * For example, if you opened two server ports such as 80 and 443, you will
45 * have two boss threads. A boss thread accepts incoming connections until
46 * the port is unbound. Once a connection is accepted successfully, the boss
47 * thread passes the accepted {@link Channel} to one of the worker
48 * threads that the {@link OioServerSocketChannelFactory} manages.
49 *
50 * <h4>Worker threads</h4>
51 * <p>
52 * Each connected {@link Channel} has a dedicated worker thread, just like a
53 * traditional blocking I/O thread model.
54 *
55 * <h3>Life cycle of threads and graceful shutdown</h3>
56 * <p>
57 * All threads are acquired from the {@link Executor}s which were specified
58 * when a {@link OioServerSocketChannelFactory} was created. Boss threads are
59 * acquired from the {@code bossExecutor}, and worker threads are acquired from
60 * the {@code workerExecutor}. Therefore, you should make sure the specified
61 * {@link Executor}s are able to lend the sufficient number of threads.
62 * <p>
63 * Both boss and worker threads are acquired lazily, and then released when
64 * there's nothing left to process. All the related resources are also
65 * released when the boss and worker threads are released. Therefore, to shut
66 * down a service gracefully, you should do the following:
67 *
68 * <ol>
69 * <li>unbind all channels created by the factory,
70 * <li>close all child channels accepted by the unbound channels,
71 * (these two steps so far is usually done using {@link ChannelGroup#close()})</li>
72 * <li>call {@link #releaseExternalResources()}.</li>
73 * </ol>
74 *
75 * Please make sure not to shut down the executor until all channels are
76 * closed. Otherwise, you will end up with a {@link RejectedExecutionException}
77 * and the related resources might not be released properly.
78 *
79 * <h3>Limitation</h3>
80 * <p>
81 * A {@link ServerSocketChannel} created by this factory and its child channels
82 * do not support asynchronous operations. Any I/O requests such as
83 * {@code "write"} will be performed in a blocking manner.
84 *
85 * @apiviz.landmark
86 */
87 public class OioServerSocketChannelFactory implements ServerSocketChannelFactory {
88
89 final Executor bossExecutor;
90 private final Executor workerExecutor;
91 private final ChannelSink sink;
92 private boolean shutdownExecutor;
93
94 /**
95 * Create a new {@link OioServerSocketChannelFactory} with a {@link Executors#newCachedThreadPool()}
96 * for the boss and worker executor.
97 *
98 * See {@link #OioServerSocketChannelFactory(Executor, Executor)}
99 */
100 public OioServerSocketChannelFactory() {
101 this(Executors.newCachedThreadPool(), Executors.newCachedThreadPool());
102 shutdownExecutor = true;
103 }
104
105 /**
106 * Creates a new instance.
107 *
108 * @param bossExecutor
109 * the {@link Executor} which will execute the boss threads
110 * @param workerExecutor
111 * the {@link Executor} which will execute the I/O worker threads
112 */
113 public OioServerSocketChannelFactory(
114 Executor bossExecutor, Executor workerExecutor) {
115 if (bossExecutor == null) {
116 throw new NullPointerException("bossExecutor");
117 }
118 if (workerExecutor == null) {
119 throw new NullPointerException("workerExecutor");
120 }
121 this.bossExecutor = bossExecutor;
122 this.workerExecutor = workerExecutor;
123 sink = new OioServerSocketPipelineSink(workerExecutor);
124 }
125
126 public ServerSocketChannel newChannel(ChannelPipeline pipeline) {
127 return new OioServerSocketChannel(this, pipeline, sink);
128 }
129
130 public void shutdown() {
131 if (shutdownExecutor) {
132 ExecutorUtil.terminate(workerExecutor);
133 }
134 }
135
136 public void releaseExternalResources() {
137 shutdown();
138 ExecutorUtil.terminate(workerExecutor);
139 }
140 }