sourceif.java

The Staged Event-Driven Architecture (SEDA) is a new design for building scalable Internet services.

/* 
 * Copyright (c) 2001 by Matt Welsh and The Regents of the University of 
 * California. All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice and the following
 * two paragraphs appear in all copies of this software.
 * 
 * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
 * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
 * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 *
 * Author: Matt Welsh <[e-mail]>
 * 
 */

package seda.sandStorm.api;

/**
 * A SourceIF implements the 'source side' of an event queue: it supports 
 * dequeue operations only.
 * 
 * @author   Matt Welsh
 */

public interface SourceIF {

  /**
   * Dequeues the next element, or returns <code>null</code> if there is
   * nothing left on the queue.
   *
   * @return the next <code>QueueElementIF</code> on the queue
   */
  public QueueElementIF dequeue();

  /**
   * Dequeues all available elements, or returns <code>null</code> if there is
   * nothing left on the queue.
   *
   * @return all pending <code>QueueElementIF</code>s on the queue
   */
  public QueueElementIF[] dequeue_all();

  /**
   * Dequeues at most <code>num</code> available elements, or returns 
   * <code>null</code> if there is nothing left on the queue.
   *
   * @return At most <code>num</code> <code>QueueElementIF</code>s on the queue
   */
  public QueueElementIF[] dequeue(int num);

  /**
   * Just like blocking_dequeue_all, but returns only a single element.
   */
  public QueueElementIF blocking_dequeue(int timeout_millis);

  /**
   * This method blocks on the queue up until a timeout occurs or
   * until an element appears on the queue. It returns all elements waiting 
   * on the queue at that time.
   *
   * @param timeout_millis if timeout_millis is <code>0</code>, 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
   *    <code>-1</code>, 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.
   *
   * @return an array of <code>QueueElementIF</code>'s.  This array will
   *    be null if no elements were pending.
   */
  public QueueElementIF[] blocking_dequeue_all(int timeout_millis);

  /**
   * This method blocks on the queue up until a timeout occurs or
   * until an element appears on the queue. It returns at most 
   * <code>num</code> elements waiting on the queue at that time.
   */
  public QueueElementIF[] blocking_dequeue(int timeout_millis, int num);

  /**
   * Returns the number of elements waiting in this queue.
   */
  public int size();


}