/* 

  * tclThreadJoin.c --

  *

  *	This file implements a platform independent emulation layer for

  *	the handling of joinable threads. The Mac and Windows platforms

  *	use this code to provide the functionality of joining threads.

  *	This code is currently not necessary on Unix.

  *

  * Copyright (c) 2000 by Scriptics Corporation

  *

  * See the file "license.terms" for information on usage and redistribution

  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.

  *

  * RCS: @(#) $Id: tclThreadJoin.c,v 1.4 2002/04/24 20:35:40 hobbs Exp $

  */

 #include "tclInt.h"

 #if defined(WIN32) || defined(MAC_TCL)

 /* The information about each joinable thread is remembered in a

  * structure as defined below.

  */

 typedef struct JoinableThread {

   Tcl_ThreadId  id;                     /* The id of the joinable thread */

   int           result;                 /* A place for the result after the

 					 * demise of the thread */

   int           done;                   /* Boolean flag. Initialized to 0

 					 * and set to 1 after the exit of

 					 * the thread. This allows a thread

 					 * requesting a join to detect when

 					 * waiting is not necessary. */

   int           waitedUpon;             /* Boolean flag. Initialized to 0

 					 * and set to 1 by the thread waiting

 					 * for this one via Tcl_JoinThread.

 					 * Used to lock any other thread

 					 * trying to wait on this one.

 					 */

   Tcl_Mutex     threadMutex;            /* The mutex used to serialize access

 					 * to this structure. */

   Tcl_Condition cond;                   /* This is the condition a thread has

 					 * to wait upon to get notified of the

 					 * end of the described thread. It is

 					 * signaled indirectly by

 					 * Tcl_ExitThread. */

   struct JoinableThread* nextThreadPtr; /* Reference to the next thread in the

 					 * list of joinable threads */

 } JoinableThread;

 /* The following variable is used to maintain the global list of all

  * joinable threads. Usage by a thread is allowed only if the

  * thread acquired the 'joinMutex'.

  */

 TCL_DECLARE_MUTEX(joinMutex)

 static JoinableThread* firstThreadPtr;

 /*

  *----------------------------------------------------------------------

  *

  * TclJoinThread --

  *

  *	This procedure waits for the exit of the thread with the specified

  *	id and returns its result.

  *

  * Results:

  *	A standard tcl result signaling the overall success/failure of the

  *	operation and an integer result delivered by the thread which was

  *	waited upon.

  *

  * Side effects:

  *	Deallocates the memory allocated by TclRememberJoinableThread.

  *	Removes the data associated to the thread waited upon from the

  *	list of joinable threads.

  *

  *----------------------------------------------------------------------

  */

 int

 TclJoinThread(id, result)

     Tcl_ThreadId id;     /* The id of the thread to wait upon. */

     int*         result; /* Reference to a location for the result

 			  * of the thread we are waiting upon. */

 {

     /* Steps done here:

      * i.    Acquire the joinMutex and search for the thread.

      * ii.   Error out if it could not be found.

      * iii.  If found, switch from exclusive access to the list to exclusive

      *       access to the thread structure.

      * iv.   Error out if some other is already waiting.

      * v.    Skip the waiting part of the thread is already done.

      * vi.   Wait for the thread to exit, mark it as waited upon too.

      * vii.  Get the result form the structure, 

      * viii. switch to exclusive access of the list,

      * ix.   remove the structure from the list,

      * x.    then switch back to exclusive access to the structure

      * xi.   and delete it.

      */

     JoinableThread* threadPtr;

     Tcl_MutexLock (&joinMutex);

     for (threadPtr = firstThreadPtr;

 	 (threadPtr != (JoinableThread*) NULL) && (threadPtr->id != id);

 	 threadPtr = threadPtr->nextThreadPtr)

         /* empty body */

       ;

     if (threadPtr == (JoinableThread*) NULL) {

         /* Thread not found. Either not joinable, or already waited

 	 * upon and exited. Whatever, an error is in order.

 	 */

       Tcl_MutexUnlock (&joinMutex);

       return TCL_ERROR;

     }

     /* [1] If we don't lock the structure before giving up exclusive access

      * to the list some other thread just completing its wait on the same

      * thread can delete the structure from under us, leaving us with a

      * dangling pointer.

      */

     Tcl_MutexLock   (&threadPtr->threadMutex);

     Tcl_MutexUnlock (&joinMutex);

     /* [2] Now that we have the structure mutex any other thread that just

      * tries to delete structure will wait at location [3] until we are

      * done with the structure. And in that case we are done with it

      * rather quickly as 'waitedUpon' will be set and we will have to

      * error out.

      */

     if (threadPtr->waitedUpon) {

         Tcl_MutexUnlock (&threadPtr->threadMutex);

 	return TCL_ERROR;

     }

     /* We are waiting now, let other threads recognize this

      */

     threadPtr->waitedUpon = 1;

     while (!threadPtr->done) {

       Tcl_ConditionWait (&threadPtr->cond, &threadPtr->threadMutex, NULL);

     }

     /* We have to release the structure before trying to access the list

      * again or we can run into deadlock with a thread at [1] (see above)

      * because of us holding the structure and the other holding the list.

      * There is no problem with dangling pointers here as 'waitedUpon == 1'

      * is still valid and any other thread will error out and not come to

      * this place. IOW, the fact that we are here also means that no other

      * thread came here before us and is able to delete the structure.

      */

     Tcl_MutexUnlock (&threadPtr->threadMutex);

     Tcl_MutexLock   (&joinMutex);

     /* We have to search the list again as its structure may (may, almost

      * certainly) have changed while we were waiting. Especially now is the

      * time to compute the predecessor in the list. Any earlier result can

      * be dangling by now.

      */

     if (firstThreadPtr == threadPtr) {

         firstThreadPtr = threadPtr->nextThreadPtr;

     } else {

         JoinableThread* prevThreadPtr;

 	for (prevThreadPtr = firstThreadPtr;

 	     prevThreadPtr->nextThreadPtr != threadPtr;

 	     prevThreadPtr = prevThreadPtr->nextThreadPtr)

 	    /* empty body */

 	  ;

 	prevThreadPtr->nextThreadPtr = threadPtr->nextThreadPtr;

     }

     Tcl_MutexUnlock (&joinMutex);

     /* [3] Now that the structure is not part of the list anymore no other

      * thread can acquire its mutex from now on. But it is possible that

      * another thread is still holding the mutex though, see location [2].

      * So we have to acquire the mutex one more time to wait for that thread

      * to finish. We can (and have to) release the mutex immediately.

      */

     Tcl_MutexLock   (&threadPtr->threadMutex);

     Tcl_MutexUnlock (&threadPtr->threadMutex);

     /* Copy the result to us, finalize the synchronisation objects, then

      * free the structure and return.

      */

     *result = threadPtr->result;

     Tcl_ConditionFinalize (&threadPtr->cond);

     Tcl_MutexFinalize (&threadPtr->threadMutex);

     ckfree ((VOID*) threadPtr);

     return TCL_OK;

 }

 /*

  *----------------------------------------------------------------------

  *

  * TclRememberJoinableThread --

  *

  *	This procedure remebers a thread as joinable. Only a call to

  *	TclJoinThread will remove the structre created (and initialized)

  *	here. IOW, not waiting upon a joinable thread will cause memory

  *	leaks.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	Allocates memory, adds it to the global list of all joinable

  *	threads.

  *

  *----------------------------------------------------------------------

  */

 VOID

 TclRememberJoinableThread(id)

     Tcl_ThreadId id; /* The thread to remember as joinable */

 {

     JoinableThread* threadPtr;

     threadPtr = (JoinableThread*) ckalloc (sizeof (JoinableThread));

     threadPtr->id          = id;

     threadPtr->done        = 0;

     threadPtr->waitedUpon  = 0;

     threadPtr->threadMutex = (Tcl_Mutex) NULL;

     threadPtr->cond        = (Tcl_Condition) NULL;

     Tcl_MutexLock (&joinMutex);

     threadPtr->nextThreadPtr = firstThreadPtr;

     firstThreadPtr           = threadPtr;

     Tcl_MutexUnlock (&joinMutex);

 }

 /*

  *----------------------------------------------------------------------

  *

  * TclSignalExitThread --

  *

  *	This procedure signals that the specified thread is done with

  *	its work. If the thread is joinable this signal is propagated

  *	to the thread waiting upon it.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	Modifies the associated structure to hold the result.

  *

  *----------------------------------------------------------------------

  */

 VOID

 TclSignalExitThread(id,result)

     Tcl_ThreadId id;     /* Id of the thread signaling its exit */

     int          result; /* The result from the thread */

 {

     JoinableThread* threadPtr;

     Tcl_MutexLock (&joinMutex);

     for (threadPtr = firstThreadPtr;

 	 (threadPtr != (JoinableThread*) NULL) && (threadPtr->id != id);

 	 threadPtr = threadPtr->nextThreadPtr)

         /* empty body */

       ;

     if (threadPtr == (JoinableThread*) NULL) {

         /* Thread not found. Not joinable. No problem, nothing to do.

 	 */

         Tcl_MutexUnlock (&joinMutex);

 	return;

     }

     /* Switch over the exclusive access from the list to the structure,

      * then store the result, set the flag and notify the waiting thread,

      * provided that it exists. The order of lock/unlock ensures that a

      * thread entering 'TclJoinThread' will not interfere with us.

      */

     Tcl_MutexLock   (&threadPtr->threadMutex);

     Tcl_MutexUnlock (&joinMutex);

     threadPtr->done   = 1;

     threadPtr->result = result;

     if (threadPtr->waitedUpon) {

       Tcl_ConditionNotify (&threadPtr->cond);

     }

     Tcl_MutexUnlock (&threadPtr->threadMutex);

 }

 #endif /* WIN32 || MAC_TCL */