All Packages  This Package  Class Hierarchy  Class Search  Index

Class edu.utah.janos.nodeos.BufferHandle
java.lang.Object
   |
   +----edu.utah.janos.nodeos.BufferHandle

  Summary

public final class  BufferHandle
     extends java.lang.Object
{
          // Fields 6
     private ProtocolLayer.PacketBuffer 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 23
     static int aggregate(byte[], BufferHandle);
     static final int aggregateLength(BufferHandle);

     public void addToList(BufferHandle);
     public final void assertRefCountIs(int);
     public void copyFrom(BufferHandle);
     public void copyFrom(BufferHandle, int, int) throws ArrayIndexOutOfBoundsException, NegativeArraySizeException;
     protected void finalize() throws Throwable;
     synchronized ProtocolLayer.PacketBuffer 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(ProtocolLayer.PacketBuffer, 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;
     public String toString();
     public 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).

Author:
Janos Ministry of Development


  Cross Reference

Returned By:
Booster.newBufferHandle(), ConfigurationManager.newBufferHandle(), NodeConfigure.newBufferHandle(), BufferHandle.getNext(), BufferHandle.getPrev(), CommSpaceElement.getBufferHandle(), FlowRun.newBufferHandle(), FlowBase.newBufferHandle()





  Fields

· state

Summary  |  Top
   private final FlowState state

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


· buffer

Summary  |  Top
   private ProtocolLayer.PacketBuffer buffer


· offset

Summary  |  Top
   private int offset


· length

Summary  |  Top
   private int length


· next

Summary  |  Top
   private BufferHandle next


· prev

Summary  |  Top
   private BufferHandle prev


  Constructors

· BufferHandle

Summary  |  Top

   public BufferHandle(Flow flow) 

Construct a new (empty) BufferHandle.



· BufferHandle

Summary  |  Top
   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).



· BufferHandle

Summary  |  Top
   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).



  Methods

· reset

Summary  |  Top
   public void reset() 

Release the buffer held by this BufferHandle.



· newBuffer

Summary  |  Top
   public void newBuffer(int length) 

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



· copyFrom

Summary  |  Top
   public void copyFrom(BufferHandle src, 
                        int fromOffset, 
                        int fromLength)  throws ArrayIndexOutOfBoundsException, NegativeArraySizeException

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



· copyFrom

Summary  |  Top
   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.



· getNext

Summary  |  Top
   public BufferHandle getNext() 


· getPrev

Summary  |  Top
   public BufferHandle getPrev() 


· removeFromList

Summary  |  Top
   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.



· addToList

Summary  |  Top
   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".



· getLength

Summary  |  Top
   public synchronized int getLength() 


· getByte

Summary  |  Top
   public synchronized byte getByte(int index)  throws ArrayIndexOutOfBoundsException


· setByte

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


· getInt

Summary  |  Top
   public synchronized int getInt(int index)  throws ArrayIndexOutOfBoundsException


· setInt

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


· getBytes

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


· setBytes

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


· getBuffer

Summary  |  Top
   synchronized ProtocolLayer.PacketBuffer getBuffer(OffsetLength ol) 

Get the Buffer associated with this BufferHandle.



· aggregateLength

Summary  |  Top
   static final int aggregateLength(BufferHandle bh) 


· aggregate

Summary  |  Top
   static int aggregate(byte[] dest, 
                        BufferHandle bh) 


· setBuffer

Summary  |  Top
   synchronized void setBuffer(ProtocolLayer.PacketBuffer b, 
                               int offset, 
                               int length) 


· finalize

Summary  |  Top
   protected void finalize()  throws Throwable
Overrides:
finalize in class Object


· toString

Summary  |  Top
   public String toString() 
Overrides:
toString in class Object


· warnRefCount

Summary  |  Top
   public final void warnRefCount(int r, 
                                  String s) 


· assertRefCountIs

Summary  |  Top
   public final void assertRefCountIs(int r) 


All Packages  This Package  Class Hierarchy  Class Search  Index
Freshly brewed Java API Documentation automatically generated with polardoc Version 1.0.7