/* 

  * tclPreserve.c --

  *

  *	This file contains a collection of procedures that are used

  *	to make sure that widget records and other data structures

  *	aren't reallocated when there are nested procedures that

  *	depend on their existence.

  *

  * Copyright (c) 1991-1994 The Regents of the University of California.

  * Copyright (c) 1994-1998 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: tclPreserve.c,v 1.3.34.2 2005/06/24 18:21:41 kennykb Exp $

  */

 #include "tclInt.h"

 /*

  * The following data structure is used to keep track of all the

  * Tcl_Preserve calls that are still in effect.  It grows as needed

  * to accommodate any number of calls in effect.

  */

 typedef struct {

     ClientData clientData;	/* Address of preserved block. */

     int refCount;		/* Number of Tcl_Preserve calls in effect

 				 * for block. */

     int mustFree;		/* Non-zero means Tcl_EventuallyFree was

 				 * called while a Tcl_Preserve call was in

 				 * effect, so the structure must be freed

 				 * when refCount becomes zero. */

     Tcl_FreeProc *freeProc;	/* Procedure to call to free. */

 } Reference;

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

 static Reference *refArray;	/* First in array of references. */

 static int spaceAvl = 0;	/* Total number of structures available

 				 * at *firstRefPtr. */

 static int inUse = 0;		/* Count of structures currently in use

 				 * in refArray. */

 #else

 #define refArray (*(Reference**)get_refArray())

 #define spaceAvl (*(int *)get_spaceAvl())

 #define inUse (*(int *)get_inUse())

 #endif

 #define INITIAL_SIZE 2

 TCL_DECLARE_MUTEX(preserveMutex)/* To protect the above statics */

 /*

  * The following data structure is used to keep track of whether an

  * arbitrary block of memory has been deleted.  This is used by the

  * TclHandle code to avoid the more time-expensive algorithm of

  * Tcl_Preserve().  This mechanism is mainly used when we have lots of

  * references to a few big, expensive objects that we don't want to live

  * any longer than necessary.

  */

 typedef struct HandleStruct {

     VOID *ptr;			/* Pointer to the memory block being

 				 * tracked.  This field will become NULL when

 				 * the memory block is deleted.  This field

 				 * must be the first in the structure. */

 #ifdef TCL_MEM_DEBUG

     VOID *ptr2;			/* Backup copy of the abpve pointer used to

 				 * ensure that the contents of the handle are

 				 * not changed by anyone else. */

 #endif

     int refCount;		/* Number of TclHandlePreserve() calls in

 				 * effect on this handle. */

 } HandleStruct;

 /*

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

  *

  * TclFinalizePreserve --

  *

  *	Called during exit processing to clean up the reference array.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	Frees the storage of the reference array.

  *

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

  */

 	/* ARGSUSED */

 void

 TclFinalizePreserve()

 {

     Tcl_MutexLock(&preserveMutex);

     if (spaceAvl != 0) {

         ckfree((char *) refArray);

         refArray = (Reference *) NULL;

         inUse = 0;

         spaceAvl = 0;

     }

     Tcl_MutexUnlock(&preserveMutex);

 }

 /*

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

  *

  * Tcl_Preserve --

  *

  *	This procedure is used by a procedure to declare its interest

  *	in a particular block of memory, so that the block will not be

  *	reallocated until a matching call to Tcl_Release has been made.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	Information is retained so that the block of memory will

  *	not be freed until at least the matching call to Tcl_Release.

  *

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

  */

 EXPORT_C void

 Tcl_Preserve(clientData)

     ClientData clientData;	/* Pointer to malloc'ed block of memory. */

 {

     Reference *refPtr;

     int i;

     /*

      * See if there is already a reference for this pointer.  If so,

      * just increment its reference count.

      */

     Tcl_MutexLock(&preserveMutex);

     for (i = 0, refPtr = refArray; i < inUse; i++, refPtr++) {

 	if (refPtr->clientData == clientData) {

 	    refPtr->refCount++;

 	    Tcl_MutexUnlock(&preserveMutex);

 	    return;

 	}

     }

     /*

      * Make a reference array if it doesn't already exist, or make it

      * bigger if it is full.

      */

     if (inUse == spaceAvl) {

 	if (spaceAvl == 0) {

 	    refArray = (Reference *) ckalloc((unsigned)

 		    (INITIAL_SIZE*sizeof(Reference)));

 	    spaceAvl = INITIAL_SIZE;

 	} else {

 	    Reference *new;

 	    new = (Reference *) ckalloc((unsigned)

 		    (2*spaceAvl*sizeof(Reference)));

 	    memcpy((VOID *) new, (VOID *) refArray,

                     spaceAvl*sizeof(Reference));

 	    ckfree((char *) refArray);

 	    refArray = new;

 	    spaceAvl *= 2;

 	}

     }

     /*

      * Make a new entry for the new reference.

      */

     refPtr = &refArray[inUse];

     refPtr->clientData = clientData;

     refPtr->refCount = 1;

     refPtr->mustFree = 0;

     refPtr->freeProc = TCL_STATIC;

     inUse += 1;

     Tcl_MutexUnlock(&preserveMutex);

 }

 /*

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

  *

  * Tcl_Release --

  *

  *	This procedure is called to cancel a previous call to

  *	Tcl_Preserve, thereby allowing a block of memory to be

  *	freed (if no one else cares about it).

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	If Tcl_EventuallyFree has been called for clientData, and if

  *	no other call to Tcl_Preserve is still in effect, the block of

  *	memory is freed.

  *

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

  */

 EXPORT_C void

 Tcl_Release(clientData)

     ClientData clientData;	/* Pointer to malloc'ed block of memory. */

 {

     Reference *refPtr;

     int mustFree;

     Tcl_FreeProc *freeProc;

     int i;

     Tcl_MutexLock(&preserveMutex);

     for (i = 0, refPtr = refArray; i < inUse; i++, refPtr++) {

 	if (refPtr->clientData != clientData) {

 	    continue;

 	}

 	refPtr->refCount--;

 	if (refPtr->refCount == 0) {

             /*

              * Must remove information from the slot before calling freeProc

              * to avoid reentrancy problems if the freeProc calls Tcl_Preserve

              * on the same clientData. Copy down the last reference in the

              * array to overwrite the current slot.

              */

             freeProc = refPtr->freeProc;

             mustFree = refPtr->mustFree;

 	    inUse--;

 	    if (i < inUse) {

 		refArray[i] = refArray[inUse];

 	    }

 	    if (mustFree) {

 		if (freeProc == TCL_DYNAMIC) {

 		    ckfree((char *) clientData);

 		} else {

 		    Tcl_MutexUnlock(&preserveMutex);

 		    (*freeProc)((char *) clientData);

 		    return;

 		}

 	    }

 	}

 	Tcl_MutexUnlock(&preserveMutex);

 	return;

     }

     Tcl_MutexUnlock(&preserveMutex);

     /*

      * Reference not found.  This is a bug in the caller.

      */

     panic("Tcl_Release couldn't find reference for 0x%x", clientData);

 }

 /*

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

  *

  * Tcl_EventuallyFree --

  *

  *	Free up a block of memory, unless a call to Tcl_Preserve is in

  *	effect for that block.  In this case, defer the free until all

  *	calls to Tcl_Preserve have been undone by matching calls to

  *	Tcl_Release.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	Ptr may be released by calling free().

  *

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

  */

 EXPORT_C void

 Tcl_EventuallyFree(clientData, freeProc)

     ClientData clientData;	/* Pointer to malloc'ed block of memory. */

     Tcl_FreeProc *freeProc;	/* Procedure to actually do free. */

 {

     Reference *refPtr;

     int i;

     /*

      * See if there is a reference for this pointer.  If so, set its

      * "mustFree" flag (the flag had better not be set already!).

      */

     Tcl_MutexLock(&preserveMutex);

     for (i = 0, refPtr = refArray; i < inUse; i++, refPtr++) {

 	if (refPtr->clientData != clientData) {

 	    continue;

 	}

 	if (refPtr->mustFree) {

 	    panic("Tcl_EventuallyFree called twice for 0x%x\n", clientData);

         }

         refPtr->mustFree = 1;

 	refPtr->freeProc = freeProc;

 	Tcl_MutexUnlock(&preserveMutex);

         return;

     }

     Tcl_MutexUnlock(&preserveMutex);

     /*

      * No reference for this block.  Free it now.

      */

     if (freeProc == TCL_DYNAMIC) {

 	ckfree((char *) clientData);

     } else {

 	(*freeProc)((char *)clientData);

     }

 }

 /*

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

  *

  * TclHandleCreate --

  *

  *	Allocate a handle that contains enough information to determine

  *	if an arbitrary malloc'd block has been deleted.  This is 

  *	used to avoid the more time-expensive algorithm of Tcl_Preserve().

  *

  * Results:

  *	The return value is a TclHandle that refers to the given malloc'd

  *	block.  Doubly dereferencing the returned handle will give

  *	back the pointer to the block, or will give NULL if the block has

  *	been deleted.

  *

  * Side effects:

  *	The caller must keep track of this handle (generally by storing

  *	it in a field in the malloc'd block) and call TclHandleFree()

  *	on this handle when the block is deleted.  Everything else that

  *	wishes to keep track of whether the malloc'd block has been deleted

  *	should use calls to TclHandlePreserve() and TclHandleRelease()

  *	on the associated handle.

  *

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

  */

 TclHandle

 TclHandleCreate(ptr)

     VOID *ptr;			/* Pointer to an arbitrary block of memory

 				 * to be tracked for deletion.  Must not be

 				 * NULL. */

 {

     HandleStruct *handlePtr;

     handlePtr = (HandleStruct *) ckalloc(sizeof(HandleStruct));

     handlePtr->ptr = ptr;

 #ifdef TCL_MEM_DEBUG

     handlePtr->ptr2 = ptr;

 #endif

     handlePtr->refCount = 0;

     return (TclHandle) handlePtr;

 }

 /*

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

  *

  * TclHandleFree --

  *

  *	Called when the arbitrary malloc'd block associated with the

  *	handle is being deleted.  Modifies the handle so that doubly

  *	dereferencing it will give NULL.  This informs any user of the

  *	handle that the block of memory formerly referenced by the

  *	handle has been freed.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	If nothing is referring to the handle, the handle will be reclaimed.

  *

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

  */

 void

 TclHandleFree(handle)

     TclHandle handle;		/* Previously created handle associated

 				 * with a malloc'd block that is being

 				 * deleted.  The handle is modified so that

 				 * doubly dereferencing it will give NULL. */

 {

     HandleStruct *handlePtr;

     handlePtr = (HandleStruct *) handle;

 #ifdef TCL_MEM_DEBUG

     if (handlePtr->refCount == 0x61616161) {

 	panic("using previously disposed TclHandle %x", handlePtr);

     }

     if (handlePtr->ptr2 != handlePtr->ptr) {

 	panic("someone has changed the block referenced by the handle %x\nfrom %x to %x",

 		handlePtr, handlePtr->ptr2, handlePtr->ptr);

     }

 #endif

     handlePtr->ptr = NULL;

     if (handlePtr->refCount == 0) {

 	ckfree((char *) handlePtr);

     }

 }

 /*

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

  *

  * TclHandlePreserve --

  *

  *	Declare an interest in the arbitrary malloc'd block associated

  *	with the handle.  

  *

  * Results:

  *	The return value is the handle argument, with its ref count

  *	incremented.

  *

  * Side effects:

  *	For each call to TclHandlePreserve(), there should be a matching

  *	call to TclHandleRelease() when the caller is no longer interested

  *	in the malloc'd block associated with the handle.

  *

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

  */

 TclHandle

 TclHandlePreserve(handle)

     TclHandle handle;		/* Declare an interest in the block of

 				 * memory referenced by this handle. */

 {

     HandleStruct *handlePtr;

     handlePtr = (HandleStruct *) handle;

 #ifdef TCL_MEM_DEBUG

     if (handlePtr->refCount == 0x61616161) {

 	panic("using previously disposed TclHandle %x", handlePtr);

     }

     if ((handlePtr->ptr != NULL)

 	    && (handlePtr->ptr != handlePtr->ptr2)) {

 	panic("someone has changed the block referenced by the handle %x\nfrom %x to %x",

 		handlePtr, handlePtr->ptr2, handlePtr->ptr);

     }

 #endif

     handlePtr->refCount++;

     return handle;

 }

 /*

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

  *

  * TclHandleRelease --

  *

  *	This procedure is called to release an interest in the malloc'd

  *	block associated with the handle.

  *

  * Results:

  *	None.

  *

  * Side effects:

  *	The ref count of the handle is decremented.  If the malloc'd block

  *	has been freed and if no one is using the handle any more, the

  *	handle will be reclaimed.

  *

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

  */

 void

 TclHandleRelease(handle)

     TclHandle handle;		/* Unregister interest in the block of

 				 * memory referenced by this handle. */

 {

     HandleStruct *handlePtr;

     handlePtr = (HandleStruct *) handle;

 #ifdef TCL_MEM_DEBUG

     if (handlePtr->refCount == 0x61616161) {

 	panic("using previously disposed TclHandle %x", handlePtr);

     }

     if ((handlePtr->ptr != NULL)

 	    && (handlePtr->ptr != handlePtr->ptr2)) {

 	panic("someone has changed the block referenced by the handle %x\nfrom %x to %x",

 		handlePtr, handlePtr->ptr2, handlePtr->ptr);

     }

 #endif

     handlePtr->refCount--;

     if ((handlePtr->refCount == 0) && (handlePtr->ptr == NULL)) {

 	ckfree((char *) handlePtr);

     }

 }