Package org.omegazero.net.nio.util

Class SelectorHandler

java.lang.Object

org.omegazero.net.nio.util.SelectorHandler

Direct Known Subclasses:

ConnectionSelectorHandler

public abstract class SelectorHandler
extends Object

Wraps a java.nio Selector.

A thread must call initSelector() followed by runSelectorLoop() to start selecting keys, which can then be handled in the abstract method handleSelectedKey(SelectionKey). Additional keys may be added safely while running using registerChannel(SelectableChannel, int, Object).

This class defines the following system properties:

• org.omegazero.net.nioselector.rebuildThreshold (integer, default 1024) - The maximum number of times the selection operation may return in a row without having any keys selected. If this threshold is exceeded, the selector will be rebuilt. This feature exists to mitigate the selector/epoll immediate return bug, which may exist on older JVM distributions
• org.omegazero.net.nioselector.maxRebuilds (integer, default 8) - The maximum number of times the selector may be rebuilt in a row (see above). If this threshold is exceeded, the selector loop will exit with an IOException

API Note:

Before version 2.1.0, this class was in package org.omegazero.net.common.

Constructor Summary

Constructors

Constructor	Description
SelectorHandler()

Method Summary

Modifier and Type	Method	Description
protected void	closeSelector()	Stops the selector loop, closes all channels registered with this selector and closes the Selector instance.
protected abstract void	handleSelectedKey(SelectionKey key)	Called when a key was selected in a select call in the runSelectorLoop() method.
protected void	initSelector()	Initializes the Selector and sets this instance as running. After this method has been called successfully, invalid reference SelectorHandler#selectorLoop() should be called to start performing IO operations.
boolean	isRunning()	Returns true while this SelectorHandler is running; this is the case in the time between calls to initSelector() and closeSelector().
protected void	loopIteration()	Called every loop iteration in runSelectorLoop(), which is every time Selector.select() returns, either because a SelectionKey was selected or the selector was woken up for any other reason (for example after a call to selectorWakeup()). This method does nothing by default.
protected SelectionKey	registerChannel(SelectableChannel channel, int ops)	See registerChannel(SelectableChannel, int, Object). An invocation of this method of the form
protected SelectionKey	registerChannel(SelectableChannel channel, int ops, Object attachment)	Registers the given channel with this SelectorHandler's Selector.
protected void	runSelectorLoop()	Runs the loop that continuously selects channels using the Selector. Will not return until closeSelector() is called.
protected Set<SelectionKey>	selectorKeys()	Returns the set of registered SelectionKeys.
protected void	selectorWakeup()	Wakes up the selector, causing a selection loop iteration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SelectorHandler

public SelectorHandler()

Method Details

handleSelectedKey

protected abstract void handleSelectedKey(SelectionKey key)
                                   throws IOException

Called when a key was selected in a select call in the runSelectorLoop() method.

Parameters:

key - The selected key

Throws:

IOException - If an IO error occurs

loopIteration

protected void loopIteration()
                      throws IOException

Called every loop iteration in runSelectorLoop(), which is every time Selector.select() returns, either because a SelectionKey was selected or the selector was woken up for any other reason (for example after a call to selectorWakeup()).

This method does nothing by default. Subclasses may override this method to perform additional required operations.

Throws:

IOException - If an IO error occurs

initSelector

protected void initSelector()
                     throws IOException

Initializes the Selector and sets this instance as running.

After this method has been called successfully,

invalid reference

SelectorHandler#selectorLoop()

should be called to start performing IO operations.

Throws:

IOException

closeSelector

protected void closeSelector()
                      throws IOException

Stops the selector loop, closes all channels registered with this selector and closes the Selector instance.

Throws:

IOException

registerChannel

protected SelectionKey registerChannel(SelectableChannel channel,
 int ops)
                                throws IOException

See registerChannel(SelectableChannel, int, Object).

An invocation of this method of the form

 registerChannel(channel, ops)
 

is exactly the same as the invocation

 registerChannel(channel, ops, null)
 

Parameters:

channel - The channel to be registered

ops - The interest set for the resulting key

Returns:

The resulting SelectionKey

Throws:

IOException

registerChannel

protected SelectionKey registerChannel(SelectableChannel channel,
 int ops,
 Object attachment)
                                throws IOException

Registers the given channel with this SelectorHandler's Selector. This function is safe to be called while another thread is in a selection operation in

invalid reference

#selectorLoop()

, in which case the selection operation will be interrupted to allow the new channel to be registered.

Parameters:

channel - The channel to be registered

ops - The interest set for the resulting key

attachment - The attachment for the resulting key

Returns:

The resulting SelectionKey

Throws:

IOException

See Also:

• registerChannel(SelectableChannel, int)
• SelectableChannel.register(Selector, int, Object)

selectorWakeup

protected void selectorWakeup()

Wakes up the selector, causing a selection loop iteration.

See Also:

• Selector.wakeup()

selectorKeys

protected Set<SelectionKey> selectorKeys()

Returns the set of registered SelectionKeys. See Selector.keys().

Returns:

The set of selection keys

runSelectorLoop

protected void runSelectorLoop()
                        throws IOException

Runs the loop that continuously selects channels using the Selector.

Will not return until closeSelector() is called. If initSelector() was never called, this method returns immediately.

Throws:

IOException - If an IO error occurs, or if handleSelectedKey(SelectionKey) or loopIteration() throw an IOException

isRunning

public boolean isRunning()

Returns true while this SelectorHandler is running; this is the case in the time between calls to initSelector() and closeSelector().

Returns:

true while this SelectorHandler is running