iodine 0.7.3 → 0.7.4

data/ext/iodine/fio.h

@@ -4,6 +4,7 @@ License: MIT
 
 Feel free to copy, use and enjoy according to the license provided.
 */
+
 #ifndef H_FACIL_IO_H
 /**
 "facil.h" is the main header for the facil.io server platform.
@@ -79,6 +80,17 @@ Feel free to copy, use and enjoy according to the license provided.
  *
  *
  *
+ *            #ifdef FIO_ARY_NAME - can be included more than once
+ *
+ * Dynamic Array Data-Store
+ * Array API
+ * Array Type
+ * Array Memory Management
+ * Array API implementation
+ * Array Testing
+ *
+ *
+ *
  *            #ifdef FIO_SET_NAME - can be included more than once
  *
  * Set / Hash Map Data-Store
@@ -307,17 +319,6 @@ void *fio_mmap(size_t size);
  */
 void fio_malloc_after_fork(void);
 
-#if FIO_FORCE_MALLOC
-#define fio_malloc(size) calloc(size, 1)
-#define fio_calloc calloc
-#define fio_mmap(size) calloc(size, 1)
-#define fio_free free
-#define fio_realloc realloc
-#define fio_realloc2(ptr, new_size, old_data_len) realloc((ptr), (new_size))
-#define fio_malloc_test()
-#define fio_malloc_after_fork()
-#endif
-
 /* *****************************************************************************
 
 
@@ -370,16 +371,16 @@ extern size_t FIO_LOG_LEVEL;
   } while (0)
 #define FIO_LOG_DEBUG(...)                                                     \
   FIO_LOG_PRINT(FIO_LOG_LEVEL_DEBUG,                                           \
-                "[DEBUG ("__FILE__                                             \
-                ":" FIO_MACRO2STR(__LINE__) ")] " __VA_ARGS__)
+                "DEBUG ("__FILE__                                              \
+                ":" FIO_MACRO2STR(__LINE__) "): " __VA_ARGS__)
 #define FIO_LOG_INFO(...)                                                      \
-  FIO_LOG_PRINT(FIO_LOG_LEVEL_INFO, "[INFO] " __VA_ARGS__)
+  FIO_LOG_PRINT(FIO_LOG_LEVEL_INFO, "INFO: " __VA_ARGS__)
 #define FIO_LOG_WARNING(...)                                                   \
-  FIO_LOG_PRINT(FIO_LOG_LEVEL_WARNING, "[WARNING] " __VA_ARGS__)
+  FIO_LOG_PRINT(FIO_LOG_LEVEL_WARNING, "WARNING: " __VA_ARGS__)
 #define FIO_LOG_ERROR(...)                                                     \
-  FIO_LOG_PRINT(FIO_LOG_LEVEL_ERROR, "[ERROR] " __VA_ARGS__)
+  FIO_LOG_PRINT(FIO_LOG_LEVEL_ERROR, "ERROR: " __VA_ARGS__)
 #define FIO_LOG_FATAL(...)                                                     \
-  FIO_LOG_PRINT(FIO_LOG_LEVEL_FATAL, "[FATAL] " __VA_ARGS__)
+  FIO_LOG_PRINT(FIO_LOG_LEVEL_FATAL, "FATAL: " __VA_ARGS__)
 #endif
 
 #if FIO_PRINT_STATE
@@ -402,9 +403,8 @@ extern size_t FIO_LOG_LEVEL;
 /** Tests for an allocation failure. The behavior can be overridden. */
 #define FIO_ASSERT_ALLOC(ptr)                                                  \
   if (!(ptr)) {                                                                \
-    fprintf(stderr, "\nFATAL ERROR: memory allocation error "__FILE__          \
-                    ":" FIO_MACRO2STR(__LINE__) "\n");                         \
-    perror("             Error details (errno)");                              \
+    FIO_LOG_FATAL("memory allocation error "__FILE__                           \
+                  ":" FIO_MACRO2STR(__LINE__));                                \
     kill(0, SIGINT);                                                           \
     exit(errno);                                                               \
   }
@@ -3542,13 +3542,13 @@ String Implementation - UTF-8 State
 ***************************************************************************** */
 
 /**
- * Maps the last 5 bits in a byte (0b11111xxx) to a UTF-8 codepoint length.
+ * Maps the first 5 bits in a byte (0b11111xxx) to a UTF-8 codepoint length.
  *
  * Codepoint length 0 == error.
  *
  * The first valid length can be any value between 1 to 4.
  *
- * An intermidiate (second, third or forth) valid length must be 5.
+ * A continuation byte (second, third or forth) valid length must be 5.
  *
  * To map was populated using the following Ruby script:
  *
@@ -4031,6 +4031,804 @@ inline FIO_FUNC ssize_t fio_str_send_free2(const intptr_t uuid,
 #undef FIO_STR_NO_REF
 
 #endif /* H_FIO_STR_H */
+
+/* *****************************************************************************
+
+
+
+
+
+
+
+
+
+
+
+                               Dynamic Array Data-Store
+
+
+
+
+
+
+
+
+
+
+
+***************************************************************************** */
+
+#ifdef FIO_ARY_NAME
+/**
+ * A simple typed dynamic array with a minimal API.
+ *
+ * To create an Array type, define the macro FIO_ARY_NAME. i.e.:
+ *
+ *         #define FIO_ARY_NAME fio_cstr_ary
+ *         #define FIO_ARY_TYPE char *
+ *         #define FIO_ARY_COMPARE(k1, k2) (!strcmp((k1), (k2)))
+ *         #include <fio.h>
+ *
+ * It's possible to create a number of Array types by reincluding the fio.h
+ * header. i.e.:
+ *
+ *
+ *         #define FIO_INCLUDE_STR
+ *         #include <fio.h> // adds the fio_str_s types and functions
+ *
+ *         #define FIO_ARY_NAME fio_int_ary
+ *         #define FIO_ARY_TYPE int
+ *         #include <fio.h> // creates the fio_int_ary_s Array and functions
+ *
+ *         #define FIO_ARY_NAME fio_str_ary
+ *         #define FIO_ARY_TYPE fio_str_s *
+ *         #define FIO_ARY_COMPARE(k1, k2) (fio_str_iseq((k1), (k2)))
+ *         #define FIO_ARY_COPY(key) fio_str_dup((key))
+ *         #define FIO_ARY_DESTROY(key) fio_str_free2((key))
+ *         #include <fio.h> // creates the fio_str_ary_s Array and functions
+ *
+ * Note: Before freeing the Array, FIO_ARY_DESTROY will be automatically called
+ *       for every existing object, including any invalid objects (if any).
+ */
+
+/* Used for naming functions and types, prefixing FIO_ARY_NAME to the name */
+#define FIO_NAME_FROM_MACRO_STEP2(name, postfix) name##_##postfix
+#define FIO_NAME_FROM_MACRO_STEP1(name, postfix)                               \
+  FIO_NAME_FROM_MACRO_STEP2(name, postfix)
+#define FIO_NAME(postfix) FIO_NAME_FROM_MACRO_STEP1(FIO_ARY_NAME, postfix)
+
+/* Used for naming the `free` function */
+#define FIO_NAME_FROM_MACRO_STEP4(name) name##_free
+#define FIO_NAME_FROM_MACRO_STEP3(name) FIO_NAME_FROM_MACRO_STEP4(name)
+#define FIO_NAME_FREE() FIO_NAME_FROM_MACRO_STEP3(FIO_ARY_NAME)
+
+/* The default Array object type is `void *` */
+#if !defined(FIO_ARY_TYPE)
+#define FIO_ARY_TYPE void *
+#endif
+
+/* An invalid object has all bytes set to 0 - a static constant will do. */
+#if !defined(FIO_ARY_INVALID)
+static FIO_ARY_TYPE const FIO_NAME(s___const_invalid_object);
+#define FIO_ARY_INVALID FIO_NAME(s___const_invalid_object)
+#endif
+
+/* The default Array comparison assumes a simple type */
+#if !defined(FIO_ARY_COMPARE)
+#define FIO_ARY_COMPARE(o1, o2) ((o1) == (o2))
+#endif
+
+/** object copy required? */
+#ifndef FIO_ARY_COPY
+#define FIO_ARY_COPY(dest, obj) ((dest) = (obj))
+#endif
+
+/** object destruction required? */
+#ifndef FIO_ARY_DESTROY
+#define FIO_ARY_DESTROY(obj) ((void)0)
+#endif
+
+/* Customizable memory management */
+#ifndef FIO_ARY_MALLOC /* NULL ptr indicates new allocation */
+#define FIO_ARY_MALLOC(size) fio_malloc((size))
+#endif
+
+/* Customizable memory management */
+#ifndef FIO_ARY_REALLOC /* NULL ptr indicates new allocation */
+#define FIO_ARY_REALLOC(ptr, original_size, new_size, valid_data_length)       \
+  fio_realloc2((ptr), (new_size), (valid_data_length))
+#endif
+
+#ifndef FIO_ARY_DEALLOC
+#define FIO_ARY_DEALLOC(ptr, size) fio_free((ptr))
+#endif
+
+/* padding to be assumed for future expansion. */
+#ifndef FIO_ARY_PADDING
+#define FIO_ARY_PADDING 4
+#endif
+
+/* minimizes allocation "dead space" by alligning allocated length to 16bytes */
+#undef FIO_ARY_SIZE2WORDS
+#define FIO_ARY_SIZE2WORDS(size)                                               \
+  ((sizeof(FIO_ARY_TYPE) & 15) ? (((size) & ~(sizeof(FIO_ARY_TYPE) - 1)) +     \
+                                  (16 - (sizeof(FIO_ARY_TYPE) - 1)))           \
+                               : (size))
+
+/* *****************************************************************************
+Array API
+***************************************************************************** */
+
+/** The Array container type. */
+typedef struct FIO_NAME(s) FIO_NAME(s);
+
+#ifndef FIO_ARY_INIT
+/** Initializes the Array */
+#define FIO_ARY_INIT                                                           \
+  { .capa = 0 }
+#endif
+
+/** Frees the array's internal data. */
+FIO_FUNC inline void FIO_NAME_FREE()(FIO_NAME(s) * ary);
+
+/** Returns the number of elements in the Array. */
+FIO_FUNC inline size_t FIO_NAME(count)(FIO_NAME(s) * ary);
+
+/** Returns the current, temporary, array capacity (it's dynamic). */
+FIO_FUNC inline size_t FIO_NAME(capa)(FIO_NAME(s) * ary);
+
+/**
+ * Adds all the items in the `src` Array to the end of the `dest` Array.
+ *
+ * The `src` Array remain untouched.
+ */
+FIO_FUNC inline void FIO_NAME(concat)(FIO_NAME(s) * dest, FIO_NAME(s) * src);
+
+/**
+ * Sets `index` to the value in `data`.
+ *
+ * If `index` is negative, it will be counted from the end of the Array (-1 ==
+ * last element).
+ *
+ * If `old` isn't NULL, the existing data will be copied to the location pointed
+ * to by `old` before the copy in the Array is destroyed.
+ */
+FIO_FUNC inline void FIO_NAME(set)(FIO_NAME(s) * ary, intptr_t index,
+                                   FIO_ARY_TYPE data, FIO_ARY_TYPE *old);
+
+/**
+ * Returns the value located at `index` (no copying is peformed).
+ *
+ * If `index` is negative, it will be counted from the end of the Array (-1 ==
+ * last element).
+ */
+FIO_FUNC inline FIO_ARY_TYPE FIO_NAME(get)(FIO_NAME(s) * ary, intptr_t index);
+
+/**
+ * Returns the index of the object or -1 if the object wasn't found.
+ */
+FIO_FUNC inline intptr_t FIO_NAME(find)(FIO_NAME(s) * ary, FIO_ARY_TYPE data);
+
+/**
+ * Removes an object from the array, MOVING all the other objects to prevent
+ * "holes" in the data.
+ *
+ * If `old` is set, the data is copied to the location pointed to by `old`
+ * before the data in the array is destroyed.
+ *
+ * Returns 0 on success and -1 on error.
+ */
+FIO_FUNC inline int FIO_NAME(remove)(FIO_NAME(s) * ary, intptr_t index,
+                                     FIO_ARY_TYPE *old);
+
+/**
+ * Removes an object from the array, if it exists, MOVING all the other objects
+ * to prevent "holes" in the data.
+ *
+ * Returns -1 if the object wasn't found or 0 if the object was successfully
+ * removed.
+ */
+FIO_FUNC inline int FIO_NAME(remove2)(FIO_NAME(s) * ary, FIO_ARY_TYPE data,
+                                      FIO_ARY_TYPE *old);
+
+/**
+ * Returns a pointer to the C array containing the objects.
+ */
+FIO_FUNC inline FIO_ARY_TYPE *FIO_NAME(to_a)(FIO_NAME(s) * ary);
+
+/**
+ * Pushes an object to the end of the Array. Returns -1 on error.
+ */
+FIO_FUNC inline int FIO_NAME(push)(FIO_NAME(s) * ary, FIO_ARY_TYPE data);
+
+/**
+ * Removes an object from the end of the Array.
+ *
+ * If `old` is set, the data is copied to the location pointed to by `old`
+ * before the data in the array is destroyed.
+ *
+ * Returns -1 on error (Array is empty) and 0 on success.
+ */
+FIO_FUNC inline int FIO_NAME(pop)(FIO_NAME(s) * ary, FIO_ARY_TYPE *old);
+
+/**
+ * Unshifts an object to the beginning of the Array. Returns -1 on error.
+ *
+ * This could be expensive, causing `memmove`.
+ */
+FIO_FUNC inline int FIO_NAME(unshift)(FIO_NAME(s) * ary, FIO_ARY_TYPE data);
+
+/**
+ * Removes an object from the beginning of the Array.
+ *
+ * If `old` is set, the data is copied to the location pointed to by `old`
+ * before the data in the array is destroyed.
+ *
+ * Returns -1 on error (Array is empty) and 0 on success.
+ */
+FIO_FUNC inline int FIO_NAME(shift)(FIO_NAME(s) * ary, FIO_ARY_TYPE *old);
+
+/**
+ * Iteration using a callback for each entry in the array.
+ *
+ * The callback task function must accept an the entry data as well as an opaque
+ * user pointer.
+ *
+ * If the callback returns -1, the loop is broken. Any other value is ignored.
+ *
+ * Returns the relative "stop" position, i.e., the number of items processed +
+ * the starting point.
+ */
+FIO_FUNC inline size_t FIO_NAME(each)(FIO_NAME(s) * ary, size_t start_at,
+                                      int (*task)(FIO_ARY_TYPE pt, void *arg),
+                                      void *arg);
+/**
+ * Removes any FIO_ARY_TYPE_INVALID object from an Array (NULL pointers by
+ * default), keeping all other data in the array.
+ *
+ * This action is O(n) where n in the length of the array.
+ * It could get expensive.
+ */
+FIO_FUNC inline void FIO_NAME(compact)(FIO_NAME(s) * ary);
+
+/**
+ * Iterates through the list using a `for` loop.
+ *
+ * Access the object with the pointer `pos`. The `pos` variable can be named
+ * however you please.
+ *
+ * Avoid editing the array during a FOR loop, although I hope it's possible, I
+ * wouldn't count on it.
+ */
+#ifndef FIO_ARY_FOR
+#define FIO_ARY_FOR(ary, pos)                                                  \
+  if ((ary)->arry)                                                             \
+    for (__typeof__((ary)->arry) start__tmp__ = (ary)->arry,                   \
+                                 pos = ((ary)->arry + (ary)->start);           \
+         pos < (ary)->arry + (ary)->end;                                       \
+         (pos = (ary)->arry + (pos - start__tmp__) + 1),                       \
+                                 (start__tmp__ = (ary)->arry))
+#endif
+
+/* *****************************************************************************
+Array Type
+***************************************************************************** */
+
+struct FIO_NAME(s) {
+  size_t start;       /* first index where data was already written */
+  size_t end;         /* next spot to write at tail */
+  size_t capa;        /* existing capacity */
+  FIO_ARY_TYPE *arry; /* the actual array's memory, if any */
+};
+
+/* *****************************************************************************
+Array Memory Management
+***************************************************************************** */
+
+FIO_FUNC inline void FIO_NAME_FREE()(FIO_NAME(s) * ary) {
+  if (ary) {
+    const size_t count = ary->end;
+    for (size_t i = ary->start; i < count; ++i) {
+      FIO_ARY_DESTROY((ary->arry[i]));
+    }
+    FIO_ARY_DEALLOC(ary->arry, ary->capa * sizeof(*ary->arry));
+    *ary = (FIO_NAME(s))FIO_ARY_INIT;
+  }
+}
+
+/** Converts between a relative index to an absolute index. */
+FIO_FUNC inline intptr_t FIO_NAME(__rel2absolute)(FIO_NAME(s) * ary,
+                                                  intptr_t index) {
+  if (index >= 0)
+    return index;
+  index += ary->end - ary->start;
+  if (index >= 0)
+    return index;
+  return 0;
+}
+
+/** Makes sure that `len` positions are available at the Array's end. */
+FIO_FUNC void FIO_NAME(__require_on_top)(FIO_NAME(s) * ary, size_t len) {
+  if (ary->end + len < ary->capa)
+    return;
+  len = FIO_ARY_SIZE2WORDS(len + ary->end);
+  /* reallocate enough memory */
+  ary->arry = FIO_ARY_REALLOC(ary->arry, sizeof(*ary->arry) * ary->capa,
+                              (len) * sizeof(*ary->arry),
+                              ary->end * sizeof(*ary->arry));
+  FIO_ASSERT_ALLOC(ary->arry);
+  ary->capa = len + 1;
+}
+
+/** Makes sure that `len` positions are available at the Array's head. */
+FIO_FUNC void FIO_NAME(__require_on_bottom)(FIO_NAME(s) * ary, size_t len) {
+  if (ary->start >= len)
+    return;
+  FIO_ARY_TYPE *tmp = ary->arry;
+  len = FIO_ARY_SIZE2WORDS((len - ary->start) + ary->end);
+  if (ary->capa <= len) {
+    /* no room - allocate and copy */
+    ary->arry = FIO_ARY_MALLOC(len * sizeof(*ary->arry));
+    FIO_ASSERT_ALLOC(ary->arry);
+    ary->capa = len;
+  }
+  /* move existing data to the end of the existing space */
+  len = ary->end - ary->start;
+  ary->end = ary->capa;
+  if (len)
+    memmove(ary->arry + (ary->capa - len), tmp + ary->start,
+            len * sizeof(*ary->arry));
+  ary->start = ary->end - len;
+  if (tmp != ary->arry) {
+    fio_free(tmp);
+  }
+}
+
+/* *****************************************************************************
+Array API implementation
+***************************************************************************** */
+
+/** Returns the number of elements in the Array. */
+FIO_FUNC inline size_t FIO_NAME(count)(FIO_NAME(s) * ary) {
+  return ary ? (ary->end - ary->start) : 0;
+}
+
+/** Returns the current, temporary, array capacity (it's dynamic). */
+FIO_FUNC inline size_t FIO_NAME(capa)(FIO_NAME(s) * ary) {
+  return ary ? ary->capa : 0;
+}
+
+/**
+ * Returns a pointer to the C array containing the objects.
+ */
+FIO_FUNC inline FIO_ARY_TYPE *FIO_NAME(to_a)(FIO_NAME(s) * ary) {
+  return ary ? (ary->arry + ary->start) : NULL;
+}
+
+/**
+ * Adds all the items in the `src` Array to the end of the `dest` Array.
+ *
+ * The `src` Array remain untouched.
+ */
+FIO_FUNC inline void FIO_NAME(concat)(FIO_NAME(s) * dest, FIO_NAME(s) * src) {
+  const size_t added = FIO_NAME(count)(src);
+  if (!added || !dest)
+    return;
+  FIO_NAME(__require_on_top)(dest, added);
+  /* don't use memcpy, in case copying has side-effects (see macro) */
+  for (size_t i = 0; i < added; ++i) {
+    FIO_ARY_COPY(((dest->arry + dest->end)[i]), ((src->arry + src->start)[i]));
+  }
+  dest->end += added;
+}
+
+/**
+ * Sets `index` to the value in `data`.
+ *
+ * If `index` is negative, it will be counted from the end of the Array (-1 ==
+ * last element).
+ *
+ * If `old` isn't NULL, the existing data will be copied to the location pointed
+ * to by `old` before the copy in the Array is destroyed.
+ */
+FIO_FUNC inline void FIO_NAME(set)(FIO_NAME(s) * ary, intptr_t index,
+                                   FIO_ARY_TYPE data, FIO_ARY_TYPE *old) {
+  if (!ary)
+    return;
+  if (ary->start == ary->end) /* reset memory starting point? */
+    ary->start = ary->end = 0;
+
+  index = FIO_NAME(__rel2absolute)(ary, index);
+
+  const intptr_t spaces = index - (ary->end - ary->start);
+  if (spaces < 0) {
+    /* likely */
+    if (old)
+      FIO_ARY_COPY((*old), ((ary->arry + ary->start)[index]));
+    FIO_ARY_DESTROY(((ary->arry + ary->start)[index]));
+    FIO_ARY_COPY(((ary->arry + ary->start)[index]), data);
+    return;
+  }
+
+  /* fill empty spaces with zero */
+  FIO_NAME(__require_on_top)(ary, spaces + 1);
+  if (spaces) {
+    memset(ary->arry + ary->end, 0, sizeof(*ary->arry) * spaces);
+  }
+  FIO_ARY_COPY(((ary->arry + ary->start)[index]), data);
+  ary->end = index + 1;
+}
+
+/**
+ * Returns the value located at `index` (no copying is peformed).
+ *
+ * If `index` is negative, it will be counted from the end of the Array (-1 ==
+ * last element).
+ */
+FIO_FUNC inline FIO_ARY_TYPE FIO_NAME(get)(FIO_NAME(s) * ary, intptr_t index) {
+  if (!ary)
+    return FIO_ARY_INVALID;
+  index = FIO_NAME(__rel2absolute)(ary, index);
+  if ((size_t)index >= ary->end - ary->start)
+    return FIO_ARY_INVALID;
+  return (ary->arry + ary->start)[index];
+}
+
+/**
+ * Returns the index of the object or -1 if the object wasn't found.
+ */
+FIO_FUNC inline intptr_t FIO_NAME(find)(FIO_NAME(s) * ary, FIO_ARY_TYPE data) {
+  const size_t count = FIO_NAME(count)(ary);
+  if (!count) {
+    return -1;
+  }
+  size_t pos = ary->start;
+  register const size_t end = ary->end;
+  while (pos < end && !FIO_ARY_COMPARE(data, ary->arry[pos])) {
+    ++pos;
+  }
+  if (pos == end)
+    return -1;
+  return (pos - ary->start);
+}
+
+/**
+ * Removes an object from the array, MOVING all the other objects to prevent
+ * "holes" in the data.
+ *
+ * If `old` is set, the data is copied to the location pointed to by `old`
+ * before the data in the array is destroyed.
+ *
+ * Returns 0 on success and -1 on error.
+ */
+FIO_FUNC inline int FIO_NAME(remove)(FIO_NAME(s) * ary, intptr_t index,
+                                     FIO_ARY_TYPE *old) {
+  index = FIO_NAME(__rel2absolute)(ary, index);
+  const size_t count = FIO_NAME(count)(ary);
+  if (!count || (size_t)index >= count) {
+    return -1;
+  }
+  index += ary->start;
+  if (old)
+    FIO_ARY_COPY((*old), (ary->arry[index]));
+  FIO_ARY_DESTROY((ary->arry[index]));
+  if ((size_t)index == ary->start) {
+    ++ary->start;
+    return 0;
+  }
+  --ary->end;
+  if ((size_t)index < ary->end) {
+    memmove(ary->arry + index, ary->arry + index + 1,
+            (ary->end - index) * sizeof(*ary->arry));
+  }
+  return 0;
+}
+
+/**
+ * Removes an object from the array, if it exists, MOVING all the other objects
+ * to prevent "holes" in the data.
+ *
+ * Returns -1 if the object wasn't found or 0 if the object was successfully
+ * removed.
+ */
+FIO_FUNC inline int FIO_NAME(remove2)(FIO_NAME(s) * ary, FIO_ARY_TYPE data,
+                                      FIO_ARY_TYPE *old) {
+  intptr_t index = FIO_NAME(find)(ary, data);
+  if (index == -1) {
+    return -1;
+  }
+  return FIO_NAME(remove)(ary, index, old);
+}
+
+/**
+ * Pushes an object to the end of the Array. Returns -1 on error.
+ */
+FIO_FUNC inline int FIO_NAME(push)(FIO_NAME(s) * ary, FIO_ARY_TYPE data) {
+  if (!ary)
+    return -1;
+  if (ary->capa <= ary->end)
+    FIO_NAME(__require_on_top)(ary, 1 + FIO_ARY_PADDING);
+  if (ary->start == ary->end) /* reset memory starting point? */
+    ary->start = ary->end = 0;
+  FIO_ARY_COPY(ary->arry[ary->end], data);
+  ++ary->end;
+  return 0;
+}
+
+/**
+ * Removes an object from the end of the Array.
+ *
+ * If `old` is set, the data is copied to the location pointed to by `old`
+ * before the data in the array is destroyed.
+ *
+ * Returns -1 on error (Array is empty) and 0 on success.
+ */
+FIO_FUNC inline int FIO_NAME(pop)(FIO_NAME(s) * ary, FIO_ARY_TYPE *old) {
+  if (!FIO_NAME(count)(ary))
+    return -1;
+  --ary->end;
+  if (old)
+    FIO_ARY_COPY((*old), (ary->arry[ary->end]));
+  FIO_ARY_DESTROY((ary->arry[ary->end]));
+  return 0;
+}
+
+/**
+ * Unshifts an object to the beginning of the Array. Returns -1 on error.
+ *
+ * This could be expensive, causing `memmove`.
+ */
+FIO_FUNC inline int FIO_NAME(unshift)(FIO_NAME(s) * ary, FIO_ARY_TYPE data) {
+  if (!ary)
+    return -1;
+  if (ary->start == 0)
+    FIO_NAME(__require_on_bottom)(ary, 8);
+  --ary->start;
+  FIO_ARY_COPY(ary->arry[ary->start], data);
+  return 0;
+}
+
+/**
+ * Removes an object from the beginning of the Array.
+ *
+ * If `old` is set, the data is copied to the location pointed to by `old`
+ * before the data in the array is destroyed.
+ *
+ * Returns -1 on error (Array is empty) and 0 on success.
+ */
+FIO_FUNC inline int FIO_NAME(shift)(FIO_NAME(s) * ary, FIO_ARY_TYPE *old) {
+  if (!FIO_NAME(count)(ary))
+    return -1;
+  if (old)
+    FIO_ARY_COPY((*old), (ary->arry[ary->start]));
+  FIO_ARY_DESTROY((ary->arry[ary->start]));
+  ++ary->start;
+  return 0;
+}
+
+/**
+ * Iteration using a callback for each entry in the array.
+ *
+ * The callback task function must accept an the entry data as well as an opaque
+ * user pointer.
+ *
+ * If the callback returns -1, the loop is broken. Any other value is ignored.
+ *
+ * Returns the relative "stop" position, i.e., the number of items processed +
+ * the starting point.
+ */
+FIO_FUNC inline size_t FIO_NAME(each)(FIO_NAME(s) * ary, size_t start_at,
+                                      int (*task)(FIO_ARY_TYPE pt, void *arg),
+                                      void *arg) {
+  const size_t count = FIO_NAME(count)(ary);
+  if (!count || start_at >= count) {
+    return count;
+  }
+  while (start_at < count &&
+         task(ary->arry[ary->start + (start_at++)], arg) != -1)
+    ;
+  return start_at;
+}
+/**
+ * Removes any FIO_ARY_TYPE_INVALID object from an Array (NULL pointers by
+ * default), keeping all other data in the array.
+ *
+ * This action is O(n) where n in the length of the array.
+ * It could get expensive.
+ */
+FIO_FUNC inline void FIO_NAME(compact)(FIO_NAME(s) * ary) {
+  const size_t count = FIO_NAME(count)(ary);
+  if (!count)
+    return;
+  register FIO_ARY_TYPE *pos = ary->arry + ary->start;
+  register FIO_ARY_TYPE *reader = ary->arry + ary->start;
+  register FIO_ARY_TYPE *stop = ary->arry + ary->end;
+  while (reader < stop) {
+    if (!FIO_ARY_COMPARE((*reader), FIO_ARY_INVALID)) {
+      *pos = *reader;
+      pos += 1;
+    }
+    reader += 1;
+  }
+  ary->end = (size_t)(pos - ary->arry);
+}
+
+/* *****************************************************************************
+Array Testing
+***************************************************************************** */
+
+#if DEBUG
+#include <stdio.h>
+#define TEST_LIMIT 1016
+/**
+ * Removes any FIO_ARY_TYPE_INVALID  *pointers* from an Array, keeping all other
+ * data in the array.
+ *
+ * This action is O(n) where n in the length of the array.
+ * It could get expensive.
+ */
+FIO_FUNC inline void FIO_NAME(_test)(void) {
+  union {
+    FIO_ARY_TYPE obj;
+    uintptr_t i;
+  } mem;
+  FIO_NAME(s) ary = FIO_ARY_INIT;
+  fprintf(stderr, "=== Testing Core Array features for type " FIO_MACRO2STR(
+                      FIO_ARY_TYPE) "\n");
+
+  for (uintptr_t i = 0; i < TEST_LIMIT; ++i) {
+    mem.i = i + 1;
+    FIO_NAME(push)(&ary, mem.obj);
+  }
+  fprintf(stderr,
+          "* Array populated using `push` with %zu items,\n"
+          "  with capacity limit of %zu and start index %zu\n",
+          (size_t)FIO_NAME(count)(&ary), (size_t)FIO_NAME(capa)(&ary),
+          ary.start);
+  FIO_ASSERT(FIO_NAME(count)(&ary) == TEST_LIMIT,
+             "Wrong object count for array %zu", (size_t)FIO_NAME(count)(&ary));
+  for (uintptr_t i = 0; i < TEST_LIMIT; ++i) {
+    FIO_ASSERT(!FIO_NAME(shift)(&ary, &mem.obj), "Array shift failed at %lu.",
+               i);
+    FIO_ASSERT(mem.i == i + 1, "Array shift value error %lu != %lu", mem.i,
+               i + 1);
+    FIO_ARY_DESTROY(mem.obj);
+  }
+
+  FIO_NAME_FREE()(&ary);
+  FIO_ASSERT(!ary.arry, "Array not reset after fio_ary_free");
+
+  for (uintptr_t i = 0; i < TEST_LIMIT; ++i) {
+    mem.i = TEST_LIMIT - i;
+    FIO_NAME(unshift)(&ary, mem.obj);
+  }
+  fprintf(stderr,
+          "* Array populated using `unshift` with %zu items,\n"
+          "  with capacity limit of %zu and start index %zu\n",
+          (size_t)FIO_NAME(count)(&ary), (size_t)FIO_NAME(capa)(&ary),
+          ary.start);
+
+  FIO_ASSERT(FIO_NAME(count)(&ary) == TEST_LIMIT,
+             "Wrong object count for array %zu", (size_t)FIO_NAME(count)(&ary));
+  for (uintptr_t i = 0; i < TEST_LIMIT; ++i) {
+    FIO_NAME(pop)(&ary, &mem.obj);
+    FIO_ASSERT(mem.i == TEST_LIMIT - i, "Array pop value error");
+    FIO_ARY_DESTROY(mem.obj);
+  }
+  FIO_NAME_FREE()(&ary);
+  FIO_ASSERT(!ary.arry, "Array not reset after fio_ary_free");
+
+  for (uintptr_t i = 0; i < TEST_LIMIT; ++i) {
+    mem.i = TEST_LIMIT - i;
+    FIO_NAME(unshift)(&ary, mem.obj);
+  }
+
+  for (size_t i = 0; i < TEST_LIMIT; ++i) {
+    mem.i = i + 1;
+    FIO_ASSERT(FIO_NAME(find)(&ary, mem.obj) == (intptr_t)i,
+               "Wrong object index - ary[%zd] != %zu",
+               (ssize_t)FIO_NAME(find)(&ary, mem.obj), (size_t)mem.i);
+    mem.obj = FIO_NAME(get)(&ary, i);
+    FIO_ASSERT(mem.i == (uintptr_t)(i + 1),
+               "Wrong object returned from fio_ary_index - ary[%zu] != %zu", i,
+               i + 1);
+  }
+
+  FIO_ASSERT((FIO_NAME(count)(&ary) == TEST_LIMIT),
+             "Wrong object count before pop %zu",
+             (size_t)FIO_NAME(count)(&ary));
+  FIO_ASSERT(!FIO_NAME(pop)(&ary, &mem.obj), "Couldn't pop element.");
+  FIO_ASSERT(mem.i == TEST_LIMIT, "Element value error (%zu).", (size_t)mem.i);
+  FIO_ASSERT((FIO_NAME(count)(&ary) == TEST_LIMIT - 1),
+             "Wrong object count after pop %zu", (size_t)FIO_NAME(count)(&ary));
+  FIO_ARY_DESTROY(mem.obj);
+
+  mem.i = (TEST_LIMIT >> 1);
+  FIO_ASSERT(!FIO_NAME(remove2)(&ary, mem.obj, NULL),
+             "Couldn't fio_ary_remove2 object from Array (%zu)", (size_t)mem.i);
+  FIO_ASSERT(FIO_NAME(count)(&ary) == TEST_LIMIT - 2,
+             "Wrong object count after remove2 %zu",
+             (size_t)FIO_NAME(count)(&ary));
+  mem.i = (TEST_LIMIT >> 1) + 1;
+  FIO_ASSERT(FIO_NAME(find)(&ary, mem.obj) != (TEST_LIMIT >> 1) + 1,
+             "fio_ary_remove2 didn't clear holes from Array (%zu)",
+             (size_t)FIO_NAME(find)(&ary, mem.obj));
+  FIO_ARY_DESTROY(mem.obj);
+
+  FIO_ASSERT(!FIO_NAME(remove)(&ary, 0, &mem.obj),
+             "fio_ary_remove failed (at %zd)", (ssize_t)mem.i);
+  FIO_ASSERT(mem.i == 1, "Couldn't fio_ary_remove object from Array (%zd)",
+             (ssize_t)mem.i);
+  FIO_ASSERT(FIO_NAME(count)(&ary) == TEST_LIMIT - 3,
+             "Wrong object count after remove %zu != %d",
+             (size_t)FIO_NAME(count)(&ary), TEST_LIMIT - 3);
+  FIO_ASSERT(FIO_NAME(find)(&ary, mem.obj) == -1,
+             "fio_ary_find should have failed after fio_ary_remove (%zd)",
+             (ssize_t)FIO_NAME(find)(&ary, mem.obj));
+  FIO_ARY_DESTROY(mem.obj);
+
+  mem.i = 2;
+  FIO_ASSERT(FIO_NAME(find)(&ary, mem.obj) == 0,
+             "fio_ary_remove didn't clear holes from Array (%zu)",
+             (size_t)FIO_NAME(find)(&ary, mem.obj));
+
+  FIO_NAME_FREE()(&ary);
+
+  FIO_NAME(s) ary2 = FIO_ARY_INIT;
+  for (uintptr_t i = 0; i < (TEST_LIMIT >> 1); ++i) {
+    mem.i = ((TEST_LIMIT >> 1) << 1) - i;
+    FIO_NAME(unshift)(&ary2, mem.obj);
+    mem.i = (TEST_LIMIT >> 1) - i;
+    FIO_NAME(unshift)(&ary, mem.obj);
+  }
+  FIO_NAME(concat)(&ary, &ary2);
+  FIO_NAME_FREE()(&ary2);
+  FIO_ASSERT(FIO_NAME(count)(&ary) == ((TEST_LIMIT >> 1) << 1),
+             "Wrong object count after fio_ary_concat %zu",
+             (size_t)FIO_NAME(count)(&ary));
+  for (int i = 0; i < ((TEST_LIMIT >> 1) << 1); ++i) {
+    mem.obj = FIO_NAME(get)(&ary, i);
+    FIO_ASSERT(
+        mem.i == (uintptr_t)(i + 1),
+        "Wrong object returned from fio_ary_index after concat - ary[%d] != %d",
+        i, i + 1);
+  }
+  mem.i = 0;
+  while (FIO_NAME(pop)(&ary, &mem.obj)) {
+    ++mem.i;
+    FIO_ARY_DESTROY(mem.obj);
+  }
+  FIO_ASSERT(mem.i == ((TEST_LIMIT >> 1) << 1), "fio_ary_pop overflow (%zu)?",
+             (size_t)mem.i);
+  FIO_NAME_FREE()(&ary);
+}
+#undef TEST_LIMIT
+#else
+FIO_FUNC inline void FIO_NAME(_test)(void);
+#endif
+
+/* *****************************************************************************
+Done
+***************************************************************************** */
+
+#undef FIO_NAME_FROM_MACRO_STEP2
+#undef FIO_NAME_FROM_MACRO_STEP1
+#undef FIO_NAME
+#undef FIO_NAME_FROM_MACRO_STEP4
+#undef FIO_NAME_FROM_MACRO_STEP3
+#undef FIO_NAME_FREE
+#undef FIO_ARY_NAME
+#undef FIO_ARY_TYPE
+#undef FIO_ARY_INVALID
+#undef FIO_ARY_COMPARE
+#undef FIO_ARY_COPY
+#undef FIO_ARY_DESTROY
+#undef FIO_ARY_REALLOC
+#undef FIO_ARY_DEALLOC
+#undef FIO_ARY_SIZE2WORDS
+
+#endif
+
 /* *****************************************************************************
 
 
@@ -4135,9 +4933,13 @@ inline FIO_FUNC ssize_t fio_str_send_free2(const intptr_t uuid,
 #define FIO_NAME_FROM_MACRO_STEP2(name, postfix) name##_##postfix
 #define FIO_NAME_FROM_MACRO_STEP1(name, postfix)                               \
   FIO_NAME_FROM_MACRO_STEP2(name, postfix)
-
 #define FIO_NAME(postfix) FIO_NAME_FROM_MACRO_STEP1(FIO_SET_NAME, postfix)
 
+/* Used for naming the `free` function */
+#define FIO_NAME_FROM_MACRO_STEP4(name) name##_free
+#define FIO_NAME_FROM_MACRO_STEP3(name) FIO_NAME_FROM_MACRO_STEP4(name)
+#define FIO_NAME_FREE() FIO_NAME_FROM_MACRO_STEP3(FIO_SET_NAME)
+
 /* The default Set object / value type is `void *` */
 #if !defined(FIO_SET_OBJ_TYPE)
 #define FIO_SET_OBJ_TYPE void *
@@ -4183,13 +4985,13 @@ inline FIO_FUNC ssize_t fio_str_send_free2(const intptr_t uuid,
 /* Customizable memory management */
 #ifndef FIO_SET_REALLOC /* NULL ptr indicates new allocation */
 #define FIO_SET_REALLOC(ptr, original_size, new_size, valid_data_length)       \
-  realloc((ptr), (new_size))
+  fio_realloc2((ptr), (new_size), (valid_data_length))
 #endif
 #ifndef FIO_SET_CALLOC
-#define FIO_SET_CALLOC(size, count) calloc((size), (count))
+#define FIO_SET_CALLOC(size, count) fio_calloc((size), (count))
 #endif
 #ifndef FIO_SET_FREE
-#define FIO_SET_FREE(ptr, size) free((ptr))
+#define FIO_SET_FREE(ptr, size) fio_free((ptr))
 #endif
 
 /* The maximum number of bins to rotate when partial collisions occure */
@@ -4259,8 +5061,8 @@ typedef struct FIO_NAME(s) FIO_NAME(s);
   { .capa = 0 }
 #endif
 
-/** Deallocates any internal resources. Doesn't free any objects! */
-FIO_FUNC void FIO_NAME(free)(FIO_NAME(s) * set);
+/** Frees all the objects in the set and deallocates any internal resources. */
+FIO_FUNC void FIO_NAME_FREE()(FIO_NAME(s) * set);
 
 #ifdef FIO_SET_KEY_TYPE
 
@@ -4555,11 +5357,19 @@ FIO_FUNC inline FIO_SET_TYPE FIO_NAME(_insert_or_overwrite_)(
 
   /* locate future position, rehashing until a position is available */
   FIO_NAME(_map_s_) *pos = FIO_NAME(_find_map_pos_)(set, hash_value, obj);
-
-  while (!pos) {
-    set->mask = (set->mask << 1) | 1;
+  if (!pos) {
+    /* no pos - so we know that we are inserting an object. */
+    /* Either we are over capacity, or we have too many holes in the map. */
+    if (set->pos >= set->capa) {
+      set->mask = (set->mask << 1) | 3;
+      FIO_NAME(rehash)(set);
+    }
+    FIO_SET_COPY(set->ordered[set->pos].obj, obj);
+    set->ordered[set->pos].hash = hash_value;
+    ++set->pos;
+    ++set->count;
     FIO_NAME(rehash)(set);
-    pos = FIO_NAME(_find_map_pos_)(set, hash_value, obj);
+    return set->ordered[set->pos - 1].obj;
   }
 
   /* overwriting / new */
@@ -4601,8 +5411,8 @@ FIO_FUNC inline FIO_SET_TYPE FIO_NAME(_insert_or_overwrite_)(
 Set / Hash Map Implementation
 ***************************************************************************** */
 
-/** Deallocates any internal resources. Doesn't free any objects! */
-FIO_FUNC void FIO_NAME(free)(FIO_NAME(s) * s) {
+/** Frees all the objects in the set and deallocates any internal resources. */
+FIO_FUNC void FIO_NAME_FREE()(FIO_NAME(s) * s) {
   /* destroy existing valid objects */
   const FIO_NAME(_ordered_s_) *const end = s->ordered + s->pos;
   if (s->ordered && s->ordered != end) {
@@ -4683,6 +5493,7 @@ FIO_FUNC inline int FIO_NAME(remove)(FIO_NAME(s) * set,
   --set->count;
   pos->pos->hash = FIO_SET_HASH_INVALID;
   if (pos->pos == set->pos + set->ordered - 1) {
+    pos->hash = FIO_SET_HASH_INVALID; /* no need for a "hole" */
     do {
       --set->pos;
     } while (set->pos && FIO_SET_HASH_COMPARE(set->ordered[set->pos - 1].hash,
@@ -4818,7 +5629,7 @@ FIO_FUNC inline size_t FIO_NAME(capa_require)(FIO_NAME(s) * set,
     return FIO_NAME(capa)(set);
   set->mask = 1;
   while (min_capa > set->mask) {
-    set->mask = (set->mask << 1) | 1;
+    set->mask = (set->mask << 1) | 3;
   }
   FIO_NAME(rehash)(set);
   return FIO_NAME(capa)(set);
@@ -4839,7 +5650,7 @@ FIO_FUNC inline size_t FIO_NAME(is_fragmented)(const FIO_NAME(s) * set) {
  */
 FIO_FUNC inline size_t FIO_NAME(compact)(FIO_NAME(s) * set) {
   FIO_NAME(_compact_ordered_array_)(set);
-  set->mask = 1;
+  set->mask = 3;
   while (set->count >= set->mask) {
     set->mask = (set->mask << 1) | 1;
   }
@@ -4859,7 +5670,7 @@ restart:
       FIO_NAME(_map_s_) *mp =
           FIO_NAME(_find_map_pos_)(set, pos->hash, pos->obj);
       if (!mp) {
-        set->mask = (set->mask << 1) | 1;
+        set->mask = (set->mask << 1) | 3;
         goto restart;
       }
       mp->pos = pos;
@@ -4891,6 +5702,9 @@ restart:
 #undef FIO_NAME
 #undef FIO_NAME_FROM_MACRO_STEP2
 #undef FIO_NAME_FROM_MACRO_STEP1
+#undef FIO_NAME_FROM_MACRO_STEP4
+#undef FIO_NAME_FROM_MACRO_STEP3
+#undef FIO_NAME_FREE
 #undef FIO_SET_NAME
 
 #endif