Implements mjc, a MultiJava compiler.

Package Specification

This section is not yet completed.

!FIXME! Clean-up and move most of the root-level overview document to this point.

Related Documentation

Bytecode Encoding of MultiJava Information

The MultiJava language specifies that certain information must be added to the bytecode produced from source files that use MultiJava-specific features. This information is added to the generated bytecode using custom attributes (see the Java Virtual Machine Specification, 2nd edition, section 4.1). A MultiJava compiler must parse these custom attributes to determine the static type signature of the multimethods and generic functions implemented by the bytecode.

The specification of these attributes belongs in a language reference manual. Until we have time to produce a MultiJava reference manual we are putting the specification here. In the following, numbers in square brackets are references to sections of the JVM Specification, 2nd edition.

External Generic Functions

One instance of the following attribute must appear in the attributes list of a ClassFile structure [4.1] that corresponds to the anchor class of an external generic function.

org.multijava.anchor_attribute {
        u2      attribute_name_index;
        u4      attribute_length;
}

attribute_name_index

The value of this item must be a valid index into the constant_pool table. The entry at that index must be a CONSTANT_Utf8_info structure [4.4.7] representing the string "org.multijava.anchor".

attribute_length

The value of the attribute_length item must be 0.

Dispatchers

One instance of the following attribute must appear in the attributes list of a ClassFile structure [4.1] that corresponds to the compiler generated dispatcher class of an external generic function and in the attributes list of a MethodInfo structure [4.6] that corresponds to the compiler generated dispatcher method of a multimethod.

org.multijava.dispatcher {
        u2      attribute_name_index;
        u4      attribute_length;
}

attribute_name_index

The value of this item must be a valid index into the constant_pool table. The entry at that index must be a CONSTANT_Utf8_info structure [4.4.7] representing the string "org.multijava.dispatcher".

attribute_length

The value of the attribute_length item must be 0.

Multimethod Bodies

One instance of the following attribute must appear in the attributes list of a MethodInfo structure [4.6] that corresponds to the compiler generated body method of a multimethod.

org.multijava.mm_body {
        u2      attribute_name_index;
        u4      attribute_length;
}

attribute_name_index

The value of this item must be a valid index into the constant_pool table. The entry at that index must be a CONSTANT_Utf8_info structure [4.4.7] representing the string "org.multijava.mm_body".

attribute_length

The value of the attribute_length item must be 0.

Pleomorphic Method Redirectors

One instance of the following attribute must appear in the attributes list of a MethodInfo structure [4.6] that corresponds to the compiler generated redirector method for a method that is pleomorphic on an interface generic function and an external generic function.

org.multijava.redirector {
        u2      attribute_name_index;
        u4      attribute_length;
}

attribute_name_index

The value of this item must be a valid index into the constant_pool table. The entry at that index must be a CONSTANT_Utf8_info structure [4.4.7] representing the string "org.multijava.redirector".

attribute_length

The value of the attribute_length item must be 0.

Generic Functions

One instance of the generic_functions attribute, defined below, must appear in the attributes list of any ClassFile structure [4.1] that corresponds to

The generic_functions attribute is defined as follows:

org.multijava.generic_functions_attribute {
        u2      attribute_name_index;
        u4      attribute_length;
        u2      gf_count;
        org.multijava.gf_info 
                generic_functions[gf_count];
}

attribute_name_index

The value of this item must be a valid index into the constant_pool table. The entry at that index must be a CONSTANT_Utf8_info structure [4.4.7] representing the string "org.multijava.generic_functions".

attribute_length

The value of the attribute_length item indicates the length of the attribute excluding the initial 6 bytes.

gf_count

The value of the gf_count attribute indicates the number of generic functions for which the class or anchor includes specializing methods. A generic function is included in this count only if a method of that generic function declared in the corresponding source code is accessed via a synthetic dispatch mechanism. For example, suppose there is an internal generic function, F, for which a class only includes an unspecialized method, i.e., a regular Java method. Then F is not included in the gf_count for the class. However, if specialized methods of F are declared in the class, then F is included in the gf_count for the class.

generic_functions

Each entry in the generic_functions array gives the type signature for a collection of multimethods all declared in the same compilation unit and all overriding the same generic function.

The next data structure is used to describe the signature for a collection of multimethods all declared in the same compilation unit and all overriding the same generic function. It is quite similar to the method_info data structure [4.6], but is expanded to reference an arbitrary number of multimethods.

org.multijava.gf_info {
        u2      name_index;
        u2      descriptor_index;
        u2      collection_index;
        u2      function_number;
        u2      mm_count;
        org.multijava.mm_info 
		multimethods[mm_count];
}

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure [4.4.7] representing a valid name in the Java programming language [2.7], stored as a simple name [2.7.1].

descriptor_index

The descriptor_index item must be a valid index into the constant_pool table. The constant_pool entry at the index must be a CONSTANT_Utf8_info [4.4.7] structure representing a valid method descriptor [4.3.3] giving the type signature for the generic function without explicit specializers.

collection_index

If the methods in this collection belong to an internal generic function or are external methods of an external generic function, then the collection_index item must be a valid index into the constant_pool table and the constant_pool entry at the index must be a CONSTANT_Utf8_info [4.4.7] structure representing the empty string.
Otherwise the methods in this collection must be internal methods of an external generic function. Then the collection_index item must be a valid index into the constant_pool table and the constant_pool entry at the index must be a CONSTANT_Utf8_info [4.4.7] structure representing the valid fully qualified name [2.7.5] of the generic function to which the methods in this collection belong. For example, for a generic function named func whose top method is declared in a package named pack.sub the constant_pool entry should be pack.sub.func.

function_number

The value of the function_number item must be a unique number for differentiating overloaded external generic functions within the same anchor class. The number is used in the naming of the synthetic dispatcher and signature classes of the generic function.

mm_count

The value of the mm_count attribute indicates the number of multimethods declared in the class or anchor that belong to the generic function. If the gf_info attribute represents an external generic function, then this count includes all methods of that generic function that are defined in the source code file. If the gf_info attribute represents an internal generic function, then it must be the case that there are multimethods declared on that generic function in the source code file. In this case the mm_count include both the multimethods and the regular (i.e., non-multiple-dispath) methods of that generic function that are defined in the source code file.

multimethods

Each entry in the multimethods array must be a valid multimethod information structure (described below), one for each method of the generic function declared in the corresponding source code file.

Multimethod Signatures

The next data structure is used to describe the signature for a single multimethod. It is essentially the same as the method_info data structure [4.6], but the referenced type descriptor includes a receiver type and can include explicit specializers.

org.multijava.mm_info {
        u2      access_flags;
        u2      name_index;
        u2      descriptor_index;
        u2      attributes_count;
        attribute_info 
                attributes[attributes_count];
}

access_flags

See the item of the same name in [4.6].

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure [4.4.7] representing a valid name in the Java programming language [2.7], stored as a simple name [2.7.1].

descriptor_index

The descriptor_index item must be a valid index into the constant_pool table. The constant_pool entry at the index must be a CONSTANT_Utf8_info [4.4.7] structure representing a valid multimethod descriptor (defined below).

attributes_count

See the item of the same name in [4.6].

attributes[]

Each value of the attributes table must be an attribute structure [4.7]. A multimethod can have any number of optional attributes associated with it. The only attribute defined by this and the Java Virtual Machine specification as appearing in the attributes table of an org.multijava.mm_info structure is the Exceptions [4.7.4] attribute. As in the virtual machine specification, tools must silently ignore unrecognized attributes.

The constant_pool table of a class declaring multimethods must include one CONSTANT_Utf8_info [4.4.7] structure for each multimethod. Each of these items is an instance of multimethod descriptor, which is closely related to method descriptor [4.3.3]. MultiJava simply adds some productions to the grammar for method descriptors. For completeness the full multimethod desciptor grammar is given below, with terminal symbols in single quotes. Non-terminal symbols not defined here are defined in the JVM Specification, section 4.3.2.

MultimethodDescriptor:
    '(' ParameterDescriptor* ')' ReturnDescriptor ReceiverDescriptor

ParameterDescriptor:
    FieldType
    '@' FieldType ObjectOrArrayType
    '@@' FieldType ValueSpecializer
    
ObjectOrArrayType:
    ObjectType
    ArrayType

ReturnDescriptor:
    FieldType
    'V'

ReceiverDescriptor:
    ObjectType

ValueSpecializer:
    'X' ConstantValue '"'

ConstantValue:
    IntegerLiteral
    FloatingPointLiteral
    BooleanLiteral
    CharacterLiteral
    StringLiteral
Note that CharacterLiterals and StringLiterals in the grammar above should be escaped (including their surrounding quotes), so that the trailing double-quote of a ValueSpecializer can be uniquely determined.

Credits

The code for Mjc originated from the Kopi project. This code was adapted for the Multijava project by Curtis Clifton, Todd Millstein (value dispatching), Yoonsik Cheon and Clyde Ruby (refactoring to make mjc serve as a compiler framework), and Gary T. Leavens (project leadership, system architecture, build system, testing).

Thanks also to any contributors whose names we have failed to mention. If we've left you off this list, it is a mistake on our part and we apologize. Please let us know so the mistake can be rectified.