From fa751e537db75108f9a1597d83a4e1093173fc28 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Sun, 21 Nov 2004 02:43:05 +0000
Subject: [PATCH] some commenting

git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@298 fefdeb5f-60dc-0310-8127-8f9354f1896f
---
 polyp/alsa-util.c | 10 +++++++++-
 polyp/alsa-util.h |  2 +-
 polyp/caps.c      |  4 ++--
 polyp/dynarray.c  |  6 +++++-
 polyp/dynarray.h  | 12 ++++++++++++
 polyp/hashmap.c   | 15 ++++++++++-----
 polyp/hashmap.h   |  9 +++++++++
 polyp/idxset.h    |  4 ++++
 polyp/pid.c       | 15 ++++++++++++++-
 polyp/queue.h     |  6 ++++++
 polyp/subscribe.c | 14 +++++++++++++-
 polyp/util.c      |  5 +++--
 12 files changed, 88 insertions(+), 14 deletions(-)

diff --git a/polyp/alsa-util.c b/polyp/alsa-util.c
index eaa21d4..52eaaed 100644
--- a/polyp/alsa-util.c
+++ b/polyp/alsa-util.c
@@ -30,7 +30,9 @@
 #include "sample.h"
 #include "xmalloc.h"
 
-int pa_alsa_set_hw_params(snd_pcm_t *pcm_handle, struct pa_sample_spec *ss, uint32_t *periods, snd_pcm_uframes_t *period_size) {
+/* Set the hardware parameters of the given ALSA device. Returns the
+ * selected fragment settings in *period/*period_size */
+int pa_alsa_set_hw_params(snd_pcm_t *pcm_handle, const struct pa_sample_spec *ss, uint32_t *periods, snd_pcm_uframes_t *period_size) {
     int ret = -1;
     snd_pcm_uframes_t buffer_size;
     snd_pcm_hw_params_t *hwparams = NULL;
@@ -79,6 +81,11 @@ finish:
     return ret;
 }
 
+/* Allocate an IO event for every ALSA poll descriptor for the
+ * specified ALSA device. Return a pointer to such an array in
+ * *io_events. Store the length of that array in *n_io_events. Use the
+ * specified callback function and userdata. The array has to be freed
+ * with pa_free_io_events(). */
 int pa_create_io_events(snd_pcm_t *pcm_handle, struct pa_mainloop_api* m, struct pa_io_event ***io_events, unsigned *n_io_events, void (*cb)(struct pa_mainloop_api*a, struct pa_io_event *e, int fd, enum pa_io_event_flags events, void *userdata), void *userdata) {
     unsigned i;
     struct pollfd *pfds, *ppfd;
@@ -106,6 +113,7 @@ int pa_create_io_events(snd_pcm_t *pcm_handle, struct pa_mainloop_api* m, struct
     return 0;
 }
 
+/* Free the memory allocated by pa_create_io_events() */
 void pa_free_io_events(struct pa_mainloop_api* m, struct pa_io_event **io_events, unsigned n_io_events) {
     unsigned i;
     struct pa_io_event **ios;
diff --git a/polyp/alsa-util.h b/polyp/alsa-util.h
index c058025..adec143 100644
--- a/polyp/alsa-util.h
+++ b/polyp/alsa-util.h
@@ -27,7 +27,7 @@
 #include "sample.h"
 #include "mainloop-api.h"
 
-int pa_alsa_set_hw_params(snd_pcm_t *pcm_handle, struct pa_sample_spec *ss, uint32_t *periods, snd_pcm_uframes_t *period_size);
+int pa_alsa_set_hw_params(snd_pcm_t *pcm_handle, const struct pa_sample_spec *ss, uint32_t *periods, snd_pcm_uframes_t *period_size);
 
 int pa_create_io_events(snd_pcm_t *pcm_handle, struct pa_mainloop_api *m, struct pa_io_event ***io_events, unsigned *n_io_events, void (*cb)(struct pa_mainloop_api*a, struct pa_io_event *e, int fd, enum pa_io_event_flags events, void *userdata), void *userdata);
 void pa_free_io_events(struct pa_mainloop_api* m, struct pa_io_event **io_sources, unsigned n_io_sources);
diff --git a/polyp/caps.c b/polyp/caps.c
index d371916..e2f4573 100644
--- a/polyp/caps.c
+++ b/polyp/caps.c
@@ -42,7 +42,7 @@ void pa_drop_root(void) {
     if (uid == 0 || geteuid() != 0)
         return;
     
-    pa_log(__FILE__": dropping root rights.\n");
+/*     pa_log(__FILE__": dropping root rights.\n"); */
     
     setreuid(uid, uid);
 /*    setuid(uid);
@@ -68,7 +68,7 @@ int pa_limit_caps(void) {
     if (cap_set_proc(caps) < 0)
         goto fail;
 
-    pa_log(__FILE__": dropped capabilities successfully.\n");
+/*     pa_log(__FILE__": dropped capabilities successfully.\n"); */
     
     r = 0;
 
diff --git a/polyp/dynarray.c b/polyp/dynarray.c
index eb360b8..0e406ea 100644
--- a/polyp/dynarray.c
+++ b/polyp/dynarray.c
@@ -30,6 +30,9 @@
 #include "dynarray.h"
 #include "xmalloc.h"
 
+/* If the array becomes to small, increase its size by 100 entries */
+#define INCREASE_BY 100
+
 struct pa_dynarray {
     void **data;
     unsigned n_allocated, n_entries;
@@ -66,7 +69,7 @@ void pa_dynarray_put(struct pa_dynarray*a, unsigned i, void *p) {
         if (!p)
             return;
 
-        n = i+100;
+        n = i+INCREASE_BY;
         a->data = pa_xrealloc(a->data, sizeof(void*)*n);
         memset(a->data+a->n_allocated, 0, sizeof(void*)*(n-a->n_allocated));
         a->n_allocated = n;
@@ -88,6 +91,7 @@ void *pa_dynarray_get(struct pa_dynarray*a, unsigned i) {
     assert(a);
     if (i >= a->n_allocated)
         return NULL;
+
     assert(a->data);
     return a->data[i];
 }
diff --git a/polyp/dynarray.h b/polyp/dynarray.h
index 2e9b72f..6733e95 100644
--- a/polyp/dynarray.h
+++ b/polyp/dynarray.h
@@ -24,10 +24,22 @@
 
 struct pa_dynarray;
 
+/* Implementation of a simple dynamically sized array. The array
+ * expands if required, but doesn't shrink if possible. Memory
+ * management of the array's entries is the user's job. */
+
 struct pa_dynarray* pa_dynarray_new(void);
+
+/* Free the array calling the specified function for every entry in
+ * the array. The function may be NULL. */
 void pa_dynarray_free(struct pa_dynarray* a, void (*func)(void *p, void *userdata), void *userdata);
 
+/* Store p at position i in the array */
 void pa_dynarray_put(struct pa_dynarray*a, unsigned i, void *p);
+
+/* Store p a the first free position in the array. Returns the index
+ * of that entry. If entries are removed from the array their position
+ * are not filled any more by this function. */
 unsigned pa_dynarray_append(struct pa_dynarray*a, void *p);
 
 void *pa_dynarray_get(struct pa_dynarray*a, unsigned i);
diff --git a/polyp/hashmap.c b/polyp/hashmap.c
index 43e4456..3b1265c 100644
--- a/polyp/hashmap.c
+++ b/polyp/hashmap.c
@@ -32,6 +32,8 @@
 #include "xmalloc.h"
 #include "log.h"
 
+#define BUCKETS 1023
+
 struct hashmap_entry {
     struct hashmap_entry *next, *previous, *bucket_next, *bucket_previous;
     unsigned hash;
@@ -52,7 +54,7 @@ struct pa_hashmap {
 struct pa_hashmap *pa_hashmap_new(unsigned (*hash_func) (const void *p), int (*compare_func) (const void*a, const void*b)) {
     struct pa_hashmap *h;
     h = pa_xmalloc(sizeof(struct pa_hashmap));
-    h->data = pa_xmalloc0(sizeof(struct hashmap_entry*)*(h->size = 1023));
+    h->data = pa_xmalloc0(sizeof(struct hashmap_entry*)*(h->size = BUCKETS));
     h->first_entry = NULL;
     h->n_entries = 0;
     h->hash_func = hash_func ? hash_func : pa_idxset_trivial_hash_func;
@@ -74,8 +76,10 @@ static void remove(struct pa_hashmap *h, struct hashmap_entry *e) {
         e->bucket_next->bucket_previous = e->bucket_previous;
     if (e->bucket_previous)
         e->bucket_previous->bucket_next = e->bucket_next;
-    else
+    else {
+        assert(e->hash < h->size);
         h->data[e->hash] = e->bucket_next;
+    }
 
     pa_xfree(e);
     h->n_entries--;
@@ -96,6 +100,7 @@ void pa_hashmap_free(struct pa_hashmap*h, void (*free_func)(void *p, void *userd
 
 static struct hashmap_entry *get(struct pa_hashmap *h, unsigned hash, const void *key) {
     struct hashmap_entry *e;
+    assert(h && hash < h->size);
 
     for (e = h->data[hash]; e; e = e->bucket_next)
         if (h->compare_func(e->key, key) == 0)
@@ -107,7 +112,7 @@ static struct hashmap_entry *get(struct pa_hashmap *h, unsigned hash, const void
 int pa_hashmap_put(struct pa_hashmap *h, const void *key, void *value) {
     struct hashmap_entry *e;
     unsigned hash;
-    assert(h && key);
+    assert(h);
 
     hash = h->hash_func(key) % h->size;
 
@@ -171,9 +176,9 @@ unsigned pa_hashmap_ncontents(struct pa_hashmap *h) {
 void *pa_hashmap_iterate(struct pa_hashmap *h, void **state, const void **key) {
     assert(h && state);
 
-    if (!*state) {
+    if (!*state) 
         *state = h->first_entry;
-    } else
+    else
         *state = ((struct hashmap_entry*) *state)->next;
 
     if (!*state) {
diff --git a/polyp/hashmap.h b/polyp/hashmap.h
index f858c35..d55834c 100644
--- a/polyp/hashmap.h
+++ b/polyp/hashmap.h
@@ -22,14 +22,23 @@
   USA.
 ***/
 
+/* Simple Implementation of a hash table. Memory management is the
+ * user's job. It's a good idea to have the key pointer point to a
+ * string in the value data. */
+
 struct pa_hashmap;
 
+/* Create a new hashmap. Use the specified functions for hashing and comparing objects in the map */
 struct pa_hashmap *pa_hashmap_new(unsigned (*hash_func) (const void *p), int (*compare_func) (const void*a, const void*b));
+
+/* Free the hash table. Calls the specified function for every value in the table. The function may be NULL */
 void pa_hashmap_free(struct pa_hashmap*, void (*free_func)(void *p, void *userdata), void *userdata);
 
+/* Returns non-zero when the entry already exists */
 int pa_hashmap_put(struct pa_hashmap *h, const void *key, void *value);
 void* pa_hashmap_get(struct pa_hashmap *h, const void *key);
 
+/* Returns the data of the entry while removing */
 void* pa_hashmap_remove(struct pa_hashmap *h, const void *key);
 
 unsigned pa_hashmap_ncontents(struct pa_hashmap *h);
diff --git a/polyp/idxset.h b/polyp/idxset.h
index 1ed6615..66689fd 100644
--- a/polyp/idxset.h
+++ b/polyp/idxset.h
@@ -24,6 +24,10 @@
 
 #include <inttypes.h>
 
+/* A combination of a hashtable and a dynamic array. Entries are both
+ * indexiable through a numeric automaticly generated index and an
+ * opaque key. As usual, memory management is the user's job. */
+
 #define PA_IDXSET_INVALID ((uint32_t) -1)
 
 unsigned pa_idxset_trivial_hash_func(const void *p);
diff --git a/polyp/pid.c b/polyp/pid.c
index a52bed0..37a7698 100644
--- a/polyp/pid.c
+++ b/polyp/pid.c
@@ -38,6 +38,8 @@
 #include "util.h"
 #include "log.h"
 
+/* Read the PID data from the file descriptor fd, and return it. If no
+ * pid could be read, return 0, on failure (pid_t) -1 */
 static pid_t read_pid(const char *fn, int fd) {
     ssize_t r;
     char t[20], *e = NULL;
@@ -63,6 +65,7 @@ static pid_t read_pid(const char *fn, int fd) {
     return (pid_t) pid;
 }
 
+/* Create a new PID file for the current process. */
 int pa_pid_file_create(void) {
     int fd = -1, lock = -1;
     int ret = -1;
@@ -77,19 +80,21 @@ int pa_pid_file_create(void) {
         goto fail;
     }
 
+    /* Try to lock the file. If that fails, go without */
     lock = pa_lock_fd(fd, 1);
 
     if ((pid = read_pid(fn, fd)) == (pid_t) -1)
         pa_log(__FILE__": corrupt PID file, overwriting.\n");
     else if (pid > 0) {
         if (kill(pid, 0) >= 0 || errno != ESRCH) {
-            pa_log(__FILE__": valid PID file.\n");
+            pa_log(__FILE__": daemon already running.\n");
             goto fail;
         }
 
         pa_log(__FILE__": stale PID file, overwriting.\n");
     }
 
+    /* Overwrite the current PID file */
     if (lseek(fd, 0, SEEK_SET) == (off_t) -1 || ftruncate(fd, 0) < 0) {
         pa_log(__FILE__": failed to truncate PID fil: %s.\n", strerror(errno));
         goto fail;
@@ -116,6 +121,7 @@ fail:
     return ret;
 }
 
+/* Remove the PID file, if it is ours */
 int pa_pid_file_remove(void) {
     int fd = -1, lock = -1;
     char fn[PATH_MAX];
@@ -162,10 +168,17 @@ fail:
     return ret;
 }
 
+/* Check whether the daemon is currently running, i.e. if a PID file
+ * exists and the PID therein too. Returns 0 on succcess, -1
+ * otherwise. If pid is non-NULL and a running daemon was found,
+ * return its PID therein */
 int pa_pid_file_check_running(pid_t *pid) {
     return pa_pid_file_kill(0, pid);
 }
 
+/* Kill a current running daemon. Return non-zero on success, -1
+ * otherwise. If successful *pid contains the PID of the daemon
+ * process. */
 int pa_pid_file_kill(int sig, pid_t *pid) {
     int fd = -1, lock = -1;
     char fn[PATH_MAX];
diff --git a/polyp/queue.h b/polyp/queue.h
index 0b72f37..a739ab7 100644
--- a/polyp/queue.h
+++ b/polyp/queue.h
@@ -24,8 +24,14 @@
 
 struct pa_queue;
 
+/* A simple implementation of the abstract data type queue. Stores
+ * pointers as members. The memory has to be managed by the caller. */
+
 struct pa_queue* pa_queue_new(void);
+
+/* Free the queue and run the specified callback function for every remaining entry. The callback function may be NULL. */
 void pa_queue_free(struct pa_queue* q, void (*destroy)(void *p, void *userdata), void *userdata);
+
 void pa_queue_push(struct pa_queue *q, void *p);
 void* pa_queue_pop(struct pa_queue *q);
 
diff --git a/polyp/subscribe.c b/polyp/subscribe.c
index b552e4d..ee6ef3a 100644
--- a/polyp/subscribe.c
+++ b/polyp/subscribe.c
@@ -31,6 +31,13 @@
 #include "xmalloc.h"
 #include "log.h"
 
+/* The subscription subsystem may be used to be notified whenever an
+ * entity (sink, source, ...) is created or deleted. Modules may
+ * register a callback function that is called whenever an event
+ * matching a subscription mask happens. The execution of the callback
+ * function is postponed to the next main loop iteration, i.e. is not
+ * called from within the stack frame the entity was created in. */
+
 struct pa_subscription {
     struct pa_core *core;
     int dead;
@@ -48,6 +55,7 @@ struct pa_subscription_event {
 
 static void sched_event(struct pa_core *c);
 
+/* Allocate a new subscription object for the given subscription mask. Use the specified callback function and user data */
 struct pa_subscription* pa_subscription_new(struct pa_core *c, enum pa_subscription_mask m, void (*callback)(struct pa_core *c, enum pa_subscription_event_type t, uint32_t index, void *userdata), void *userdata) {
     struct pa_subscription *s;
     assert(c);
@@ -66,6 +74,7 @@ struct pa_subscription* pa_subscription_new(struct pa_core *c, enum pa_subscript
     return s;
 }
 
+/* Free a subscription object, effectively marking it for deletion */
 void pa_subscription_free(struct pa_subscription*s) {
     assert(s && !s->dead);
     s->dead = 1;
@@ -86,6 +95,7 @@ static void free_item(struct pa_subscription *s) {
     pa_xfree(s);
 }
 
+/* Free all subscription objects */
 void pa_subscription_free_all(struct pa_core *c) {
     struct pa_subscription_event *e;
     assert(c);
@@ -150,6 +160,7 @@ void pa_subscription_free_all(struct pa_core *c) {
     pa_log(__FILE__":  %u\n", e->index);
 }*/
 
+/* Deferred callback for dispatching subscirption events */
 static void defer_cb(struct pa_mainloop_api *m, struct pa_defer_event *e, void *userdata) {
     struct pa_core *c = userdata;
     struct pa_subscription *s;
@@ -187,6 +198,7 @@ static void defer_cb(struct pa_mainloop_api *m, struct pa_defer_event *e, void *
     }
 }
 
+/* Schedule an mainloop event so that a pending subscription event is dispatched */
 static void sched_event(struct pa_core *c) {
     assert(c);
 
@@ -198,7 +210,7 @@ static void sched_event(struct pa_core *c) {
     c->mainloop->defer_enable(c->subscription_defer_event, 1);
 }
 
-
+/* Append a new subscription event to the subscription event queue and schedule a main loop event */
 void pa_subscription_post(struct pa_core *c, enum pa_subscription_event_type t, uint32_t index) {
     struct pa_subscription_event *e;
     assert(c);
diff --git a/polyp/util.c b/polyp/util.c
index 2ad26c4..b01b80a 100644
--- a/polyp/util.c
+++ b/polyp/util.c
@@ -384,7 +384,8 @@ void pa_raise_priority(void) {
 
     if (setpriority(PRIO_PROCESS, 0, NICE_LEVEL) < 0)
         pa_log(__FILE__": setpriority() failed: %s\n", strerror(errno));
-    else pa_log(__FILE__": Successfully gained nice level %i.\n", NICE_LEVEL);
+/*     else */
+/*         pa_log(__FILE__": Successfully gained nice level %i.\n", NICE_LEVEL); */
     
 #ifdef _POSIX_PRIORITY_SCHEDULING
     {
@@ -401,7 +402,7 @@ void pa_raise_priority(void) {
             return;
         }
 
-        pa_log(__FILE__": Successfully enabled SCHED_FIFO scheduling.\n");
+/*         pa_log(__FILE__": Successfully enabled SCHED_FIFO scheduling.\n"); */
     }
 #endif
 }
-- 
2.7.4