More information: http://www.cs.berkeley.edu/~mdw/proj/seda/

mdw.sandStorm.core
Class SelectSource

java.lang.Object
  |
  +--mdw.sandStorm.core.SelectSource
All Implemented Interfaces:
SourceIF

public class SelectSource
extends java.lang.Object
implements SourceIF

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(SelectItem sel)
          Deregister a SelectItem with this SelectSource.
 SelectSet 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(SelectItem sel)
          Register a SelectItem with the SelectSource.
 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(SelectItem 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, 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 SelectSet getSelectSet()

register

public void register(SelectItem sel)
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.

See Also:
Selectable

deregister

public void deregister(SelectItem sel)
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.

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.

update

public void update(SelectItem 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.

numRegistered

public int numRegistered()
Return the number of SelectItems registered with the SelectSource.

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.

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

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
Following copied from interface: mdw.sandStorm.api.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
Following copied from interface: mdw.sandStorm.api.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
Following copied from interface: mdw.sandStorm.api.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
Following copied from interface: mdw.sandStorm.api.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

More information: http://www.cs.berkeley.edu/~mdw/proj/seda/