All Packages  This Package  Class Hierarchy  Class Search  Index

java.lang.Object
   |
   +----edu.utah.janos.core.BufferHandle

Summary

public final class  BufferHandle
     extends java.lang.Object
{
          // Fields 6
     private Buffer buffer;
     private int length;
     private BufferHandle next;
     private int offset;
     private BufferHandle prev;
     private final FlowState state;

          // Constructors 3
     public BufferHandle(Flow);
     public BufferHandle(Flow, BufferHandle);
     public BufferHandle(Flow, BufferHandle, int, int);

          // Methods 19
     public void addToList(BufferHandle);
     final void assertRefCountIs(int);
     public void copyFrom(BufferHandle);
     public void copyFrom(BufferHandle, int, int) throws ArrayIndexOutOfBoundsException;
     synchronized Buffer getBuffer(OffsetLength);
     public synchronized byte getByte(int) throws ArrayIndexOutOfBoundsException;
     public synchronized void getBytes(int, byte[], int, int) throws ArrayIndexOutOfBoundsException;
     public synchronized int getInt(int) throws ArrayIndexOutOfBoundsException;
     public synchronized int getLength();
     public BufferHandle getNext();
     public BufferHandle getPrev();
     public void newBuffer(int);
     public void removeFromList();
     public void reset();
     synchronized void setBuffer(Buffer, int, int);
     public synchronized void setByte(int, byte) throws ArrayIndexOutOfBoundsException;
     public synchronized void setBytes(int, byte[], int, int) throws ArrayIndexOutOfBoundsException;
     public synchronized void setInt(int, int) throws ArrayIndexOutOfBoundsException;
     final void warnRefCount(int, String);
}

A BufferHandle is a process's handle to a buffer. A BufferHandle object is seen by only one process, so that it is not shared between processes, while the underlying Buffer object may be shared between processes. However, a Buffer object is never directly accessible to a process; the Buffer can only be accessed through the BufferHandle.

A process is charged for the memory occupied by all buffers reachable from the process's BufferHandle objects. To avoid paying for a buffer which is no longer needed, a process can explicitly recycle a BufferHandle object, which tells Janos that the process no longer needs the buffer data associated with the BufferHandle. Janos is then free to reuse the BufferHandle object for new buffer data. An access to a BufferHandle after it has been recycled behaves unpredictably: it may continue to access the old buffer, it may access another one of the processes's buffers, or it may raise a NullPointerException. However, such an access will never read another process's buffer.

Currently, all access methods in BufferHandle are synchronized. This is inefficient. The virtual machine can eliminate these locks in a section of code by incrementing the buffer reference count before the code section and decrementing the reference count after the code section. Unfortunately, this optimization cannot be expressed at the Java source level. (XXX is this something for Jason?)

Since a BufferHandle is visible only to one process, and a process can only run on one processor at a time, simple preemption points can eliminate the per-access synchronization.

Buffers are mutable.

BufferHandles are organized as circular doubly-linked lists. At any given time, each BufferHandle object belongs to exactly one such list (all operations preserve this invariant). The constructor creates a BufferHandle which consists of a one element list.

A list of BufferHandles can be "sent" on an OutChannel. An InChannel could return a list, too. (But that doesn't happen).

Cross Reference

Returned By:

Booster.newBufferHandle(), ConfigurationManager.newBufferHandle(), BufferHandle.getNext(), BufferHandle.getPrev(), CommSpaceElement.getBufferHandle(), FlowRun.newBufferHandle(), FlowBase.newBufferHandle()

   private final FlowState state

state.lock is used to protect the per-flow lists of buffer handles.

   private Buffer buffer

   private int offset

   private int length

   private BufferHandle next

   private BufferHandle prev

Constructors

· BufferHandle

Summary  |  Top

   public BufferHandle(Flow flow) 

Construct a new (empty) BufferHandle.

   public BufferHandle(Flow flow, 
                       BufferHandle bh) 

Construct a new BufferHandle that points to the same data as the given handle. (Shallow copy of other bufferhandle).

   public BufferHandle(Flow flow, 
                       BufferHandle bh, 
                       int fromOffset, 
                       int fromLength) 

Construct a new BufferHandle that points to the same data as the given handle. (Shallow copy of other bufferhandle).

   public void reset() 

Release the buffer held by this BufferHandle.

   public void newBuffer(int length) 

Point this BufferHandle to a new buffer which holds the specified array. The old buffer is released.

   public void copyFrom(BufferHandle src, 
                        int fromOffset, 
                        int fromLength)  throws ArrayIndexOutOfBoundsException

Set this BufferHandle's buffer to point to src's buffer. The positions of the BufferHandles in their lists are not affected.

   public void copyFrom(BufferHandle src) 

Set this BufferHandle's buffer to point to src's buffer. The positions of the BufferHandles in their lists are not affected.

   public BufferHandle getNext() 

   public BufferHandle getPrev() 

   public void removeFromList() 

Removes the object from the list that it is in. This splits a list of length n into two lists, one of 1 (which contains this object), and one of length n-1 (which contains all the other objects). If n==1, then removeFromList does nothing.

   public void addToList(BufferHandle list) 

Removes the object from its current list and adds it to a new list. The object is added after "list".

   public synchronized int getLength() 

   public synchronized byte getByte(int index)  throws ArrayIndexOutOfBoundsException

   public synchronized void setByte(int index, 
                                    byte val)  throws ArrayIndexOutOfBoundsException

   public synchronized int getInt(int index)  throws ArrayIndexOutOfBoundsException

   public synchronized void setInt(int index, 
                                   int val)  throws ArrayIndexOutOfBoundsException

   public synchronized void getBytes(int srcPosition, 
                                     byte[] dest, 
                                     int destPosition, 
                                     int destLength)  throws ArrayIndexOutOfBoundsException

   public synchronized void setBytes(int destPosition, 
                                     byte[] src, 
                                     int srcPosition, 
                                     int srcLength)  throws ArrayIndexOutOfBoundsException

   synchronized Buffer getBuffer(OffsetLength ol) 

Get the Buffer associated with this BufferHandle.

   synchronized void setBuffer(Buffer b, 
                               int offset, 
                               int length) 

   final void warnRefCount(int r, 
                           String s) 

   final void assertRefCountIs(int r) 

All Packages  This Package  Class Hierarchy  Class Search  Index