public abstract class

AbstractMultiworkerIOReactor

extends Object
implements IOReactor
java.lang.Object
   ↳ org.apache.http.impl.nio.reactor.AbstractMultiworkerIOReactor
Known Direct Subclasses

Class Overview

Generic implementation of IOReactor that can run multiple BaseIOReactor instance in separate worker threads and distribute newly created I/O session equally across those I/O reactors for a more optimal resource utilization and a 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.

The following parameters can be used to customize the behavior of this class:

Summary

Fields
protected List<ExceptionEvent> auditLog
protected IOReactorExceptionHandler exceptionHandler
protected final boolean interestOpsQueueing
protected final HttpParams params
protected final long selectTimeout
protected final Selector selector
protected IOReactorStatus status
Public Constructors
AbstractMultiworkerIOReactor(int workerCount, ThreadFactory threadFactory, HttpParams params)
Creates an instance of AbstractMultiworkerIOReactor.
Public Methods
void execute(IOEventDispatch eventDispatch)
Activates the main I/O reactor as well as all worker I/O reactors.
synchronized List<ExceptionEvent> getAuditLog()
Returns the audit log containing exceptions thrown by the I/O reactor prior and in the course of the reactor shutdown.
IOReactorStatus getStatus()
Returns the current status of the reactor.
void setExceptionHandler(IOReactorExceptionHandler exceptionHandler)
Sets exception handler for this I/O reactor.
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.
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.
Protected Methods
void addChannel(ChannelEntry entry)
Assigns the given channel entry to one of the worker I/O reactors.
synchronized void addExceptionEvent(Throwable ex, Date timestamp)
Adds the given Throwable object with the given time stamp to the audit log.
void addExceptionEvent(Throwable ex)
Adds the given Throwable object to the audit log.
void awaitShutdown(long timeout)
Blocks for the given period of time in milliseconds awaiting the completion of the reactor shutdown.
abstract void cancelRequests()
Triggered to cancel pending session requests.
void doShutdown()
Activates the shutdown sequence for this reactor.
void prepareSocket(Socket socket)
Prepares the given Socket by resetting some of its properties.
abstract void processEvents(int count)
Triggered to process I/O events registered by the main Selector.
SelectionKey registerChannel(SelectableChannel channel, int ops)
Registers the given channel with the main Selector.
[Expand]
Inherited Methods
From class java.lang.Object
From interface org.apache.http.nio.reactor.IOReactor

Fields

protected List<ExceptionEvent> auditLog

protected IOReactorExceptionHandler exceptionHandler

protected final boolean interestOpsQueueing

protected final HttpParams params

protected final long selectTimeout

protected final Selector selector

protected IOReactorStatus status

Public Constructors

public AbstractMultiworkerIOReactor (int workerCount, ThreadFactory threadFactory, HttpParams params)

Creates an instance of AbstractMultiworkerIOReactor.

Parameters
workerCount number of worker I/O reactors.
threadFactory the factory to create threads. Can be null.
params HTTP parameters.
Throws
IOReactorException in case if a non-recoverable I/O error.

Public Methods

public void execute (IOEventDispatch eventDispatch)

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 given IOEventDispatch 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.

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.

public synchronized List<ExceptionEvent> 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.

public IOReactorStatus getStatus ()

Returns the current status of the reactor.

Returns
  • reactor status.

public void setExceptionHandler (IOReactorExceptionHandler exceptionHandler)

Sets exception handler for this I/O reactor.

Parameters
exceptionHandler the exception handler.

public 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.

Parameters
waitMs wait time in milliseconds.
Throws
IOException

public 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. It is up to individual implementations to decide for how long this method can remain blocked.

Throws
IOException

Protected Methods

protected void addChannel (ChannelEntry entry)

Assigns the given channel entry to one of the worker I/O reactors.

Parameters
entry the channel entry.

protected synchronized void addExceptionEvent (Throwable ex, Date timestamp)

Adds the given Throwable 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 be null in which case the current date / time will be used.

protected void addExceptionEvent (Throwable ex)

Adds the given Throwable object to the audit log.

Parameters
ex the exception thrown by the I/O reactor.

protected void awaitShutdown (long timeout)

Blocks for the given period of time in milliseconds awaiting the completion of the reactor shutdown. If the value of timeout is set to 0 this method blocks indefinitely.

Parameters
timeout the maximum wait time.
Throws
InterruptedException if interrupted.

protected abstract void 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.

protected void 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.

protected void prepareSocket (Socket socket)

Prepares the given Socket by resetting some of its properties.

Parameters
socket the socket
Throws
IOException in case of an I/O error.

protected abstract void processEvents (int count)

Triggered to process I/O events registered by the main Selector.

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.

protected SelectionKey registerChannel (SelectableChannel channel, int ops)

Registers the given channel with the main Selector.

Parameters
channel the channel.
ops interest ops.
Returns
  • selection key.
Throws
ClosedChannelException if the channel has been already closed.