README Java Solaris Native Threads Pack Version 1.1.8 ----------------------------------------------------------------------- CONTENTS Overview of the Native Threads Pack System Requirements Installation Using the Native Threads Pack - The THREADS_FLAG environment variable - The -native and -green convenience options ======================================================================= OVERVIEW OF THE NATIVE THREADS PACK ----------------------------------------------------------------------- When you install the Native Threads Pack, the Java virtual machine (VM) is able to use native threads when running Java code. Native threads can provide several advantages over the default threads package (called green threads), depending on your computing situation. Among the benefits of using the native threads VM are: - If you run Java code in a multi-processor environment, the Solaris kernel can schedule native threads on the parallel processors for increased performance. By contrast, green threads exist only at the user-level and are not mapped to multiple kernel threads by the operating system. Performance enhancement from parallelism cannot be realized using green threads. - The native threads VM can call into C libraries that use Solaris native threads. Such libraries cannot be used with green threads. - When using the native threads, the VM can avoid some inefficient remapping of I/O system calls that are necessary when green threads are used. In some instances, it may be advisable to use the default green threads. Native code that is not multithread safe (MT-safe) may not work correctly with native threads. In general, if you aren't using the native Solaris threads mechanisms directly, then you need to compile your native code with the option -D_REENTRANT to make sure that they work correctly in a threaded environment. You may also need to use reentrant versions of certain Solaris interfaces. Specific information concerning multithreaded programming on Solaris may be found in the Multithreaded Programming Guide of the Solaris Software Developer AnswerBook. This information is also available at http://docs.sun.com. Navigate to the Tools link under the Programming heading and go to the link "Solaris 2.6 Software Developer Collection Vol. 1". It is possible that thread-synchronization bugs in code that you run may be hidden when using green threads, but may manifest themselves when run under native threads. You should consider this possibility if your code runs differently under the two threads packages. The Native Threads Pack has not been tested in conjunction with any JIT compiler, and its use with JIT compilers is not recommended. If you encounter any problems or bugs with the Native Threads Pack, please report them via the JavaSoft bug submission web page at http://java.sun.com/cgi-bin/bugreport.cgi. Please select the "runtime" subcategory when reporting a bug against the Native Threads Pack. ======================================================================= SYSTEM REQUIREMENTS ----------------------------------------------------------------------- Version 1.1.8 of the JRE or JDK software must be installed on your machine prior to the installation of the Native Threads Pack. To use Solaris Native Threads, you need Solaris 2.5.1, Solaris 2.6, or Solaris 7. Earlier versions of Solaris, including Solaris 2.5, are not supported. To support Native Threads, Solaris 2.5.1 needs two patches which resolve thread synchronization problems. On Solaris-SPARC, the required patches are 103566-08 and 103640-08. On Solaris-x86, the required patches are 104241-01 and 103641-08. The last two digits of the patch numbers indicate the patch version; you can use the indicated patch versions or later versions of the same patches. To determine which patches are installed, use the shell command "showrev": % showrev -p You can obtain patches from your warranty provider, from SunService (if you have a SunSpectrum contract) or from the SunSolve web site. To obtain these patches from the SunSolve web site: 1. Access the web site at http://sunsolve.sun.com/. 2. Choose the "Public Patches" link. 3. Download either the Solaris 2.5.1 Recommended Patch Cluster or the Solaris 2.5.1 x86_Recommended Patch Cluster. 4. Follow the instructions in the Patch Cluster README, available from the "Public Patches" page. See http://java.sun.com/products/jdk/1.2/install-solaris-patches.html for more information on Solaris patches. ======================================================================= 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. ----------------------------------------------------------------------- Copyright © 1997-1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, CA 94303-4900. USA All rights reserved.