seda.sandStorm.lib.aSocket.nbio
Class SelectSource

java.lang.Object
  extended by seda.sandStorm.lib.aSocket.nbio.SelectSource
All Implemented Interfaces:
SourceIF, SelectSourceIF

public class SelectSource
extends java.lang.Object
implements SelectSourceIF

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

SelectSource can 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'.

Author:
Matt Welsh

Constructor Summary
SelectSource()
          Create a new empty SelectSource.
SelectSource(boolean do_balance)
          Create a new empty SelectSource.
 
Method Summary
 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 selobj)
          Deregister a SelectItem with this SelectSource.
 java.lang.Object getSelectSet()
           
 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 selobj)
          Register a SelectItem with the SelectSource.
 java.lang.Object register(java.lang.Object sc_obj, int ops)
           
 int size()
          Return the number of elements waiting in the queue (that is, which don't require a SelectSet poll operation to retrieve).
 void update()
          Must be called if the 'events' mask of any SelectItem registered with this SelectSource changes.
 void update(java.lang.Object selobj)
          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, toString, wait, wait, wait
 

Constructor Detail

SelectSource

public SelectSource()
Create a new empty SelectSource. This SelectSource will perform event balancing.


SelectSource

public SelectSource(boolean do_balance)
Create a new empty SelectSource.

Parameters:
do_balance - Indicates whether this SelectSource should perform event balancing.
Method Detail

getSelectSet

public java.lang.Object getSelectSet()

register

public void register(java.lang.Object selobj)
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

register

public java.lang.Object register(java.lang.Object sc_obj,
                                 int ops)
Specified by:
register in interface SelectSourceIF

deregister

public void deregister(java.lang.Object selobj)
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 selobj)
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