gcj.texi

来自「理解和实践操作系统的一本好书」· TEXI 代码 · 共 1,908 行 · 第 1/5 页

  [@option{-v}]
  [@option{--verbose}]
  [@option{-p} @var{tool-prefix}]
  [@option{-d} @var{directory}]
  [@option{--version}]
  [@option{--help}]
@end ignore
@c man end

@c man begin DESCRIPTION gc-analyze

@command{gc-analyze} prints an analysis of a GC memory dump to
standard out.

The memory dumps may be created by calling
@code{gnu.gcj.util.GCInfo.enumerate(String namePrefix)} from java
code.  A memory dump will be created on an out of memory condition if
@code{gnu.gcj.util.GCInfo.setOOMDump(String namePrefix)} is called
before the out of memory occurs.

Running this program will create two files: @file{TestDump001} and
@file{TestDump001.bytes}.

@example
import gnu.gcj.util.*;
import java.util.*;

public class GCDumpTest
@{
    static public void main(String args[])
    @{
        ArrayList<String> l = new ArrayList<String>(1000);
        
        for (int i = 1; i < 1500; i++) @{
            l.add("This is string #" + i);
        @}
        GCInfo.enumerate("TestDump");
    @}
@}
@end example

The memory dump may then be displayed by running:

@example
gc-analyze -v TestDump001
@end example

@c FIXME: Add real information here.
@c This really isn't much more than the --help output.

@c man end

@c man begin OPTIONS gc-analyze

@table @gcctabopt
@item --verbose
@itemx -v
Verbose output.

@item -p @var{tool-prefix}
Prefix added to the names of the @command{nm} and @command{readelf} commands.

@item -d @var{directory}
Directory that contains the executable and shared libraries used when
the dump was generated.

@item --help
Print a help message, then exit.

@item --version
Print version information, then exit.
@end table

@c man end

@node About CNI
@chapter About CNI

This documents CNI, the Compiled Native Interface,
which is is a convenient way to write Java native methods using C++.
This is a more efficient, more convenient, but less portable
alternative to the standard JNI (Java Native Interface).

@menu
* Basic concepts::              Introduction to using CNI@.
* Packages::                    How packages are mapped to C++.
* Primitive types::             Handling primitive Java types in C++.
* Reference types::             Handling Java reference types in C++.
* Interfaces::                  How Java interfaces map to C++.
* Objects and Classes::         C++ and Java classes.
* Class Initialization::        How objects are initialized.
* Object allocation::           How to create Java objects in C++.
* Memory allocation::           How to allocate and free memory.
* Arrays::                      Dealing with Java arrays in C++.
* Methods::                     Java methods in C++.
* Strings::                     Information about Java Strings.
* Mixing with C++::             How CNI can interoperate with C++.
* Exception Handling::          How exceptions are handled.
* Synchronization::             Synchronizing between Java and C++.
* Invocation::			Starting the Java runtime from C++.
* Reflection::                  Using reflection from C++.
@end menu


@node Basic concepts
@section Basic concepts

In terms of languages features, Java is mostly a subset
of C++.  Java has a few important extensions, plus a powerful standard
class library, but on the whole that does not change the basic similarity.
Java is a hybrid object-oriented language, with a few native types,
in addition to class types.  It is class-based, where a class may have
static as well as per-object fields, and static as well as instance methods.
Non-static methods may be virtual, and may be overloaded.  Overloading is
resolved at compile time by matching the actual argument types against
the parameter types.  Virtual methods are implemented using indirect calls
through a dispatch table (virtual function table).  Objects are
allocated on the heap, and initialized using a constructor method.
Classes are organized in a package hierarchy.

All of the listed attributes are also true of C++, though C++ has
extra features (for example in C++ objects may be allocated not just
on the heap, but also statically or in a local stack frame).  Because
@command{gcj} uses the same compiler technology as G++ (the GNU
C++ compiler), it is possible to make the intersection of the two
languages use the same ABI (object representation and calling
conventions).  The key idea in CNI is that Java objects are C++
objects, and all Java classes are C++ classes (but not the other way
around).  So the most important task in integrating Java and C++ is to
remove gratuitous incompatibilities.

You write CNI code as a regular C++ source file.  (You do have to use
a Java/CNI-aware C++ compiler, specifically a recent version of G++.)

@noindent A CNI C++ source file must have:

@example
#include <gcj/cni.h>
@end example

@noindent and then must include one header file for each Java class it uses, e.g.:

@example
#include <java/lang/Character.h>
#include <java/util/Date.h>
#include <java/lang/IndexOutOfBoundsException.h>
@end example

@noindent These header files are automatically generated by @code{gcjh}.


CNI provides some functions and macros to make using Java objects and
primitive types from C++ easier.  In general, these CNI functions and
macros start with the @code{Jv} prefix, for example the function
@code{JvNewObjectArray}.  This convention is used to avoid conflicts
with other libraries.  Internal functions in CNI start with the prefix
@code{_Jv_}.  You should not call these; if you find a need to, let us
know and we will try to come up with an alternate solution.


@subsection Limitations

Whilst a Java class is just a C++ class that doesn't mean that you are
freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
rules of the Java programming language.

For example: it is not possible to declare a method in a CNI class
that will take a C string (@code{char*}) as an argument, or to declare a
member variable of some non-Java datatype.


@node Packages
@section Packages

The only global names in Java are class names, and packages.  A
@dfn{package} can contain zero or more classes, and also zero or more
sub-packages.  Every class belongs to either an unnamed package or a
package that has a hierarchical and globally unique name.

A Java package is mapped to a C++ @dfn{namespace}.  The Java class
@code{java.lang.String} is in the package @code{java.lang}, which is a
sub-package of @code{java}.  The C++ equivalent is the class
@code{java::lang::String}, which is in the namespace @code{java::lang}
which is in the namespace @code{java}.

@noindent Here is how you could express this:

@example
(// @r{Declare the class(es), possibly in a header file:}
namespace java @{
  namespace lang @{
    class Object;
    class String;
    ...
  @}
@}

class java::lang::String : public java::lang::Object
@{
  ...
@};
@end example

@noindent The @code{gcjh} tool automatically generates the necessary namespace
declarations.


@subsection Leaving out package names

Always using the fully-qualified name of a java class can be
tiresomely verbose.  Using the full qualified name also ties the code
to a single package making code changes necessary should the class
move from one package to another.  The Java @code{package} declaration
specifies that the following class declarations are in the named
package, without having to explicitly name the full package
qualifiers.  The @code{package} declaration can be
followed by zero or more @code{import} declarations, which
allows either a single class or all the classes in a package to be
named by a simple identifier.  C++ provides something similar with the
@code{using} declaration and directive.

@noindent In Java:

@example
import @var{package-name}.@var{class-name};
@end example

@noindent allows the program text to refer to @var{class-name} as a shorthand for 
the fully qualified name: @code{@var{package-name}.@var{class-name}}.


@noindent To achieve the same effect C++, you have to do this:

@example
using @var{package-name}::@var{class-name};
@end example


@noindent Java can also cause imports on demand, like this:

@example
import @var{package-name}.*;
@end example

@noindent Doing this allows any class from the package @var{package-name} to be
referred to only by its class-name within the program text.


@noindent The same effect can be achieved in C++ like this:

@example
using namespace @var{package-name};
@end example


@node Primitive types
@section Primitive types

Java provides 8 @dfn{primitives} types which represent integers, floats, 
characters and booleans (and also the void type).  C++ has its own
very similar concrete types.  Such types in C++ however are not always
implemented in the same way (an int might be 16, 32 or 64 bits for example) 
so CNI provides a special C++ type for each primitive Java type:

@multitable @columnfractions .20 .25 .60
@item @strong{Java type}   @tab @strong{C/C++ typename} @tab @strong{Description}
@item @code{char}        @tab @code{jchar}          @tab 16 bit Unicode character
@item @code{boolean}     @tab @code{jboolean}       @tab logical (true or false) values
@item @code{byte}        @tab @code{jbyte}          @tab 8-bit signed integer
@item @code{short}       @tab @code{jshort}         @tab 16 bit signed integer
@item @code{int}         @tab @code{jint}           @tab 32 bit signed integer
@item @code{long}        @tab @code{jlong}          @tab 64 bit signed integer
@item @code{float}       @tab @code{jfloat}         @tab 32 bit IEEE floating point number
@item @code{double}      @tab @code{jdouble}        @tab 64 bit IEEE floating point number
@item @code{void}        @tab @code{void}           @tab no value
@end multitable

When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
to avoid disappointment.


@subsection Reference types associated with primitive types

In Java each primitive type has an associated reference type, 
e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
In order to make working with such classes easier GCJ provides the macro
@code{JvPrimClass}:

@deffn macro JvPrimClass type
Return a pointer to the @code{Class} object corresponding to the type supplied.

@example
JvPrimClass(void) @result{} java.lang.Void.TYPE
@end example

@end deffn


@node Reference types
@section Reference types

A Java reference type is treated as a class in C++.  Classes and
interfaces are handled this way.  A Java reference is translated to a
C++ pointer, so for instance a Java @code{java.lang.String} becomes,
in C++, @code{java::lang::String *}.

CNI provides a few built-in typedefs for the most common classes:
@multitable @columnfractions .30 .25 .60
@item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
@item @code{java.lang.Object} @tab @code{jobject} @tab Object type
@item @code{java.lang.String} @tab @code{jstring} @tab String type
@item @code{java.lang.Class} @tab @code{jclass} @tab Class type
@end multitable
@cindex jobject
@cindex jstring
@cindex jclass

Every Java class or interface has a corresponding @code{Class}
instance.  These can be accessed in CNI via the static @code{class$}
field of a class.  The @code{class$} field is of type @code{Class}
(and not @code{Class *}), so you will typically take the address of
it.
@cindex class$

Here is how you can refer to the class of @code{String}, which in
Java would be written @code{String.class}:

@example
using namespace java::lang;
doSomething (&String::class$);
@end example


@node Interfaces
@section Interfaces

A Java class can @dfn{implement} zero or more
@dfn{interfaces}, in addition to inheriting from
a single base class. 

@acronym{CNI} allows CNI code to implement methods of interfaces.
You can also call methods through interface references, with some
limitations.

@acronym{CNI} doesn't understand interface inheritance at all yet.  So,
you can only call an interface method when the declared type of the
field being called matches the interface which declares that
method.  The workaround is to cast the interface reference to the right
superinterface.
 
For example if you have: 

@example 
interface A 
@{ 
  void a(); 
@} 
 
interface B extends A 
@{ 
  void b(); 
@} 
@end example
 
and declare a variable of type @code{B} in C++, you can't call
@code{a()} unless you cast it to an @code{A} first.

@node Objects and Classes
@section Objects and Classes

@subsection Classes

All Java classes are derived from @code{java.lang.Object}.  C++ does
not have a unique root class, but we use the C++ class
@code{java::lang::Object} as the C++ version of the
@code{java.lang.Object} Java class.  All other Java classes are mapped
into corresponding C++ classes derived from @code{java::lang::Object}.

Interface inheritance (the @code{implements} keyword) is currently not
reflected in the C++ mapping.