web: port-threads doc update

[Bryce McKinlay <bryce at waitaki dot otago dot ac dot nz>]

2001-12-15  Bryce McKinlay  <bryce@waitaki.otago.ac.nz>

	* port-threads.html: Updated.

Index: port-threads.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/java/port-threads.html,v
retrieving revision 1.7
diff -u -r1.7 port-threads.html
--- port-threads.html	2001/03/16 15:20:44	1.7
+++ port-threads.html	2001/12/15 08:04:00
@@ -107,7 +107,9 @@
 performance penalty.
 
 <dt>int _Jv_MutexLock (_Jv_Mutex_t *mutex)
-<dd>Lock the mutex.  Returns 0 on success, -1 on failure.
+<dd>Lock the mutex.  Note that Java mutexes are recursive, so this function
+must maintain a lock-depth counter in the _Jv_Mutex_t if the underlying 
+platform's mutex is not recursive.  Returns 0 on success, -1 on failure.
 
 <dt>int _Jv_MutexUnlock (_Jv_Mutex_t *mutex)
 <dd>Unlock the mutex.  Returns 0 on success, -1 on failure.
@@ -117,7 +119,7 @@
 <h3>Condition Variables</h3>
 
 Condition variables are the other synchronization primitive used by
-libjava.  They are used to implement the wait and signal functions.<p>
+libjava.  They are used to implement the wait and notify functions.<p>
 
 Each condition variable has an associated mutex.  A thread acquires
 the mutex and then waits on the condition variable.  This waiting
@@ -125,7 +127,7 @@
 if it is held several times by the thread) followed by blocking.  When
 the condition variable is signalled by some other thread, the waiting
 thread reawakens, re-acquires the mutex (restoring it to its previous
-state -- the reference counting must be handled correctly), and
+state -- the lock depth counting must be handled correctly), and
 returns.  It's possible for several threads to wait on a condition
 variable at the same time, and to all be reawakened simultaneously (of
 course, only one thread at a time can re-acquire the mutex).<p>
@@ -173,8 +175,8 @@
 <h3>Everything Else</h3>
 
 There is one remaining typedef that must be defined:
-``_Jv_Thread_t''.  This is a package-specific typedef which
-represents the thread system's notion of a thread.  Each
+``_Jv_Thread_t''.  This is a typedef specific to the threads system
+which represents the thread system's notion of a thread.  Each
 ``java.lang.Thread'' object has an associated native thread object of
 this type.<p>
 
@@ -190,11 +192,18 @@
 the first thread; that is handled elsewhere.  This probably won't be
 needed by most thread packages.
 
-<dt>void _Jv_ThreadInitData (_Jv_Thread_t **data, java::lang::Thread *thread)
+<dt>_Jv_Thread_t * _Jv_ThreadInitData (java::lang::Thread *thread)
 <dd>This is called when a new Java thread object is created.  The
-thread system should allocate a new thread object and initialize it as
-needed.  The thread should not be started yet -- in Java, thread
-creation and execution are separate.
+thread system should create a new thread, allocate any data needed to assist
+the implementation of mutexes and condition variables, initialize it as
+needed, and return a pointer to it (this pointer is opaque to generic threads
+code).  The thread should not be started yet -- in Java, thread creation and 
+execution are separate.
+
+<dt>void _Jv_ThreadDestroyData (_Jv_Thread_t *data)
+<dd>This function should clean up and/or free any native resources allocated 
+for the thread in _Jv_ThreadInitData. It is called when the Java thread object 
+is finalized.  
 
 <dt>void _Jv_ThreadStart (java::lang::Thread *thread, _Jv_Thread_t *data, _Jv_ThreadStartFunc *method)
 <dd>Start running the indicated thread.  This function should examine
@@ -205,6 +214,20 @@
 
 <dt>void _Jv_ThreadWait (void)
 <dd>Wait for all non-daemon threads to exit.
+
+<dt>void _Jv_ThreadRegister (_Jv_Thread_t *data)
+<dd>This is called from a newly created thread before the run() method is 
+invoked, or when a native thread is attached to the Java runtime via 
+JvAttachThread.  It can be used to create and/or register thread-specific data
+to assist the implementation of _Jv_ThreadCurrent, for example.
+
+<dt>void _Jv_ThreadUnRegister ()
+<dd>This is called from a thread which is about to die, because its run() method
+has returned or it is being "detached" from the Java runtime.  It gives the
+thread layer a chance to clean up thread-specific data allocated in 
+_Jv_ThreadRegister. Note that the thread object may still be visible to Java, 
+so _Jv_Thread_t data should only be freed by _Jv_ThreadDestroyData.
+
 </dl>
 
 <h4>Truly Miscellaneous Functions</h4>
@@ -256,8 +279,7 @@
       <dt>Thread.stop</dt>
       <dd>These functions are unimplemented and never will be
       implemented.  They are deprecated in JDK 1.2.  The current
-      implementations simply cause the program to crash (not the best
-      idea, I admit).
+      implementations simply throw an exception.
 
     </dl>