Add some comments.

1 files changed, 12 insertions, 1 deletions

diff --git a/libdimension/error.c b/libdimension/error.c
index 728652b..38ba40b 100644
--- a/libdimension/error.c
+++ b/libdimension/error.c
@@ -26,29 +26,36 @@
 static dmnsn_severity dmnsn_resilience = DMNSN_SEVERITY_MEDIUM;
 static pthread_mutex_t dmnsn_resilience_mutex = PTHREAD_MUTEX_INITIALIZER;
 
+// Called by dmnsn_error macro (don't call directly).
 void
 dmnsn_report_error(dmnsn_severity severity, const char *func, unsigned int line,
                    const char *str)
 {
   if (severity >= dmnsn_get_resilience()) {
+    // An error more severe than our resilience happened, bail out
     fprintf(stderr, "Dimension ERROR: %s, line %u: %s\n", func, line, str);
     exit(EXIT_FAILURE);
   } else {
+    // A trivial error happened, warn and continue
     fprintf(stderr, "Dimension WARNING: %s, line %u: %s\n", func, line, str);
   }
 }
 
+/* Return the current resilience, thread-safely. */
 dmnsn_severity
 dmnsn_get_resilience()
 {
   dmnsn_severity resilience;
   if (pthread_mutex_lock(&dmnsn_resilience_mutex) != 0) {
+    // Couldn't lock the mutex, so warn and continue.
     fprintf(stderr, "Dimension WARNING: %s, line %u: %s\n",
             __PRETTY_FUNCTION__, __LINE__,
             "Couldn't lock resilience mutex.");
   }
-  resilience = dmnsn_resilience;
+  resilience = dmnsn_resilience; // Copy the static variable to a local
   if (pthread_mutex_unlock(&dmnsn_resilience_mutex) != 0) {
+    // Couldn't unlock the mutex, so warn and continue.  If the mutex was locked
+    // earlier, the next dmnsn_get/set_resilience is likely to hang.
     fprintf(stderr, "Dimension WARNING: %s, line %u: %s\n",
             __PRETTY_FUNCTION__, __LINE__,
             "Couldn't unlock resilience mutex.");
@@ -60,6 +67,7 @@ void
 dmnsn_set_resilience(dmnsn_severity resilience)
 {
   if (resilience > DMNSN_SEVERITY_HIGH) {
+    // Tried to set an illegal resilience, bail out
     fprintf(stderr, "Dimension ERROR: %s, line %u: %s\n",
             __PRETTY_FUNCTION__, __LINE__,
             "Resilience has wrong value.");
@@ -67,12 +75,15 @@ dmnsn_set_resilience(dmnsn_severity resilience)
   }
 
   if (pthread_mutex_lock(&dmnsn_resilience_mutex) != 0) {
+    // Couldn't lock the mutex, so warn and continue.
     fprintf(stderr, "Dimension WARNING: %s, line %u: %s\n",
             __PRETTY_FUNCTION__, __LINE__,
             "Couldn't lock resilience mutex.");
   }
   dmnsn_resilience = resilience;
   if (pthread_mutex_unlock(&dmnsn_resilience_mutex) != 0) {
+    // Couldn't unlock the mutex, so warn and continue.  If the mutex was locked
+    // earlier, the next dmnsn_get/set_resilience is likely to hang.
     fprintf(stderr, "Dimension WARNING: %s, line %u: %s\n",
             __PRETTY_FUNCTION__, __LINE__,
             "Couldn't unlock resilience mutex.");