Patch: Document and prototype JvAllocBytes() for CNI

[Bryce McKinlay <mckinlay at redhat dot com>]

Paul Gear wrote:

> More questions along the same topic: has _Jv_AllocBytes been deprecated
> or something?  It appears in the doco at
> http://gcc.gnu.org/java/papers/cni/t1308.html
> and
> http://gcc.gnu.org/onlinedocs/gcj/Object-allocation.html#Object%20allocation
> but when i try to use it it is not defined.
>  
Yeah, it looks like this function is documented but not actually 
declared in cni.h which is odd. This patch adds the appropriate 
declaration (which is JvAllocBytes, not _Jv_AllocBytes), and improves 
the documentation a bit. I'll be checking it in shortly.

> (I'm also not sure which one of the above doco links i should be working
> from.  I'm using gcc 3.3.1 on Red Hat Linux 9.)
>
> Also, assuming _Jv_AllocBytes() is still the right thing to use, does it
> return zeroed memory?
>  
Yes.

Regards

Bryce

Index: gcc/java/gcj.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/java/gcj.texi,v
retrieving revision 1.61
diff -u -r1.61 gcj.texi
--- gcc/java/gcj.texi	23 Mar 2004 17:49:22 -0000	1.61
+++ gcc/java/gcj.texi	25 May 2004 18:53:41 -0000
@@ -1171,9 +1171,7 @@
 @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.  (This
-manual lists @code{_Jv_AllocBytes} as an example; CNI should instead
-provide a @code{JvAllocBytes} function.)
+know and we will try to come up with an alternate solution.
 
 
 @subsection Limitations
@@ -1488,9 +1486,15 @@
 java::util::Hashtable *ht = new java::util::Hashtable(120);
 @end example
 
-@deftypefun void* _Jv_AllocBytes (jsize @var{size})
-Allocates @var{size} bytes from the heap.  The memory is not scanned
-by the garbage collector but it freed if no references to it are discovered.
+@deftypefun void* JvAllocBytes (jsize @var{size})
+Allocates @var{size} bytes from the heap.  The memory returned is zeroed.
+This memory is not scanned for pointers by the garbage collector, but will 
+be freed if no references to it are discovered.
+
+This function can be useful if you need to associate some native data with a
+Java object (perhaps stored in a RawData field - @pxref{Mixing with C++,,The
+RawData Type}), 
+which is automatically freed when the Java object itself becomes unreachable.
 @end deftypefun
 
 
@@ -1784,7 +1788,9 @@
 @}
 @end example
 
-But this restriction can cause a problem so @acronym{CNI} includes the
+@section The RawData type
+
+The above restriction can cause a problem, so @acronym{CNI} includes the
 @code{gnu.gcj.RawData} class.  The @code{RawData} class is a
 @dfn{non-scanned reference} type.  In other words variables declared
 of type @code{RawData} can contain any data and are not checked by the
Index: libjava/gcj/cni.h
===================================================================
RCS file: /cvs/gcc/gcc/libjava/gcj/cni.h,v
retrieving revision 1.12
diff -u -r1.12 cni.h
--- libjava/gcj/cni.h	20 Apr 2004 01:38:45 -0000	1.12
+++ libjava/gcj/cni.h	25 May 2004 18:53:41 -0000
@@ -22,6 +22,7 @@
 
 extern "C" jstring _Jv_NewStringUTF (const char *bytes);
 extern "C" void _Jv_InitClass (jclass);
+extern "C" void *_Jv_AllocBytes (jsize size) __attribute__((__malloc__));
 
 extern inline void
 JvInitClass (jclass cls)
@@ -29,6 +30,12 @@
   return _Jv_InitClass (cls);
 }
 
+extern inline void
+JvAllocBytes (jsize sz)
+{
+  return _Jv_AllocBytes (sz);
+}
+
 extern inline jstring
 JvAllocString (jsize sz)
 {