From 8fc66e17f9378567c87e271ce2ff54b1c166cc7f Mon Sep 17 00:00:00 2001
From: bryce <bryce@138bc75d-0d04-0410-961f-82ee72b054a4>
Date: Mon, 8 Apr 2002 06:37:26 +0000
Subject: [PATCH] * gcj.texi (Invocation): Document CNI invocation API.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@52012 138bc75d-0d04-0410-961f-82ee72b054a4
---
gcc/java/ChangeLog | 4 +++
gcc/java/gcj.texi | 64 +++++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 67 insertions(+), 1 deletion(-)
diff --git a/gcc/java/ChangeLog b/gcc/java/ChangeLog
index ae7090115283..60620e60fd2d 100644
--- a/gcc/java/ChangeLog
+++ b/gcc/java/ChangeLog
@@ -1,3 +1,7 @@
+2002-04-08 Bryce McKinlay <bryce@waitaki.otago.ac.nz>
+
+ * gcj.texi (Invocation): Document CNI invocation API.
+
2002-04-04 Neil Booth <neil@daikokuya.demon.co.uk>
* expr.c (truthvalue_conversion): Rename. Update.
diff --git a/gcc/java/gcj.texi b/gcc/java/gcj.texi
index b6067ce545b1..c7776ebfb0fb 100644
--- a/gcc/java/gcj.texi
+++ b/gcc/java/gcj.texi
@@ -860,6 +860,7 @@ alternative to the standard JNI (Java Native Interface).
* 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
@@ -1544,7 +1545,7 @@ in your @acronym{CNI} classes, as long as you use the appropriate cast.
class ::MyClass : public java::lang::Object
@{
- GcjRaw string;
+ gnu.gcj.RawData string;
MyClass ();
gnu.gcj.RawData getText ();
@@ -1683,6 +1684,67 @@ of a synchronized native method to handle the synchronization
In otherwords, you need to manually add @code{JvSynchronize}
in a @code{native synchornized} method.
+@node Invocation
+@section Invocation
+
+CNI permits C++ applications to make calls into Java classes, in addition to
+allowing Java code to call into C++. Several functions, known as the
+@dfn{invocation API}, are provided to support this.
+
+@deftypefun jint JvCreateJavaVM (void* @var{vm_args})
+Initializes the Java runtime. This function performs essential initialization
+of the threads interface, garbage collector, exception handling and other key
+aspects of the runtime. It must be called once by an application with
+a non-Java @code{main()} function, before any other Java or CNI calls are made.
+It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
+once provided it is only called from a single thread.
+The @var{vmargs} parameter can be used to specify initialization parameters
+for the Java runtime. It may be @code{NULL}.
+This function returns @code{0} upon success, or @code{-1} if the runtime is
+already initialized.
+
+@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be
+used in a future release.
+@end deftypefun
+
+@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.
+@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.
+@end deftypefun
+
+@deftypefun jint JvDetachCurrentThread ()
+Unregisters a thread from the Java runtime. This should be called by threads
+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.
+@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}.
+
+@example
+// test.cc
+#include <gcj/cni.h>
+#include <java/lang/System.h>
+#include <java/io/PrintStream.h>
+
+int main(int argc, char *argv)
+@{
+ using namespace java::lang;
+
+ JvCreateJavaVM(NULL);
+ String *hello = JvNewStringLatin1("Hello from C++");
+ System::out->println(hello);
+@}
+@end example
@node Reflection
@section Reflection
--
GitLab