[asterisk-commits] russell: branch russell/debug_threads r77848 - /team/russell/debug_threads/

[SVN commits to the Asterisk project]

Author: russell
Date: Tue Jul 31 16:49:19 2007
New Revision: 77848

URL: http://svn.digium.com/view/asterisk?view=rev&rev=77848
Log:
add some comments

Modified:
    team/russell/debug_threads/utils.c

Modified: team/russell/debug_threads/utils.c
URL: http://svn.digium.com/view/asterisk/team/russell/debug_threads/utils.c?view=diff&rev=77848&r1=77847&r2=77848
==============================================================================
--- team/russell/debug_threads/utils.c (original)
+++ team/russell/debug_threads/utils.c Tue Jul 31 16:49:19 2007
@@ -495,17 +495,24 @@
 /*! \brief A reasonable maximum number of locks a thread would be holding ... */
 #define AST_MAX_LOCKS 16
 
-/* Allow direct use of pthread_mutex_t */
+/* Allow direct use of pthread_mutex_t and friends */
 #undef pthread_mutex_t
 #undef pthread_mutex_lock
 #undef pthread_mutex_unlock
 #undef pthread_mutex_init
 #undef pthread_mutex_destroy
 
-/*! \brief Keep track of which locks a thread holds */
+/*! 
+ * \brief Keep track of which locks a thread holds 
+ *
+ * There is an instance of this struct for every active thread
+ */
 struct thr_lock_info {
+	/*! The thread's ID */
 	pthread_t thread_id;
+	/*! The thread name which includes where the thread was started */
 	const char *thread_name;
+	/*! This is the actual container of info for what locks this thread holds */
 	struct {
 		const char *file;
 		int line_num;
@@ -514,16 +521,30 @@
 		void *lock_addr;
 		int times_locked;
 	} locks[AST_MAX_LOCKS];
+	/*! This is the number of locks currently held by this thread.
+	 *  The index (num_locks - 1) has the info on the last one in the
+	 *  locks member */
 	unsigned int num_locks;
-	/* Protects the contents of the locks member 
+	/*! Protects the contents of the locks member 
 	 * Intentionally not ast_mutex_t */
 	pthread_mutex_t lock;
 	AST_LIST_ENTRY(thr_lock_info) entry;
 };
 
+/*! 
+ * \brief Locked when accessing the lock_infos list 
+ */
 AST_RWLOCK_DEFINE_STATIC(lock_infos_rwlock);
+/*!
+ * \brief A list of each thread's lock info 
+ */
 static AST_LIST_HEAD_NOLOCK_STATIC(lock_infos, thr_lock_info);
 
+/*!
+ * \brief Destroy a thread's lock info
+ *
+ * This gets called automatically when the thread stops
+ */
 static void lock_info_destroy(void *data)
 {
 	struct thr_lock_info *lock_info = data;
@@ -537,8 +558,18 @@
 	free(lock_info);
 }
 
+/*!
+ * \brief The thread storage key for per-thread lock info
+ */
 AST_THREADSTORAGE_CUSTOM(thread_lock_info, NULL, lock_info_destroy);
 
+/*!
+ * \brief Store lock info for the current thread
+ *
+ * This function gets called in ast_mutex_lock() and ast_mutex_trylock() so
+ * that information about this lock can be stored in this thread's
+ * lock info struct.
+ */
 void ast_store_lock_info(const char *filename, int line_num, 
 	const char *func, const char *lock_name, void *lock_addr)
 {
@@ -577,6 +608,12 @@
 	pthread_mutex_unlock(&lock_info->lock);
 }
 
+/*!
+ * \brief Remove lock info for the current thread
+ *
+ * This gets called by ast_mutex_unlock so that information on the lock can
+ * be removed from the current thread's lock info struct.
+ */
 void ast_remove_lock_info(void *lock_addr)
 {
 	struct thr_lock_info *lock_info;