From b9e19e076662ae5743b9c81eb238fe11204f6dbd Mon Sep 17 00:00:00 2001
From: Tavian Barnes <tavianator@gmail.com>
Date: Sun, 12 Apr 2009 19:06:50 +0000
Subject: Add some comments.

---
 libdimension/canvas.c | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

(limited to 'libdimension/canvas.c')

diff --git a/libdimension/canvas.c b/libdimension/canvas.c
index 49096fc..516c978 100644
--- a/libdimension/canvas.c
+++ b/libdimension/canvas.c
@@ -19,24 +19,33 @@
  *************************************************************************/
 
 #include "dimension.h"
-#include <pthread.h> /* Must be first included header */
-#include <stdlib.h>  /* For malloc(), free() */
+#include <pthread.h>
+#include <stdlib.h> /* For malloc(), free() */
 
+/* Allocate a new canvas, of width x and height y.  If any intermediary step
+   fails, free all acquired memory to avoid leaks. */
 dmnsn_canvas *
 dmnsn_new_canvas(unsigned int x, unsigned int y)
 {
   unsigned int i, j, k, l;
+  /* Allocate the dmnsn_canvas struct */
   dmnsn_canvas *canvas = malloc(sizeof(dmnsn_canvas));
 
   if (canvas) {
+    /* *canvas exists */
+
+    /* Set the width and height */
     canvas->x = x;
     canvas->y = y;
+
+    /* Allocate the pixels */
     canvas->pixels = malloc(sizeof(dmnsn_color)*x*y);
     if (!canvas->pixels) {
       free(canvas);
       return NULL;
     }
 
+    /* Allocate the rwlocks */
     canvas->rwlocks = malloc(sizeof(pthread_rwlock_t)*x*y);
     if (!canvas->rwlocks) {
       free(canvas->pixels);
@@ -44,6 +53,7 @@ dmnsn_new_canvas(unsigned int x, unsigned int y)
       return NULL;
     }
 
+    /* Initialize the rwlocks */
     for (i = 0; i < x; ++i) {
       for (j = 0; j < y; ++j) {
         if (pthread_rwlock_init(&canvas->rwlocks[j*x + i], NULL) != 0) {
@@ -53,7 +63,7 @@ dmnsn_new_canvas(unsigned int x, unsigned int y)
           for (l = 0; l < j; ++l) {
             for (k = 0; k < x; ++k) {
               if (pthread_rwlock_destroy(&canvas->rwlocks[l*x + k]) != 0) {
-                /* Low severity, because leaked memory won't actually hurt us */
+                /* Low severity, because leaked locks won't actually hurt us */
                 dmnsn_error(DMNSN_SEVERITY_LOW,
                             "Leaking rwlocks in failed allocation.");
               }
@@ -79,12 +89,16 @@ dmnsn_new_canvas(unsigned int x, unsigned int y)
   return canvas;
 }
 
+/* Delete a dmnsn_canvas allocated with dmnsn_new_canvas */
 void
 dmnsn_delete_canvas(dmnsn_canvas *canvas)
 {
   unsigned int i, j;
 
   if (canvas) {
+    /* *canvas exists */
+
+    /* Destroy the rwlocks */
     for (i = 0; i < canvas->x; ++i) {
       for (j = 0; j < canvas->y; ++j) {
         if (pthread_rwlock_destroy(&canvas->rwlocks[j*canvas->x + i]) != 0) {
@@ -94,12 +108,14 @@ dmnsn_delete_canvas(dmnsn_canvas *canvas)
       }
     }
 
+    /* Free the locks, pixels, and canvas */
     free(canvas->rwlocks);
     free(canvas->pixels);
     free(canvas);
   }
 }
 
+/* Get a pixel at (x,y) thread-safely, using dmnsn_rdlock_pixel. */
 dmnsn_color
 dmnsn_get_pixel(const dmnsn_canvas *canvas, unsigned int x, unsigned int y)
 {
@@ -110,6 +126,7 @@ dmnsn_get_pixel(const dmnsn_canvas *canvas, unsigned int x, unsigned int y)
   return color;
 }
 
+/* Set a pixel at (x,y) thread-safely, using dmnsn_wrlock_pixel. */
 void
 dmnsn_set_pixel(dmnsn_canvas *canvas,
                 unsigned int x, unsigned int y, dmnsn_color color)
@@ -119,28 +136,37 @@ dmnsn_set_pixel(dmnsn_canvas *canvas,
   dmnsn_unlock_pixel(canvas, x, y);
 }
 
+/* Acquire a read-lock for a pixel */
 void
 dmnsn_rdlock_pixel(const dmnsn_canvas *canvas, unsigned int x, unsigned int y)
 {
   if (pthread_rwlock_rdlock(&canvas->rwlocks[y*canvas->x + x]) != 0) {
+    /* Medium severity, because undefined behaviour is pretty likely if our
+       reads and writes aren't synced */
     dmnsn_error(DMNSN_SEVERITY_MEDIUM,
                 "Couldn't acquire read-lock for pixel.");
   }
 }
 
+/* Acquire a write-lock for a pixel */
 void
 dmnsn_wrlock_pixel(dmnsn_canvas *canvas, unsigned int x, unsigned int y)
 {
   if (pthread_rwlock_wrlock(&canvas->rwlocks[y*canvas->x + x]) != 0) {
+    /* Medium severity, because undefined behaviour is pretty likely if our
+       reads and writes aren't synced */
     dmnsn_error(DMNSN_SEVERITY_MEDIUM,
                 "Couldn't acquire write-lock for pixel.");
   }
 }
 
+/* Unlock a pixel */
 void
 dmnsn_unlock_pixel(const dmnsn_canvas *canvas, unsigned int x, unsigned int y)
 {
   if (pthread_rwlock_unlock(&canvas->rwlocks[y*canvas->x + x]) != 0) {
+    /* Medium severity, because if the pixel is locked, we're likely to hang
+       the next time we try to read or write it */
     dmnsn_error(DMNSN_SEVERITY_MEDIUM, "Couldn't unlock pixel.");
   }
 }
-- 
cgit v1.2.3