Clean up code style and add key phrases to documentation.

1 files changed, 95 insertions, 52 deletions

diff --git a/unix/tclUnixThrd.c b/unix/tclUnixThrd.c
index 925f8b8..60340b0 100644
--- a/unix/tclUnixThrd.c
+++ b/unix/tclUnixThrd.c
@@ -14,37 +14,83 @@
 #include "tclInt.h"
 
 #if TCL_THREADS
-
+
 /*
- * TIP #509.
+ * TIP #509. Ensures that Tcl's mutexes are reentrant.
+ *
+ *----------------------------------------------------------------------
+ *
+ * PMutexInit --
+ *
+ *	Sets up the memory pointed to by its argument so that it contains the
+ *	implementation of a recursive lock. Caller supplies the space.
+ *
+ *----------------------------------------------------------------------
+ *
+ * PMutexDestroy --
+ *
+ *	Tears down the implementation of a recursive lock (but does not
+ *	deallocate the space holding the lock).
+ *
+ *----------------------------------------------------------------------
+ *
+ * PMutexLock --
+ *
+ *	Locks a recursive lock. (Similar to pthread_mutex_lock)
+ *
+ *----------------------------------------------------------------------
+ *
+ * PMutexUnlock --
+ *
+ *	Unlocks a recursive lock. (Similar to pthread_mutex_unlock)
+ *
+ *----------------------------------------------------------------------
+ *
+ * PCondWait --
+ *
+ *	Waits on a condition variable linked a recursive lock. (Similar to
+ *	pthread_cond_wait)
+ *
+ *----------------------------------------------------------------------
+ *
+ * PCondTimedWait --
+ *
+ *	Waits for a limited amount of time on a condition variable linked to a
+ *	recursive lock. (Similar to pthread_cond_timedwait)
+ *
+ *----------------------------------------------------------------------
  */
 
-#if defined(HAVE_DECL_PTHREAD_MUTEX_RECURSIVE) \
-    && HAVE_DECL_PTHREAD_MUTEX_RECURSIVE
+#ifndef HAVE_DECL_PTHREAD_MUTEX_RECURSIVE
+#define HAVE_DECL_PTHREAD_MUTEX_RECURSIVE 0
+#endif
+
+#if HAVE_DECL_PTHREAD_MUTEX_RECURSIVE
 /*
- * Pthread has native reentrant (AKA recursive) mutexes. Use them for Tcl_Mutex.
+ * Pthread has native reentrant (AKA recursive) mutexes. Use them for
+ * Tcl_Mutex.
  */
 
 typedef pthread_mutex_t PMutex;
 
 static void
 PMutexInit(
-    PMutex *pmutexPtr
-)
+    PMutex *pmutexPtr)
 {
     pthread_mutexattr_t attr;
+
     pthread_mutexattr_init(&attr);
     pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_RECURSIVE);
     pthread_mutex_init(pmutexPtr, &attr);
 }
 
-#define PMutexDestroy pthread_mutex_destroy
-#define PMutexLock pthread_mutex_lock
-#define PMutexUnlock pthread_mutex_unlock
-#define PCondWait pthread_cond_wait
-#define PCondTimedWait pthread_cond_timedwait
+#define PMutexDestroy	pthread_mutex_destroy
+#define PMutexLock	pthread_mutex_lock
+#define PMutexUnlock	pthread_mutex_unlock
+#define PCondWait	pthread_cond_wait
+#define PCondTimedWait	pthread_cond_timedwait
 
-#else /* HAVE_PTHREAD_MUTEX_RECURSIVE */
+#else /* !HAVE_PTHREAD_MUTEX_RECURSIVE */
 
 /*
  * No native support for reentrant mutexes. Emulate them with regular mutexes
@@ -59,8 +105,7 @@ typedef struct PMutex {
 
 static void
 PMutexInit(
-    PMutex *pmutexPtr
-)
+    PMutex *pmutexPtr)
 {
     pthread_mutex_init(&pmutexPtr->mutex, NULL);
     pmutexPtr->thread = 0;
@@ -69,42 +114,38 @@ PMutexInit(
 
 static void
 PMutexDestroy(
-    PMutex *pmutexPtr
-)
+    PMutex *pmutexPtr)
 {
-	pthread_mutex_destroy(&pmutexPtr->mutex);
+    pthread_mutex_destroy(&pmutexPtr->mutex);
 }
 
 static void
 PMutexLock(
-    PMutex *pmutexPtr
-)
+    PMutex *pmutexPtr)
 {
     if (pmutexPtr->thread != pthread_self() || pmutexPtr->counter == 0) {
-	    pthread_mutex_lock(&pmutexPtr->mutex);
-        pmutexPtr->thread = pthread_self();
-        pmutexPtr->counter = 0;
+	pthread_mutex_lock(&pmutexPtr->mutex);
+	pmutexPtr->thread = pthread_self();
+	pmutexPtr->counter = 0;
     }
     pmutexPtr->counter++;
 }
 
 static void
 PMutexUnlock(
-    PMutex *pmutexPtr
-)
+    PMutex *pmutexPtr)
 {
     pmutexPtr->counter--;
     if (pmutexPtr->counter == 0) {
-        pmutexPtr->thread = 0;
-	    pthread_mutex_unlock(&pmutexPtr->mutex);
+	pmutexPtr->thread = 0;
+	pthread_mutex_unlock(&pmutexPtr->mutex);
     }
 }
 
 static void
 PCondWait(
     pthread_cond_t *pcondPtr,
-    PMutex *pmutexPtr
-)
+    PMutex *pmutexPtr)
 {
     pthread_cond_wait(pcondPtr, &pmutexPtr->mutex);
 }
@@ -113,20 +154,19 @@ static void
 PCondTimedWait(
     pthread_cond_t *pcondPtr,
     PMutex *pmutexPtr,
-    struct timespec *ptime
-)
+    struct timespec *ptime)
 {
     pthread_cond_timedwait(pcondPtr, &pmutexPtr->mutex, ptime);
 }
 #endif /* HAVE_PTHREAD_MUTEX_RECURSIVE */
-
+
 #ifndef TCL_NO_DEPRECATED
 typedef struct {
     char nabuf[16];
 } ThreadSpecificData;
 
 static Tcl_ThreadDataKey dataKey;
-#endif
+#endif /* TCL_NO_DEPRECATED */
 
 /*
  * masterLock is used to serialize creation of mutexes, condition variables,
@@ -150,8 +190,9 @@ static pthread_mutex_t initLock = PTHREAD_MUTEX_INITIALIZER;
 
 static PMutex allocLock;
 static pthread_once_t allocLockInitOnce = PTHREAD_ONCE_INIT;
+
 static void
-allocLockInit()
+allocLockInit(void)
 {
     PMutexInit(&allocLock);
 }
@@ -220,17 +261,17 @@ TclpThreadCreate(
     }
 #endif /* HAVE_PTHREAD_ATTR_SETSTACKSIZE */
 
-    if (! (flags & TCL_THREAD_JOINABLE)) {
-	pthread_attr_setdetachstate (&attr, PTHREAD_CREATE_DETACHED);
+    if (!(flags & TCL_THREAD_JOINABLE)) {
+	pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
     }
 
     if (pthread_create(&theThread, &attr,
-	    (void * (*)(void *))proc, (void *)clientData) &&
+	    (void * (*)(void *)) proc, (void *) clientData) &&
 	    pthread_create(&theThread, NULL,
-		    (void * (*)(void *))proc, (void *)clientData)) {
+		    (void * (*)(void *)) proc, (void *) clientData)) {
 	result = TCL_ERROR;
     } else {
-	*idPtr = (Tcl_ThreadId)theThread;
+	*idPtr = (Tcl_ThreadId) theThread;
 	result = TCL_OK;
     }
     pthread_attr_destroy(&attr);
@@ -442,7 +483,6 @@ TclpMasterLock(void)
     pthread_mutex_lock(&masterLock);
 #endif
 }
-
 
 /*
  *----------------------------------------------------------------------
@@ -493,6 +533,7 @@ Tcl_GetAllocMutex(void)
 {
 #if TCL_THREADS
     PMutex **allocLockPtrPtr = &allocLockPtr;
+
     pthread_once(&allocLockInitOnce, allocLockInit);
     return (Tcl_Mutex *) allocLockPtrPtr;
 #else
@@ -538,12 +579,12 @@ Tcl_MutexLock(
 
 	    pmutexPtr = ckalloc(sizeof(PMutex));
 	    PMutexInit(pmutexPtr);
-	    *mutexPtr = (Tcl_Mutex)pmutexPtr;
+	    *mutexPtr = (Tcl_Mutex) pmutexPtr;
 	    TclRememberMutex(mutexPtr);
 	}
 	pthread_mutex_unlock(&masterLock);
     }
-    pmutexPtr = *((PMutex **)mutexPtr);
+    pmutexPtr = *((PMutex **) mutexPtr);
     PMutexLock(pmutexPtr);
 }
 
@@ -653,8 +694,8 @@ Tcl_ConditionWait(
 	}
 	pthread_mutex_unlock(&masterLock);
     }
-    pmutexPtr = *((PMutex **)mutexPtr);
-    pcondPtr = *((pthread_cond_t **)condPtr);
+    pmutexPtr = *((PMutex **) mutexPtr);
+    pcondPtr = *((pthread_cond_t **) condPtr);
     if (timePtr == NULL) {
 	PCondWait(pcondPtr, pmutexPtr);
     } else {
@@ -696,12 +737,13 @@ void
 Tcl_ConditionNotify(
     Tcl_Condition *condPtr)
 {
-    pthread_cond_t *pcondPtr = *((pthread_cond_t **)condPtr);
+    pthread_cond_t *pcondPtr = *((pthread_cond_t **) condPtr);
+
     if (pcondPtr != NULL) {
 	pthread_cond_broadcast(pcondPtr);
     } else {
 	/*
-	 * Noone has used the condition variable, so there are no waiters.
+	 * No-one has used the condition variable, so there are no waiters.
 	 */
     }
 }
@@ -729,7 +771,7 @@ void
 TclpFinalizeCondition(
     Tcl_Condition *condPtr)
 {
-    pthread_cond_t *pcondPtr = *(pthread_cond_t **)condPtr;
+    pthread_cond_t *pcondPtr = *(pthread_cond_t **) condPtr;
 
     if (pcondPtr != NULL) {
 	pthread_cond_destroy(pcondPtr);
@@ -796,15 +838,15 @@ static pthread_key_t key;
 typedef struct {
     Tcl_Mutex tlock;
     PMutex plock;
-} allocMutex;
+} AllocMutex;
 
 Tcl_Mutex *
 TclpNewAllocMutex(void)
 {
-    allocMutex *lockPtr;
+    AllocMutex *lockPtr;
     register PMutex *plockPtr;
 
-    lockPtr = malloc(sizeof(allocMutex));
+    lockPtr = malloc(sizeof(AllocMutex));
     if (lockPtr == NULL) {
 	Tcl_Panic("could not allocate lock");
     }
@@ -818,7 +860,8 @@ void
 TclpFreeAllocMutex(
     Tcl_Mutex *mutex)		/* The alloc mutex to free. */
 {
-    allocMutex* lockPtr = (allocMutex*) mutex;
+    AllocMutex *lockPtr = (AllocMutex *) mutex;
+
     if (!lockPtr) {
 	return;
     }
@@ -874,7 +917,7 @@ TclpThreadCreateKey(void)
 {
     pthread_key_t *ptkeyPtr;
 
-    ptkeyPtr = TclpSysAlloc(sizeof *ptkeyPtr, 0);
+    ptkeyPtr = TclpSysAlloc(sizeof(pthread_key_t), 0);
     if (NULL == ptkeyPtr) {
 	Tcl_Panic("unable to allocate thread key!");
     }