/* 

 * 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 */