edu.rit.mp
Class Buf

java.lang.Object
  edu.rit.mp.Buf

Direct Known Subclasses:

BooleanBuf, ByteBuf, CharacterBuf, DoubleBuf, FloatBuf, IntegerBuf, LongBuf, ObjectBuf, ShortBuf, Signed16BitIntegerBuf, Signed8BitIntegerBuf, Unsigned16BitIntegerBuf, Unsigned8BitIntegerBuf

public abstract class Buf
extends Object

Class Buf is the abstract base class for a buffer of items sent or received using the Message Protocol (MP).

A buffer may be used to send one or more messages at the same time in multiple threads. If a buffer is being used to send a message or messages, the buffer must not be used to receive a message at the same time.

A buffer may be used to receive one message at a time. If a buffer is being used to receive a message, the buffer must not be used to receive another message in a different thread, and the buffer must not be used to send a message or messages.

A buffer is a conduit for retrieving and storing data in some underlying data structure. If the underlying data structure is multiple thread safe, then one thread can be retrieving or storing data via the buffer at the same time as other threads are accessing the data structure. If the underlying data structure is not multiple thread safe, then other threads must not access the data structure while one thread is retrieving or storing data via the buffer.

Field Summary

protected int

myLength Number of items in this buffer.

Method Summary

abstract void	copy(Buf theSrc) Copy items from the given buffer to this buffer.
abstract void	fill(Object item) Fill this buffer with the given item.
abstract Buf	getReductionBuf(Op op) Create a buffer for performing parallel reduction using the given binary operation.
abstract Buf	getTemporaryBuf() Create a temporary buffer with the same type of items and the same length as this buffer.
int	length() Obtain the number of items in this buffer.
protected abstract int	receiveItems(int i, int num, ByteBuffer buffer) Receive as many items as possible from the given byte buffer to this buffer.
protected abstract int	sendItems(int i, ByteBuffer buffer) Send as many items as possible from this buffer to the given byte buffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

myLength

protected final int myLength

Number of items in this buffer.

Method Detail

length

public final int length()

Obtain the number of items in this buffer.

Returns:

Number of items.

copy

public abstract void copy(Buf theSrc)

Copy items from the given buffer to this buffer. The number of items copied is this buffer's length or theSrc's length, whichever is smaller. If theSrc is this buffer, the copy() method does nothing.

Parameters:

theSrc - Source of items to copy into this buffer.

Throws:

ClassCastException - (unchecked exception) Thrown if theSrc's item data type is not the same as this buffer's item data type.

fill

public abstract void fill(Object item)

Fill this buffer with the given item. The item is assigned to each element in this buffer.

If this buffer's item data type is a primitive type, the item must be an instance of the corresponding primitive wrapper class -- class Integer for type int, class Double for type double, and so on. If the item is null, the item data type's default initial value is assigned to each element in this buffer.

If this buffer's item data type is a nonprimitive type, the item must be an instance of the item class or a subclass thereof. The item may be null. Note that since item is assigned to every buffer element, every buffer element ends up referring to the same item.

Parameters:

item - Item.

Throws:

ClassCastException - (unchecked exception) Thrown if the item's data type is not the same as this buffer's item data type.

getReductionBuf

public abstract Buf getReductionBuf(Op op)

Create a buffer for performing parallel reduction using the given binary operation. The results of the reduction are placed into this buffer.

Operations performed on the returned reduction buffer have the same effect as operations performed on this buffer, except whenever a source item S is put into a destination item D in this buffer, D is set to D op S, that is, the reduction of D and S using the given binary operation (rather than just setting D to S).

Parameters:

op - Binary operation.

Throws:

ClassCastException - (unchecked exception) Thrown if this buffer's element data type and the given binary operation's argument data type are not the same.

getTemporaryBuf

public abstract Buf getTemporaryBuf()

Create a temporary buffer with the same type of items and the same length as this buffer. The new buffer items are stored in a newly created array, separate from the storage for this buffer's items.

sendItems

protected abstract int sendItems(int i,
                                 ByteBuffer buffer)

Send as many items as possible from this buffer to the given byte buffer.

The sendItems() method must not block the calling thread; if it does, all message I/O in MP will be blocked.

Parameters:

i - Index of first item to send, in the range 0 .. length-1.

buffer - Byte buffer.

Returns:

Number of items sent.

receiveItems

protected abstract int receiveItems(int i,
                                    int num,
                                    ByteBuffer buffer)

Receive as many items as possible from the given byte buffer to this buffer.

The receiveItems() method must not block the calling thread; if it does, all message I/O in MP will be blocked.

Parameters:

i - Index of first item to receive, in the range 0 .. length-1.

num - Maximum number of items to receive.

buffer - Byte buffer.

Returns:

Number of items received.