Getting more systematic about style

1 files changed, 142 insertions, 130 deletions

diff --git a/generic/tclPreserve.c b/generic/tclPreserve.c
index cea5725..8281bc4 100644
--- a/generic/tclPreserve.c
+++ b/generic/tclPreserve.c
@@ -1,71 +1,73 @@
-/* 
+/*
  * 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.
+ *	This file contains a collection of functions that are used to make
+ *	sure that widget records and other data structures aren't reallocated
+ *	when there are nested functions that depend on their existence.
  *
  * Copyright (c) 1991-1994 The Regents of the University of California.
  * Copyright (c) 1994-1998 Sun Microsystems, Inc.
  *
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * 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.6 2005/06/24 20:07:22 kennykb Exp $
+ * RCS: @(#) $Id: tclPreserve.c,v 1.7 2005/07/24 22:56:43 dkf 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.
+ * 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 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. */
+				 * effect, so the structure must be freed when
+				 * refCount becomes zero. */
+    Tcl_FreeProc *freeProc;	/* Function to call to free. */
 } Reference;
 
+/*
+ * Global data structures used to hold the list of preserved data references.
+ * These variables are protected by "preserveMutex".
+ */
+
 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. */
-#define INITIAL_SIZE 2
+static int spaceAvl = 0;	/* Total number of structures available at
+				 * *firstRefPtr. */
+static int inUse = 0;		/* Count of structures currently in use in
+				 * refArray. */
 TCL_DECLARE_MUTEX(preserveMutex)/* To protect the above statics */
 
+#define INITIAL_SIZE	2	/* Initial number of reference slots to make */
+
 /*
- * 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.
+ * 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. */
+    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
+    VOID *ptr2;			/* Backup copy of the above 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;
-
-
 
 /*
  *----------------------------------------------------------------------
@@ -102,16 +104,16 @@ TclFinalizePreserve()
  *
  * 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.
+ *	This function is used by a function 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.
+ *	Information is retained so that the block of memory will not be freed
+ *	until at least the matching call to Tcl_Release.
  *
  *----------------------------------------------------------------------
  */
@@ -124,12 +126,12 @@ Tcl_Preserve(clientData)
     int i;
 
     /*
-     * See if there is already a reference for this pointer.  If so,
-     * just increment its reference count.
+     * 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++) {
+    for (i=0, refPtr=refArray ; i<inUse ; i++, refPtr++) {
 	if (refPtr->clientData == clientData) {
 	    refPtr->refCount++;
 	    Tcl_MutexUnlock(&preserveMutex);
@@ -138,8 +140,8 @@ Tcl_Preserve(clientData)
     }
 
     /*
-     * Make a reference array if it doesn't already exist, or make it
-     * bigger if it is full.
+     * Make a reference array if it doesn't already exist, or make it bigger
+     * if it is full.
      */
 
     if (inUse == spaceAvl) {
@@ -178,17 +180,16 @@ Tcl_Preserve(clientData)
  *
  * 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).
+ *	This function 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.
+ *	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.
  *
  *----------------------------------------------------------------------
  */
@@ -198,48 +199,57 @@ 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++) {
+    for (i=0, refPtr=refArray ; i<inUse ; i++, refPtr++) {
+	int mustFree;
+	Tcl_FreeProc *freeProc;
+
 	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;
-		}
-	    }
+
+	if (--refPtr->refCount != 0) {
+	    Tcl_MutexUnlock(&preserveMutex);
+	    return;
+	}
+
+	/*
+	 * 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];
 	}
+
+	/*
+	 * Now committed to disposing the data. But first, we've patched up
+	 * all the global data structures so we should release the mutex now.
+	 * Only then should we dabble around with potentially-slow memory
+	 * managers...
+	 */
+
 	Tcl_MutexUnlock(&preserveMutex);
+	if (mustFree) {
+	    if (freeProc == TCL_DYNAMIC) {
+		ckfree((char *) clientData);
+	    } else {
+		(*freeProc)((char *) clientData);
+	    }
+	}
 	return;
     }
     Tcl_MutexUnlock(&preserveMutex);
 
     /*
-     * Reference not found.  This is a bug in the caller.
+     * Reference not found. This is a bug in the caller.
      */
 
     Tcl_Panic("Tcl_Release couldn't find reference for 0x%x", clientData);
@@ -250,10 +260,9 @@ Tcl_Release(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.
+ *	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.
@@ -267,14 +276,14 @@ Tcl_Release(clientData)
 void
 Tcl_EventuallyFree(clientData, freeProc)
     ClientData clientData;	/* Pointer to malloc'ed block of memory. */
-    Tcl_FreeProc *freeProc;	/* Procedure to actually do free. */
+    Tcl_FreeProc *freeProc;	/* Function 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!).
+     * 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);
@@ -283,7 +292,8 @@ Tcl_EventuallyFree(clientData, freeProc)
 	    continue;
 	}
 	if (refPtr->mustFree) {
-	    Tcl_Panic("Tcl_EventuallyFree called twice for 0x%x\n", clientData);
+	    Tcl_Panic("Tcl_EventuallyFree called twice for 0x%x\n",
+		    clientData);
         }
         refPtr->mustFree = 1;
 	refPtr->freeProc = freeProc;
@@ -308,31 +318,29 @@ Tcl_EventuallyFree(clientData, freeProc)
  *
  * 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().
+ *	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.
+ *	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.
+ *	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
+    VOID *ptr;			/* Pointer to an arbitrary block of memory to
+				 * be tracked for deletion. Must not be
 				 * NULL. */
 {
     HandleStruct *handlePtr;
@@ -351,11 +359,10 @@ TclHandleCreate(ptr)
  *
  * 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.
+ *	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.
@@ -368,10 +375,10 @@ TclHandleCreate(ptr)
 
 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. */
+    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;
 
@@ -396,25 +403,25 @@ TclHandleFree(handle)
  *
  * TclHandlePreserve --
  *
- *	Declare an interest in the arbitrary malloc'd block associated
- *	with the handle.  
+ *	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.
+ *	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. */
+    TclHandle handle;		/* Declare an interest in the block of memory
+				 * referenced by this handle. */
 {
     HandleStruct *handlePtr;
 
@@ -423,8 +430,7 @@ TclHandlePreserve(handle)
     if (handlePtr->refCount == 0x61616161) {
 	Tcl_Panic("using previously disposed TclHandle %x", handlePtr);
     }
-    if ((handlePtr->ptr != NULL)
-	    && (handlePtr->ptr != handlePtr->ptr2)) {
+    if ((handlePtr->ptr != NULL) && (handlePtr->ptr != handlePtr->ptr2)) {
 	Tcl_Panic("someone has changed the block referenced by the handle %x\nfrom %x to %x",
 		handlePtr, handlePtr->ptr2, handlePtr->ptr);
     }
@@ -439,24 +445,24 @@ TclHandlePreserve(handle)
  *
  * TclHandleRelease --
  *
- *	This procedure is called to release an interest in the malloc'd
- *	block associated with the handle.
+ *	This function 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.
+ *	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. */
+    TclHandle handle;		/* Unregister interest in the block of memory
+				 * referenced by this handle. */
 {
     HandleStruct *handlePtr;
 
@@ -465,8 +471,7 @@ TclHandleRelease(handle)
     if (handlePtr->refCount == 0x61616161) {
 	Tcl_Panic("using previously disposed TclHandle %x", handlePtr);
     }
-    if ((handlePtr->ptr != NULL)
-	    && (handlePtr->ptr != handlePtr->ptr2)) {
+    if ((handlePtr->ptr != NULL) && (handlePtr->ptr != handlePtr->ptr2)) {
 	Tcl_Panic("someone has changed the block referenced by the handle %x\nfrom %x to %x",
 		handlePtr, handlePtr->ptr2, handlePtr->ptr);
     }
@@ -476,4 +481,11 @@ TclHandleRelease(handle)
 	ckfree((char *) handlePtr);
     }
 }
-    
+
+/*
+ * Local Variables:
+ * mode: c
+ * c-basic-offset: 4
+ * fill-column: 78
+ * End:
+ */