001: /*
002: * Copyright (c) 2001 by Matt Welsh and The Regents of the University of
003: * California. All rights reserved.
004: *
005: * Permission to use, copy, modify, and distribute this software and its
006: * documentation for any purpose, without fee, and without written agreement is
007: * hereby granted, provided that the above copyright notice and the following
008: * two paragraphs appear in all copies of this software.
009: *
010: * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
011: * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
012: * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
013: * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
014: *
015: * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
016: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
017: * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
018: * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
019: * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
020: *
021: * Author: Matt Welsh <mdw@cs.berkeley.edu>
022: *
023: */
024:
025: package seda.sandStorm.lib.aSocket;
026:
027: import seda.sandStorm.api.*;
028:
029: import java.net.*;
030: import java.io.*;
031: import java.util.*;
032:
033: /**
034: * A SelectSource is an implementation of SourceIF which pulls events from
035: * the operating system via the NBIO SelectSet interface. This can be thought
036: * of as a 'shim' which turns a SelectSet into a SourceIF.
037: *
038: * <p>SelectSource can also "balances" the set of events returned on
039: * subsequent calls to dequeue, in order to avoid biasing the servicing of
040: * underlying O/S events to a particular order. This feature can be
041: * disabled by creating a SelectSource with the boolean flag 'do_balance'.
042: *
043: * @author Matt Welsh
044: */
045: public interface SelectSourceIF extends SourceIF {
046:
047: /**
048: * Register a SelectItem with the SelectSource. The SelectItem should
049: * generally correspond to a Selectable along with a set of event flags
050: * that we wish this SelectSource to test for.
051: *
052: * <p>The user is allowed to modify the event flags in the SelectItem
053: * directly (say, to cause the SelectSource ignore a given SelectItem for
054: * the purposes of future calls to one of the dequeue methods). However,
055: * modifying the event flags may not be synchronous with calls to dequeue -
056: * generally because SelectSource maintains a cache of recently-received
057: * events.
058: *
059: * @see seda.nbio.Selectable
060: */
061: // SelectItem sel
062: public void register(Object sel);
063:
064: // SelectableChannel sc
065: public Object register(Object sc, int ops);
066:
067: /**
068: * Deregister a SelectItem with this SelectSource.
069: * Note that after calling deregister, subsequent calls to dequeue
070: * may in fact return this SelectItem as a result. This is because
071: * the SelectQueue internally caches results.
072: */
073: public void deregister(Object sel);
074:
075: /**
076: * Must be called if the 'events' mask of any SelectItem registered
077: * with this SelectSource changes. Pushes event mask changes down to
078: * the underlying event-dispatch mechanism.
079: */
080: public void update();
081:
082: /**
083: * Must be called if the 'events' mask of this SelectItem (which
084: * must be registered with this SelectSource) changes. Pushes
085: * event mask changes down to the underlying event-dispatch mechanism.
086: */
087: public void update(Object sel);
088:
089: /**
090: * Return the number of SelectItems registered with the SelectSource.
091: */
092: public int numRegistered();
093:
094: /**
095: * Return the number of active SelectItems registered with the SelectSource.
096: * An active SelectItem is one defined as having a non-zero events
097: * interest mask.
098: */
099: public int numActive();
100:
101: /**
102: * Return the number of elements waiting in the queue (that is,
103: * which don't require a SelectSet poll operation to retrieve).
104: */
105: public int size();
106:
107: /*
108:
109: // Actually performs the poll and sets ready[], ready_off, ready_size
110: private void doPoll(int timeout);
111:
112: // Balances selarr[] by shuffling the entries - sets ready[]
113: private void balance(SelectItem selarr[]);
114:
115: // Initialize the balancer
116: private void initBalancer();
117: */
118:
119: }
|