edu.utah.janos.nodeos
Class BufferHandle

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

public class BufferHandle

extends edu.utah.janos.nodeos.pj_BufferHandle

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

Method Summary

void	cloneHandle(BufferHandle src) Set this BufferHandle's buffer to point to src's buffer.
void	cloneHandle(BufferHandle src, int fromOffset, int fromLength) Set this BufferHandle's buffer to point to some sub-sequence of src's buffer.
boolean	compareBytes(int offset, byte[] bytes) Compare the given sequence of bytes to a sequence in this buffer.
short	computeChecksum(int offset, int count) Compute an IP style checksum over the given segment of the buffer.
static BufferHandle	create() Construct a new BufferHandle.
static BufferHandle	create(BufferHandle other) Construct a new BufferHandle that points to the same data as the given handle.
static BufferHandle	create(BufferHandle other, int offset, int length) Construct a new BufferHandle that points to the same data as the given handle.
static BufferHandle	create(int offset, int length) Constructs a new buffer handle with the given offset and "length".
byte	getByte(int index)
void	getBytes(byte[] dest, int destPosition)
void	getBytes(int srcPosition, byte[] dest, int destPosition, int destLength)
int	getInt(int index)
void	getInts(int srcPosition, int[] dest, int destPosition, int destLength)
int	getLength() Get the valid data length of the underlying NodeOS pbuf.
short	getShort(int index)
void	newBuffer(int offset, int length) Point this BufferHandle to a new buffer.
void	reset() Release the buffer held by this BufferHandle.
void	setByte(int index, byte val)
void	setBytes(int destPosition, byte[] src, int srcPosition, int srcLength)
void	setInt(int index, int val)
void	setInts(int destPosition, int[] src, int srcPosition, int srcLength)
void	setShort(int index, short val)
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

public static BufferHandle create()

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

create

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

create

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

Parameters:

bh - the BufferHandle to copy from

See Also:

cloneHandle(BufferHandle)

create

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.

Parameters:

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(BufferHandle)

reset

public final void reset()

Release the buffer held by this BufferHandle. Subsequent accesses to the buffer must fail.

newBuffer

public final void newBuffer(int offset,
                            int length)
                     throws java.lang.ArrayIndexOutOfBoundsException,
                            java.lang.NegativeArraySizeException

Point this BufferHandle to a new buffer.

cloneHandle

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

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

cloneHandle

public final void cloneHandle(BufferHandle src)

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

getLength

public final int getLength()

Get the valid data length of the underlying NodeOS pbuf.

getByte

public final byte getByte(int index)
                   throws java.lang.ArrayIndexOutOfBoundsException

setByte

public final void setByte(int index,
                          byte val)
                   throws java.lang.ArrayIndexOutOfBoundsException

getShort

public final short getShort(int index)
                     throws java.lang.ArrayIndexOutOfBoundsException

setShort

public final void setShort(int index,
                           short val)
                    throws java.lang.ArrayIndexOutOfBoundsException

getInt

public final int getInt(int index)
                 throws java.lang.ArrayIndexOutOfBoundsException

setInt

public final void setInt(int index,
                         int val)
                  throws java.lang.ArrayIndexOutOfBoundsException

getBytes

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

getBytes

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

setBytes

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

getInts

public final void getInts(int srcPosition,
                          int[] dest,
                          int destPosition,
                          int destLength)
                   throws java.lang.ArrayIndexOutOfBoundsException

setInts

public final void setInts(int destPosition,
                          int[] src,
                          int srcPosition,
                          int srcLength)
                   throws java.lang.ArrayIndexOutOfBoundsException

computeChecksum

public final short computeChecksum(int offset,
                                   int count)

Compute an IP style checksum over the given segment of the buffer.

Parameters:

offset - Offset into the buffer to start computing the checksum

count - The number of bytes the checksum should cover.

Returns:

The checksum value.

compareBytes

public final boolean compareBytes(int offset,
                                  byte[] bytes)
                           throws java.lang.ArrayIndexOutOfBoundsException

Compare the given sequence of bytes to a sequence in this buffer. Returns true if the sequences are identical, false if not.

XXX a more generic version that allows sub-sequences of 'bytes' might be handy.

Parameters:

offset - Offset into the buffer to start comparison

bytes - The byte sequence to compare with.

toString

public java.lang.String toString()

Overrides:

toString in class edu.utah.janos.nodeos.pj_BufferHandle