Update comments

m-genint.h

@@ -31,49 +31,56 @@
 /* GENINT is a container of integers with the following properties:
 
    - it stores integer from [0..N) (N is fixed).
-   - an integer can have only one occurence in the container
+   - an integer can have only one occurrence in the container.
-   (makeing the container a kind of permutation of [0..N) )
+   - you can atomically push in / pop out integer from this container
-   - you can atomically push in / pop out integer from this container.
+   provided that they were not already in the container.
+   - there are no order (like FIFO or stack)
 
-   This can be used to map integers to index of ressources in a table.
+   This can be used to map integers to index of resources in a table.
+   At most we can support N = GENINT_LIMBSIZE * GENINT_LIMBSIZE >= 4096
+   due to the master trick. For the typical usage of this container
+   (mapping hardware or software limited resources), this should be
+   enough.
 */
 
-// TODO: We may want a specialization with constant N value.
+// TO DO: We may want a specialization with constant N value.
 
+// Define the limb size 
 typedef unsigned long long genint_limb_t;
 
 typedef struct genint_s {
-  size_t n;
+  size_t n;                  // size of the container
-  size_t max;
+  size_t max;                // number of allocated limb - 1
-  genint_limb_t mask0; 
+  genint_limb_t mask0;       // mask of the last limb
-  genint_limb_t mask_master;
+  genint_limb_t mask_master; // mask of master
-  atomic_ullong master;
+  atomic_ullong master;      // master bitfield (which informs if a limb is full or not)
-  atomic_ullong *data;
+  atomic_ullong *data;       // the bitfield which informs if an integer
 } genint_t[1];
 
 #define GENINT_LIMBSIZE (sizeof(genint_limb_t) * CHAR_BIT)
 
-#define GENINT_CONTRACT(s)                              do {    \
+#define GENINT_CONTRACT(s)                              do {            \
-    assert (s != NULL);                                         \
+    assert (s != NULL);                                                 \
-    assert (s->n > 0);                                          \
+    assert (s->n > 0 && s->n <= GENINT_LIMBSIZE * GENINT_LIMBSIZE);     \
-    assert (s->data != NULL);                                   \
+    assert ((s->max+1) * GENINT_LIMBSIZE >= s->n);                      \
+    assert (s->data != NULL);                                           \
   } while (0)
 
 #define GENINT_ONE  ((genint_limb_t)1)
 
 static inline void genint_init(genint_t s, size_t n)
 {
-  assert (s != NULL && n > 0 && n <= GENINT_LIMBSIZE * GENINT_LIMBSIZE );
+  assert (s != NULL && n > 0 && n <= GENINT_LIMBSIZE * GENINT_LIMBSIZE);
   const size_t alloc = (n + GENINT_LIMBSIZE - 1) / GENINT_LIMBSIZE;
+  const size_t index  = n % GENINT_LIMBSIZE;
   atomic_ullong *ptr = M_MEMORY_REALLOC (atomic_ullong, NULL, alloc);
-  s->n = n;
-  s->data = ptr;
   if (M_UNLIKELY (ptr == NULL)) {
     M_MEMORY_FULL(alloc);
     return;
   }
+  s->n = n;
+  s->data = ptr;
   s->max = alloc-1;
-  const size_t index  = s->n % GENINT_LIMBSIZE;
   s->mask0 = (index == 0) ? -GENINT_ONE : ~((GENINT_ONE<<(GENINT_LIMBSIZE-index))-1);
   s->mask_master = ((GENINT_ONE << alloc) - 1) << (GENINT_LIMBSIZE-alloc);
   atomic_init (&s->master, (genint_limb_t)0);
@@ -89,30 +96,34 @@ static inline void genint_clear(genint_t s)
   s->data = NULL;
 }
 
+// Typical case: one CAS per pop.
 static inline size_t genint_pop(genint_t s)
 {
   GENINT_CONTRACT(s);
   // First read master to see which limb is not full.
   genint_limb_t master = atomic_load(&s->master);
+  // While master is not full
   while (master != s->mask_master) {
-    // Let's get the index i of the first not full limb.
+    // Let's get the index i of the first not full limb according to master.
     unsigned int i = m_core_clz(~master);
-    // An compute the mask of this limb being full
+    // Let's compute the mask of this limb representing the limb as being full
     const size_t mask = (i == s->max) ? s->mask0 : -GENINT_ONE;
     unsigned int bit;
     // Let's load this limb,
     genint_limb_t next, org = atomic_load(&s->data[i]);
     do {
-      // If it is now full, we have been prempted by another. Let's restart.
+      // If it is now full, we have been preempted by another.
       if (M_UNLIKELY (org == mask))
         goto next_element;
-      // At least one bit is free in the limb
+      // At least one bit is free in the limb. Find one.
       bit = GENINT_LIMBSIZE - 1 - m_core_clz(~org);
       assert ((org & (GENINT_ONE<<bit)) == 0);
       assert (i * GENINT_LIMBSIZE + GENINT_LIMBSIZE - 1 - bit < s->n);
-      // Set & reserve the integer as being used.
+      // Set the integer as being used.
       next = org | (GENINT_ONE << bit);
+      // Try to reserve the integer 
     } while (!atomic_compare_exchange_weak (&s->data[i], &org, next));
+    // We have reserved the integer.
     // If the limb is now full, try to update master
     while (M_UNLIKELY(next == mask
                       && !atomic_compare_exchange_weak (&s->master, &master, master|(GENINT_ONE << (GENINT_LIMBSIZE - 1 - i) ))
@@ -128,27 +139,35 @@ static inline size_t genint_pop(genint_t s)
     master = atomic_load(&s->master);
   }
   GENINT_CONTRACT(s);
-  return -(size_t)1; // No more ressource available
+  return -(size_t)1; // No more resource available
 }
 
+// Typical usage: one CAS per push
 static inline void genint_push(genint_t s, size_t n)
 {
   GENINT_CONTRACT(s);
   assert (n < s->n);
   size_t i    = n / GENINT_LIMBSIZE;
   size_t bit  = GENINT_LIMBSIZE - 1 - (n % GENINT_LIMBSIZE);
+  // Load the limb
   genint_limb_t next, org = atomic_load(&s->data[i]);
   do {
     assert ((org & (GENINT_ONE << bit)) != 0);
+    // Reset it
     next = org & (~(GENINT_ONE << bit));
+    //  Try to unreserve it.
   } while (!atomic_compare_exchange_weak (&s->data[i], &org, next));
   genint_limb_t master = atomic_load(&s->master);
   genint_limb_t mask_i = GENINT_ONE << (GENINT_LIMBSIZE - 1 - i);
+  // if the limb  was marked as full by master
   if (M_UNLIKELY (master & mask_i)) {
+    // Let's try to update master to reflech that limb is not full
     while (!atomic_compare_exchange_weak (&s->master, &master, master & (~mask_i)) && (master & mask_i)) {
+      // Fail to update master. Check if limb is still free
       const size_t mask = (i == s->max) ? s->mask0 : -GENINT_ONE;
       org = atomic_load(&s->data[i]);
       if (org == mask)
+        // Limb is full once again. Stop
         return;
     }
   }