Merged gcj-eclipse branch to trunk.

From-SVN: r120621

6 files changed, 137 insertions, 62 deletions

diff --git a/libjava/classpath/doc/.cvsignore b/libjava/classpath/doc/.cvsignore
new file mode 100644
index 0000000..1c4ea81
--- /dev/null
+++ b/libjava/classpath/doc/.cvsignore
@@ -0,0 +1,13 @@
+Makefile
+Makefile.in
+*.info
+*.aux
+*.cp
+*.dvi
+*.fn
+*.ky
+*.log
+*.pg
+*.toc
+*.tp
+*.vr
diff --git a/libjava/classpath/doc/Makefile.in b/libjava/classpath/doc/Makefile.in
index 20a8729..56bd79e 100644
--- a/libjava/classpath/doc/Makefile.in
+++ b/libjava/classpath/doc/Makefile.in
@@ -41,12 +41,14 @@ DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in texinfo.tex
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
 am__aclocal_m4_deps = $(top_srcdir)/../../config/depstand.m4 \
 	$(top_srcdir)/../../config/lead-dot.m4 \
+	$(top_srcdir)/../../config/no-executables.m4 \
 	$(top_srcdir)/../../libtool.m4 $(top_srcdir)/m4/acattribute.m4 \
 	$(top_srcdir)/m4/accross.m4 $(top_srcdir)/m4/acinclude.m4 \
 	$(top_srcdir)/m4/ax_create_stdint_h.m4 \
-	$(top_srcdir)/m4/iconv.m4 $(top_srcdir)/m4/lib-ld.m4 \
-	$(top_srcdir)/m4/lib-link.m4 $(top_srcdir)/m4/lib-prefix.m4 \
-	$(top_srcdir)/m4/pkg.m4 $(top_srcdir)/configure.ac
+	$(top_srcdir)/m4/gcc_attribute.m4 $(top_srcdir)/m4/iconv.m4 \
+	$(top_srcdir)/m4/lib-ld.m4 $(top_srcdir)/m4/lib-link.m4 \
+	$(top_srcdir)/m4/lib-prefix.m4 $(top_srcdir)/m4/pkg.m4 \
+	$(top_srcdir)/configure.ac
 am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
 	$(ACLOCAL_M4)
 mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
@@ -166,6 +168,8 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_SCRIPT = @INSTALL_SCRIPT@
 INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
 JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION = @JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION@
+JAVA_MAINTAINER_MODE_FALSE = @JAVA_MAINTAINER_MODE_FALSE@
+JAVA_MAINTAINER_MODE_TRUE = @JAVA_MAINTAINER_MODE_TRUE@
 JAY = @JAY@
 JAY_SKELETON = @JAY_SKELETON@
 JIKES = @JIKES@
@@ -287,7 +291,6 @@ target_alias = @target_alias@
 target_cpu = @target_cpu@
 target_os = @target_os@
 target_vendor = @target_vendor@
-toolexeclibdir = @toolexeclibdir@
 vm_classes = @vm_classes@
 SUBDIRS = api
 EXTRA_DIST = README.jaxp
diff --git a/libjava/classpath/doc/api/.cvsignore b/libjava/classpath/doc/api/.cvsignore
new file mode 100644
index 0000000..282522d
--- /dev/null
+++ b/libjava/classpath/doc/api/.cvsignore
@@ -0,0 +1,2 @@
+Makefile
+Makefile.in
diff --git a/libjava/classpath/doc/api/Makefile.am b/libjava/classpath/doc/api/Makefile.am
index 96c586e..b63b31f 100644
--- a/libjava/classpath/doc/api/Makefile.am
+++ b/libjava/classpath/doc/api/Makefile.am
@@ -36,6 +36,7 @@ clean-local:
 
 create_html:
 	-$(MKDIR) html > /dev/null 2>&1
+if CREATE_API_DOCS
 	$(GJDOC) \
 	-use \
 	-sourcepath "$(sourcepath)" \
@@ -51,3 +52,4 @@ create_html:
 	-header $(classpathbox) -footer $(classpathbox) \
 	-subpackages java:javax:org
 	touch create_html
+endif
diff --git a/libjava/classpath/doc/api/Makefile.in b/libjava/classpath/doc/api/Makefile.in
index 4ed24ce..231a47a 100644
--- a/libjava/classpath/doc/api/Makefile.in
+++ b/libjava/classpath/doc/api/Makefile.in
@@ -42,12 +42,14 @@ DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
 am__aclocal_m4_deps = $(top_srcdir)/../../config/depstand.m4 \
 	$(top_srcdir)/../../config/lead-dot.m4 \
+	$(top_srcdir)/../../config/no-executables.m4 \
 	$(top_srcdir)/../../libtool.m4 $(top_srcdir)/m4/acattribute.m4 \
 	$(top_srcdir)/m4/accross.m4 $(top_srcdir)/m4/acinclude.m4 \
 	$(top_srcdir)/m4/ax_create_stdint_h.m4 \
-	$(top_srcdir)/m4/iconv.m4 $(top_srcdir)/m4/lib-ld.m4 \
-	$(top_srcdir)/m4/lib-link.m4 $(top_srcdir)/m4/lib-prefix.m4 \
-	$(top_srcdir)/m4/pkg.m4 $(top_srcdir)/configure.ac
+	$(top_srcdir)/m4/gcc_attribute.m4 $(top_srcdir)/m4/iconv.m4 \
+	$(top_srcdir)/m4/lib-ld.m4 $(top_srcdir)/m4/lib-link.m4 \
+	$(top_srcdir)/m4/lib-prefix.m4 $(top_srcdir)/m4/pkg.m4 \
+	$(top_srcdir)/configure.ac
 am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
 	$(ACLOCAL_M4)
 mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
@@ -159,6 +161,8 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_SCRIPT = @INSTALL_SCRIPT@
 INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
 JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION = @JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION@
+JAVA_MAINTAINER_MODE_FALSE = @JAVA_MAINTAINER_MODE_FALSE@
+JAVA_MAINTAINER_MODE_TRUE = @JAVA_MAINTAINER_MODE_TRUE@
 JAY = @JAY@
 JAY_SKELETON = @JAY_SKELETON@
 JIKES = @JIKES@
@@ -280,7 +284,6 @@ target_alias = @target_alias@
 target_cpu = @target_cpu@
 target_os = @target_os@
 target_vendor = @target_vendor@
-toolexeclibdir = @toolexeclibdir@
 vm_classes = @vm_classes@
 @CREATE_API_DOCS_TRUE@noinst_DATA = html
 sourcepath = $(top_builddir):$(top_srcdir):$(top_srcdir)/vm/reference:$(top_srcdir)/external/w3c_dom:$(top_srcdir)/external/sax
@@ -475,21 +478,21 @@ clean-local:
 
 create_html:
 	-$(MKDIR) html > /dev/null 2>&1
-	$(GJDOC) \
-	-use \
-	-sourcepath "$(sourcepath)" \
-	-encoding UTF-8 \
-	-breakiterator \
-	-licensetext \
-	-linksource \
-	-splitindex \
-	-validhtml \
-	-d html \
-	-doctitle "GNU Classpath $(VERSION)" \
-	-windowtitle "GNU Classpath $(VERSION) Documentation" \
-	-header $(classpathbox) -footer $(classpathbox) \
-	-subpackages java:javax:org
-	touch create_html
+@CREATE_API_DOCS_TRUE@	$(GJDOC) \
+@CREATE_API_DOCS_TRUE@	-use \
+@CREATE_API_DOCS_TRUE@	-sourcepath "$(sourcepath)" \
+@CREATE_API_DOCS_TRUE@	-encoding UTF-8 \
+@CREATE_API_DOCS_TRUE@	-breakiterator \
+@CREATE_API_DOCS_TRUE@	-licensetext \
+@CREATE_API_DOCS_TRUE@	-linksource \
+@CREATE_API_DOCS_TRUE@	-splitindex \
+@CREATE_API_DOCS_TRUE@	-validhtml \
+@CREATE_API_DOCS_TRUE@	-d html \
+@CREATE_API_DOCS_TRUE@	-doctitle "GNU Classpath $(VERSION)" \
+@CREATE_API_DOCS_TRUE@	-windowtitle "GNU Classpath $(VERSION) Documentation" \
+@CREATE_API_DOCS_TRUE@	-header $(classpathbox) -footer $(classpathbox) \
+@CREATE_API_DOCS_TRUE@	-subpackages java:javax:org
+@CREATE_API_DOCS_TRUE@	touch create_html
 # Tell versions [3.59,3.63) of GNU make to not export all variables.
 # Otherwise a system limit (for SysV at least) may be exceeded.
 .NOEXPORT:
diff --git a/libjava/classpath/doc/vmintegration.texinfo b/libjava/classpath/doc/vmintegration.texinfo
index e7f85d0..6d59b5d 100644
--- a/libjava/classpath/doc/vmintegration.texinfo
+++ b/libjava/classpath/doc/vmintegration.texinfo
@@ -144,7 +144,7 @@ A simple, small bytecode interpreter that works out-of-the-box with
 pure GNU Classpath; it is emerging as the preferred platform for
 quickly testing a new build of GNU Classpath.  Licensed under the GPL.
 
-@item @uref{http://oss.software.ibm.com/jikesrvm,Jikes RVM}
+@item @uref{http://jikesrvm.sourceforge.net/,Jikes RVM}
 A free runtime environment for Java, written in Java.  Works
 out-of-the-box with pure GNU Classpath.  Features an optimizing JIT.
 Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
@@ -1859,8 +1859,7 @@ Classpath places a few requirements on the VM that uses it.
 
 Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
 in the JNI Invocation API: GetEnv().  And GetEnv() is only used in the
-``portable native sync'' code, so it's only actually used by Jikes RVM
-and Kaffe.  
+now deprecated ``portable native sync'' code.
 
 A future direction will probably be to require that all VMs provide
 JNI 1.2.  If this poses problems, please raise them on the classpath
@@ -1870,42 +1869,95 @@ mailing list.
 @comment  node-name,  next,  previous,  up
 @section VM Threading Model
 
-Classpath's AWT peers use GTK+.  GTK+ uses GLIB.  Normally, Classpath
-will initialize GLIB's @dfn{gthreads} to use
-the platform's native threading model@footnote{The native threading
-model is pthreads on Linux and AIX, the two platforms Classpath
-currently runs on.}
-
-If the Java runtime doesn't use the native threading model, then you
-will want Classpath to tell GLIB to use the Java threading primitives
-instead.  Otherwise, GLIB would use the native threading model to
-perform operations such as creating thread-local data, and that just
-doesn't work on systems (such as Kaffe in some configurations, and
-such as Jikes RVM) that use @i{m}:@i{n} threading.
-
-Historically, enabling the Java threading primitives had been done at
-build time, by configuring classpath with the
-@option{--portable-native-sync} option.  This had bad consequences,
-though -- it meant that the prebuild GNU Classpath package distributed
-with Debian GNU/Linux would not be usable with VMs that could
-otherwise have used it.  Instead, we encourage
-the use of the Java system property
-@code{gnu.classpath.awt.gtk.portable.native.sync}.  A VM that wants
-GLIB to use the Java threading primitives should modify
-@code{VMRuntime.insertSystemProperties()} to include code like the
-following:
-
-@example
-static void insertSystemProperties(Properties @var{p}) 
-@end example
-...
-@example
-@var{p}.put("gnu.classpath.awt.gtk.portable.native.sync", "true");
-@end example
-
-So, the configure option
-@option{--portable-native-sync} is deprecated, and should go away in a
-subsequent release of GNU Classpath.
+VM authors can implement a number of different threading models. When
+native code is also threaded there is the potential for one threading
+model to deadlock the other. The
+@uref{http://java.sun.com/docs/books/jni/html/other.html#29406,Java
+Native Interface Programmer's Guide and Specification} suggests
+consulting VM documentation in such situations. Classpath uses
+existing libraries, for example the AWT peers can use the GTK+
+graphics library. As these libraries assume a different threading
+model, there is the potential for the native code to deadlock a VM.
+
+The different threading models available to a VM author are:
+@enumerate
+@item
+@i{Native threads}: Map a Java thread to an underlying operating system
+thread (normally a POSIX compatible pthread). This approach reduces
+the potential for deadlock as there is only one thread scheduling
+mechanism.
+@item
+@i{Green threads 1}: Green threads are threads scheduled by the VM,
+typically by switching swapping registers. In early VMs green threads
+were seen as advantageous as they didn't require the operating system
+to resechedule, save and swap all of a threads registers. The green
+thread 1 model switches thread on an externally created event, such as
+a timer interrupt. An example of a VM using this approach is Kaffe
+configured with its jthreads model.
+@item
+@i{Green threads 2}: The essential difference with this model is to
+not switch threads on an event, but at fixed points in the code being
+executed by the VM. Points chosen could be backward branches (loops)
+or method calls. This approach can be advantageous to nonconservative
+garbage collectors, as non-running threads would be at known points
+and can have fixed register maps. It can also reduce the number of
+registers it is necessary to swap when switching threads.
+@item
+@i{M:N threading}: a flaw to green threading is that it is unable to
+use multiple processors. @i{M}:@i{N} threading fixes this problem by
+running groups of green threads on multiple underlying native
+threads. An example of a VM using this approach is the Jikes RVM,
+which uses @i{M}:@i{N} threading combined with the green thread 2
+model.
+@end enumerate
+
+An example of the problem of mixing threading models is:
+@itemize @bullet
+@item
+A Java thread calls a native method. The native method aquires a lock.
+@item
+The native method calls back into the VM.
+@item
+An event triggers the VM to reschedule the currently running thread.
+@item
+A new VM thread, executing on the same underlying native thread, calls
+a native method.
+@item
+The native method tries to aquire the lock already aquired earlier. As
+the lock is busy the thread waits and allows the operating system to
+reschedule native threads.
+@item
+The operating system reschedules the VM thread again, but the lock is
+still busy and in some threading models will remain busy forever
+(the VM is deadlocked).
+@end itemize
+
+VMs that don't use the underlying operating system thread scheduling
+mechanism need to avoid deadlock. One now deprecated approach was to
+build Classpath and VMs on top of a wrapper thread library (aka
+portable native sync). The wrapper thread library used was GLIB's
+@dfn{gthreads}. This approach has been deprecated because:
+@enumerate
+@item
+The wrapper library is only in use by some native libraries. For
+example, GTK+ uses the gthread library but QT does not.
+@item
+The wrapper library can't be in use prior to the VM starting as the VM
+must replace the wrapper libraries functions with its own. This
+prevents the VM from running as a plugin in an application that
+already uses the wrapper library.
+@end enumerate
+
+An alternative approach is for the VM to detect deadlocked native code
+and swap Java threads off of that native thread. The VM can't,
+however, swap two blocked native threads that are potentially
+deadlocking each other on a lock. The lock will be associated with the
+native thread. To prevent this from happening the VM must hijack
+functions that operate on locks. This is done by redifining the lock
+functions inside the VM and configuring the linker so that it uses the
+VMs symbol in preference to that of the external thread support
+library. The VM's lock function can then reschedule Java threads if it
+must wait for the lock.
 
 @node Boot Library Path Property,  , VM Threading Model, Miscellaneous VM Requirements
 @comment  node-name,  next,  previous,  up