Core Configuration
The primary points of configuration of the core framework are that of the Transport instances and their associated thread pools. The ability to configure both entities is possible via the NIOTransportBuilder.
Transport Configuration
Just as there are concrete NIOTransport implementations for TCP and UDP, so too are there two concrete NIOTransportBuilder implementations. Each NIOTransportBuilder implementation exposes configurable features unique to each transport. The following describes configuration properties common to all NIOTransports and then describes the properties for the TCP and UDP NIOTransport implementations.
| workerThreadPoolConfig | This property exposes a ThreadPoolConfig instance that allows configuration of the worker thread pool used by the transport that will be constructed by this builder. Note: depending on the IOStrategy being used, this value may be null. |
| selectorThreadPoolConfig | This propery exposes a ThreadPoolConfig instance that allows configuration of the selector/kernel thread pool used by the transport that will be constructed by this builder. |
| IOStrategy | Sets the IOStrategy that will be used by this transport. Note that changing this value before the transport has been started may have an impact on the return value of the workerThreadPoolConfig property. If no value is explicitly set, the WorkerThreadIOStrategy will be employed. See the section on IOStrategies for specifics on each concrete IOStrategy included with Grizzly 2.3 |
| memoryManager | Sets the MemoryManager to be used by this transport. If no value is explicitly set, the MemoryManager used will be the NIOTransportBuilder.DEFAULT_MEMORY_MANAGER. See the section on Memory Management for specifics on the MemoryManager system. |
| selectorHandler | Sets the SelectorHandler to be used by this transport. If no value is explicitly set, the SelectorHandler used wil be the NIOTransportBuilder.DEFAULT_SELECTOR_HANDLER. See the section on Transports and Connections for specifics on the SelectorHandler. |
| selectionKeyHandler | Sets the SelectionKeyHandler to be used by this transport. If no value is explicitly set, the SelectionKeyHandler used will be the NIOTransportBuilder.DEFAULT_SELECTION_KEY_HANDLER. See the section on Transports and Connections for specifics on the SelectionKeyHandler. |
| attributeBuilder | Sets the AttributeBuilder to be used by this transport. If no value is explicitly set, the AttributeBuilder used will be the NIOTransportBuilder.DEFAULT_ATTRIBUTE_BUILDER. |
| NIOChannelDistributor | Sets the NIOChannelDistributor used by this transport. See the section on Transports and Connections for specifics on the NIOChannelDistributor. |
| processor | Sets the Processor used by this transport. |
| processorSelector | Sets the ProcessorSelector used by this transport. |
| readBufferSize | Sets the size of the Buffer that will be allocated, per-connection, to read incoming data. |
| writeBuffersSize | Sets the size of the Buffer that will be applicated, per-connection, to write outgoing data. |
| clientSocketSoTimeout | Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds (client mode). |
| connectionTimeout | Time in milliseconds for how long establishing a connection can take before the operation times out. |
| keepAlive | Enable/disable SO_KEEPALIVE. |
| linger | Enable/disable SO_LINGER with the specified linger time in seconds. The maximum timeout value is platform specific. The setting only affects socket close. |
| reuseAddress | Enable/disable the SO_REUSEADDR socket option. When a TCP connection is closed the connection may remain in a timeout state for a period of time after the connection is closed (typically known as the TIME_WAIT state or 2MSL wait state). For applications using a well known socket address or port it may not be possible to bind a socket to the required SocketAddress if there is a connection in the timeout state involving the socket address or port. |
| serverConnectionBacklog | Specifies the maximum pending connection queue length. |
| serverSocketSoTimeout | Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds (server mode). |
| tcpNoDelay | Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm). |
| temporarySelectorIO | Allows the specification of a TemporarySelectorIO instance to aid in the simulation of blocking IO. |
| optimizedForMultiplexing | Controls the behavior of writing to a connection. If enabled, then all writes regardless if the current thread can write directly to the connection or not, will be passed to the async write queue. When the write actually occurs, the transport will attempt to write as much content from the write queue as possible. This option is disabled by default. |
| maxAsyncWriteQueueSizeInBytes | Specifies the size, in bytes, of the async write queue on a per-connection basis. If not specified, the value will be configured to be four times the size of the system's socket write buffer size. Setting this value to -1 will allow the queue to be unbounded. |
| connectionTimeout | Time in milliseconds for how long establishing a connection can take before the operation times out. |
| reuseAddress | Enable/disable the SO_REUSEADDR socket option. When a TCP connection is closed the connection may remain in a timeout state for a period of time after the connection is closed (typically known as the TIME_WAIT state or 2MSL wait state). For applications using a well known socket address or port it may not be possible to bind a socket to the required SocketAddress if there is a connection in the timeout state involving the socket address or port. |
| temporarySelectorIO | Allows the specification of a TemporarySelectorIO instance to aid in the simulation of blocking IO. |
Thread Pool Configuration
Grizzly’s thread pool configuration is managed by the ThreadPoolConfig object:
| queue | The task Queue implementation to be used. |
| queueLimit | The maximum number of pending tasks that may be queued. |
| threadFactory | The ThreadFactory that the pool will use to create new Threads. |
| poolName | The name of this thread pool. |
| priority | The priority to be assigned to each thread. This will override any priority assigned by the specified ThreadFactory. |
| corePoolSize | The initial number of threads that will be present with the thread pool is created. |
| maxPoolSize | The maximum number threads that may be maintained by this thread pool. |
| keepAliveTime | The maximum time a thread may stay idle and wait for a new task to execute before it will be released. Custom time units can be used. |
| transactionTimeout | The maximum time a thread may be allowed to run a single task before interrupt signal will be sent. Custom time units can be used. |
The thread pool configuration is fairly straight forward. However, it should be noted that Grizzly, internally, has several thread pool implementations: SyncThreadPool, FixedThreadPool, and QueueLimitedThreadPool. Which implementation is chosen is based on the configuration. The following sections describe each of the thread pool implementations.
FixedThreadPool
This pool will be selected when the queueLimit property is less than zero, and the max and core pool sizes are the same. The FixedThreadPool has no synchronization when executing tasks, so it offers better performance.
QueueLimitedThreadPool
This pool will be selected when the queueLimit property is greater than zero, and the max and core pool sizes are the same. The QueueLimitedThreadPool is an extension of the FixedThreadPool, so if offers the same benefits of the FixedThreadPool without having an unbounded task queue.
SyncThreadPool
This pool will be selected when none of the criteria for the other thread pools apply. This thread pool does have synchronization to have precise control over the decision of thread creation.
Examples
Here are some examples of using the TCPNIOTransportBuilder to configure the Transport and/or thread pool.
final TCPNIOTransportBuilder builder = TCPNIOTransportBuilder.newInstance(); final TCPNIOTransport transport = builder.build();
Creates a new TCPNIOTransport using all default configuration values.
final TCPNIOTransportBuilder builder = TCPNIOTransportBuilder.newInstance(); final TCPNIOTransport transport = builder.setIOStrategy(SameThreadIOStrategy.getInstance()).setTcpNoDelay(true).build();
Creates a new TCPNIOTransport instance using the SameThreadIOStrategy, and tcp-no-delay set to true. Note that configuration calls can be chained.
final TCPNIOTransportBuilder builder = TCPNIOTransportBuilder.newInstance(); final ThreadPoolConfig config = builder.getWorkerThreadPoolConfig(); config.setCorePoolSize(5).setMaxPoolSize(5).setQueueLimit(-1); final TCPNIOTransport transport = builder.build();
This example will configure the TCPNIOTransport to use the FixedThreadPool implementation due to the fact that there is no queue limit and the core and max pool sizes are the same.