except.c (choose_personality_routine): Export.

gcc/cp:
	* except.c (choose_personality_routine): Export.  Add
	explanatory comment.  Take an enum languages, not a boolean.
	(initialize_handler_parm): Adjust to match.
	* cp-tree.h: Prototype choose_personality_routine.
	* lex.c (handle_pragma_java_exceptions): New function.
	(init_cp_pragma): Register #pragma GCC java_exceptions.

gcc:
	* extend.texi: Document #pragma GCC java_exceptions.

libjava:
	* Makefile.am (libgcj_la_OBJECTS): Remove libsupc++convenience.la.
	* Makefile.in: Regenerate (by hand).
	* include/jvm.h: Add #pragma GCC java_exceptions at top of file.
	* doc/cni.sgml: Document #pragma GCC java_exceptions.

From-SVN: r42027

1 files changed, 25 insertions, 0 deletions

diff --git a/libjava/doc/cni.sgml b/libjava/doc/cni.sgml
index 0c82ca67ddd..495e3e9c5a5 100644
--- a/libjava/doc/cni.sgml
+++ b/libjava/doc/cni.sgml
@@ -779,6 +779,31 @@ if (i >= count)
    throw new java::lang::IndexOutOfBoundsException();
 </programlisting>
 </para>
+<para>
+Normally, GNU C++ will automatically detect when you are writing C++
+code that uses Java exceptions, and handle them appropriately.
+However, if C++ code only needs to execute destructors when Java
+exceptions are thrown through it, GCC will guess incorrectly.  Sample
+problematic code:
+<programlisting>
+  struct S { ~S(); };
+  extern void bar();    // is implemented in Java and may throw exceptions
+  void foo()
+  {
+    S s;
+    bar();
+  }
+</programlisting>
+The usual effect of an incorrect guess is a link failure, complaining of
+a missing routine called <literal>__gxx_personality_v0</literal>.
+</para>
+<para>
+You can inform the compiler that Java exceptions are to be used in a
+translation unit, irrespective of what it might think, by writing
+<literal>#pragma GCC java_exceptions</literal> at the head of the
+file.  This <literal>#pragma</literal> must appear before any
+functions that throw or catch exceptions, or run destructors when
+exceptions are thrown through them.</para>
 </sect1>
 
 <sect1><title>Synchronization</title>