/* 

  * tclAsync.c --

  *

  *	This file provides low-level support needed to invoke signal

  *	handlers in a safe way.  The code here doesn't actually handle

  *	signals, though.  This code is based on proposals made by

  *	Mark Diekhans and Don Libes.

  *

  * Copyright (c) 1993 The Regents of the University of California.

  * Copyright (c) 1994 Sun Microsystems, Inc.

  * Portions Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiaries. All rights reserved.  

  * 

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

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

  *

  * RCS: @(#) $Id: tclAsync.c,v 1.6.12.1 2006/07/11 13:18:10 vasiljevic Exp $

  */

 #include "tclInt.h"

 #include "tclPort.h"

 #if defined(__SYMBIAN32__) && defined(__WINSCW__)

 #include "tclSymbianGlobals.h"

 #define dataKey getdataKey(1)

 #endif 

 /* Forward declaration */

 struct ThreadSpecificData;

 /*

  * One of the following structures exists for each asynchronous

  * handler:

  */

 typedef struct AsyncHandler {

     int ready;				/* Non-zero means this handler should

 					 * be invoked in the next call to

 					 * Tcl_AsyncInvoke. */

     struct AsyncHandler *nextPtr;	/* Next in list of all handlers for

 					 * the process. */

     Tcl_AsyncProc *proc;		/* Procedure to call when handler

 					 * is invoked. */

     ClientData clientData;		/* Value to pass to handler when it

 					 * is invoked. */

     struct ThreadSpecificData *originTsd;

 					/* Used in Tcl_AsyncMark to modify thread-

 					 * specific data from outside the thread

 					 * it is associated to. */

     Tcl_ThreadId originThrdId;		/* Origin thread where this token was

 					 * created and where it will be

 					 * yielded. */

 } AsyncHandler;

 typedef struct ThreadSpecificData {

     /*

      * The variables below maintain a list of all existing handlers

      * specific to the calling thread.

      */

     AsyncHandler *firstHandler;	    /* First handler defined for process,

 				     * or NULL if none. */

     AsyncHandler *lastHandler;	    /* Last handler or NULL. */

     /*

      * The variable below is set to 1 whenever a handler becomes ready and

      * it is cleared to zero whenever Tcl_AsyncInvoke is called.  It can be

      * checked elsewhere in the application by calling Tcl_AsyncReady to see

      * if Tcl_AsyncInvoke should be invoked.

      */

     int asyncReady;

     /*

      * The variable below indicates whether Tcl_AsyncInvoke is currently

      * working.  If so then we won't set asyncReady again until

      * Tcl_AsyncInvoke returns.

      */

     int asyncActive;

     Tcl_Mutex asyncMutex;   /* Thread-specific AsyncHandler linked-list lock */

 } ThreadSpecificData;

 #if !defined(__SYMBIAN32__) || !defined(__WINSCW__)

 static Tcl_ThreadDataKey dataKey;

 #endif

 /*

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

  *

  * TclFinalizeAsync --

  *

  *	Finalizes the mutex in the thread local data structure for the

  *	async subsystem.

  *

  * Results:

  *	None.	

  *

  * Side effects:

  *	Forgets knowledge of the mutex should it have been created.

  *

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

  */

 void

 TclFinalizeAsync()

 {

     ThreadSpecificData *tsdPtr = TCL_TSD_INIT(&dataKey);

     if (tsdPtr->asyncMutex != NULL) {

 	Tcl_MutexFinalize(&tsdPtr->asyncMutex);

     }

 }

 /*

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

  *

  * Tcl_AsyncCreate --

  *

  *	This procedure creates the data structures for an asynchronous

  *	handler, so that no memory has to be allocated when the handler

  *	is activated.

  *

  * Results:

  *	The return value is a token for the handler, which can be used

  *	to activate it later on.

  *

  * Side effects:

  *	Information about the handler is recorded.

  *

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

  */

 EXPORT_C Tcl_AsyncHandler

 Tcl_AsyncCreate(proc, clientData)

     Tcl_AsyncProc *proc;		/* Procedure to call when handler

 					 * is invoked. */

     ClientData clientData;		/* Argument to pass to handler. */

 {

     AsyncHandler *asyncPtr;

     ThreadSpecificData *tsdPtr = TCL_TSD_INIT(&dataKey);

     asyncPtr = (AsyncHandler *) ckalloc(sizeof(AsyncHandler));

     asyncPtr->ready = 0;

     asyncPtr->nextPtr = NULL;

     asyncPtr->proc = proc;

     asyncPtr->clientData = clientData;

     asyncPtr->originTsd = tsdPtr;

     asyncPtr->originThrdId = Tcl_GetCurrentThread();

     Tcl_MutexLock(&tsdPtr->asyncMutex);

     if (tsdPtr->firstHandler == NULL) {

 	tsdPtr->firstHandler = asyncPtr;

     } else {

 	tsdPtr->lastHandler->nextPtr = asyncPtr;

     }

     tsdPtr->lastHandler = asyncPtr;

     Tcl_MutexUnlock(&tsdPtr->asyncMutex);

     return (Tcl_AsyncHandler) asyncPtr;

 }

 /*

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

  *

  * Tcl_AsyncMark --

  *

  *	This procedure is called to request that an asynchronous handler

  *	be invoked as soon as possible.  It's typically called from

  *	an interrupt handler, where it isn't safe to do anything that

  *	depends on or modifies application state.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	The handler gets marked for invocation later.

  *

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

  */

 EXPORT_C void

 Tcl_AsyncMark(async)

     Tcl_AsyncHandler async;		/* Token for handler. */

 {

     AsyncHandler *token = (AsyncHandler *) async;

     Tcl_MutexLock(&token->originTsd->asyncMutex);

     token->ready = 1;

     if (!token->originTsd->asyncActive) {

 	token->originTsd->asyncReady = 1;

 	Tcl_ThreadAlert(token->originThrdId);

     }

     Tcl_MutexUnlock(&token->originTsd->asyncMutex);

 }

 /*

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

  *

  * Tcl_AsyncInvoke --

  *

  *	This procedure is called at a "safe" time at background level

  *	to invoke any active asynchronous handlers.

  *

  * Results:

  *	The return value is a normal Tcl result, which is intended to

  *	replace the code argument as the current completion code for

  *	interp.

  *

  * Side effects:

  *	Depends on the handlers that are active.

  *

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

  */

 EXPORT_C int

 Tcl_AsyncInvoke(interp, code)

     Tcl_Interp *interp;			/* If invoked from Tcl_Eval just after

 					 * completing a command, points to

 					 * interpreter.  Otherwise it is

 					 * NULL. */

     int code; 				/* If interp is non-NULL, this gives

 					 * completion code from command that

 					 * just completed. */

 {

     AsyncHandler *asyncPtr;

     ThreadSpecificData *tsdPtr = TCL_TSD_INIT(&dataKey);

     Tcl_MutexLock(&tsdPtr->asyncMutex);

     if (tsdPtr->asyncReady == 0) {

 	Tcl_MutexUnlock(&tsdPtr->asyncMutex);

 	return code;

     }

     tsdPtr->asyncReady = 0;

     tsdPtr->asyncActive = 1;

     if (interp == NULL) {

 	code = 0;

     }

     /*

      * Make one or more passes over the list of handlers, invoking

      * at most one handler in each pass.  After invoking a handler,

      * go back to the start of the list again so that (a) if a new

      * higher-priority handler gets marked while executing a lower

      * priority handler, we execute the higher-priority handler

      * next, and (b) if a handler gets deleted during the execution

      * of a handler, then the list structure may change so it isn't

      * safe to continue down the list anyway.

      */

     while (1) {

 	for (asyncPtr = tsdPtr->firstHandler; asyncPtr != NULL;

 		asyncPtr = asyncPtr->nextPtr) {

 	    if (asyncPtr->ready) {

 		break;

 	    }

 	}

 	if (asyncPtr == NULL) {

 	    break;

 	}

 	asyncPtr->ready = 0;

 	Tcl_MutexUnlock(&tsdPtr->asyncMutex);

 	code = (*asyncPtr->proc)(asyncPtr->clientData, interp, code);

 	Tcl_MutexLock(&tsdPtr->asyncMutex);

     }

     tsdPtr->asyncActive = 0;

     Tcl_MutexUnlock(&tsdPtr->asyncMutex);

     return code;

 }

 /*

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

  *

  * Tcl_AsyncDelete --

  *

  *	Frees up all the state for an asynchronous handler.  The handler

  *	should never be used again.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	The state associated with the handler is deleted.

  *

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

  */

 EXPORT_C void

 Tcl_AsyncDelete(async)

     Tcl_AsyncHandler async;		/* Token for handler to delete. */

 {

     ThreadSpecificData *tsdPtr = TCL_TSD_INIT(&dataKey);

     AsyncHandler *asyncPtr = (AsyncHandler *) async;

     AsyncHandler *prevPtr;

     /*

      * Conservatively check the existence of the linked list of

      * registered handlers, as we may come at this point even

      * when the TSD's for the current thread have been already

      * garbage-collected.

      */

     Tcl_MutexLock(&tsdPtr->asyncMutex);

     if (tsdPtr->firstHandler != NULL ) {

 	if (tsdPtr->firstHandler == asyncPtr) {

 	    tsdPtr->firstHandler = asyncPtr->nextPtr;

 	    if (tsdPtr->firstHandler == NULL) {

 		tsdPtr->lastHandler = NULL;

 	    }

 	} else {

 	    prevPtr = tsdPtr->firstHandler;

 	    while (prevPtr->nextPtr != asyncPtr) {

 		prevPtr = prevPtr->nextPtr;

 	    }

 	    prevPtr->nextPtr = asyncPtr->nextPtr;

 	    if (tsdPtr->lastHandler == asyncPtr) {

 		tsdPtr->lastHandler = prevPtr;

 	    }

 	}

     }

     Tcl_MutexUnlock(&tsdPtr->asyncMutex);

     ckfree((char *) asyncPtr);

 }

 /*

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

  *

  * Tcl_AsyncReady --

  *

  *	This procedure can be used to tell whether Tcl_AsyncInvoke

  *	needs to be called.  This procedure is the external interface

  *	for checking the thread-specific asyncReady variable.

  *

  * Results:

  * 	The return value is 1 whenever a handler is ready and is 0

  *	when no handlers are ready.

  *

  * Side effects:

  *	None.

  *

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

  */

 EXPORT_C int

 Tcl_AsyncReady()

 {

     ThreadSpecificData *tsdPtr = TCL_TSD_INIT(&dataKey);

     return tsdPtr->asyncReady;

 }