iodine 0.7.60 → 0.8.0

data/ext/iodine/iodine.h

@@ -1,63 +1,258 @@
-#ifndef H_IODINE_H
-#define H_IODINE_H
-
-#include "ruby.h"
-
-#include "fio.h"
-#include "fio_tls.h"
-#include "fiobj.h"
-/* used for iodine_connect and iodine_listen routing */
-typedef struct {
-  fio_str_info_s address;
-  fio_str_info_s port;
-  fio_str_info_s method;
-  fio_str_info_s path;
-  fio_str_info_s body;
-  fio_str_info_s public;
-  fio_str_info_s url;
-#ifndef __MINGW32__
-  fio_tls_s *tls;
+/**
+ * @file iodine.h
+ * @brief Main header file for the Iodine Ruby C extension.
+ *
+ * This file serves as the central include point for the Iodine HTTP/WebSocket
+ * server extension. It includes Ruby headers, defines global constants and
+ * symbols, configures the facil.io C STL library, and includes all Iodine
+ * sub-modules in the correct dependency order.
+ *
+ * Iodine is built on top of the facil.io C STL library (fio-stl.h) which
+ * provides the underlying IO reactor, HTTP server, WebSocket support, and
+ * various utilities.
+ */
+#ifndef H___IODINE___H
+#define H___IODINE___H
+/* *****************************************************************************
+facil.io
+***************************************************************************** */
+
+/* Fix: __attribute__((weak)) doesn't work correctly on Windows PE/COFF
+   (MinGW DLLs) — weak symbols may not be properly allocated in the DLL's data
+   segment, causing segfaults when accessed (e.g., writing to FIO_LOG_LEVEL).
+   Since iodine compiles as a single translation unit, weak symbols are
+   unnecessary — override FIO_WEAK to empty before fio-stl.h is included. */
+#if defined(_WIN32) || defined(__MINGW32__) || defined(__CYGWIN__)
+#ifndef FIO_WEAK
+#define FIO_WEAK /* empty — no weak attribute on Windows */
+#endif
 #endif
-  VALUE handler;
-  FIOBJ headers;
-  FIOBJ cookies;
-  size_t max_headers;
-  size_t max_body;
-  intptr_t max_clients;
-  size_t max_msg;
-  uint8_t timeout;
-  uint8_t ping;
-  uint8_t log;
-  enum {
-    IODINE_SERVICE_RAW,
-    IODINE_SERVICE_HTTP,
-    IODINE_SERVICE_WS,
-  } service;
-} iodine_connection_args_s;
 
-#include "iodine_caller.h"
-#include "iodine_connection.h"
-#include "iodine_defer.h"
-#include "iodine_helpers.h"
-#include "iodine_http.h"
-#include "iodine_json.h"
-#include "iodine_mustache.h"
-#include "iodine_pubsub.h"
-#include "iodine_rack_io.h"
-#include "iodine_store.h"
-#include "iodine_tcp.h"
-#include "iodine_tls.h"
+#define FIO_LEAK_COUNTER 1
+#include "fio-stl.h"
+
+typedef unsigned long long fio_thread_t;
+typedef int fio_thread_pid_t;
+
+#if defined(_WIN32) || defined(__MINGW32__) || defined(__CYGWIN__)
+#include <synchapi.h>
+typedef CONDITION_VARIABLE fio_thread_cond_t;
+#else
+#include <pthread.h>
+typedef pthread_cond_t fio_thread_cond_t;
+#endif
+
+#define FIO_MUSTACHE_LAMBDA_SUPPORT 1
+#define FIO_THREADS_BYO             1
+#define FIO_THREADS_FORK_BYO        1
+#define FIO_MEMORY_ARENA_COUNT_MAX  4
+#define FIO_EVERYTHING
+
+#ifndef DEBUG
+// #undef FIO_LEAK_COUNTER_SKIP_EXIT
+// #define FIO_LEAK_COUNTER_SKIP_EXIT 1
+/* Ruby doesn't always free everything pre-cleanup, so no point in counting */
+// #undef FIO_LEAK_COUNTER
+// #define FIO_LEAK_COUNTER 0
+#endif
+
+#include FIO_INCLUDE_FILE
+
+#ifndef DEBUG
+#endif
 
 /* *****************************************************************************
-Constants
+Ruby
 ***************************************************************************** */
-extern VALUE IodineModule;
-extern VALUE IodineBaseModule;
-extern VALUE iodine_default_args;
-extern ID iodine_call_id;
-extern ID iodine_to_s_id;
 
-#define IODINE_RSTRINFO(rstr)                                                  \
-  ((fio_str_info_s){.len = RSTRING_LEN(rstr), .data = RSTRING_PTR(rstr)})
+#include <ruby.h>
+#include <ruby/encoding.h>
+#include <ruby/intern.h>
+#include <ruby/io.h>
+#include <ruby/thread.h>
 
+/* ruby_thread_has_gvl_p() exists since Ruby 2.x but was only publicly declared
+   in ruby/thread.h starting with Ruby 4.0. On older Rubies, provide our own
+   declaration to avoid implicit-function-declaration errors on Windows/macOS.
+   On Ruby 4.0+, rb_thread_call_with_gvl() is GVL-lenient (safe to call whether
+   or not the GVL is held), so the check is unnecessary — but we still declare
+   it to keep the code unconditionally compilable. */
+#if RUBY_API_VERSION_MAJOR < 4
+int ruby_thread_has_gvl_p(void);
 #endif
+
+/* *****************************************************************************
+Ruby Method ID Constants
+
+These IDs are cached for efficient Ruby method calls from C code.
+They are initialized in Init_iodine() using IODINE_CONST_ID_STORE().
+***************************************************************************** */
+
+/** @brief Cached Ruby method ID for `call` */
+static ID IODINE_CALL_ID;
+static ID IODINE_CLOSE_ID;
+static ID IODINE_EACH_ID;
+static ID IODINE_FILENO_ID;
+static ID IODINE_NEW_ID;
+static ID IODINE_CURRENT_ID;
+static ID IODINE_JOIN_ID;
+static ID IODINE_TO_PATH_ID;
+static ID IODINE_TO_S_ID;
+static ID IODINE_TO_JSON_ID;
+static ID IODINE_RACK_HIJACK_ID;
+static ID IODINE_ON_AUTHENTICATE_ID;
+static ID IODINE_ON_AUTHENTICATE_SSE_ID;
+static ID IODINE_ON_AUTHENTICATE_WEBSOCKET_ID;
+static ID IODINE_ON_CLOSE_ID;
+static ID IODINE_ON_DATA_ID;
+static ID IODINE_ON_DRAINED_ID;
+static ID IODINE_ON_EVENTSOURCE_ID;
+static ID IODINE_ON_EVENTSOURCE_RECONNECT_ID;
+static ID IODINE_ON_FINISH_ID;
+static ID IODINE_ON_HTTP_ID;
+static ID IODINE_ON_MESSAGE_ID;
+static ID IODINE_ON_OPEN_ID;
+static ID IODINE_ON_SHUTDOWN_ID;
+static ID IODINE_ON_TIMEOUT_ID;
+static ID IODINE_QUERY_ID;
+
+static ID IODINE_INDEX_ID;
+static ID IODINE_SHOW_ID;
+// static ID IODINE_NEW_ID;
+static ID IODINE_EDIT_ID;
+static ID IODINE_CREATE_ID;
+static ID IODINE_UPDATE_ID;
+static ID IODINE_DELETE_ID;
+
+/**
+ * Stores a Ruby method ID constant and protects its Symbol from GC.
+ *
+ * @param name The C variable name to store the ID in.
+ * @param value The Ruby method name as a C string.
+ */
+#define IODINE_CONST_ID_STORE(name, value)                                     \
+  name = rb_intern(value);                                                     \
+  STORE.hold(RB_ID2SYM(name));
+
+static VALUE iodine_rb_IODINE;
+static VALUE iodine_rb_IODINE_BASE;
+static VALUE iodine_rb_IODINE_BASE_APP404;
+static VALUE iodine_rb_IODINE_CONNECTION;
+static VALUE iodine_rb_IODINE_PUBSUB;
+static VALUE iodine_rb_IODINE_PUBSUB_ENG;
+static VALUE iodine_rb_IODINE_PUBSUB_MSG;
+static VALUE iodine_rb_IODINE_PUBSUB_SUB;
+static VALUE iodine_rb_IODINE_TLS;
+static rb_encoding *IodineUTF8Encoding;
+static rb_encoding *IodineBinaryEncoding;
+
+static VALUE IODINE_CONNECTION_ENV_TEMPLATE = Qnil;
+static VALUE IODINE_CONNECTION_ENV_TEMPLATE_HTTPS = Qnil;
+static VALUE IODINE_RACK_PROTOCOL_STR;
+static VALUE IODINE_RACK_HIJACK_ID_SYM;
+static VALUE IODINE_RACK_HIJACK_STR;
+static VALUE IODINE_RACK_HIJACK_SYM;
+static VALUE IODINE_RACK_UPGRADE_STR;
+static VALUE IODINE_RACK_UPGRADE_Q_STR;
+static VALUE IODINE_RACK_UPGRADE_WS_SYM;
+static VALUE IODINE_RACK_UPGRADE_SSE_SYM;
+static VALUE IODINE_RACK_AFTER_RPLY_STR;
+
+/** Buffer size for raw TCP/IP connection data reads (16KB default). */
+#ifndef IODINE_RAW_ON_DATA_READ_BUFFER
+#define IODINE_RAW_ON_DATA_READ_BUFFER (1ULL << 14)
+#endif
+
+/**
+ * Returns true if the Ruby VALUE should be skipped for GC store operations.
+ * Immediate values (nil, true, false, fixnums) don't need GC protection.
+ */
+#define IODINE_STORE_IS_SKIP(o)                                                \
+  (!o || o == Qnil || o == Qtrue || o == Qfalse || TYPE(o) == RUBY_T_FIXNUM)
+
+/**
+ * Converts a Ruby String to a fio_str_info_s struct.
+ * @note The Ruby String must remain valid while the struct is in use.
+ */
+#define IODINE_RSTR_INFO(o)                                                    \
+  { .buf = RSTRING_PTR(o), .len = (size_t)RSTRING_LEN(o) }
+
+/* *****************************************************************************
+Deferring Ruby Blocks
+
+Provides macros for scheduling Ruby blocks to run asynchronously in the
+IO reactor's thread pool.
+***************************************************************************** */
+
+/** Forward declaration for async block execution callback. */
+static void iodine_defer_performe_once(void *block, void *ignr);
+
+/**
+ * Schedules a Ruby block (Proc) to run asynchronously in the thread pool.
+ *
+ * The block is protected from GC until execution completes.
+ *
+ * @param blk A Ruby VALUE representing a Proc object.
+ */
+#define IODINE_DEFER_BLOCK(blk)                                                \
+  do {                                                                         \
+    STORE.hold((blk));                                                         \
+    fio_io_async(&IODINE_THREAD_POOL,                                          \
+                 iodine_defer_performe_once,                                   \
+                 (void *)(blk));                                               \
+  } while (0)
+
+/* *****************************************************************************
+Leak Counters
+***************************************************************************** */
+FIO_LEAK_COUNTER_DEF(iodine_connection)
+FIO_LEAK_COUNTER_DEF(iodine_minimap)
+FIO_LEAK_COUNTER_DEF(iodine_mustache)
+FIO_LEAK_COUNTER_DEF(iodine_pubsub_msg)
+FIO_LEAK_COUNTER_DEF(iodine_pubsub_sub)
+// FIO_LEAK_COUNTER_DEF(iodine_pubsub_eng) /* Ruby doesn't free */
+FIO_LEAK_COUNTER_DEF(iodine_hmap)
+
+/* *****************************************************************************
+Common Iodine Helpers
+
+Core infrastructure shared across all Iodine modules.
+***************************************************************************** */
+
+/** The global IO reactor thread pool for async task execution. */
+static fio_io_async_s IODINE_THREAD_POOL;
+
+static VALUE iodine_handler_method_injection__inner(VALUE self,
+                                                    VALUE handler,
+                                                    bool is_middleware);
+/* Core GC protection */
+#include "iodine_store.h"
+/* layer 1 helpers */
+#include "iodine_arg_helper.h"
+/* layer 2 helpers */
+#include "iodine_caller.h"
+#include "iodine_json.h"
+#include "iodine_listener.h"
+#include "iodine_pubsub_msg.h"
+#include "iodine_utils.h"
+/* layer 1 modules */
+#include "iodine_cli.h"
+#include "iodine_defer.h"
+#include "iodine_log.h"
+#include "iodine_minimap.h"
+/* layer 2 modules */
+#include "iodine_compression.h"
+#include "iodine_crypto.h"
+#include "iodine_mustache.h"
+#include "iodine_pubsub_eng.h"
+#include "iodine_pubsub_history.h"
+#include "iodine_redis.h"
+#include "iodine_threads.h"
+#include "iodine_tls.h"
+/* layer 3 modules */
+#include "iodine_connection.h"
+
+/* layer 4 modules */
+#include "iodine_core.h"
+
+#endif /* H___IODINE___H */

data/ext/iodine/iodine_arg_helper.h

@@ -0,0 +1,329 @@
+#ifndef H___IODINE_ARG_HELPER___H
+#define H___IODINE_ARG_HELPER___H
+#include "iodine.h"
+
+/* *****************************************************************************
+Ruby Multi-Argument Helper
+
+Reads and validates method arguments (either "splat" or Hash Map).
+
+    iodine_rb2c_arg(argc, argv,
+         IODINE_ARG_RB(var_name, id_or_0, "name1", 1),
+         IODINE_ARG_STR(var_name, id_or_0, "name2", 0),
+         IODINE_ARG_NUM(var_name, id_or_0, "name3", 0),
+         IODINE_ARG_PROC(var_name, id_or_0, "name4", 0));
+
+The `IODINE_ARG_XXX` macro arguments are as follows:
+
+    IODINE_ARG_XXX(target_varriable, id_or_0, named_argument, required)
+
+Example:
+
+    fio_buf_info_s file_name = {0};
+    fio_buf_info_s file_content = {0};
+    VALUE on_yaml_block = Qnil;
+    iodine_rb2c_arg(argc, argv,
+         IODINE_ARG_STR(file_name, 0, "file", 0),
+         IODINE_ARG_STR(file_content, 0, "data", 0),
+         IODINE_ARG_PROC(on_yaml_block, 0, "on_yaml", 1));
+
+For Ruby methods declared as:
+
+    static VALUE my_method(int argc, VALUE *argv, VALUE klass);
+    rb_define_singleton_method(klass, "method", my_method, -1);
+
+***************************************************************************** */
+
+/* *****************************************************************************
+Ruby arguments to C arguments
+***************************************************************************** */
+
+typedef struct {
+  int expected_type;
+  union {
+    VALUE *rb;
+    fio_buf_info_s *buf;
+    fio_str_info_s *str;
+    int64_t *num;
+    size_t *zu;
+    int32_t *i32;
+    int16_t *i16;
+    int8_t *i8;
+    uint64_t *u64;
+    uint32_t *u32;
+    uint16_t *u16;
+    uint8_t *u8;
+  };
+  ID id;
+  fio_buf_info_s name;
+  int required;
+} iodine_rb2c_arg_s;
+
+#define IODINE_ARG_RB(t_var, id_, name_, required_)                            \
+  {                                                                            \
+    .expected_type = 0, .rb = &(t_var), .id = (id_),                           \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_BUF(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 1, .buf = &(t_var), .id = (id_),                          \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_STR(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 2, .str = &(t_var), .id = (id_),                          \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_NUM(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 3, .num = &(t_var), .id = (id_),                          \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_PROC(t_var, id_, name_, required_)                          \
+  {                                                                            \
+    .expected_type = 4, .rb = &(t_var), .id = (id_),                           \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_SIZE_T(t_var, id_, name_, required_)                        \
+  {                                                                            \
+    .expected_type = 5, .zu = &(t_var), .id = (id_),                           \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_I32(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 6, .i32 = &(t_var), .id = (id_),                          \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_I16(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 7, .i16 = &(t_var), .id = (id_),                          \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_I8(t_var, id_, name_, required_)                            \
+  {                                                                            \
+    .expected_type = 8, .i8 = &(t_var), .id = (id_),                           \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_BOOL(t_var, id_, name_, required_)                          \
+  {                                                                            \
+    .expected_type = 9, .u8 = &(t_var), .id = (id_),                           \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_U64(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 10, .u64 = &(t_var), .id = (id_),                         \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_U32(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 11, .u32 = &(t_var), .id = (id_),                         \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_U16(t_var, id_, name_, required_)                           \
+  {                                                                            \
+    .expected_type = 12, .u16 = &(t_var), .id = (id_),                         \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+#define IODINE_ARG_U8(t_var, id_, name_, required_)                            \
+  {                                                                            \
+    .expected_type = 13, .u8 = &(t_var), .id = (id_),                          \
+    .name = FIO_BUF_INFO1(((char *)name_)), .required = (required_)            \
+  }
+
+/** Converts a Ruby Integer to a signed value in [min, max] or raises. */
+static int64_t iodine___rb2c_arg2i(VALUE o,
+                                   int64_t min,
+                                   int64_t max,
+                                   const char *name) {
+  if (!RB_INTEGER_TYPE_P(o))
+    rb_raise(rb_eTypeError, "%s should be a Number", name);
+  long long v = NUM2LL(o); /* raises RangeError beyond int64 */
+  if (v < min || v > max)
+    rb_raise(rb_eRangeError, "%s out of range", name);
+  return (int64_t)v;
+}
+
+/** Converts a Ruby Integer to an unsigned value in [0, max] or raises. */
+static uint64_t iodine___rb2c_arg2u(VALUE o, uint64_t max, const char *name) {
+  if (!RB_INTEGER_TYPE_P(o))
+    rb_raise(rb_eTypeError, "%s should be a Number", name);
+  uint64_t u = 0;
+  /* returns sign: -1/-2 when negative, +2 on uint64 overflow */
+  int s = rb_integer_pack(o,
+                          &u,
+                          1,
+                          sizeof(u),
+                          0,
+                          INTEGER_PACK_LSWORD_FIRST |
+                              INTEGER_PACK_NATIVE_BYTE_ORDER);
+  if (s < 0 || s > 1 || u > max)
+    rb_raise(rb_eRangeError, "%s out of range", name);
+  return u;
+}
+
+/** Reads and validates method arguments (either "splat" or Hash Map). */
+static int iodine_rb2c_arg(int argc, const VALUE *argv, iodine_rb2c_arg_s *a) {
+  int i = 0;
+  VALUE tmp = Qnil;
+
+#define IODINE_RB2C_STORE_ARG()                                                \
+  if (!a[i].rb)                                                                \
+    goto too_many_arguments;                                                   \
+  if (tmp == Qnil && a[i].expected_type != 4) {                                \
+    if (a[i].required)                                                         \
+      goto missing_required;                                                   \
+    continue;                                                                  \
+  }                                                                            \
+  switch (a[i].expected_type) {                                                \
+  case 0:                                                                      \
+    a[i].rb[0] = tmp;                                                          \
+    STORE.cache(tmp);                                                          \
+    continue;                                                                  \
+  case 1:                                                                      \
+    if (RB_TYPE_P(tmp, RUBY_T_SYMBOL))                                         \
+      tmp = rb_sym2str(tmp);                                                   \
+    if (!RB_TYPE_P(tmp, RUBY_T_STRING))                                        \
+      rb_raise(rb_eTypeError,                                                  \
+               "%s should be a String (or Symbol)",                            \
+               a[i].name.buf);                                                 \
+    STORE.cache(tmp);                                                          \
+    a[i].buf[0] = FIO_BUF_INFO2(RSTRING_PTR(tmp), (size_t)RSTRING_LEN(tmp));   \
+    continue;                                                                  \
+  case 2:                                                                      \
+    if (RB_TYPE_P(tmp, RUBY_T_SYMBOL))                                         \
+      tmp = rb_sym2str(tmp);                                                   \
+    if (!RB_TYPE_P(tmp, RUBY_T_STRING))                                        \
+      rb_raise(rb_eTypeError,                                                  \
+               "%s should be a String (or Symbol)",                            \
+               a[i].name.buf);                                                 \
+    STORE.cache(tmp);                                                          \
+    a[i].str[0] = FIO_STR_INFO2(RSTRING_PTR(tmp), (size_t)RSTRING_LEN(tmp));   \
+    continue;                                                                  \
+  case 3:                                                                      \
+    a[i].num[0] = (int64_t)                                                    \
+        iodine___rb2c_arg2i(tmp, INT64_MIN, INT64_MAX, a[i].name.buf);         \
+    continue;                                                                  \
+  case 4:                                                                      \
+    if (tmp == Qnil) {                                                         \
+      if (rb_block_given_p()) {                                                \
+        tmp = rb_block_proc();                                                 \
+        STORE.cache(tmp);                                                      \
+      } else if (a[i].required)                                                \
+        goto missing_required;                                                 \
+      else                                                                     \
+        continue;                                                              \
+    } else if (tmp != Qnil && !rb_respond_to(tmp, rb_intern2("call", 4)))      \
+      rb_raise(rb_eArgError, "a callback object MUST respond to `call`");      \
+    a[i].rb[0] = tmp;                                                          \
+    STORE.cache(tmp);                                                          \
+    continue;                                                                  \
+  case 5:                                                                      \
+    a[i].zu[0] = (size_t)                                                      \
+        iodine___rb2c_arg2u(tmp, SIZE_MAX, a[i].name.buf);                     \
+    continue;                                                                  \
+  case 6:                                                                      \
+    a[i].i32[0] = (int32_t)                                                    \
+        iodine___rb2c_arg2i(tmp, INT32_MIN, INT32_MAX, a[i].name.buf);         \
+    continue;                                                                  \
+  case 7:                                                                      \
+    a[i].i16[0] = (int16_t)                                                    \
+        iodine___rb2c_arg2i(tmp, INT16_MIN, INT16_MAX, a[i].name.buf);         \
+    continue;                                                                  \
+  case 8:                                                                      \
+    a[i].i8[0] = (int8_t)                                                      \
+        iodine___rb2c_arg2i(tmp, INT8_MIN, INT8_MAX, a[i].name.buf);           \
+    continue;                                                                  \
+  case 9: /* nil keeps the default (handled above) */                          \
+    if (tmp != Qtrue && tmp != Qfalse)                                         \
+      rb_raise(rb_eTypeError, "%s should be a Boolean", a[i].name.buf);        \
+    a[i].u8[0] = (tmp == Qtrue);                                               \
+    continue;                                                                  \
+  case 10:                                                                     \
+    a[i].u64[0] = (uint64_t)                                                   \
+        iodine___rb2c_arg2u(tmp, UINT64_MAX, a[i].name.buf);                   \
+    continue;                                                                  \
+  case 11:                                                                     \
+    a[i].u32[0] = (uint32_t)                                                   \
+        iodine___rb2c_arg2u(tmp, UINT32_MAX, a[i].name.buf);                   \
+    continue;                                                                  \
+  case 12:                                                                     \
+    a[i].u16[0] = (uint16_t)                                                   \
+        iodine___rb2c_arg2u(tmp, UINT16_MAX, a[i].name.buf);                   \
+    continue;                                                                  \
+  case 13:                                                                     \
+    a[i].u8[0] = (uint8_t)                                                     \
+        iodine___rb2c_arg2u(tmp, UINT8_MAX, a[i].name.buf);                    \
+    continue;                                                                  \
+  default:                                                                     \
+    rb_raise(rb_eException,                                                    \
+             "C code failure - missing valid expected_type @ %s",              \
+             a[i].name.buf);                                                   \
+  }
+  /* FIXME: allow partially named arguments. */
+  if (argc) {
+    --argc;
+    for (; i < argc; ++i) {
+      /* unnamed parameters (list of parameters), excluding last parameter */
+      tmp = argv[i];
+      IODINE_RB2C_STORE_ARG();
+    }
+    /* last parameter is special, as it may be a named parameter Hash */
+    tmp = argv[argc];
+    i = argc; /* does `for` add even after condition breaks loop? no, so why? */
+
+    if (RB_TYPE_P(tmp, RUBY_T_HASH)) { /* named parameters (hash table) */
+      VALUE tbl = tmp;
+      if (a[i].expected_type == 0)
+        a[i].rb[0] = tmp;
+      for (; a[i].rb; ++i) {
+        tmp = rb_hash_aref(
+            tbl,
+            rb_id2sym(a[i].id ? a[i].id
+                              : rb_intern2(a[i].name.buf, a[i].name.len)));
+        IODINE_RB2C_STORE_ARG();
+      }
+      return 0;
+    }
+    if (a[i].rb) {
+      do {
+        IODINE_RB2C_STORE_ARG();
+      } while (0);
+      ++i;
+    }
+    tmp = Qnil;
+  }
+  for (; a[i].rb; ++i) {
+    /* possible leftover last parameter */
+    if (a[i].expected_type == 4) {
+      IODINE_RB2C_STORE_ARG();
+      continue;
+    }
+    if (a[i].required)
+      goto missing_required;
+  }
+  return 0;
+
+#undef IODINE_RB2C_STORE_ARG
+too_many_arguments:
+  rb_raise(rb_eArgError, "too many arguments in method call.");
+  return -1;
+missing_required:
+  rb_raise(rb_eArgError, "missing required argument %s.", a[i].name.buf);
+  return -1;
+}
+
+/**
+ * Reads and validates method arguments (either "splat" or Hash Map).
+ *
+ * Use:
+ *
+ *     iodine_rb2c_arg(argc, argv,
+ *          IODINE_ARG_RB(var_name, id_or_0, "name1", 1),
+ *          IODINE_ARG_STR(var_name, id_or_0, "name2", 0),
+ *          IODINE_ARG_NUM(var_name, id_or_0, "name3", 0),
+ *          IODINE_ARG_PROC(var_name, id_or_0, "name4", 0));
+ */
+#define iodine_rb2c_arg(argc, argv, ...)                                       \
+  iodine_rb2c_arg(argc, argv, (iodine_rb2c_arg_s[]){__VA_ARGS__, {0}})
+
+#endif /* H___IODINE_ARG_HELPER___H */