fixed for pub/sub global subscriptions + naming + docs

facil-io · Oct 13, 2023 · 7125592 · 7125592
1 parent 3ec73d8
commit 7125592
Show file tree

Hide file tree

Showing 23 changed files with 532 additions and 402 deletions.
diff --git a/fio-stl.h b/fio-stl.h
diff --git a/fio-stl.md b/fio-stl.md
@@ -178,14 +178,6 @@ To test the library, define the `FIO_TEST_ALL` macro and include the header. A t
 
 Defined the `fio_test_dynamic_types` and enables as many testing features as possible, such as the `FIO_LEAK_COUNTER`.
 
-#### `FIO_LEAK_COUNTER`
-
-If defined, facil.io will count allocations and deallocations for custom memory allocators and reference counted types - allowing memory leaks to be detected with certainty.
-
-This also prints out some minimal usage information about each allocator when exiting the program. 
-
-**Note**: enabling leak detection automatically adds the `FIO_LOG` module (to print errors), the `FIO_ATOMIC` module (for atomic counters) and the `FIO_STATE` module (for more predictable `at_exit` callbacks).
-
 -------------------------------------------------------------------------------
 
 ## Version and Common Helper Macros
@@ -230,6 +222,88 @@ The facil.io C STL can be used as either a single header library (`fio-stl.h`) o
 
 -------------------------------------------------------------------------------
 
+### Default Memory Allocation
+
+By setting these macros, the memory allocator used by facil.io could be changed from the default allocator (either the custom allocator or, if missing, the system's allocator).
+
+When facil.io's memory allocator is defined (using `FIO_MALLOC`), **these macros will be automatically overwritten to use the custom memory allocator**. To use a different allocator, you may redefine the macros.
+
+#### `FIO_MEM_REALLOC`
+
+```c
+#define FIO_MEM_REALLOC(ptr, old_size, new_size, copy_len) realloc((ptr), (new_size))
+```
+
+Reallocates memory, copying (at least) `copy_len` if necessary.
+
+If `ptr` is `NULL`, behaves like `malloc`.
+
+If `new_size` is 0, behaves like `free`.
+
+#### `FIO_MEM_FREE`
+
+```c
+#define FIO_MEM_FREE(ptr, size) free((ptr))
+```
+
+Frees allocated memory.
+
+#### `FIO_MALLOC_TMP_USE_SYSTEM`
+
+When defined, temporarily bypasses the `FIO_MEM_REALLOC` macros and uses the system's `realloc` and `free` functions for newly created types.
+
+#### `FIO_MEMORY_DISABLE`
+
+When `FIO_MEMORY_DISABLE` is defined, all (future) custom memory allocators will route to the system's `malloc`. Set this when compiling to test the effects of all custom memory allocators working together.
+
+-------------------------------------------------------------------------------
+
+## Memory Leak Detection
+
+#### `FIO_LEAK_COUNTER`
+
+If defined, facil.io will count allocations and deallocations for custom memory allocators and reference counted types - allowing memory leaks to be detected with a high degree of certainty.
+
+This also prints out some minimal usage information about each allocator when exiting the program. 
+
+**Note**: enabling leak detection automatically adds the `FIO_LOG` module (to print errors), the `FIO_ATOMIC` module (for atomic counters) and the `FIO_STATE` module (for more predictable `at_exit` callbacks).
+
+When this MACRO is defined and truthful, the following macros have an effect:
+
+- `FIO_LEAK_COUNTER_DEF(name)` - defines the named memory leak counter / detection functions.
+
+- `FIO_LEAK_COUNTER_ON_ALLOC(name)` - adds an allocation to the named memory leak counter.
+
+- `FIO_LEAK_COUNTER_ON_FREE(name)` - subtracts an allocation from the named memory leak counter and tests if `free` was called more than `malloc` for this named allocation counter.
+
+For example:
+
+```c
+typedef struct { int i; } my_type_s;
+/* define the allocation counter */
+FIO_LEAK_COUNTER_DEF(my_type_s)
+/* allocation function */
+my_type_s * my_type_new() {
+  my_type_s *t = malloc(sizeof(*t));
+  if(!t)
+    return t;
+  /* count allocation */
+  FIO_LEAK_COUNTER_ON_ALLOC(my_type_s);
+  *t = (my_type_s){0};
+  return t;
+}
+/* deallocation function */
+void my_type_free(my_type_s * t) {
+  if(!t)
+    return;
+  /* count deallocation before freeing object - tests excessive calls to free) */
+  FIO_LEAK_COUNTER_ON_FREE(my_type_s);
+  free(t);
+}
+```
+
+-------------------------------------------------------------------------------
+
 ### Pointer Arithmetics
 
 #### `FIO_PTR_MATH_LMASK`
@@ -279,42 +353,6 @@ Find the root object (of a `struct`) from a pointer to its field's (the field's
 
 -------------------------------------------------------------------------------
 
-### Default Memory Allocation
-
-By setting these macros, the memory allocator used by facil.io could be changed from the default allocator (either the custom allocator or, if missing, the system's allocator).
-
-When facil.io's memory allocator is defined (using `FIO_MALLOC`), **these macros will be automatically overwritten to use the custom memory allocator**. To use a different allocator, you may redefine the macros.
-
-#### `FIO_MEM_REALLOC`
-
-```c
-#define FIO_MEM_REALLOC(ptr, old_size, new_size, copy_len) realloc((ptr), (new_size))
-```
-
-Reallocates memory, copying (at least) `copy_len` if necessary.
-
-If `ptr` is `NULL`, behaves like `malloc`.
-
-If `new_size` is 0, behaves like `free`.
-
-#### `FIO_MEM_FREE`
-
-```c
-#define FIO_MEM_FREE(ptr, size) free((ptr))
-```
-
-Frees allocated memory.
-
-#### `FIO_MALLOC_TMP_USE_SYSTEM`
-
-When defined, temporarily bypasses the `FIO_MEM_REALLOC` macros and uses the system's `realloc` and `free` functions for newly created types.
-
-#### `FIO_MEMORY_DISABLE`
-
-When `FIO_MEMORY_DISABLE` is defined, all (future) custom memory allocators will route to the system's `malloc`. Set this when compiling to test the effects of all custom memory allocators working together.
-
--------------------------------------------------------------------------------
-
 ## Pointer Tagging Support:
 
 Pointer tagging allows types created using this library to have their pointers "tagged".
@@ -363,7 +401,7 @@ any code.
 
 -------------------------------------------------------------------------------
 
-## Binary Data Informational Types and Helper Macros
+## Core Binary Strings and Buffer Helpers
 
 Some informational types and helpers are always defined (similarly to the [Linked Lists Macros](#linked-lists-macros)). These include:
 

diff --git a/fio-stl/000 core.md b/fio-stl/000 core.md
@@ -178,14 +178,6 @@ To test the library, define the `FIO_TEST_ALL` macro and include the header. A t
 
 Defined the `fio_test_dynamic_types` and enables as many testing features as possible, such as the `FIO_LEAK_COUNTER`.
 
-#### `FIO_LEAK_COUNTER`
-
-If defined, facil.io will count allocations and deallocations for custom memory allocators and reference counted types - allowing memory leaks to be detected with certainty.
-
-This also prints out some minimal usage information about each allocator when exiting the program. 
-
-**Note**: enabling leak detection automatically adds the `FIO_LOG` module (to print errors), the `FIO_ATOMIC` module (for atomic counters) and the `FIO_STATE` module (for more predictable `at_exit` callbacks).
-
 -------------------------------------------------------------------------------
 
 ## Version and Common Helper Macros
@@ -230,6 +222,88 @@ The facil.io C STL can be used as either a single header library (`fio-stl.h`) o
 
 -------------------------------------------------------------------------------
 
+### Default Memory Allocation
+
+By setting these macros, the memory allocator used by facil.io could be changed from the default allocator (either the custom allocator or, if missing, the system's allocator).
+
+When facil.io's memory allocator is defined (using `FIO_MALLOC`), **these macros will be automatically overwritten to use the custom memory allocator**. To use a different allocator, you may redefine the macros.
+
+#### `FIO_MEM_REALLOC`
+
+```c
+#define FIO_MEM_REALLOC(ptr, old_size, new_size, copy_len) realloc((ptr), (new_size))
+```
+
+Reallocates memory, copying (at least) `copy_len` if necessary.
+
+If `ptr` is `NULL`, behaves like `malloc`.
+
+If `new_size` is 0, behaves like `free`.
+
+#### `FIO_MEM_FREE`
+
+```c
+#define FIO_MEM_FREE(ptr, size) free((ptr))
+```
+
+Frees allocated memory.
+
+#### `FIO_MALLOC_TMP_USE_SYSTEM`
+
+When defined, temporarily bypasses the `FIO_MEM_REALLOC` macros and uses the system's `realloc` and `free` functions for newly created types.
+
+#### `FIO_MEMORY_DISABLE`
+
+When `FIO_MEMORY_DISABLE` is defined, all (future) custom memory allocators will route to the system's `malloc`. Set this when compiling to test the effects of all custom memory allocators working together.
+
+-------------------------------------------------------------------------------
+
+## Memory Leak Detection
+
+#### `FIO_LEAK_COUNTER`
+
+If defined, facil.io will count allocations and deallocations for custom memory allocators and reference counted types - allowing memory leaks to be detected with a high degree of certainty.
+
+This also prints out some minimal usage information about each allocator when exiting the program. 
+
+**Note**: enabling leak detection automatically adds the `FIO_LOG` module (to print errors), the `FIO_ATOMIC` module (for atomic counters) and the `FIO_STATE` module (for more predictable `at_exit` callbacks).
+
+When this MACRO is defined and truthful, the following macros have an effect:
+
+- `FIO_LEAK_COUNTER_DEF(name)` - defines the named memory leak counter / detection functions.
+
+- `FIO_LEAK_COUNTER_ON_ALLOC(name)` - adds an allocation to the named memory leak counter.
+
+- `FIO_LEAK_COUNTER_ON_FREE(name)` - subtracts an allocation from the named memory leak counter and tests if `free` was called more than `malloc` for this named allocation counter.
+
+For example:
+
+```c
+typedef struct { int i; } my_type_s;
+/* define the allocation counter */
+FIO_LEAK_COUNTER_DEF(my_type_s)
+/* allocation function */
+my_type_s * my_type_new() {
+  my_type_s *t = malloc(sizeof(*t));
+  if(!t)
+    return t;
+  /* count allocation */
+  FIO_LEAK_COUNTER_ON_ALLOC(my_type_s);
+  *t = (my_type_s){0};
+  return t;
+}
+/* deallocation function */
+void my_type_free(my_type_s * t) {
+  if(!t)
+    return;
+  /* count deallocation before freeing object - tests excessive calls to free) */
+  FIO_LEAK_COUNTER_ON_FREE(my_type_s);
+  free(t);
+}
+```
+
+-------------------------------------------------------------------------------
+
 ### Pointer Arithmetics
 
 #### `FIO_PTR_MATH_LMASK`
@@ -279,42 +353,6 @@ Find the root object (of a `struct`) from a pointer to its field's (the field's
 
 -------------------------------------------------------------------------------
 
-### Default Memory Allocation
-
-By setting these macros, the memory allocator used by facil.io could be changed from the default allocator (either the custom allocator or, if missing, the system's allocator).
-
-When facil.io's memory allocator is defined (using `FIO_MALLOC`), **these macros will be automatically overwritten to use the custom memory allocator**. To use a different allocator, you may redefine the macros.
-
-#### `FIO_MEM_REALLOC`
-
-```c
-#define FIO_MEM_REALLOC(ptr, old_size, new_size, copy_len) realloc((ptr), (new_size))
-```
-
-Reallocates memory, copying (at least) `copy_len` if necessary.
-
-If `ptr` is `NULL`, behaves like `malloc`.
-
-If `new_size` is 0, behaves like `free`.
-
-#### `FIO_MEM_FREE`
-
-```c
-#define FIO_MEM_FREE(ptr, size) free((ptr))
-```
-
-Frees allocated memory.
-
-#### `FIO_MALLOC_TMP_USE_SYSTEM`
-
-When defined, temporarily bypasses the `FIO_MEM_REALLOC` macros and uses the system's `realloc` and `free` functions for newly created types.
-
-#### `FIO_MEMORY_DISABLE`
-
-When `FIO_MEMORY_DISABLE` is defined, all (future) custom memory allocators will route to the system's `malloc`. Set this when compiling to test the effects of all custom memory allocators working together.
-
--------------------------------------------------------------------------------
-
 ## Pointer Tagging Support:
 
 Pointer tagging allows types created using this library to have their pointers "tagged".
@@ -363,7 +401,7 @@ any code.
 
 -------------------------------------------------------------------------------
 
-## Binary Data Informational Types and Helper Macros
+## Core Binary Strings and Buffer Helpers
 
 Some informational types and helpers are always defined (similarly to the [Linked Lists Macros](#linked-lists-macros)). These include:
 

diff --git a/fio-stl/001 header.h b/fio-stl/001 header.h
@@ -161,16 +161,17 @@ Recursive inclusion management
 /* *****************************************************************************
 Leak Counter Helpers
 ***************************************************************************** */
+#undef FIO_LEAK_COUNTER_DEF
+#undef FIO_LEAK_COUNTER_ON_ALLOC
+#undef FIO_LEAK_COUNTER_ON_FREE
+
 #if (FIO_LEAK_COUNTER + 1) == 1
 /* No leak counting defined */
-#define FIO___LEAK_COUNTER_DEF(name)
-#define FIO___LEAK_COUNTER_ON_ALLOC(name)
-#define FIO___LEAK_COUNTER_ON_FREE(name)
+#define FIO_LEAK_COUNTER_DEF(name)
+#define FIO_LEAK_COUNTER_ON_ALLOC(name)
+#define FIO_LEAK_COUNTER_ON_FREE(name)
 #else
-#undef FIO___LEAK_COUNTER_DEF
-#undef FIO___LEAK_COUNTER_ON_ALLOC
-#undef FIO___LEAK_COUNTER_ON_FREE
-#define FIO___LEAK_COUNTER_DEF(name)                                           \
+#define FIO_LEAK_COUNTER_DEF(name)                                             \
   FIO_IFUNC size_t FIO_NAME(fio___leak_counter, name)(size_t i) {              \
     static volatile size_t counter;                                            \
     size_t tmp = fio_atomic_add_fetch(&counter, i);                            \
@@ -191,8 +192,8 @@ Leak Counter Helpers
                            FIO_NAME(fio___leak_counter_cleanup, name),         \
                            NULL);                                              \
   }
-#define FIO___LEAK_COUNTER_ON_ALLOC(name) FIO_NAME(fio___leak_counter, name)(1)
-#define FIO___LEAK_COUNTER_ON_FREE(name)                                       \
+#define FIO_LEAK_COUNTER_ON_ALLOC(name) FIO_NAME(fio___leak_counter, name)(1)
+#define FIO_LEAK_COUNTER_ON_FREE(name)                                         \
   FIO_NAME(fio___leak_counter, name)(((size_t)-1))
 #endif
 

diff --git a/fio-stl/002 imap.h b/fio-stl/002 imap.h
@@ -74,7 +74,7 @@ iMap Creation Macro
                                hash_fn,                                        \
                                cmp_fn,                                         \
                                is_valid_fn)                                    \
-  FIO___LEAK_COUNTER_DEF(FIO_NAME(array_name, s))                              \
+  FIO_LEAK_COUNTER_DEF(FIO_NAME(array_name, s))                                \
   typedef struct {                                                             \
     array_type *ary;                                                           \
     imap_type count;                                                           \
@@ -105,7 +105,7 @@ iMap Creation Macro
   FIO_IFUNC void FIO_NAME(array_name, destroy)(FIO_NAME(array_name, s) * a) {  \
     size_t capa = FIO_NAME(array_name, capa)(a);                               \
     if (a->ary) {                                                              \
-      FIO___LEAK_COUNTER_ON_FREE(FIO_NAME(array_name, s));                     \
+      FIO_LEAK_COUNTER_ON_FREE(FIO_NAME(array_name, s));                       \
       FIO_TYPEDEF_IMAP_FREE(                                                   \
           a->ary,                                                              \
           (capa * (sizeof(*a->ary)) + (capa * (sizeof(imap_type)))));          \
@@ -131,7 +131,7 @@ iMap Creation Macro
     if (!tmp)                                                                  \
       return -1;                                                               \
     if (!a->ary)                                                               \
-      FIO___LEAK_COUNTER_ON_ALLOC(FIO_NAME(array_name, s));                    \
+      FIO_LEAK_COUNTER_ON_ALLOC(FIO_NAME(array_name, s));                      \
     a->capa_bits = (uint32_t)bits;                                             \
     a->ary = tmp;                                                              \
     if (!FIO_TYPEDEF_IMAP_REALLOC_IS_SAFE) {                                   \

diff --git a/fio-stl/004 state callbacks.h b/fio-stl/004 state callbacks.h
@@ -271,14 +271,12 @@ SFUNC void fio_state_callback_force(fio_state_event_type_e e) {
       ary[i].func(ary[i].arg);
   } else if (e <= FIO_CALL_ON_IDLE) {
     /* perform tasks in order */
-    for (size_t i = 0; i < len; ++i) {
+    for (size_t i = 0; i < len; ++i)
       ary[i].func(ary[i].arg);
-    }
   } else {
     /* perform tasks in reverse */
-    while (len--) {
+    while (len--)
       ary[len].func(ary[len].arg);
-    }
   }
   /* cleanup */
   FIO_MEM_FREE(ary, ary_capa);