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

seda.sandStorm.api
Interface SinkIF

All Known Subinterfaces:
QueueIF
All Known Implementing Classes:
SimpleSink, SinkProxy

public interface SinkIF

A SinkIF implements the 'sink' end of a finite-length event queue: it supports enqueue operations only. These operations can throw a SinkException if the sink is closed or becomes full, allowing event queues to support thresholding and backpressure.

Author:
Matt Welsh

Method Summary
 void enqueue_abort(java.lang.Object enqueue_key)
          Abort a previously prepared provisional enqueue operation (from the enqueue_prepare() method).
 void enqueue_commit(java.lang.Object enqueue_key)
          Commit a previously prepared provisional enqueue operation (from the enqueue_prepare() method).
 boolean enqueue_lossy(QueueElementIF element)
          Enqueues the given element onto the queue.
 void enqueue_many(QueueElementIF[] elements)
          Given an array of elements, atomically enqueues all of the elements in the array.
 java.lang.Object enqueue_prepare(QueueElementIF[] elements)
          Support for transactional enqueue.
 void enqueue(QueueElementIF element)
          Enqueues the given element onto the queue.
 EnqueuePredicateIF getEnqueuePredicate()
          Return the enqueue predicate for this sink.
 void setEnqueuePredicate(EnqueuePredicateIF pred)
          Set the enqueue predicate for this sink.
 int size()
          Return the number of elements in this sink.
 

Method Detail

enqueue

public void enqueue(QueueElementIF element)
             throws SinkException
Enqueues the given element onto the queue.
Parameters:
element - The QueueElementIF to enqueue
Throws:
SinkFullException - Indicates that the sink is temporarily full.
SinkClosedException - Indicates that the sink is no longer being serviced.

enqueue_lossy

public boolean enqueue_lossy(QueueElementIF element)
Enqueues the given element onto the queue. This is lossy in that this method drops the element if the element could not be enqueued, rather than throwing a SinkFullException or SinkClosedException. This is meant as a convenience interface for "low priority" enqueue events which can be safely dropped.
Parameters:
element - The QueueElementIF to enqueue
Returns:
true if the element was enqueued, false otherwise.

enqueue_many

public void enqueue_many(QueueElementIF[] elements)
                  throws SinkException
Given an array of elements, atomically enqueues all of the elements in the array. This guarantees that no other thread can interleave its own elements with those being inserted from this array. The implementation must enqueue all of the elements or none of them; if a SinkFullException or SinkClosedException is thrown, none of the elements will have been enqueued. This implies that the enqueue predicate (if any) must accept all elements in the array for the enqueue to proceed.
Parameters:
elements - The element array to enqueue
Throws:
SinkFullException - Indicates that the sink is temporarily full.
SinkClosedException - Indicates that the sink is no longer being serviced.

enqueue_prepare

public java.lang.Object enqueue_prepare(QueueElementIF[] elements)
                                 throws SinkException
Support for transactional enqueue.

This method allows a client to provisionally enqueue a number of elements onto the queue, and then later commit the enqueue (with a enqueue_commit() call), or abort (with a enqueue_abort() call). This mechanism can be used to perform "split-phase" enqueues, where a client first enqueues a set of elements on the queue and then performs some work to "fill in" those elements before performing a commit. This can also be used to perform multi-queue transactional enqueue operations, with an "all-or-nothing" strategy for enqueueing events on multiple queues.

This method would generally be used in the following manner:

   Object key = sink.enqueue_prepare(someElements);
   if (can_commit) {
     sink.enqueue_commit(key);
   } else {
     sink.enqueue_abort(key);
   }
 

Note that this method does not protect against "dangling prepares" -- that is, a prepare without an associated commit or abort operation. This method should be used with care. In particular, be sure that all code paths (such as exceptions) after a prepare include either a commit or an abort.

Like enqueue_many, enqueue_prepare is an "all or none" operation: the enqueue predicate must accept all elements for enqueue, or none of them will be enqueued.

Parameters:
elements - The element array to provisionally enqueue
Returns:
A "transaction key" that may be used to commit or abort the provisional enqueue
Throws:
SinkFullException - Indicates that the sink is temporarily full and that the requested elements could not be provisionally enqueued.
SinkClosedException - Indicates that the sink is no longer being serviced.
See Also:
enqueue_commit, enqueue_abort

enqueue_commit

public void enqueue_commit(java.lang.Object enqueue_key)
Commit a previously prepared provisional enqueue operation (from the enqueue_prepare() method). Causes the provisionally enqueued elements to appear on the queue for future dequeue operations. Note that once a enqueue_prepare() has returned an enqueue key, the queue cannot reject the entries.
Parameters:
key - The enqueue key returned by a previous call to enqueue_prepare().
Throws:
java.lang.IllegalArgumentException - Thrown if an unknown enqueue key is provided.

enqueue_abort

public void enqueue_abort(java.lang.Object enqueue_key)
Abort a previously prepared provisional enqueue operation (from the enqueue_prepare() method). Causes the queue to discard the provisionally enqueued elements.
Parameters:
key - The enqueue key returned by a previous call to enqueue_prepare().
Throws:
java.lang.IllegalArgumentException - Thrown if an unknown enqueue key is provided.

setEnqueuePredicate

public void setEnqueuePredicate(EnqueuePredicateIF pred)
Set the enqueue predicate for this sink. This mechanism allows user to define a method that will 'screen' QueueElementIF's during the enqueue procedure to either accept or reject them. The enqueue predicate runs in the context of the caller of enqueue(), which means it must be simple and fast. This can be used to implement many interesting queue-thresholding policies, such as simple count threshold, credit-based mechanisms, and more.

getEnqueuePredicate

public EnqueuePredicateIF getEnqueuePredicate()
Return the enqueue predicate for this sink.

size

public int size()
Return the number of elements in this sink.

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