From 0bb06853c3f6e4d4ff811f756245d0a4d8d0a2ee Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Tue, 5 Sep 2000 17:48:57 +0000 Subject: * doc/cni.sgml: Updated from master copy. From-SVN: r36162 --- libjava/doc/cni.sgml | 141 +++++++++------------------------------------------ 1 file changed, 24 insertions(+), 117 deletions(-) (limited to 'libjava/doc') diff --git a/libjava/doc/cni.sgml b/libjava/doc/cni.sgml index 208a6e1..0c82ca6 100644 --- a/libjava/doc/cni.sgml +++ b/libjava/doc/cni.sgml @@ -6,7 +6,7 @@ Cygnus Solutions -February, 1999 +March, 2000 @@ -369,98 +369,6 @@ to private C++ fields and methods, but other fields and methods are mapped to public fields and methods. -Non-Java fields - -When you write a Java wrapper around an existing library, that library -will often allocate and manage its own data structures. These are -objects that are not Java Objects; -instead they are usually C struct instances. -Typically, you will write a Java class, and use native CNI methods -which call functions in the C library. The problem is how to get -from the Java wrapper object to the C struct instances. -The obvious solution is to add a field to the Java object that -points to the C structure. The problem is that there is no Java -type that we can give to this field. -The GCJ solution is to define a special dummy class -gnu.gcj.RawData. This can be used as the type for fields, -parameters, array elements, or local variables in Java code. -It means that the field or variable is a pointer to a non-Java object. -Nothing else is known about it, so it corresponds to a -(void*) declaration is C or C++ code. - -The garbage collector will ignore a field that has type -gnu.gcj.RawData. You are responsible for -freeing the C data structure when you are done with it, and -performing any necessary cleanups. In most cases, you should -use a finalize method, and have it call -the library's cleanup routine. Also, the C data structure -should not contain a pointer back to the Java object, since -the garbage collector will not know about the pointer. -If you need to save a pointer to a Java object inside some -non-Java data structure, you first need to pin -or globalize the pointer; there is no CNI function -to do this yet. -(From the point of view of the -implementation, a gnu.gcj.RawData value is -the same as an integer that has the same size as a pointer.) - -Here is an example where we create a Java wrapper around C stdio: - -import gnu.gcj.RawData; - -public class StdioFile -{ - private RawData file; - public StdioFile (RawData file) { this.file = file; } - public StdioFile (String name, String mode) - throws FileNotFoundException - { init(name, mode); } - private native void init (String name, String mode) - throws FileNotFoundException; - public native int getc(); - public native int close(); - protected native void finalize(); -} - -This is the CNI implementation: - -jint -StdioFile::getc() -{ - return getc((FILE*) file); -} - -jint -StdioFile::close() -{ - return fclose((FILE*) file); -} - -void -StdioFile::init(jstring name, jstring mode) -{ - int cname_len = JvGetStringUTFLength (name); - int cmode_len = JvGetStringUTFLength (mode); - char cname[cname_len + 1]; - char cmode[cmode_len + 1]; - JvGetStringUTFRegion (name, 0, name->length(), cname); - JvGetStringUTFRegion (mode, 0, mode->length(), cmode); - cname[cname_len] = '\0'; - cmode[cmode_len] = '\0'; - file = (gnu::gcj::RawData*) fopen(cname, cmode); - if (file == NULL) - JvThrow(new java::lang::FileNotFoundException(name)); -} - -void -StdioFile::finalize() -{ - fclose((FILE*) file); -} - - - - Arrays @@ -640,7 +548,8 @@ During 1999, G++ will switch to a new ABI that is compatible with gcj. Some platforms (including Linux) have already changed. On other platforms, you will have to pass the -fvtable-thunks flag to g++ when -compiling CNI code. +compiling CNI code. Note that you must also compile +your C++ source code with -fno-rtti. Calling a Java instance method in CNI is done @@ -850,33 +759,24 @@ initialized before you access a static field. Exception Handling While C++ and Java share a common exception handling framework, -things are not quite as integrated as we would like, yet. -The main issue is the incompatible exception values, -and that the run-time type information facilities of the -two languages are not integrated. - -Basically, this means that you cannot in C++ catch an exception -value (Throwable) thrown from Java code, nor -can you use throw on a Java exception value from C++ code, -and expect to be able to catch it in Java code. -We do intend to change this. - -You can throw a Java exception from C++ code by using -the JvThrow CNI function. - - void JvThrow - jobject obj - - Throws an exception obj, in a way compatible -with the Java exception-handling functions. - The class of obj must be a subclass of - Throwable. +things are not yet perfectly integrated. The main issue is that the +run-time type information facilities of the two +languages are not integrated. + +Still, things work fairly well. You can throw a Java exception from +C++ using the ordinary throw construct, and this +exception can be caught by Java code. Similarly, you can catch an +exception thrown from Java using the C++ catch +construct. + +Note that currently you cannot mix C++ catches and Java catches in +a single C++ translation unit. We do intend to fix this eventually. Here is an example: if (i >= count) - JvThrow (new java::lang::IndexOutOfBoundsException()); + throw new java::lang::IndexOutOfBoundsException(); @@ -1044,7 +944,14 @@ as the names of classes for which headers should be generated. gcjh will generate all the required namespace declarations and #include's for the header file. -In some situations, gcjh will generate simple inline member functions. +In some situations, gcjh will generate simple inline member +functions. Note that, while gcjh puts #pragma +interface in the generated header file, you should +not put #pragma implementation +into your C++ source file. If you do, duplicate definitions of +inline functions will sometimes be created, leading to link-time +errors. + There are a few cases where gcjh will fail to work properly: -- cgit v1.1