Package edu.rit.mp

Class ObjectBuf<T>

java.lang.Object
edu.rit.mp.Buf
edu.rit.mp.ObjectBuf<T>
Type Parameters:
T - Data type of the objects in the buffer.
Direct Known Subclasses:
EmptyObjectBuf, ObjectArrayBuf, ObjectItemBuf, ObjectMatrixBuf, SharedObjectArrayBuf, SharedObjectBuf
public abstract class ObjectBuf<T> extends Buf
Class ObjectBuf is the abstract base class for a buffer of object items sent or received using the Message Protocol (MP). In a message, an object item is represented as a sequence of bytes using Java Object Serialization.

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 ObjectBuf, call one of the following static factory methods:

  • emptyBuffer()
  • buffer()
  • buffer (T)
  • buffer (T[])
  • sliceBuffer (T[], Range)
  • sliceBuffers (T[], Range[])
  • objectBuffer (T[])
  • buffer (T[][])
  • rowSliceBuffer (T[][], Range)
  • rowSliceBuffers (T[][], Range[])
  • colSliceBuffer (T[][], Range)
  • colSliceBuffers (T[][], Range[])
  • patchBuffer (T[][], Range, Range)
  • patchBuffers (T[][], Range[], Range[])
  • objectBuffer (T[][])
  • buffer (SharedObject<T>)
  • buffer (SharedObjectArray<T>)
  • sliceBuffer (SharedObjectArray<T>, Range)
  • sliceBuffers (SharedObjectArray<T>, Range[])

There are two ways to create a buffer for an array of objects (type T[]):

  1. With the buffer(T[]), sliceBuffer(T[],Range), and sliceBuffers(T[],Range[]) methods. These methods create a buffer that sends and receives the array elements as multiple separate objects of type T. The receiver must allocate an array of the proper dimension to receive the incoming objects and must create a buffer that receives the array elements as separate objects.
  2. With the objectBuffer(T[]) method. This method creates a buffer that sends and receives the entire array as one object of type T[]. The receiver must also create a buffer that receives the entire array as one object; the buffer's item field is automatically set to an array of the proper dimension.

There are two ways to create a buffer for a matrix of objects (type T[][]):

  1. With the buffer(T[][]), rowSliceBuffer(T[][],Range), rowSliceBuffers(T[][],Range[]), colSliceBuffer(T[][],Range), colSliceBuffers(T[][],Range[]), patchBuffer(T[][],Range), and patchBuffers(T[][],Range[]) methods. These methods create a buffer that sends and receives the matrix elements as multiple separate objects of type T. The receiver must allocate a matrix of the proper dimensions to receive the incoming objects and must create a buffer that receives the matrix elements as separate objects.
  2. With the objectBuffer(T[][]) method. This method creates a buffer that sends and receives the entire matrix as one object of type T[][]. The receiver must also create a buffer that receives the matrix as one object; the buffer's item field is automatically set to a matrix of the proper dimensions.

Important Note: An ObjectBuf uses the protected field mySerializedItems to store the serialized representation of the objects in the buffer. If the buffer is used to receive a message, the serialized representation of the received objects is cached in mySerializedItems. If the buffer is used to send a message and mySerializedItems is empty, the objects in the buffer are serialized, the serialized representation is cached in mySerializedItems, and the serialized representation is sent in the message. If the buffer is used to send a message and mySerializedItems is not empty, the objects in the buffer are not serialized; rather, the cached serialized representation is sent. This is done to avoid re-serializing the objects if the buffer is used to send copies of a message to multiple destinations, or if the buffer is used to receive and then immediately send a message. However, if the state of any object in the buffer changes, the buffer's reset() method must be called; this tells the buffer to discard the cached serialized representation and re-serialize the objects in the buffer.

Version:
03-Jul-2008
Author:
Alan Kaminsky

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected byte[]
    mySerializedItems
    Byte array containing this buffer's object items in serialized form.

    Fields inherited from class edu.rit.mp.Buf

    myLength

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    ObjectBuf(int theLength)
    Construct a new object buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> ObjectItemBuf<T>
    buffer()
    Create a buffer for an object item.
    static <T> ObjectBuf<T>
    buffer(SharedObject<T> item)
    Create a buffer for a shared object item.
    static <T> ObjectBuf<T>
    buffer(SharedObjectArray<T> theArray)
    Create a buffer for the entire given shared object array.
    static <T> ObjectItemBuf<T>
    buffer(T item)
    Create a buffer for an object item with the given initial value.
    static <T> ObjectBuf<T>
    buffer(T[] theArray)
    Create a buffer for the entire given object array.
    static <T> ObjectBuf<T>
    buffer(T[][] theMatrix)
    Create a buffer for the entire given object matrix.
    static <T> ObjectBuf<T>
    colSliceBuffer(T[][] theMatrix, Range theColRange)
    Create a buffer for one column slice of the given object matrix.
    static <T> ObjectBuf<T>[]
    colSliceBuffers(T[][] theMatrix, Range[] theColRanges)
    Create an array of buffers for multiple column slices of the given object matrix.
    void
    copy(Buf theSrc)
    Copy items from the given buffer to this buffer.
    protected static <T> void
    defaultCopy(ObjectBuf<T> theSrc, ObjectBuf<T> theDst)
    Copy items from the given source buffer to the given destination buffer.
    static ObjectBuf<Object>
    emptyBuffer()
    Create an empty buffer.
    void
    fill(Object item)
    Fill this buffer with the given item.
    abstract T
    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 <T> ObjectItemBuf<T[]>
    objectBuffer(T[] theArray)
    Create a buffer for the entire given object array.
    static <T> ObjectItemBuf<T[][]>
    objectBuffer(T[][] theMatrix)
    Create a buffer for the entire given object matrix.
    static <T> ObjectBuf<T>
    patchBuffer(T[][] theMatrix, Range theRowRange, Range theColRange)
    Create a buffer for one patch of the given object matrix.
    static <T> ObjectBuf<T>[]
    patchBuffers(T[][] theMatrix, Range[] theRowRanges, Range[] theColRanges)
    Create an array of buffers for multiple patches of the given object matrix.
    abstract void
    put(int i, T item)
    Store the given item in this buffer.
    protected int
    receiveItems(int i, int num, ByteBuffer buffer)
    Receive as many items as possible from the given byte buffer to this buffer.
    void
    reset()
    Reset this buffer.
    static <T> ObjectBuf<T>
    rowSliceBuffer(T[][] theMatrix, Range theRowRange)
    Create a buffer for one row slice of the given object matrix.
    static <T> ObjectBuf<T>[]
    rowSliceBuffers(T[][] theMatrix, Range[] theRowRanges)
    Create an array of buffers for multiple row slices of the given object matrix.
    protected int
    sendItems(int i, ByteBuffer buffer)
    Send as many items as possible from this buffer to the given byte buffer.
    static <T> ObjectBuf<T>
    sliceBuffer(SharedObjectArray<T> theArray, Range theRange)
    Create a buffer for one slice of the given shared object array.
    static <T> ObjectBuf<T>
    sliceBuffer(T[] theArray, Range theRange)
    Create a buffer for one slice of the given object array.
    static <T> ObjectBuf<T>[]
    sliceBuffers(SharedObjectArray<T> theArray, Range[] theRanges)
    Create an array of buffers for multiple slices of the given shared object array.
    static <T> ObjectBuf<T>[]
    sliceBuffers(T[] theArray, Range[] theRanges)
    Create an array of buffers for multiple slices of the given object array.

    Methods inherited from class edu.rit.mp.Buf

    getReductionBuf, length

    Methods inherited from class java.lang.Object

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

  • Field Details

    • mySerializedItems

      protected byte[] mySerializedItems
      Byte array containing this buffer's object items in serialized form. If null, the object items need to be serialized.

  • Constructor Details

    • ObjectBuf

      protected ObjectBuf(int theLength)
      Construct a new object buffer.
      Parameters:
      theLength - Number of items.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if theLength < 0.

  • Method Details

    • emptyBuffer

      public static ObjectBuf<Object> emptyBuffer()
      Create an empty buffer. The buffer's length is 0. The buffer's item type is Object.
      Returns:
      Empty buffer.

    • buffer

      public static <T> ObjectItemBuf<T> buffer()
      Create a buffer for an object item. The item is stored in the item field of the buffer.
      Type Parameters:
      T - Data type of the objects in the buffer.
      Returns:
      Buffer.

    • buffer

      public static <T> ObjectItemBuf<T> buffer(T item)
      Create a buffer for an object item with the given initial value. The item is stored in the item field of the buffer.
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      item - Initial value of the item field.
      Returns:
      Buffer.

    • buffer

      public static <T> ObjectBuf<T> buffer(T[] theArray)
      Create a buffer for the entire given object array. The returned buffer encompasses all the elements in theArray. The array elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      theArray - Array.
      Returns:
      Buffer.
      Throws:
      NullPointerException - (unchecked exception) Thrown if theArray is null.

    • sliceBuffer

      public static <T> ObjectBuf<T> sliceBuffer(T[] theArray, Range theRange)
      Create a buffer for one slice of the given object array. The returned buffer encompasses theRange of elements in theArray. The range's stride may be 1 or greater than 1. The array elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 <T> ObjectBuf<T>[] sliceBuffers(T[] theArray, Range[] theRanges)
      Create an array of buffers for multiple slices of the given object 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. The array elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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.

    • objectBuffer

      public static <T> ObjectItemBuf<T[]> objectBuffer(T[] theArray)
      Create a buffer for the entire given object array. The returned buffer encompasses all the elements in theArray. The array is sent and received as a single object of type T[].
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      theArray - Array. May be null.
      Returns:
      Buffer.

    • buffer

      public static <T> ObjectBuf<T> buffer(T[][] theMatrix)
      Create a buffer for the entire given object matrix. The returned buffer encompasses all the rows and all the columns in theMatrix. The matrix elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      theMatrix - Matrix.
      Returns:
      Buffer.
      Throws:
      NullPointerException - (unchecked exception) Thrown if theMatrix is null.

    • rowSliceBuffer

      public static <T> ObjectBuf<T> rowSliceBuffer(T[][] theMatrix, Range theRowRange)
      Create a buffer for one row slice of the given object 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. The matrix elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 <T> ObjectBuf<T>[] rowSliceBuffers(T[][] theMatrix, Range[] theRowRanges)
      Create an array of buffers for multiple row slices of the given object 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. The matrix elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 <T> ObjectBuf<T> colSliceBuffer(T[][] theMatrix, Range theColRange)
      Create a buffer for one column slice of the given object 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. The matrix elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 <T> ObjectBuf<T>[] colSliceBuffers(T[][] theMatrix, Range[] theColRanges)
      Create an array of buffers for multiple column slices of the given object 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. The matrix elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 <T> ObjectBuf<T> patchBuffer(T[][] theMatrix, Range theRowRange, Range theColRange)
      Create a buffer for one patch of the given object 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. The matrix elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 <T> ObjectBuf<T>[] patchBuffers(T[][] theMatrix, Range[] theRowRanges, Range[] theColRanges)
      Create an array of buffers for multiple patches of the given object 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. The matrix elements are sent and received as multiple separate objects of type T.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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.

    • objectBuffer

      public static <T> ObjectItemBuf<T[][]> objectBuffer(T[][] theMatrix)
      Create a buffer for the entire given object matrix. The returned buffer encompasses all the rows and all the columns in theMatrix. The matrix is sent and received as a single object of type T[][].
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      theMatrix - Matrix. May be null.
      Returns:
      Buffer.

    • buffer

      public static <T> ObjectBuf<T> buffer(SharedObject<T> item)
      Create a buffer for a shared object item. The item is wrapped in an instance of class SharedObject. Use the methods of the SharedObject object to access the actual item.
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      item - SharedObject object that wraps the item.
      Returns:
      a ObjectBuf object.
      Throws:
      NullPointerException - (unchecked exception) Thrown if item is null.

    • buffer

      public static <T> ObjectBuf<T> buffer(SharedObjectArray<T> theArray)
      Create a buffer for the entire given shared object array. The returned buffer encompasses all the elements in theArray.
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      theArray - Array.
      Returns:
      Buffer.
      Throws:
      NullPointerException - (unchecked exception) Thrown if theArray is null.

    • sliceBuffer

      public static <T> ObjectBuf<T> sliceBuffer(SharedObjectArray<T> theArray, Range theRange)
      Create a buffer for one slice of the given shared object array. The returned buffer encompasses theRange of elements in theArray. The range's stride may be 1 or greater than 1.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 <T> ObjectBuf<T>[] sliceBuffers(SharedObjectArray<T> theArray, Range[] theRanges)
      Create an array of buffers for multiple slices of the given shared object 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.
      Type Parameters:
      T - Data type of the objects in the buffer.
      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 T 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, T 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. 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.

      The default implementation of the copy() method also calls the reset() method.

      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.

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

      The fill() method calls the reset() method.

      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
      Returns:
      a Buf object.

    • reset

      public void reset()
      Reset this buffer. Call reset() if the state of any object in this buffer changes.

    • sendItems

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

      Specified by:
      sendItems in class Buf
      Parameters:
      i - Index of first item to send, in the range 0 .. length-1.
      buffer - Byte buffer.
      Returns:
      Number of items sent.

    • receiveItems

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

      Specified by:
      receiveItems in class Buf
      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.

    • defaultCopy

      protected static <T> void defaultCopy(ObjectBuf<T> theSrc, ObjectBuf<T> 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.
      Type Parameters:
      T - Data type of the objects in the buffer.
      Parameters:
      theSrc - Source of items to copy.
      theDst - Destination of items to copy.