Message Format

This section describes the message format used by mpjdev. The specification here doesn't define how a message vector which contained in the Buffer object is stored internally--for example it may be as a Java byte [] array or it may be as a C char [] array, accessed through native methods. But this section does define the organization of data in the buffer. For example it includes formula for computing the required buffer capacity, as a function of the set of Java data that is to be written to the buffer. It is the responsibility of the user to ensure that sufficient space is available in the buffer to hold the desired message. Trying to write too much data to a buffer causes an exception to be thrown. Likewise, trying to receive a message into a buffer that is too small will cause an exception to be thrown. These features are (arguably) in the spirit of MPI.

A message is divided into two main parts. The primary payload is used to store message elements of primitive type. The secondary payload is intended to hold the data from object elements in the message (although other uses for the secondary payload are conceivable). The size of the primary payload is limited by the fixed capacity of the buffer, as discussed above. The size of the secondary payload, if it is non-empty, is likely to be determined ``dynamically''--for example as objects are written to the buffer.

The message starts with a short primary header, defining an encoding scheme used in headers and primary payload, and the total number of data bytes in the primary payload. Only one byte is allocated in the message to describe the encoding scheme: currently the only encoding schemes supported or envisaged are big-ending and little-endian. This is to allow for native implementations of the buffer operations, which (unlike standard Java read/write operations) may use either byte order.

A message is divided into zero or more sections. Each section contains a fixed number of elements of homogeneous type. The elements in a section will all have identical primitive Java type, or they will all have Object type (in the latter case the exact classes of the objects need not be homogeneous within the section).

Each section has a short header in the primary payload, specifying the type of the elements, and the number of elements in the section. For sections with primitive type, the header is followed by the actual data. For sections with object type, the header is the only representation of the section appearing in the primary payload--the actual data will go in the secondary payload.

After the primary payload there is a secondary header. The secondary header defines the number of bytes of data in the secondary payload.

The secondary header is followed in the logical message by the secondary payload. This section says nothing about the layout of the secondary payload. In practice this layout will be determined by the Java Object Serialization specification.