Class AbstractMultiworkerIOReactor
- All Implemented Interfaces:
IOReactor
- Direct Known Subclasses:
DefaultConnectingIOReactor
,DefaultListeningIOReactor
IOReactor
that can run multiple
BaseIOReactor
instances in separate worker threads and distribute
newly created I/O sessions equally across those I/O reactors for more
optimal resource utilization and better I/O performance. Usually it is
recommended to have one worker I/O reactor per physical CPU core.
Important note about exception handling
Protocol specific exceptions as well as those I/O exceptions thrown in the course of interaction with the session's channel are to be expected are to be dealt with by specific protocol handlers. These exceptions may result in termination of an individual session but should not affect the I/O reactor and all other active sessions. There are situations, however, when the I/O reactor itself encounters an internal problem such as an I/O exception in the underlying NIO classes or an unhandled runtime exception. Those types of exceptions are usually fatal and will cause the I/O reactor to shut down automatically.
There is a possibility to override this behavior and prevent I/O reactors
from shutting down automatically in case of a runtime exception or an I/O
exception in internal classes. This can be accomplished by providing a custom
implementation of the IOReactorExceptionHandler
interface.
If an I/O reactor is unable to automatically recover from an I/O or a runtime
exception it will enter the shutdown mode. First off, it cancel all pending
new session requests. Then it will attempt to close all active I/O sessions
gracefully giving them some time to flush pending output data and terminate
cleanly. Lastly, it will forcibly shut down those I/O sessions that still
remain active after the grace period. This is a fairly complex process, where
many things can fail at the same time and many different exceptions can be
thrown in the course of the shutdown process. The I/O reactor will record all
exceptions thrown during the shutdown process, including the original one
that actually caused the shutdown in the first place, in an audit log. One
can obtain the audit log using getAuditLog()
, examine exceptions
thrown by the I/O reactor prior and in the course of the reactor shutdown
and decide whether it is safe to restart the I/O reactor.
- Since:
- 4.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static class
(package private) static class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected List
<ExceptionEvent> protected final IOReactorConfig
private int
private final BaseIOReactor[]
protected IOReactorExceptionHandler
protected final boolean
protected final HttpParams
Deprecated.(4.2)protected final Selector
protected final long
protected IOReactorStatus
private final Object
private final ThreadFactory
private final Thread[]
private final int
private final AbstractMultiworkerIOReactor.Worker[]
-
Constructor Summary
ConstructorsConstructorDescriptionCreates an instance of AbstractMultiworkerIOReactor with default configuration.AbstractMultiworkerIOReactor
(int workerCount, ThreadFactory threadFactory, HttpParams params) Deprecated.AbstractMultiworkerIOReactor
(IOReactorConfig config, ThreadFactory threadFactory) Creates an instance of AbstractMultiworkerIOReactor with the given configuration. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
addChannel
(ChannelEntry entry) Assigns the given channel entry to one of the worker I/O reactors.protected void
Adds the givenThrowable
object to the audit log.protected void
addExceptionEvent
(Throwable ex, Date timestamp) Adds the givenThrowable
object with the given time stamp to the audit log.protected void
awaitShutdown
(long timeout) Blocks for the given period of time in milliseconds awaiting the completion of the reactor shutdown.protected abstract void
Triggered to cancel pending session requests.(package private) static void
closeChannel
(Channel channel) (package private) static IOReactorConfig
convert
(int workerCount, HttpParams params) Deprecated.Do not use.protected void
Activates the shutdown sequence for this reactor.void
execute
(IOEventDispatch eventDispatch) Activates the main I/O reactor as well as all worker I/O reactors.Returns the audit log containing exceptions thrown by the I/O reactor prior and in the course of the reactor shutdown.Returns the current status of the reactor.protected void
prepareSocket
(Socket socket) Prepares the givenSocket
by resetting some of its properties.protected abstract void
processEvents
(int count) Triggered to process I/O events registered by the mainSelector
.protected SelectionKey
registerChannel
(SelectableChannel channel, int ops) Registers the given channel with the mainSelector
.void
setExceptionHandler
(IOReactorExceptionHandler exceptionHandler) Sets exception handler for this I/O reactor.void
shutdown()
Initiates shutdown of the reactor and blocks for a default period of time waiting for the reactor to terminate all active connections, to shut down itself and to release system resources it currently holds.void
shutdown
(long waitMs) Initiates shutdown of the reactor and blocks approximately for the given period of time in milliseconds waiting for the reactor to terminate all active connections, to shut down itself and to release system resources it currently holds.
-
Field Details
-
status
-
params
Deprecated.(4.2) -
config
-
selector
-
selectTimeout
protected final long selectTimeout -
interestOpsQueueing
protected final boolean interestOpsQueueing -
workerCount
private final int workerCount -
threadFactory
-
dispatchers
-
workers
-
threads
-
statusLock
-
exceptionHandler
-
auditLog
-
currentWorker
private int currentWorker
-
-
Constructor Details
-
AbstractMultiworkerIOReactor
public AbstractMultiworkerIOReactor(IOReactorConfig config, ThreadFactory threadFactory) throws IOReactorException Creates an instance of AbstractMultiworkerIOReactor with the given configuration.- Parameters:
config
- I/O reactor configuration.threadFactory
- the factory to create threads. Can benull
.- Throws:
IOReactorException
- in case if a non-recoverable I/O error.- Since:
- 4.2
-
AbstractMultiworkerIOReactor
Creates an instance of AbstractMultiworkerIOReactor with default configuration.- Throws:
IOReactorException
- in case if a non-recoverable I/O error.- Since:
- 4.2
-
AbstractMultiworkerIOReactor
@Deprecated public AbstractMultiworkerIOReactor(int workerCount, ThreadFactory threadFactory, HttpParams params) throws IOReactorException Deprecated.Creates an instance of AbstractMultiworkerIOReactor.- Parameters:
workerCount
- number of worker I/O reactors.threadFactory
- the factory to create threads. Can benull
.params
- HTTP parameters.- Throws:
IOReactorException
- in case if a non-recoverable I/O error.
-
-
Method Details
-
convert
Deprecated.Do not use. -
getStatus
Description copied from interface:IOReactor
Returns the current status of the reactor. -
getAuditLog
Returns the audit log containing exceptions thrown by the I/O reactor prior and in the course of the reactor shutdown.- Returns:
- audit log.
-
addExceptionEvent
Adds the givenThrowable
object with the given time stamp to the audit log.- Parameters:
ex
- the exception thrown by the I/O reactor.timestamp
- the time stamp of the exception. Can benull
in which case the current date / time will be used.
-
addExceptionEvent
Adds the givenThrowable
object to the audit log.- Parameters:
ex
- the exception thrown by the I/O reactor.
-
setExceptionHandler
Sets exception handler for this I/O reactor.- Parameters:
exceptionHandler
- the exception handler.
-
processEvents
Triggered to process I/O events registered by the mainSelector
.Super-classes can implement this method to react to the event.
- Parameters:
count
- event count.- Throws:
IOReactorException
- in case if a non-recoverable I/O error.
-
cancelRequests
Triggered to cancel pending session requests.Super-classes can implement this method to react to the event.
- Throws:
IOReactorException
- in case if a non-recoverable I/O error.
-
execute
public void execute(IOEventDispatch eventDispatch) throws InterruptedIOException, IOReactorException Activates the main I/O reactor as well as all worker I/O reactors. The I/O main reactor will start reacting to I/O events and triggering notification methods. The worker I/O reactor in their turn will start reacting to I/O events and dispatch I/O event notifications to the givenIOEventDispatch
interface.This method will enter the infinite I/O select loop on the
Selector
instance associated with this I/O reactor and used to manage creation of new I/O channels. Once a new I/O channel has been created the processing of I/O events on that channel will be delegated to one of the worker I/O reactors.The method will remain blocked unto the I/O reactor is shut down or the execution thread is interrupted.
- Specified by:
execute
in interfaceIOReactor
- Parameters:
eventDispatch
- the I/O event dispatch.- Throws:
InterruptedIOException
- if the dispatch thread is interrupted.IOReactorException
- in case if a non-recoverable I/O error.- See Also:
-
doShutdown
Activates the shutdown sequence for this reactor. This method will cancel all pending session requests, close out all active I/O channels, make an attempt to terminate all worker I/O reactors gracefully, and finally force-terminate those I/O reactors that failed to terminate after the specified grace period.- Throws:
InterruptedIOException
- if the shutdown sequence has been interrupted.
-
addChannel
Assigns the given channel entry to one of the worker I/O reactors.- Parameters:
entry
- the channel entry.
-
registerChannel
protected SelectionKey registerChannel(SelectableChannel channel, int ops) throws ClosedChannelException Registers the given channel with the mainSelector
.- Parameters:
channel
- the channel.ops
- interest ops.- Returns:
- selection key.
- Throws:
ClosedChannelException
- if the channel has been already closed.
-
prepareSocket
Prepares the givenSocket
by resetting some of its properties.- Parameters:
socket
- the socket- Throws:
IOException
- in case of an I/O error.
-
awaitShutdown
Blocks for the given period of time in milliseconds awaiting the completion of the reactor shutdown. If the value oftimeout
is set to0
this method blocks indefinitely.- Parameters:
timeout
- the maximum wait time.- Throws:
InterruptedException
- if interrupted.
-
shutdown
Description copied from interface:IOReactor
Initiates shutdown of the reactor and blocks for a default period of time waiting for the reactor to terminate all active connections, to shut down itself and to release system resources it currently holds. It is up to individual implementations to decide for how long this method can remain blocked.- Specified by:
shutdown
in interfaceIOReactor
- Throws:
IOException
- in case of an I/O error.
-
shutdown
Description copied from interface:IOReactor
Initiates shutdown of the reactor and blocks approximately for the given period of time in milliseconds waiting for the reactor to terminate all active connections, to shut down itself and to release system resources it currently holds.- Specified by:
shutdown
in interfaceIOReactor
- Parameters:
waitMs
- wait time in milliseconds.- Throws:
IOException
- in case of an I/O error.
-
closeChannel
-