Add some docs in subscriber source

Author: codepr

src/handlers.c

@@ -604,8 +604,8 @@ static int subscribe_handler(struct io_event *e) {
              * the topic to the wildcards list as we can't know at this point
              * which topic it will match
              */
-            struct subscriber *sub =
-                subscriber_new(t, e->client->session, s->tuples[i].qos);
+            struct subscriber *sub = subscriber_new(e->client->session,
+                                                    s->tuples[i].qos);
             add_wildcard(topic, sub, wildcard);
         }
 #if THREADSNR > 0

src/sol_internal.h

@@ -237,11 +237,27 @@ extern pthread_mutex_t mutex;
 
 struct server;
 
+/*
+ * Checks if a client is subscribed to a topic by trying to fetch the
+ * client_session by its ID on the subscribers inner hashmap of the topic.
+ */
 bool is_subscribed(const struct topic *, const struct client_session *);
 
-struct subscriber *subscriber_new(struct topic *,
-                                  struct client_session *, unsigned char);
+/*
+ * Allocate memory on the heap to create and return a pointer to a struct
+ * subscriber, assigining the passed in QoS, session pointer, and
+ * instantiating a reference counter to 0.
+ * It may fail as it needs to allocate some bytes on the heap.
+ */
+struct subscriber *subscriber_new(struct client_session *, unsigned char);
 
+/*
+ * Allocate memory on the heap to clone a subscriber pointer, deep copies all
+ * fields into the newly allocated pointer except for the reference counter,
+ * the new pointer will have its own refcount set to 0. Finally the newly
+ * allocated pointer is returned.
+ * It may fail as it needs to allocate some bytes on the heap.
+ */
 struct subscriber *subscriber_clone(const struct subscriber *);
 
 /*

src/subscriber.c

@@ -30,9 +30,13 @@
 
 static void subscriber_destroy(const struct ref *);
 
-struct subscriber *subscriber_new(struct topic *t,
-                                  struct client_session * s,
-                                  unsigned char qos) {
+/*
+ * Allocate memory on the heap to create and return a pointer to a struct
+ * subscriber, assigining the passed in QoS, session pointer, and
+ * instantiating a reference counter to 0.
+ * It may fail as it needs to allocate some bytes on the heap.
+ */
+struct subscriber *subscriber_new(struct client_session * s, unsigned char qos) {
     struct subscriber *sub = try_alloc(sizeof(*sub));
     sub->session = s;
     sub->granted_qos = qos;
@@ -41,6 +45,13 @@ struct subscriber *subscriber_new(struct topic *t,
     return sub;
 }
 
+/*
+ * Allocate memory on the heap to clone a subscriber pointer, deep copies all
+ * fields into the newly allocated pointer except for the reference counter,
+ * the new pointer will have its own refcount set to 0. Finally the newly
+ * allocated pointer is returned.
+ * It may fail as it needs to allocate some bytes on the heap.
+ */
 struct subscriber *subscriber_clone(const struct subscriber *s) {
     struct subscriber *sub = try_alloc(sizeof(*sub));
     sub->session = s->session;
@@ -50,13 +61,21 @@ struct subscriber *subscriber_clone(const struct subscriber *s) {
     return sub;
 }
 
-static void subscriber_destroy(const struct ref *r) {
-    struct subscriber *sub = container_of(r, struct subscriber, refcount);
-    free_memory(sub);
-}
-
+/*
+ * Checks if a client is subscribed to a topic by trying to fetch the
+ * client_session by its ID on the subscribers inner hashmap of the topic.
+ */
 bool is_subscribed(const struct topic *t, const struct client_session *s) {
     struct subscriber *dummy = NULL;
     HASH_FIND_STR(t->subscribers, s->session_id, dummy);
     return dummy != NULL;
 }
+
+/*
+ * Auxiliary function, defines the destructor behavior for subscriber, just
+ * decreasing the reference counter till 0, then free the memory.
+ */
+static void subscriber_destroy(const struct ref *r) {
+    struct subscriber *sub = container_of(r, struct subscriber, refcount);
+    free_memory(sub);
+}

src/topic.c

@@ -84,7 +84,7 @@ void topic_destroy(struct topic *t) {
 struct subscriber *topic_add_subscriber(struct topic *t,
                                         struct client_session *s,
                                         unsigned char qos) {
-    struct subscriber *sub = subscriber_new(t, s, qos), *tmp;
+    struct subscriber *sub = subscriber_new(s, qos), *tmp;
     HASH_FIND_STR(t->subscribers, sub->id, tmp);
     if (!tmp)
         HASH_ADD_STR(t->subscribers, id, sub);