All Packages  This Package  Class Hierarchy  Class Search  Index

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

Summary

public class  BufferHandle
     extends edu.utah.janos.nodeos.pj_BufferHandle
{
          // Fields 4
     static final int NativeNodeOSID;
     private static final int SYSTEM_OWNER;
     private static final int USER_OWNER;
     private int owner;

          // Constructors 1
     private BufferHandle(BufferHandle, int, int);

          // Methods 20
     public static BufferHandle create();
     public static BufferHandle create(BufferHandle);
     public static BufferHandle create(BufferHandle, int, int);
     public static BufferHandle create(int, int);

     public final void cloneHandle(BufferHandle);
     public final void cloneHandle(BufferHandle, int, int) throws ArrayIndexOutOfBoundsException, NegativeArraySizeException;
     public final synchronized byte getByte(int) throws ArrayIndexOutOfBoundsException;
     public final void getBytes(byte[], int);
     public final synchronized void getBytes(int, byte[], int, int) throws ArrayIndexOutOfBoundsException;
     public final synchronized int getInt(int) throws ArrayIndexOutOfBoundsException;
     public final int getLength();
     synchronized pj_BufferHandle getNativeBufH();
     public final synchronized void newBuffer(int, int) throws ArrayIndexOutOfBoundsException, NegativeArraySizeException;
     public final synchronized void reset();
     public final synchronized void setByte(int, byte) throws ArrayIndexOutOfBoundsException;
     public final synchronized void setBytes(int, byte[], int, int) throws ArrayIndexOutOfBoundsException;
     public final synchronized void setInt(int, int) throws ArrayIndexOutOfBoundsException;
     void systemOwns();
     public String toString();
     void userOwns();
}

A Java wrapper around the native buffer handle object. The Java wrapper protects the NodeOS buffer handle from errant or malicious Java code.

• This layer does the run-time bounds checks on reads and writes.
• Provides a layer of indirection so that the BufferHandle can be revoked (for example when passed to an InChannel)

There is a one-to-one correspondence between a Java BufferHandle and the underlying NodeOS buffer handle (pbuf).

A BufferHandle is a process's handle to a buffer. A BufferHandle object is seen by only one process--it cannot be shared between processes. However, the underlying buffer object may be visible in more than one process. The underlying buffer is never directly accessible to a process, it can only be accessed through the BufferHandle.

The "offset" and "length" associated with a buffer handle are immutable once a buffer is associated with the handle. They can thus be used to provide safe views onto subsequences of a buffer.

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 reset() a BufferHandle object, which tells Janos that the process no longer needs the buffer data associated with the BufferHandle. 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 a per-BufferHandle reference count before the code section and decrementing the reference count after the code section (and postponing all resets until the reference count is zero). Unfortunately, this optimization cannot be expressed at the Java source level (without using synchronization).

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.

This class is not final so that you can subclass it an add things like buffer aggregates on top. XXX need to be sure NATIVE_BUFFERHANDLE methods are not exposed...

XXX Perhaps BufferHandle shouldn't be doing any run-time checks? That should be the responsibility of the EE, right?

XXX WARNING DO NOT ADD ANY INSTANCE FIELDS TO THIS CLASS WITHOUT CHANGING THE GLUE CODE IN moabthread.c. THAT CODE ASSUMES THAT "owner" IS THE FIRST AND ONLY FIELD IN THIS CLASS. THAT IS A STRONG ASSUMPTION TO MAKE. ALSO ASSUMES THE VALUE '2' IS FOR THE USER_OWNER.

Author:

Janos Ministry of Development

Cross Reference

Returned By:

Booster.newBufferHandle(), ConfigurationManager.newBufferHandle(), NodeConfigure.newBufferHandle(), BufferHandle.create(), BufferHandle.create(), BufferHandle.create(), BufferHandle.create(), CommSpaceElement.getBufferHandle(), CutThroughChannel.remBuffer(), InChannel.remBuffer()

   private static final int SYSTEM_OWNER

Constant used for the owner field. Indicates that the system has control over this buffer.

See Also: owner

   private static final int USER_OWNER

Constant used for the owner field. Indicates that the user has control over this buffer.

See Also: owner

   static final int NativeNodeOSID

A bit of a debugging hack. All the "native" classes contain a bit of debugging magic that asserts that this field is what they expect it to be. Look at java/Defines.cpp.

   private int owner

A BufferHandle is owned by the user when it is created. It becomes owned by the system when passed to InChannel.addBuffer(). Ownership is restored to the user when the buffer is passed to a recieve callback. XXX this field may not be necessary (except for debugging Moab). (May be required for reset()/getInt() sequence checks... XXX WARNING DO NOT ADD ANY INSTANCE FIELDS TO THIS CLASS WITHOUT CHANGING THE GLUE CODE IN moabthread.c. THAT CODE ASSUMES THAT "owner" IS THE FIRST AND ONLY FIELD IN THIS CLASS. THAT IS A STRONG ASSUMPTION TO MAKE.

See Also: addBuffer, DeliverFunc

Constructors

· BufferHandle

Summary  |  Top

   private BufferHandle(BufferHandle other, 
                        int offset, 
                        int length) 

Construct a new buffer handle. If bh is null, create a new underlying buffer, otherwise point the new buffer handle at the same buffer as 'other'.

Parameter	Description
other	null or a buffer handle to clone
offset	initial offset
length	length of data

   public static BufferHandle create() 

Construct a new BufferHandle. Constructs a buffer handle that points to a newly allocated, maximum size buffer. Offset is zero.

   public static BufferHandle create(int offset, 
                                     int length) 

Constructs a new buffer handle with the given offset and "length". (The underlying buffer may have a greater actual offset, and may be larger than offset+length bytes.)

   public static BufferHandle create(BufferHandle other) 

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

Parameter	Description
bh	the BufferHandle to copy from

See Also: cloneHandle

   public static BufferHandle create(BufferHandle other, 
                                     int offset, 
                                     int length) 

Construct a new BufferHandle that points to the same data as the given handle. (Shallow copy of other bufferhandle). The new buffer handle's offset and length are set to the provided values.

Parameter	Description
other	the buffer handle to "copy" from (or null).
offset	the new offset this bufferhandle will have.
length	the new length this bufferhandle will have.

See Also: cloneHandle

   public final synchronized void reset() 

Release the buffer held by this BufferHandle.

Overrides:

reset in class pj_BufferHandle

   public final synchronized void newBuffer(int offset, 
                                            int length)  throws ArrayIndexOutOfBoundsException, NegativeArraySizeException

Point this BufferHandle to a new buffer.

Overrides:

newBuffer in class pj_BufferHandle

   public final void cloneHandle(BufferHandle src, 
                                 int fromOffset, 
                                 int fromLength)  throws ArrayIndexOutOfBoundsException, NegativeArraySizeException

Set this BufferHandle's buffer to point to some sub-sequence of src's buffer.

   public final void cloneHandle(BufferHandle src) 

Set this BufferHandle's buffer to point to src's buffer.

   public final int getLength() 

Get the valid data length of the underlying NodeOS pbuf.

Overrides:

getLength in class pj_BufferHandle

   public final synchronized byte getByte(int index)  throws ArrayIndexOutOfBoundsException

Overrides:

getByte in class pj_BufferHandle

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

Overrides:

setByte in class pj_BufferHandle

   public final synchronized int getInt(int index)  throws ArrayIndexOutOfBoundsException

Overrides:

getInt in class pj_BufferHandle

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

Overrides:

setInt in class pj_BufferHandle

   public final void getBytes(byte[] dest, 
                              int destPosition) 

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

Overrides:

getBytes in class pj_BufferHandle

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

Overrides:

setBytes in class pj_BufferHandle

   synchronized pj_BufferHandle getNativeBufH() 

   void systemOwns() 

Change ownership of this BufferHandle from user to system.

   void userOwns() 

Change ownership of this BufferHandle from system to user.

   public String toString() 

Overrides:

toString in class pj_BufferHandle

All Packages  This Package  Class Hierarchy  Class Search  Index