iodine 0.4.19 → 0.5.0

data/ext/iodine/facil.h

@@ -10,20 +10,73 @@ Feel free to copy, use and enjoy according to the license provided.
 */
 #define H_FACIL_H
 #define FACIL_VERSION_MAJOR 0
-#define FACIL_VERSION_MINOR 5
-#define FACIL_VERSION_PATCH 8
+#define FACIL_VERSION_MINOR 6
+#define FACIL_VERSION_PATCH 4
 
 #ifndef FACIL_PRINT_STATE
 /**
-When FACIL_PRINT_STATE is set to 1, facil.io will print out common messages
-regarding the server state (start / finish / listen messages).
-*/
+ * When FACIL_PRINT_STATE is set to 1, facil.io will print out common messages
+ * regarding the server state (start / finish / listen messages).
+ */
 #define FACIL_PRINT_STATE 1
 #endif
+
+#ifndef FACIL_CPU_CORES_LIMIT
+/**
+ * If facil.io detects more CPU cores than the number of cores stated in the
+ * FACIL_CPU_CORES_LIMIT, it will assume an error and cap the number of cores
+ * detected to the assigned limit.
+ *
+ * This is only relevant to automated values, when running facil.io with zero
+ * threads and processes, which invokes a large matrix of workers and threads
+ * (see {facil_run})
+ *
+ * The default auto-detection cap is set at 8 cores. The number is arbitrary
+ * (historically the number 7 was used after testing `malloc` race conditions on
+ * a MacBook Pro).
+ *
+ * The does NOT effect manually set (non-zero) worker/thread values.
+ */
+#define FACIL_CPU_CORES_LIMIT 8
+#endif
+
+#ifndef FIO_DEDICATED_SYSTEM
+/**
+ * If FIO_DEDICATED_SYSTEM is false, threads will be used (mostly) for
+ * non-prallel concurrency (protection against slow user code / high load) and
+ * processes will be used for parallelism. Otherwise, both threads and processes
+ * will be used for prallel concurrency (at the expense of increased polling).
+ *
+ * If FIO_DEDICATED_SYSTEM is true, facil.io assumes that the whole system is at
+ * it's service and that no other process is using the CPU cores.
+ *
+ * Accordingly, facil.io will poll the IO more often in an attempt to activate
+ * the threads and utilize all the cores whenever events occur.
+ *
+ * My tests show that the non-polling approach is faster, but it may be system
+ * specific.
+ */
+#define FIO_DEDICATED_SYSTEM 0
+#endif
+
+#ifndef FACIL_DISABLE_HOT_RESTART
+/**
+ * Disables the hot restart reaction to the SIGUSR1 signal
+ *
+ * The hot restart will attempt to shut down all workers, and spawn new workers,
+ * cleaning up any data cached by any of the workers.
+ *
+ * It's quite useless unless the workers are running their own VMs which are
+ * initialized in the listening socket's `on_start` callback.
+ */
+#define FACIL_DISABLE_HOT_RESTART 0
+#endif
+
 /* *****************************************************************************
 Required facil libraries
 ***************************************************************************** */
 #include "defer.h"
+#include "fiobj.h"
 #include "sock.h"
 
 /* support C++ */
@@ -60,14 +113,19 @@ struct FacilIOProtocol {
    * used (not `strcmp`).
    */
   const char *service;
-  /** called when a data is available, but will not run concurrently */
+  /** Called when a data is available, but will not run concurrently */
   void (*on_data)(intptr_t uuid, protocol_s *protocol);
   /** called when the socket is ready to be written to. */
   void (*on_ready)(intptr_t uuid, protocol_s *protocol);
-  /** called when the server is shutting down,
-   * but before closing the connection. */
+  /**
+   * Called when the server is shutting down, immediately before closing the
+   * connection.
+   *
+   * The callback runs within a {FIO_PR_LOCK_TACK} lock, so it will never run
+   * concurrently wil {on_data} or other connection specific tasks.
+   */
   void (*on_shutdown)(intptr_t uuid, protocol_s *protocol);
-  /** called when the connection was closed, but will not run concurrently */
+  /** Called when the connection was closed, but will not run concurrently */
   void (*on_close)(intptr_t uuid, protocol_s *protocol);
   /** called when a connection's timeout was reached */
   void (*ping)(intptr_t uuid, protocol_s *protocol);
@@ -144,8 +202,10 @@ static protocol_s *echo_on_open(intptr_t uuid, void *udata) {
 
 int main() {
   // Setup a listening socket
-  if (facil_listen(.port = "8888", .on_open = echo_on_open))
-    perror("No listening socket available on port 8888"), exit(-1);
+  if (facil_listen(.port = "8888", .on_open = echo_on_open)) {
+      perror("No listening socket available on port 8888");
+      exit(-1);
+  }
   // Run the server and hang until a stop signal is received.
   facil_run(.threads = 4, .processes = 1);
 }
@@ -155,40 +215,30 @@ int main() {
 struct facil_listen_args {
   /**
    * Called whenever a new connection is accepted.
-   * Should return a pointer to the connection's protocol
+   *
+   * Should either call `facil_attach` or close the connection.
    */
-  protocol_s *(*on_open)(intptr_t fduuid, void *udata);
+  void (*on_open)(intptr_t fduuid, void *udata);
   /** The network service / port. Defaults to "3000". */
   const char *port;
   /** The socket binding address. Defaults to the recommended NULL. */
   const char *address;
   /** Opaque user data. */
   void *udata;
-  /** Opaque user data for `set_rw_hooks`. */
-  void *rw_udata;
-  /** (optional)
-   * Called before `on_open`, allowing Read/Write hook initialization.
-   * Should return a pointer to the new RW hooks or NULL (to use default hooks).
-   *
-   * This allows a seperation between the transport layer (i.e. TLS) and the
-   * protocol (i.e. HTTP).
-   */
-  sock_rw_hook_s *(*set_rw_hooks)(intptr_t fduuid, void *rw_udata);
   /**
-   * Called when the server starts, allowing for further initialization, such as
-   * timed event scheduling.
+   * Called when the server starts (or a worker process is respawned), allowing
+   * for further initialization, such as timed event scheduling or VM
+   * initialization.
    *
-   * This will be called seperately for every process. */
+   * This will be called seperately for every worker process whenever it is
+   * spawned.
+   */
   void (*on_start)(intptr_t uuid, void *udata);
   /**
    * Called when the server is done, usable for cleanup.
    *
    * This will be called seperately for every process. */
   void (*on_finish)(intptr_t uuid, void *udata);
-  /**
-   * A cleanup callback for the `rw_udata`.
-   */
-  void (*on_finish_rw)(intptr_t uuid, void *rw_udata);
 };
 
 /** Schedule a network service on a listening socket. */
@@ -217,8 +267,10 @@ struct facil_connect_args {
   /**
    * The `on_connect` callback should return a pointer to a protocol object
    * that will handle any connection related events.
+   *
+   * Should either call `facil_attach` or close the connection.
    */
-  protocol_s *(*on_connect)(intptr_t uuid, void *udata);
+  void (*on_connect)(intptr_t uuid, void *udata);
   /**
    * The `on_fail` is called when a socket fails to connect. The old sock UUID
    * is passed along.
@@ -226,16 +278,8 @@ struct facil_connect_args {
   void (*on_fail)(intptr_t uuid, void *udata);
   /** Opaque user data. */
   void *udata;
-  /** Opaque user data for `set_rw_hooks`. */
-  void *rw_udata;
-  /** (optional)
-   * Called before `on_connect`, allowing Read/Write hook initialization.
-   * Should return a pointer to the new RW hooks or NULL (to use default hooks).
-   *
-   * This allows a seperation between the transport layer (i.e. TLS) and the
-   * protocol (i.e. HTTP).
-   */
-  sock_rw_hook_s *(*set_rw_hooks)(intptr_t fduuid, void *udata);
+  /** A non-system timeout after which connection is assumed to have failed. */
+  uint8_t timeout;
 };
 
 /**
@@ -267,10 +311,26 @@ Core API
 ***************************************************************************** */
 
 struct facil_run_args {
-  /** The number of threads to run in the thread pool. Has "smart" defaults. */
-  uint16_t threads;
-  /** The number of processes to run (including this one). "smart" defaults. */
-  uint16_t processes;
+  /**
+   * The number of threads to run in the thread pool. Has "smart" defaults.
+   *
+   *
+   * A positive value will indicate a set number of threads (or processes).
+   *
+   * Zeros and negative values are fun and include an interesting shorthand:
+   *
+   * * Negative values indicate a fraction of the number of CPU cores. i.e.
+   *   -2 will normally indicate "half" (1/2) the number of cores.
+   *
+   * * If the other option (i.e. `.processes` when setting `.threads`) is zero,
+   *   it will be automatically updated to reflect the option's absolute value.
+   *   i.e.:
+   *   if .threads == -2 and .processes == 0,
+   *   than facil.io will run 2 processes with (cores/2) threads per process.
+   */
+  int16_t threads;
+  /** The number of processes to run (including this one). See `threads`. */
+  int16_t processes;
   /** called if the event loop in cycled with no pending events. */
   void (*on_idle)(void);
   /** called when the server is done, to clean up any leftovers. */
@@ -290,13 +350,21 @@ void facil_run(struct facil_run_args args);
  */
 int facil_is_running(void);
 
+/**
+OVERRIDE THIS to replace the default `fork` implementation or to inject hooks
+into the forking function.
+
+Behaves like the system's `fork`.
+*/
+int facil_fork(void);
+
 /**
  * Attaches (or updates) a protocol object to a socket UUID.
  *
- * The new protocol object can be NULL, which will practically "hijack" the
- * socket away from facil.
+ * The new protocol object can be NULL, which will detach ("hijack"), the
+ * socket.
  *
- * The old protocol's `on_close` will be scheduled, if they both exist.
+ * The old protocol's `on_close` (if any) will be scheduled.
  *
  * Returns -1 on error and 0 on success.
  *
@@ -310,10 +378,7 @@ int facil_attach(intptr_t uuid, protocol_s *protocol);
  * The protocol will be attached in the FIO_PR_LOCK_TASK state, requiring a
  * furthur call to `facil_protocol_unlock`.
  *
- * The new protocol object can be NULL, which will practically "hijack" the
- * socket away from facil.
- *
- * The old protocol's `on_close` will be scheduled, if they both exist.
+ * The old protocol's `on_close` (if any) will be scheduled.
  *
  * Returns -1 on error and 0 on success.
  *
@@ -335,14 +400,33 @@ enum facil_io_event {
 /** Schedules an IO event, even id it did not occur. */
 void facil_force_event(intptr_t uuid, enum facil_io_event);
 
+/**
+ * Temporarily prevents `on_data` events from firing.
+ *
+ * The `on_data` event will be automatically rescheduled when (if) the socket's
+ * outgoing buffer fills up or when `facil_force_event` is called with
+ * `FIO_EVENT_ON_DATA`.
+ *
+ * Note: the function will work as expected when called within the protocol's
+ * `on_data` callback and the `uuid` refers to a valid socket. Otherwise the
+ * function might quitely fail.
+ */
+void facil_quite(intptr_t uuid);
+
 /* *****************************************************************************
 Helper API
 ***************************************************************************** */
 
 /**
-Returns the last time the server reviewed any pending IO events.
-*/
-time_t facil_last_tick(void);
+ * Initializes zombie reaping for the process. Call before `facil_run` to enable
+ * global zombie reaping.
+ */
+void facil_reap_children(void);
+
+/**
+ * Returns the last time the server reviewed any pending IO events.
+ */
+struct timespec facil_last_tick(void);
 
 /** Counts all the connections of a specific type `service`. */
 size_t facil_count(void *service);
@@ -392,7 +476,7 @@ struct facil_defer_args_s {
   intptr_t uuid;
   /** The type of task to be performed. Defaults to `FIO_PR_LOCK_TASK` but could
    * also be seto to `FIO_PR_LOCK_WRITE`. */
-  enum facil_protocol_lock_e task_type;
+  enum facil_protocol_lock_e type;
   /** The task (function) to be performed. This is required. */
   void (*task)(intptr_t uuid, protocol_s *, void *arg);
   /** An opaque user data that will be passed along to the task. */
@@ -441,11 +525,14 @@ int facil_each(struct facil_each_args_s args);
 #define facil_each(...) facil_each((struct facil_each_args_s){__VA_ARGS__})
 
 /* *****************************************************************************
-Cluster specific API - local cluster messaging.
+ * Cluster specific API - local cluster messaging.
+ *
+ * Facil supports message process clustering, so that a multi-process
+ * application can easily send and receive messages across process boundries.
+ **************************************************************************** */
 
-Facil supports message process clustering, so that a multi-process application
-can easily send and receive messages across process boundries.
-***************************************************************************** */
+/** returns facil.io's parent (root) process pid. */
+pid_t facil_parent_pid(void);
 
 /**
 Sets a callback / handler for a message of type `msg_type`.
@@ -456,9 +543,9 @@ registered callbacks.
 The `msg_type` value can be any positive number up to 2^31-1 (2,147,483,647).
 All values less than 0 are reserved for internal use.
 */
-void facil_cluster_set_handler(int32_t msg_type,
-                               void (*on_message)(void *data, uint32_t len));
-
+void facil_cluster_set_handler(int32_t filter,
+                               void (*on_message)(int32_t filter, FIOBJ ch,
+                                                  FIOBJ msg));
 /** Sends a message of type `msg_type` to the **other** cluster processes.
 
 `msg_type` should match a message type used when calling
@@ -472,7 +559,7 @@ starting at 1,073,741,824 are reserved for internal use.
 Callbacks are invoked using an O(n) matching, where `n` is the number of
 registered callbacks.
 */
-int facil_cluster_send(int32_t msg_type, void *data, uint32_t len);
+int facil_cluster_send(int32_t filter, FIOBJ ch, FIOBJ msg);
 
 /* *****************************************************************************
 Lower Level API - for special circumstances, use with care under .

data/ext/iodine/fio_ary.h

@@ -0,0 +1,418 @@
+#ifndef H_FIO_ARRAY_H
+/*
+Copyright: Boaz Segev, 2017-2018
+License: MIT
+*/
+
+/**
+ * A Dynamic Array for general use (void * pointers).
+ *
+ * The file was written to be compatible with C++ as well as C, hence some
+ * pointer casting.
+ *
+ * Use:
+
+fio_ary_s ary;                   // a container can be placed on the stack.
+fio_ary_new(&ary);               // initialize the container
+fio_ary_push(&ary, (void*)1 );   // add / remove / read data...
+fio_ary_free(&ary)               // free any resources, not the container.
+
+
+ */
+#define H_FIO_ARRAY_H
+
+#include <errno.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#ifndef _GNU_SOURCE
+#define _GNU_SOURCE
+#endif
+
+#ifndef FIO_FUNC
+#define FIO_FUNC static __attribute__((unused))
+#endif
+
+#ifdef __cplusplus
+#define register
+#endif
+
+typedef struct fio_ary_s {
+  size_t start;
+  size_t end;
+  size_t capa;
+  void **arry;
+} fio_ary_s;
+
+/** this value can be used for lazy initialization. */
+#define FIO_ARY_INIT ((fio_ary_s){.arry = NULL})
+
+/* *****************************************************************************
+Array API
+***************************************************************************** */
+
+/** Initializes the array and allocates memory for it's internal data. */
+FIO_FUNC inline void fio_ary_new(fio_ary_s *ary, size_t capa);
+
+/** Frees the array's internal data. */
+FIO_FUNC inline void fio_ary_free(fio_ary_s *ary);
+
+/** Returns the number of elements in the Array. */
+FIO_FUNC inline size_t fio_ary_count(fio_ary_s *ary);
+
+/** Returns the current, temporary, array capacity (it's dynamic). */
+FIO_FUNC inline size_t fio_ary_capa(fio_ary_s *ary);
+
+/**
+ * Returns the object placed in the Array, if any. Returns NULL if no data or if
+ * the index is out of bounds.
+ *
+ * Negative values are retrived from the end of the array. i.e., `-1`
+ * is the last item.
+ */
+FIO_FUNC inline void *fio_ary_index(fio_ary_s *ary, intptr_t pos);
+
+/** alias for `fiobj_ary_index` */
+#define fio_ary_entry(a, p) fiobj_ary_index((a), (p))
+
+/**
+ * Sets an object at the requested position.
+ *
+ * Returns the old value, if any.
+ *
+ * If an error occurs, the same data passed to the function is returned.
+ */
+FIO_FUNC inline void *fio_ary_set(fio_ary_s *ary, void *data, intptr_t pos);
+
+/**
+ * Pushes an object to the end of the Array. Returns -1 on error.
+ */
+FIO_FUNC inline int fio_ary_push(fio_ary_s *ary, void *data);
+
+/** Pops an object from the end of the Array. */
+FIO_FUNC inline void *fio_ary_pop(fio_ary_s *ary);
+
+/**
+ * Unshifts an object to the beginning of the Array. Returns -1 on error.
+ *
+ * This could be expensive, causing `memmove`.
+ */
+FIO_FUNC inline int fio_ary_unshift(fio_ary_s *ary, void *data);
+
+/** Shifts an object from the beginning of the Array. */
+FIO_FUNC inline void *fio_ary_shift(fio_ary_s *ary);
+
+/**
+ * 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_ary_each(fio_ary_s *ary, size_t start_at,
+                                    int (*task)(void *pt, void *arg),
+                                    void *arg);
+/**
+ * Removes any NULL *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_ary_compact(fio_ary_s *ary);
+
+/**
+ * Iterates through the list using a `for` loop.
+ *
+ * Access the data with `pos.obj` and it's index with `pos.i`. the `pos`
+ * variable can be named however you please.
+ */
+#define FIO_ARY_FOR(ary, pos)                                                  \
+  if ((ary)->arry)                                                             \
+    for (struct fio_ary_pos_for_loop_s pos = {0, (ary)->arry[(ary)->start]};   \
+         (pos.i + (ary)->start) < (ary)->end &&                                \
+         ((pos.obj = (ary)->arry[pos.i + (ary)->start]), 1);                   \
+         (++pos.i))
+struct fio_ary_pos_for_loop_s {
+  unsigned long i;
+  void *obj;
+};
+
+/* *****************************************************************************
+Array creation API
+***************************************************************************** */
+
+FIO_FUNC inline void fio_ary_new(fio_ary_s *ary, size_t capa) {
+  if (!capa)
+    capa = 32;
+  *ary = (fio_ary_s){.arry = (void **)malloc(capa * sizeof(*ary->arry)),
+                     .capa = capa};
+  if (!ary->arry) {
+    perror("ERROR: facil.io dynamic array couldn't be allocated");
+    exit(errno);
+  }
+}
+FIO_FUNC inline void fio_ary_free(fio_ary_s *ary) {
+  if (ary)
+    free(ary->arry);
+}
+
+/* *****************************************************************************
+Array memory management
+***************************************************************************** */
+
+/* This funcation manages the Array's memory. */
+FIO_FUNC void fio_ary_getmem(fio_ary_s *ary, intptr_t needed) {
+  /* we have enough memory, but we need to re-organize it. */
+  if (needed == -1) {
+    if (ary->end < ary->capa) {
+      /* since allocation can be cheaper than memmove (depending on size),
+       * we'll just shove everything to the end...
+       */
+      size_t len = ary->end - ary->start;
+      memmove(ary->arry + ary->capa - len, ary->arry + ary->start,
+              len * sizeof(*ary->arry));
+      ary->start = ary->capa - len;
+      ary->end = ary->capa;
+      return;
+    }
+    /* add some breathing room for future `unshift`s */
+    needed = 0 - ((ary->capa < 1024) ? (ary->capa >> 1) : 1024);
+
+  } else if (needed == 1 && ary->start >= (ary->capa >> 1)) {
+    /* FIFO support optimizes smaller FIFO ranges over bloating allocations. */
+    size_t len = ary->end - ary->start;
+    memmove(ary->arry + 2, ary->arry + ary->start, len * sizeof(*ary->arry));
+    ary->start = 2;
+    ary->end = len + 2;
+    return;
+  }
+
+  /* alocate using exponential growth, up to single page size. */
+  size_t updated_capa = ary->capa;
+  size_t minimum = ary->capa + ((needed < 0) ? (0 - needed) : needed);
+  while (updated_capa <= minimum)
+    updated_capa =
+        (updated_capa <= 4096) ? (updated_capa << 1) : (updated_capa + 4096);
+
+  /* we assume memory allocation works. it's better to crash than to continue
+   * living without memory... besides, malloc is optimistic these days. */
+  ary->arry = (void **)realloc(ary->arry, updated_capa * sizeof(*ary->arry));
+  ary->capa = updated_capa;
+  if (!ary->arry) {
+    perror("ERROR: facil.io dynamic array couldn't be reallocated");
+    exit(errno);
+  }
+
+  if (needed >= 0) /* we're done, realloc grows the top of the address space*/
+    return;
+
+  /* move everything to the max, since  memmove could get expensive  */
+  size_t len = ary->end - ary->start;
+  memmove((ary->arry + ary->capa) - len, ary->arry + ary->start,
+          len * sizeof(*ary->arry));
+  ary->end = ary->capa;
+  ary->start = ary->capa - len;
+}
+/** Creates a mutable empty Array object with the requested capacity. */
+FIO_FUNC inline void fiobj_ary_init(fio_ary_s *ary) {
+  *ary = (fio_ary_s){.arry = NULL};
+}
+
+/* *****************************************************************************
+Array direct entry access API
+***************************************************************************** */
+
+/** Returns the number of elements in the Array. */
+FIO_FUNC inline size_t fio_ary_count(fio_ary_s *ary) {
+  return ary->end - ary->start;
+}
+
+/** Returns the current, temporary, array capacity (it's dynamic). */
+FIO_FUNC inline size_t fio_ary_capa(fio_ary_s *ary) { return ary->capa; }
+
+/**
+ * Returns a temporary object owned by the Array.
+ *
+ * Wrap this function call within `fiobj_dup` to get a persistent handle. i.e.:
+ *
+ *     fiobj_dup(fiobj_ary_index(array, 0));
+ *
+ * Negative values are retrived from the end of the array. i.e., `-1`
+ * is the last item.
+ */
+FIO_FUNC inline void *fio_ary_index(fio_ary_s *ary, intptr_t pos) {
+  if (!ary || !ary->arry)
+    return NULL;
+  /* position is relative to `start`*/
+  if (pos >= 0) {
+    pos = pos + ary->start;
+    if ((size_t)pos >= ary->end)
+      return NULL;
+    return ary->arry[pos];
+  }
+  /* position is relative to `end`*/
+  pos = (intptr_t)ary->end + pos;
+  if (pos < 0 || (size_t)pos < ary->start)
+    return NULL;
+  return ary->arry[pos];
+}
+
+/** alias for `fiobj_ary_index` */
+#define fio_ary_entry(a, p) fiobj_ary_index((a), (p))
+
+/**
+ * Sets an object at the requested position.
+ *
+ * Returns the old value, if any.
+ *
+ * If an error occurs, the same data passed to the function is returned.
+ */
+FIO_FUNC inline void *fio_ary_set(fio_ary_s *ary, void *data, intptr_t pos) {
+  if (!ary->arry) {
+    fio_ary_new(ary, 0);
+  }
+  void *old = NULL;
+  /* test for memory and request memory if missing, promises valid bounds. */
+  if (pos >= 0) {
+    if ((size_t)pos + ary->start >= ary->capa)
+      fio_ary_getmem(ary, (((size_t)pos + ary->start) - (ary->capa - 1)));
+  } else if (pos + (intptr_t)ary->end < 0)
+    fio_ary_getmem(ary, pos + ary->end);
+
+  if (pos >= 0) {
+    /* position relative to start */
+    pos = pos + ary->start;
+    /* initialize empty spaces, if any, setting new boundries */
+    while ((size_t)pos >= ary->end)
+      ary->arry[(ary->end)++] = NULL;
+  } else {
+    /* position relative to end */
+    pos = pos + (intptr_t)ary->end;
+    /* initialize empty spaces, if any, setting new boundries */
+    while (ary->start > (size_t)pos)
+      ary->arry[--(ary->start)] = NULL;
+  }
+
+  /* check for an existing object and set new objects */
+  if (ary->arry[pos])
+    old = ary->arry[pos];
+  ary->arry[pos] = data;
+  return old;
+}
+
+/* *****************************************************************************
+Array push / shift API
+***************************************************************************** */
+
+/**
+ * Pushes an object to the end of the Array. Returns -1 on error.
+ */
+FIO_FUNC inline int fio_ary_push(fio_ary_s *ary, void *data) {
+  if (!ary->arry)
+    fio_ary_new(ary, 0);
+  else if (ary->capa <= ary->end)
+    fio_ary_getmem(ary, 1);
+  ary->arry[ary->end] = data;
+  ary->end += 1;
+  return 0;
+}
+
+/** Pops an object from the end of the Array. */
+FIO_FUNC inline void *fio_ary_pop(fio_ary_s *ary) {
+  if (!ary || ary->start == ary->end)
+    return NULL;
+  ary->end -= 1;
+  return ary->arry[ary->end];
+}
+
+/**
+ * Unshifts an object to the begining of the Array. Returns -1 on error.
+ *
+ * This could be expensive, causing `memmove`.
+ */
+FIO_FUNC inline int fio_ary_unshift(fio_ary_s *ary, void *data) {
+  if (!ary->arry)
+    fio_ary_new(ary, 0);
+  else if (!ary->start)
+    fio_ary_getmem(ary, -1);
+  ary->start -= 1;
+  ary->arry[ary->start] = data;
+  return 0;
+}
+
+/** Shifts an object from the beginning of the Array. */
+FIO_FUNC inline void *fio_ary_shift(fio_ary_s *ary) {
+  if (!ary || ary->start == ary->end)
+    return NULL;
+#ifdef __cplusplus
+  const size_t pos = ary->start;
+#else
+  register const size_t pos = ary->start;
+#endif
+  ary->start += 1;
+  return ary->arry[pos];
+}
+
+/**
+ * Single layer 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_ary_each(fio_ary_s *ary, size_t start_at,
+                                    int (*task)(void *data, void *arg),
+                                    void *arg) {
+  if (!ary || ary->start == ary->end)
+    return 0;
+  const size_t start_pos = ary->start;
+  start_at += start_pos;
+  while (start_at < ary->end && task(ary->arry[start_at++], arg) != -1)
+    ;
+  return start_at - start_pos;
+}
+
+/* *****************************************************************************
+Array compacting (untested)
+***************************************************************************** */
+
+/**
+ * Removes any NULL *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_ary_compact(fio_ary_s *ary) {
+  if (!ary || ary->start == ary->end)
+    return;
+  register void **pos = ary->arry + ary->start;
+  register void **reader = ary->arry + ary->start;
+  register void **stop = ary->arry + ary->end;
+  while (reader < stop) {
+    if (*reader) {
+      *pos = *reader;
+      pos += 1;
+    }
+    reader += 1;
+  }
+  ary->end = (size_t)(pos - ary->arry);
+}
+
+#ifdef __cplusplus
+#undef register
+#endif
+
+#undef FIO_FUNC
+
+#endif