seda.sandStorm.lib.aSocket.nio
Class NIOSelectSource

java.lang.Object
  seda.sandStorm.lib.aSocket.nio.NIOSelectSource

All Implemented Interfaces:

SourceIF, SelectSourceIF

public class NIOSelectSource
extends java.lang.Object
implements SelectSourceIF

A NIOSelectSource is an implementation of SourceIF which pulls events from the operating system via the NIO Selector interface. This can be thought of as a 'shim' which turns a Selector into a SourceIF.

NIOSelectSource also "balances" the set of events returned on subsequent calls to dequeue, in order to avoid biasing the servicing of underlying O/S events to a particular order. This feature can be disabled by creating a SelectSource with the boolean flag 'do_balance'.

Important note: This class is not threadsafe with respect to multiple threads calling dequeue() or blocking_dequeue() at once. Clients must synchronize their access to this class.

Field Summary

private int[]	balancer_seq
private int	balancer_seq_off
private int	BALANCER_SEQUENCE_SIZE
private java.lang.Object	blocker
private static boolean	DEBUG
private boolean	do_balance
private java.lang.String	name
private java.nio.channels.SelectionKey[]	ready
private int	ready_offset
private int	ready_size
private java.nio.channels.Selector	selector

Constructor Summary

NIOSelectSource()
Create a new empty SelectSource.

NIOSelectSource(boolean do_balance)
Create a new empty SelectSource.

Method Summary

private void	balance(java.nio.channels.SelectionKey[] selarr)
QueueElementIF[]	blocking_dequeue_all(int timeout_millis) Dequeue a set of elements from the SelectSource.
QueueElementIF	blocking_dequeue(int timeout_millis) Dequeue the next element from the SelectSource.
QueueElementIF[]	blocking_dequeue(int timeout_millis, int num) Dequeue a set of elements from the SelectSource.
QueueElementIF[]	dequeue_all() Dequeues all elements which are ready from the SelectSource.
QueueElementIF	dequeue() Dequeues the next element from the SelectSource without blocking.
QueueElementIF[]	dequeue(int num) Dequeues at most num elements which are ready from the SelectSource.
void	deregister(java.lang.Object selkey_obj) Deregister a SelectItem with this SelectSource.
private void	doPoll(int timeout)
java.nio.channels.Selector	getSelector()
private void	initBalancer()
int	numActive() Return the number of active SelectItems registered with the SelectSource.
int	numRegistered() Return the number of SelectItems registered with the SelectSource.
void	register(java.lang.Object sel) Register a SelectItem with the SelectSource.
java.lang.Object	register(java.lang.Object nio_sc_obj, int ops) Register a SelectItem with the SelectSource.
(package private) void	setName(java.lang.String thename)
int	size() Return the number of elements waiting in the queue (that is, which don't require a SelectSet poll operation to retrieve).
java.lang.String	toString()
void	update() Must be called if the 'events' mask of any SelectItem registered with this SelectSource changes.
void	update(java.lang.Object sel) Must be called if the 'events' mask of this SelectItem (which must be registered with this SelectSource) changes.

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

private static final boolean DEBUG

See Also:

Constant Field Values

selector

private java.nio.channels.Selector selector

ready

private java.nio.channels.SelectionKey[] ready

ready_offset

private int ready_offset

ready_size

private int ready_size

do_balance

private boolean do_balance

BALANCER_SEQUENCE_SIZE

private final int BALANCER_SEQUENCE_SIZE

See Also:

Constant Field Values

balancer_seq

private int[] balancer_seq

balancer_seq_off

private int balancer_seq_off

blocker

private java.lang.Object blocker

name

private java.lang.String name

Constructor Detail

NIOSelectSource

public NIOSelectSource()

Create a new empty SelectSource. This SelectSource will perform event balancing.

NIOSelectSource

public NIOSelectSource(boolean do_balance)

Create a new empty SelectSource.

Parameters:

do_balance - Indicates whether this SelectSource should perform event balancing.

Method Detail

getSelector

public java.nio.channels.Selector getSelector()

register

public java.lang.Object register(java.lang.Object nio_sc_obj,
                                 int ops)

Register a SelectItem with the SelectSource. The SelectItem should generally correspond to a Selectable along with a set of event flags that we wish this SelectSource to test for.

The user is allowed to modify the event flags in the SelectItem directly (say, to cause the SelectSource ignore a given SelectItem for the purposes of future calls to one of the dequeue methods). However, modifying the event flags may not be synchronous with calls to dequeue - generally because SelectSource maintains a cache of recently-received events.

Specified by:

register in interface SelectSourceIF

register

public void register(java.lang.Object sel)

Description copied from interface: SelectSourceIF

Register a SelectItem with the SelectSource. The SelectItem should generally correspond to a Selectable along with a set of event flags that we wish this SelectSource to test for.

The user is allowed to modify the event flags in the SelectItem directly (say, to cause the SelectSource ignore a given SelectItem for the purposes of future calls to one of the dequeue methods). However, modifying the event flags may not be synchronous with calls to dequeue - generally because SelectSource maintains a cache of recently-received events.

Specified by:

register in interface SelectSourceIF

See Also:

Selectable

deregister

public void deregister(java.lang.Object selkey_obj)

Deregister a SelectItem with this SelectSource. Note that after calling deregister, subsequent calls to dequeue may in fact return this SelectItem as a result. This is because the SelectQueue internally caches results.

Specified by:

deregister in interface SelectSourceIF

update

public void update()

Must be called if the 'events' mask of any SelectItem registered with this SelectSource changes. Pushes event mask changes down to the underlying event-dispatch mechanism.

Specified by:

update in interface SelectSourceIF

update

public void update(java.lang.Object sel)

Must be called if the 'events' mask of this SelectItem (which must be registered with this SelectSource) changes. Pushes event mask changes down to the underlying event-dispatch mechanism.

Specified by:

update in interface SelectSourceIF

numRegistered

public int numRegistered()

Return the number of SelectItems registered with the SelectSource.

Specified by:

numRegistered in interface SelectSourceIF

numActive

public int numActive()

Return the number of active SelectItems registered with the SelectSource. An active SelectItem is one defined as having a non-zero events interest mask.

Specified by:

numActive in interface SelectSourceIF

size

public int size()

Return the number of elements waiting in the queue (that is, which don't require a SelectSet poll operation to retrieve).

Specified by:

size in interface SourceIF

Specified by:

size in interface SelectSourceIF

dequeue

public QueueElementIF dequeue()

Dequeues the next element from the SelectSource without blocking. Returns null if no entries available.

Specified by:

dequeue in interface SourceIF

Returns:

the next QueueElementIF on the queue

dequeue_all

public QueueElementIF[] dequeue_all()

Dequeues all elements which are ready from the SelectSource. Returns null if no entries available.

Specified by:

dequeue_all in interface SourceIF

Returns:

all pending QueueElementIFs on the queue

dequeue

public QueueElementIF[] dequeue(int num)

Dequeues at most num elements which are ready from the SelectSource. Returns null if no entries available.

Specified by:

dequeue in interface SourceIF

Returns:

At most num QueueElementIFs on the queue

blocking_dequeue

public QueueElementIF blocking_dequeue(int timeout_millis)

Dequeue the next element from the SelectSource. Blocks up to timeout_millis milliseconds; returns null if no entries available after that time. A timeout of -1 blocks forever.

Specified by:

blocking_dequeue in interface SourceIF

blocking_dequeue_all

public QueueElementIF[] blocking_dequeue_all(int timeout_millis)

Dequeue a set of elements from the SelectSource. Blocks up to timeout_millis milliseconds; returns null if no entries available after that time. A timeout of -1 blocks forever.

Specified by:

blocking_dequeue_all in interface SourceIF

Parameters:

timeout_millis - if timeout_millis is 0, this method will be non-blocking and will return right away, whether or not any elements are pending on the queue. If timeout_millis is -1, this method blocks forever until something is available. If timeout_millis is positive, this method will wait about that number of milliseconds before returning, but possibly a little more.

Returns:

an array of QueueElementIF's. This array will be null if no elements were pending.

blocking_dequeue

public QueueElementIF[] blocking_dequeue(int timeout_millis,
                                         int num)

Dequeue a set of elements from the SelectSource. Blocks up to timeout_millis milliseconds; returns null if no entries available after that time. A timeout of -1 blocks forever.

Specified by:

blocking_dequeue in interface SourceIF

doPoll

private void doPoll(int timeout)

balance

private void balance(java.nio.channels.SelectionKey[] selarr)

initBalancer

private void initBalancer()

setName

void setName(java.lang.String thename)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object