edu.rit.mp
Class Unsigned16BitIntegerBuf

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

Direct Known Subclasses:

EmptyUnsigned16BitIntegerBuf, SharedUnsigned16BitIntegerArrayBuf, SharedUnsigned16BitIntegerBuf, Unsigned16BitIntegerArrayBuf, Unsigned16BitIntegerItemBuf, Unsigned16BitIntegerMatrixBuf

public abstract class Unsigned16BitIntegerBuf
extends Buf

Class Unsigned16BitIntegerBuf is the abstract base class for a buffer of unsigned 16-bit integer items sent or received using the Message Protocol (MP). In a message, an unsigned 16-bit integer item is represented as two bytes, most significant byte first. The range of values that can be represented is 0 .. 65535.

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.

To create an Unsigned16BitIntegerBuf, call one of the following static factory methods:

• emptyBuffer()
• buffer()
• buffer (int)
• buffer (int[])
• sliceBuffer (int[], Range)
• sliceBuffers (int[], Range[])
• buffer (int[][])
• rowSliceBuffer (int[][], Range)
• rowSliceBuffers (int[][], Range[])
• colSliceBuffer (int[][], Range)
• colSliceBuffers (int[][], Range[])
• patchBuffer (int[][], Range, Range)
• patchBuffers (int[][], Range[], Range[])
• buffer (SharedInteger)
• buffer (SharedIntegerArray)
• sliceBuffer (SharedIntegerArray, Range)
• sliceBuffers (SharedIntegerArray, Range[])

Field Summary

Fields inherited from class edu.rit.mp.Buf

myLength

Constructor Summary

protected

Unsigned16BitIntegerBuf(int theLength) Construct a new unsigned 16-bit integer buffer.

Method Summary

static Unsigned16BitIntegerItemBuf	buffer() Create a buffer for an integer item.
static Unsigned16BitIntegerItemBuf	buffer(int item) Create a buffer for an integer item with the given initial value.
static Unsigned16BitIntegerBuf	buffer(int[] theArray) Create a buffer for the entire given integer array.
static Unsigned16BitIntegerBuf	buffer(int[][] theMatrix) Create a buffer for the entire given integer matrix.
static Unsigned16BitIntegerBuf	buffer(SharedInteger item) Create a buffer for a shared integer item.
static Unsigned16BitIntegerBuf	buffer(SharedIntegerArray theArray) Create a buffer for the entire given shared integer array.
static Unsigned16BitIntegerBuf	colSliceBuffer(int[][] theMatrix, Range theColRange) Create a buffer for one column slice of the given integer matrix.
static Unsigned16BitIntegerBuf[]	colSliceBuffers(int[][] theMatrix, Range[] theColRanges) Create an array of buffers for multiple column slices of the given integer matrix.
void	copy(Buf theSrc) Copy items from the given buffer to this buffer.
protected static void	defaultCopy(Unsigned16BitIntegerBuf theSrc, Unsigned16BitIntegerBuf theDst) Copy items from the given source buffer to the given destination buffer.
static Unsigned16BitIntegerBuf	emptyBuffer() Create an empty buffer.
void	fill(Object item) Fill this buffer with the given item.
abstract int	get(int i) Obtain the given item from this buffer.
Buf	getTemporaryBuf() Create a temporary buffer with the same type of items and the same length as this buffer.
static Unsigned16BitIntegerBuf	patchBuffer(int[][] theMatrix, Range theRowRange, Range theColRange) Create a buffer for one patch of the given integer matrix.
static Unsigned16BitIntegerBuf[]	patchBuffers(int[][] theMatrix, Range[] theRowRanges, Range[] theColRanges) Create an array of buffers for multiple patches of the given integer matrix.
abstract void	put(int i, int item) Store the given item in this buffer.
static Unsigned16BitIntegerBuf	rowSliceBuffer(int[][] theMatrix, Range theRowRange) Create a buffer for one row slice of the given integer matrix.
static Unsigned16BitIntegerBuf[]	rowSliceBuffers(int[][] theMatrix, Range[] theRowRanges) Create an array of buffers for multiple row slices of the given integer matrix.
static Unsigned16BitIntegerBuf	sliceBuffer(int[] theArray, Range theRange) Create a buffer for one slice of the given integer array.
static Unsigned16BitIntegerBuf	sliceBuffer(SharedIntegerArray theArray, Range theRange) Create a buffer for one slice of the given shared integer array.
static Unsigned16BitIntegerBuf[]	sliceBuffers(int[] theArray, Range[] theRanges) Create an array of buffers for multiple slices of the given integer array.
static Unsigned16BitIntegerBuf[]	sliceBuffers(SharedIntegerArray theArray, Range[] theRanges) Create an array of buffers for multiple slices of the given shared integer array.

Methods inherited from class edu.rit.mp.Buf

getReductionBuf, length, receiveItems, sendItems

Methods inherited from class java.lang.Object

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

Constructor Detail

Unsigned16BitIntegerBuf

protected Unsigned16BitIntegerBuf(int theLength)

Construct a new unsigned 16-bit integer buffer.

Parameters:

theLength - Number of items.

Throws:

IllegalArgumentException - (unchecked exception) Thrown if theLength < 0.

Method Detail

emptyBuffer

public static Unsigned16BitIntegerBuf emptyBuffer()

Create an empty buffer. The buffer's length is 0. The buffer's item type is unsigned 16-bit integer.

Returns:

Empty buffer.

buffer

public static Unsigned16BitIntegerItemBuf buffer()

Create a buffer for an integer item. The item is stored in the item field of the buffer.

Returns:

Buffer.

buffer

public static Unsigned16BitIntegerItemBuf buffer(int item)

Create a buffer for an integer item with the given initial value. The item is stored in the item field of the buffer.

Parameters:

item - Initial value of the item field.

Returns:

Buffer.

buffer

public static Unsigned16BitIntegerBuf buffer(int[] theArray)

Create a buffer for the entire given integer array. The returned buffer encompasses all the elements in theArray.

Parameters:

theArray - Array.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theArray is null.

sliceBuffer

public static Unsigned16BitIntegerBuf sliceBuffer(int[] theArray,
                                                  Range theRange)

Create a buffer for one slice of the given integer array. The returned buffer encompasses theRange of elements in theArray. The range's stride may be 1 or greater than 1.

Parameters:

theArray - Array.

theRange - Range of elements to include.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theArray is null or theRange is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theArray does not include all the indexes in theRange.

sliceBuffers

public static Unsigned16BitIntegerBuf[] sliceBuffers(int[] theArray,
                                                     Range[] theRanges)

Create an array of buffers for multiple slices of the given integer array. The returned buffer array has the same length as theRanges. Each element [i] of the returned buffer array encompasses the elements of theArray specified by theRanges[i]. Each range's stride may be 1 or greater than 1.

Parameters:

theArray - Array.

theRanges - Array of ranges of elements to include.

Returns:

Array of buffers.

Throws:

NullPointerException - (unchecked exception) Thrown if theArray is null or theRanges or any element thereof is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theArray's allocation does not include any element of theRanges.

buffer

public static Unsigned16BitIntegerBuf buffer(int[][] theMatrix)

Create a buffer for the entire given integer matrix. The returned buffer encompasses all the rows and all the columns in theMatrix.

Parameters:

theMatrix - Matrix.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theMatrix is null.

rowSliceBuffer

public static Unsigned16BitIntegerBuf rowSliceBuffer(int[][] theMatrix,
                                                     Range theRowRange)

Create a buffer for one row slice of the given integer matrix. The returned buffer encompasses theRowRange of rows, and all the columns, in theMatrix. The range's stride may be 1 or greater than 1.

Parameters:

theMatrix - Matrix.

theRowRange - Range of rows to include.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theMatrix is null or theRowRange is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theMatrix's allocation does not include theRowRange.

rowSliceBuffers

public static Unsigned16BitIntegerBuf[] rowSliceBuffers(int[][] theMatrix,
                                                        Range[] theRowRanges)

Create an array of buffers for multiple row slices of the given integer matrix. The returned buffer array has the same length as theRowRanges. Each element [i] of the returned buffer array encompasses the rows of theMatrix specified by theRowRanges[i] and all the columns of theMatrix. Each range's stride may be 1 or greater than 1.

Parameters:

theMatrix - Matrix.

theRowRanges - Array of ranges of rows to include.

Returns:

Array of buffers.

Throws:

NullPointerException - (unchecked exception) Thrown if theMatrix is null or theRowRanges or any element thereof is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theMatrix's allocation does not include any element of theRowRanges.

colSliceBuffer

public static Unsigned16BitIntegerBuf colSliceBuffer(int[][] theMatrix,
                                                     Range theColRange)

Create a buffer for one column slice of the given integer matrix. The returned buffer encompasses all the rows, and theColRange of columns, in theMatrix. The range's stride may be 1 or greater than 1.

Parameters:

theMatrix - Matrix.

theColRange - Range of columns to include.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theMatrix is null or theColRange is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theMatrix's allocation does not include theColRange.

colSliceBuffers

public static Unsigned16BitIntegerBuf[] colSliceBuffers(int[][] theMatrix,
                                                        Range[] theColRanges)

Create an array of buffers for multiple column slices of the given integer matrix. The returned buffer array has the same length as theColRanges. Each element [i] of the returned buffer array encompasses all the rows of theMatrix and the columns of theMatrix specified by theColRanges[i]. Each range's stride may be 1 or greater than 1.

Parameters:

theMatrix - Matrix.

theColRanges - Array of ranges of columns to include.

Returns:

Array of buffers.

Throws:

NullPointerException - (unchecked exception) Thrown if theMatrix is null or theColRanges or any element thereof is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theMatrix's allocation does not include any element of theColRanges.

patchBuffer

public static Unsigned16BitIntegerBuf patchBuffer(int[][] theMatrix,
                                                  Range theRowRange,
                                                  Range theColRange)

Create a buffer for one patch of the given integer matrix. The returned buffer encompasses theRowRange of rows, and theColRange of columns, in theMatrix. Each range's stride may be 1 or greater than 1.

Parameters:

theMatrix - Matrix.

theRowRange - Range of rows to include.

theColRange - Range of columns to include.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theMatrix is null, theRowRange is null, or theColRange is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theMatrix's allocation does not include theRowRange and theColRange.

patchBuffers

public static Unsigned16BitIntegerBuf[] patchBuffers(int[][] theMatrix,
                                                     Range[] theRowRanges,
                                                     Range[] theColRanges)

Create an array of buffers for multiple patches of the given integer matrix. The length of the returned buffer array is equal to the length of theRowRanges times the length of theColRanges. Each element of the returned buffer array encompasses the rows given in one element of theRowRanges array, and the columns given in one element of theColRanges array, in all possible combinations, of theMatrix. Each range's stride may be 1 or greater than 1.

Parameters:

theMatrix - Matrix.

theRowRanges - Array of ranges of rows to include.

theColRanges - Array of ranges of columns to include.

Returns:

Array of buffers.

Throws:

NullPointerException - (unchecked exception) Thrown if theMatrix is null, theRowRanges or any element thereof is null, or theColRanges or any element thereof is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theMatrix's allocation does not include any element of theRowRanges or theColRanges.

buffer

public static Unsigned16BitIntegerBuf buffer(SharedInteger item)

Create a buffer for a shared integer item. The item is wrapped in an instance of class SharedInteger. Use the methods of the SharedInteger object to access the actual item.

Parameters:

item - SharedInteger object that wraps the item.

Throws:

NullPointerException - (unchecked exception) Thrown if item is null.

buffer

public static Unsigned16BitIntegerBuf buffer(SharedIntegerArray theArray)

Create a buffer for the entire given shared integer array. The returned buffer encompasses all the elements in theArray.

Parameters:

theArray - Array.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theArray is null.

sliceBuffer

public static Unsigned16BitIntegerBuf sliceBuffer(SharedIntegerArray theArray,
                                                  Range theRange)

Create a buffer for one slice of the given shared integer array. The returned buffer encompasses theRange of elements in theArray. The range's stride may be 1 or greater than 1.

Parameters:

theArray - Array.

theRange - Range of elements to include.

Returns:

Buffer.

Throws:

NullPointerException - (unchecked exception) Thrown if theArray is null or theRange is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theArray does not include all the indexes in theRange.

sliceBuffers

public static Unsigned16BitIntegerBuf[] sliceBuffers(SharedIntegerArray theArray,
                                                     Range[] theRanges)

Create an array of buffers for multiple slices of the given shared integer array. The returned buffer array has the same length as theRanges. Each element [i] of the returned buffer array encompasses the elements of theArray specified by theRanges[i]. Each range's stride may be 1 or greater than 1.

Parameters:

theArray - Array.

theRanges - Array of ranges of elements to include.

Returns:

Array of buffers.

Throws:

NullPointerException - (unchecked exception) Thrown if theArray is null or theRanges or any element thereof is null.

IndexOutOfBoundsException - (unchecked exception) Thrown if theArray's allocation does not include any element of theRanges.

get

public abstract int get(int i)

Obtain the given item from this buffer.

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

Parameters:

i - Item index in the range 0 .. length()-1.

Returns:

Item at index i.

put

public abstract void put(int i,
                         int item)

Store the given item in this buffer.

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

Parameters:

i - Item index in the range 0 .. length()-1.

item - Item to be stored at index i.

copy

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

The default implementation of the copy() method calls the defaultCopy() method. A subclass can override the copy() method to use a more efficient algorithm.

Specified by:

copy in class Buf

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 void fill(Object item)

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

The item must be an instance of class Integer. If the item is null, 0 is assigned to each element in this buffer.

Specified by:

fill in class Buf

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.

getTemporaryBuf

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

Specified by:

getTemporaryBuf in class Buf

defaultCopy

protected static void defaultCopy(Unsigned16BitIntegerBuf theSrc,
                                  Unsigned16BitIntegerBuf theDst)

Copy items from the given source buffer to the given destination buffer. The number of items copied is theSrc's length or theDst's length, whichever is smaller. Each item is copied individually using the get() and put() methods. It is assumed that theSrc is not the same as theDst.

Parameters:

theSrc - Source of items to copy.

theDst - Destination of items to copy.