Implements mjc, a MultiJava compiler.
This section is not yet completed.
!FIXME! Clean-up and move most of the root-level overview document to this point.
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.
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 theconstant_pool
table. The entry at that index must be aCONSTANT_Utf8_info
structure [4.4.7] representing the string"org.multijava.anchor"
.
attribute_length
The value of the attribute_length
item must be 0.
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 theconstant_pool
table. The entry at that index must be aCONSTANT_Utf8_info
structure [4.4.7] representing the string"org.multijava.dispatcher"
.
attribute_length
The value of the attribute_length
item must be 0.
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 theconstant_pool
table. The entry at that index must be aCONSTANT_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.
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 theconstant_pool
table. The entry at that index must be aCONSTANT_Utf8_info
structure [4.4.7] representing the string"org.multijava.redirector"
.
attribute_length
The value of the attribute_length
item must be 0.
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 theconstant_pool
table. The entry at that index must be aCONSTANT_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 thegf_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 thegf_count
for the class. However, if specialized methods of F are declared in the class, then F is included in thegf_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 thename_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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
Thedescriptor_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at the index must be aCONSTANT_Utf8_info
[4.4.7] structure representing a validmethod 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 thecollection_index
item must be a valid index into theconstant_pool
table and theconstant_pool
entry at the index must be aCONSTANT_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 thecollection_index
item must be a valid index into theconstant_pool
table and theconstant_pool
entry at the index must be aCONSTANT_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 namedfunc
whose top method is declared in a package namedpack.sub
theconstant_pool
entry should bepack.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.
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 thename_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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
Thedescriptor_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at the index must be aCONSTANT_Utf8_info
[4.4.7] structure representing a validmultimethod descriptor
(defined below).
attributes_count
See the item of the same name in [4.6].
attributes[]
Each value of theattributes
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 anorg.multijava.mm_info
structure is theExceptions
[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.
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.