README

                   Java Linux Native Threads Pack
                         Version 1.1.7 v1a

=======================================================================
                           INSTALLATION
-----------------------------------------------------------------------

To use the native threads package, you must first install the matching
JDK release.  Then, the matching native thread package must be installed
at the same location.  This package adds some directories to the JDK
tree.  For example, the x86 install would best be done as:

	% tar -zxf jdk_1.1.7-v1a-x86-glibc.tar.gz
	% tar -zxf jdk_1.1.7-v1a-x86-glibc-native.tar.gz

This will make the JDK directory tree in "jdk117_v1a"

=======================================================================
                    USING THE NATIVE THREADS PACK
-----------------------------------------------------------------------

The THREADS_FLAG Environment Variable ---------------------------------

All the tools in the JDK use green threads as a default. To specify
that native threads should be used, set the THREADS_FLAG environment
variable:

        % setenv THREADS_FLAG native

You can revert to use of green threads by setting THREADS_FLAG to
the value green:

        % setenv THREADS_FLAG green


The -native and -green Convenience Options ----------------------------

You can specify that the JDK tools should use either native threads or
green threads by using the -native and -green convenience options. If
you use -native or -green, they must be the first option specified on
the command line.

The convenience options can be used as in these examples:

        % java -native mypkg.MyClass
        % javac -native MyClass.java
        % appletviewer -green MyApplet.html

The convenience options override the setting of the THREADS_FLAG
environment variable.


Native Threads support
----------------------

Starting with the 1.1.7 v1a port of the Java Virtual Machine, we have
added native thread support.  Traditionally, the JVM used user based
threads, also known as "green" threads.  Native threads, on the other
hand, use the operating system to do the task switching.

Native threads are thus a benefit in multi-processor (SMP) systems
and they tend to make native method invocation support easier to
deal with.

Native threads do have some limitations relative to green threads.
They require more overhead and are limited to the number of processes
your Linux kernel supports.

Native thread support is new as of 1.1.7 v1a due to the wonderful
effort of Phill Edwards.

To install the native threads package, you need to first download
the JDK, JRE, RT and install that.  Next, you need to get the matching
native threads package and install that into the same location.
Finally, to use the native threads version of the JVM, you need
to set the THREADS_FLAG environment variable to "native"

Note, that while the native threads support works very well and has
been tested by the Java-Linux porting team, it should still be viewed
as "beta" code as it has not had the extended testing that the
green threads code has.

Also, at this time there is no native threads support for libc5 systems.
Only glibc based Linux systems.


Native Threads vs Green Threads
-------------------------------

This release includes both green and native threads.  Green threads are
user based theads that have been part of the JDK since its inception.
Green threads  are very stable, have a lower memory footprint, and
involve much lower overhead for creation and context switching.

Native threads are linux threads (one-to-one implementation of pthreads)
and are kernel based.  Each thread is basically a clone of the its
parent process and therefore has a higher overhead for context
switching and creation and a larger memory footprint.  Because they
are processes, the number of threads is limited by the number of
processes/tasks built into the Linux kernel. You will have to recompile
your kernel to handle larger number of threads.

So why use native threads? Native threads deal better with some JNI
native C programs than green_threads because you do not have to make
all io non-blocking and therefore do not have to redefine all of the
system calls related to io.  But the main reason to use native
threads is that on multi-processor systems, native threads can be
easily split among processors greatly improving performance while
green_threads can not.  Although on single processor systems, green
threads will probably be faster for most programs.