mirrors/gcc
0
0
Fork 0
mirror of https://gcc.gnu.org/git/gcc.git synced 2025-01-22 12:24:38 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

* doc/cni.sgml: Document RawData.

Browse Source 
From-SVN: r26791
This commit is contained in:
Per Bothner 1999-05-05 16:15:04 -07:00
parent cd9643f75b
commit 148017e025
1 changed files with 92 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
libjava/doc/cni.sgml
View File

@ -369,6 +369,98 @@ to private C++ fields and methods, but other fields and methods
are mapped to public fields and methods.
</para>
</sect2>
<sect2><title>Non-Java fields</title>
<para>
When you write a Java wrapper around an existing library, that library
will often allocate and manage its own data structures. These are
<quote>objects</quote> that are not Java <literal>Object</literal>s;
instead they are usually C <literal>struct</literal> 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 <literal>struct</literal> 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.</para>
<para>The GCJ solution is to define a special dummy class
<literal>gnu.gcj.RawData</literal>. 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
<literal>(void*)</literal> declaration is C or C++ code.</para>
<para>
The garbage collector will ignore a field that has type
<literal>gnu.gcj.RawData</literal>. 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 <literal>finalize</literal> 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 <quote>pin</quote>
or <quote>globalize</quote> the pointer; there is no CNI function
to do this yet.
(From the point of view of the
implementation, a <literal>gnu.gcj.RawData</literal> value is
the same as an integer that has the same size as a pointer.)</para>
<para>
Here is an example where we create a Java wrapper around C stdio:
<programlisting>
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();
}
</programlisting>
This is the CNI implementation:
<programlisting>
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);
}
</programlisting>
</sect2>
</sect1>
<sect1><title>Arrays</title>