Re: Document CNI invocation functions

[Bryce McKinlay <bryce at waitaki dot otago dot ac dot nz>]

Per Bothner wrote:

> It's a little unclear on when JvAttachCurrentThread needs to be called.
> Your example does not call it.   Should it?  (I don't know.)


Oops - yes it should. This update should clarify that. I've also added a 
note about needing to handle uncaught exceptions  from Java code and 
updated the example to do so.

regards

Bryce.

2002-04-08  Bryce McKinlay  <bryce@waitaki.otago.ac.nz>

	* gcj.texi (Invocation): Update JvAttachCurrentThread documentation.
	Add note about handling uncaught exceptions. Add an exception handler
	to example.
	
Index: gcj.texi
===================================================================
RCS file: /cvs/gcc/egcs/gcc/java/gcj.texi,v
retrieving revision 1.26
diff -u -r1.26 gcj.texi
--- gcj.texi	8 Apr 2002 06:37:26 -0000	1.26
+++ gcj.texi	8 Apr 2002 12:02:20 -0000
@@ -1709,13 +1709,16 @@
 
 @deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
 Registers an existing thread with the Java runtime.  This must be called once
-by a multi-threaded C++ application for each thread, before that thread makes
-any other Java or CNI calls.
+from each thread, before that thread makes any other Java or CNI calls. It
+must be called after @code{JvCreateJavaVM}.
 @var{name} specifies a name for the thread. It may be @code{NULL}, in which 
 case a name will be generated.
 @var{group} is the ThreadGroup in which this thread will be a member. If it
 is @code{NULL}, the thread will be a member of the main thread group.
 The return value is the Java @code{Thread} object that represents the thread.
+It is safe to call @code{JvAttachCurrentThread()} more than once from the same
+thread. If the thread is already attached, the call is ignored and the current
+thread object is returned.
 @end deftypefun
 
 @deftypefun jint JvDetachCurrentThread ()
@@ -1723,26 +1726,57 @@
 that were attached using @code{JvAttachCurrentThread()}, after they have 
 finished making calls to Java code. This ensures that any resources associated
 with the thread become eligible for garbage collection.
-This function returns @code{0} upon success.
+This function returns @code{0} upon success, or @code{-1} if the current thread
+is not attached.
 @end deftypefun
 
-The following example demonstrates the use of @code{JvCreateJavaVM()} from
-a simple C++ application. It can be compiled with 
-@command{c++ test.cc -lgcj}.
+@subsection Handling uncaught exceptions
+
+If an exception is thrown from Java code called using the invocation API, and
+no handler for the exception can be found, the runtime will abort the
+application. In order to make the application more robust, it is recommended 
+that code which uses the invocation API be wrapped by a top-level try/catch 
+block that catches all Java exceptions.
+
+@subsection Example
+
+The following code demonstrates the use of the invocation API. In this
+example, the C++ application initializes the Java runtime and attaches
+itself. The @code{java.lang.System} class is initialized in order to
+access its @code{out} field, and a Java string is printed. Finally, the thread
+is detached from the runtime once it has finished making Java calls. Everything
+is wrapped with a try/catch block to provide a default handler for any uncaught 
+exceptions.
+
+The example can be compiled with @command{c++ test.cc -lgcj}.
 
 @example
 // test.cc
 #include <gcj/cni.h>
 #include <java/lang/System.h>
 #include <java/io/PrintStream.h>
+#include <java/lang/Throwable.h>
 
 int main(int argc, char *argv)
 @{
   using namespace java::lang;
   
-  JvCreateJavaVM(NULL);
-  String *hello = JvNewStringLatin1("Hello from C++");
-  System::out->println(hello);
+  try
+  @{
+    JvCreateJavaVM(NULL);
+    JvAttachCurrentThread(NULL, NULL);
+
+    String *message = JvNewStringLatin1("Hello from C++");
+    JvInitClass(&System.class$);
+    System::out->println(message);
+
+    JvDetachCurrentThread();
+  @}
+  catch (Throwable *t)
+  @{
+    System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
+    t->printStackTrace();
+  @}
 @}
 @end example