iodine 0.5.2 → 0.6.0

data/examples/pubsub_engine.ru

@@ -9,9 +9,9 @@ class PubSubReporter < Iodine::PubSub::Engine
     # make sure engine setup is complete
     super 
     # register engine and make it into the new default
-    @target = Iodine::PubSub.default_engine
-    Iodine::PubSub.default_engine = self
-    Iodine::PubSub.register self
+    @target = Iodine::PubSub.default
+    Iodine::PubSub.default = self
+    Iodine::PubSub.attach self
   end
   def subscribe to, as = nil
     puts "* Subscribing to \"#{to}\" (#{as || "exact match"})"
@@ -57,22 +57,22 @@ class PubSubClient
     @name = name
   end
   # seng a message to new clients.
-  def on_open
-    subscribe "chat"
+  def on_open(client)
+    client.subscribe "chat"
     # let everyone know we arrived
-    publish "chat", "#{@name} entered the chat."
+    client.publish "chat", "#{@name} entered the chat."
   end
   # send a message, letting the client know the server is suggunt down.
-  def on_shutdown
-    write "Server shutting down. Goodbye."
+  def on_shutdown(client)
+    client.write "Server shutting down. Goodbye."
   end
   # perform the echo
-  def on_message data
-    publish "chat", "#{@name}: #{data}"
+  def on_message(client, data)
+    client.publish "chat", "#{@name}: #{data}"
   end
-  def on_close
+  def on_close(client)
     # let everyone know we left
-    publish "chat", "#{@name} left the chat."
+    client.publish "chat", "#{@name} left the chat."
     # we don't need to unsubscribe, subscriptions are cleared automatically once the connection is closed.
   end
 end

data/examples/redis.ru

@@ -5,12 +5,10 @@
 #      REDIS_URL=redis://localhost:6379/0 iodine -t 1 -p 3000 redis.ru
 #      REDIS_URL=redis://localhost:6379/0 iodine -t 1 -p 3030 redis.ru
 #
-require 'uri'
 require 'iodine'
 # initialize the Redis engine for each Iodine process.
 if ENV["REDIS_URL"]
-  uri = URI(ENV["REDIS_URL"])
-  Iodine.default_pubsub = Iodine::PubSub::RedisEngine.new(uri.host, uri.port, 0, uri.password)
+  Iodine::PubSub.default = Iodine::PubSub::Redis.new(ENV["REDIS_URL"], ping: 10)
 else
   puts "* No Redis, it's okay, pub/sub will support the process cluster."
 end
@@ -43,22 +41,22 @@ class WS_RedisPubSub
     @name = name
   end
   # seng a message to new clients.
-  def on_open
-    subscribe "chat"
+  def on_open client
+    client.subscribe "chat"
     # let everyone know we arrived
-    publish "chat", "#{@name} entered the chat."
+    client.publish "chat", "#{@name} entered the chat."
   end
   # send a message, letting the client know the server is suggunt down.
-  def on_shutdown
-    write "Server shutting down. Goodbye."
+  def on_shutdown client 
+    client.write "Server shutting down. Goodbye."
   end
   # perform the echo
-  def on_message data
-    publish "chat", "#{@name}: #{data}"
+  def on_message client, data
+    client.publish "chat", "#{@name}: #{data}"
   end
-  def on_close
+  def on_close client
     # let everyone know we left
-    publish "chat", "#{@name} left the chat."
+    client.publish "chat", "#{@name} left the chat."
     # we don't need to unsubscribe, subscriptions are cleared automatically once the connection is closed.
   end
 end

data/examples/shootout.ru

@@ -1,22 +1,12 @@
 require 'iodine'
 require 'json'
 
-# ON_IDLE = proc { Iodine::Base.db_print_registry ; Iodine.on_idle(&ON_IDLE) }
-# ON_IDLE.call
-
-class ShootoutApp
+module ShootoutApp
   # the default HTTP response
   def self.call(env)
-    if(Iodine::VERSION >= "0.5.0")
-       if(env['rack.upgrade?'.freeze] == :websocket)
-        env['rack.upgrade'.freeze] = ShootoutApp.new
-        return [0, {}, []]
-      end
-    else
-       if(env['upgrade.websocket?'.freeze])
-        env['upgrade.websocket'.freeze] = ShootoutApp.new
-        return [0, {}, []]
-      end
+     if(env['rack.upgrade?'.freeze] == :websocket)
+      env['rack.upgrade'.freeze] = ShootoutApp
+      return [0, {}, []]
     end
     out = []
     len = 0
@@ -36,46 +26,27 @@ class ShootoutApp
   # We'll base the shootout on the internal Pub/Sub service.
   # It's slower than writing to every socket a pre-parsed message, but it's closer
   # to real-life implementations.
-  def on_open
-    if(Iodine::VERSION >= "0.5.0")
-      subscribe :shootout, as: :binary
-    else
-      subscribe channel: :shootout
-    end
+  def self.on_open client
+      client.subscribe :shootout_b, as: :binary
+      client.subscribe :shootout
   end
-  def on_message data
+  def self.on_message client, data
     if data[0] == 'b' # binary
-      if(Iodine::VERSION >= "0.5.0")
-        publish :shootout, data
-      else
-        publish channel: :shootout, message: data
-      end
+        client.publish :shootout_b, data
       data[0] = 'r'
-      write data
+      client.write data
       return
     end
     cmd, payload = JSON(data).values_at('type', 'payload')
     if cmd == 'echo'
-      write({type: 'echo', payload: payload}.to_json)
+      client.write({type: 'echo', payload: payload}.to_json)
     else
-      # data = {type: 'broadcast', payload: payload}.to_json
-      # broadcast :push2client, data
-      if(Iodine::VERSION >= "0.5.0")
-        publish :shootout, {type: 'broadcast', payload: payload}.to_json
-      else
-        publish channel: :shootout, message: {type: 'broadcast', payload: payload}.to_json
-      end
-      write({type: "broadcastResult", payload: payload}.to_json)
+      client.publish :shootout, {type: 'broadcast', payload: payload}.to_json
+      client.write({type: "broadcastResult", payload: payload}.to_json)
     end
-  rescue
-    puts "Incoming message format error - not JSON?"
   end
 end
 
-# if defined?(Iodine)
-#   Iodine.run_every(5000) { Iodine::Base.db_print_registry }
-# end
-
 run ShootoutApp
 #
 # def cycle
@@ -85,3 +56,9 @@ run ShootoutApp
 #   true
 # end
 # sleep(10) while cycle
+
+# # Used when debugging:
+# ON_IDLE = proc { Iodine::Base.db_print_protected_objects ; Iodine.on_idle(&ON_IDLE) }
+# ON_IDLE.call
+# Iodine.on_shutdown { Iodine::Base.db_print_protected_objects }
+

data/exe/iodine

@@ -1,5 +1,120 @@
 #!/usr/bin/env ruby
+require 'rack'
+require 'iodine'
 
-require 'iodine/cli'
+module Iodine
+  # The Iodine::Base namespace is reserved for internal use and is NOT part of the public API.
+  module Base
+    # Command line interface. The Ruby CLI might be changed in future versions.
+    module CLI
+
+      def print_help
+        puts <<-EOS
+
+Iodine's HTTP/Websocket server version #{Iodine::VERSION}
+
+Use:
+
+    iodine <options> <filename>
+
+Both <options> and <filename> are optional.
+
+Available options:
+ -b          Binding address. Default: nil (same as 0.0.0.0).
+ -p          Port number. Default: 3000.
+ -t          Number of threads. Default: CPU core count.
+ -w          Number of worker processes. Default: CPU core count.
+ -www        Public folder for static file serving. Default: nil (none).
+ -v          Log responses. Default: never log responses.
+ -warmup     Warmup invokes autoloading (lazy loading) during server startup.
+ -tout       HTTP inactivity connection timeout. Default: 40 seconds.
+ -maxhead    Maximum total headers length per HTTP request. Default: 32Kb.
+ -maxbd      Maximum Mb per HTTP message (max body size). Default: 50Mb.
+ -maxms      Maximum Bytes per Websocket message. Default: 250Kb.
+ -ping       WebSocket / SSE ping interval in seconds. Default: 40 seconds.
+ <filename>  Defaults to: config.ru
+
+Example:
+
+    iodine -p 80
+
+    iodine -p 8080 path/to/app/conf.ru
+
+    iodine -p 8080 -w 4 -t 16
+
+EOS
+      end
+
+
+      def try_file filename
+        return nil unless File.exist? filename
+        return ::Rack::Builder.parse_file filename
+      end
+
+      def filename_argument
+        return ((ARGV[-2].to_s[0] != '-' || ARGV[-2].to_s == '-warmup' || ARGV[-2].to_s == '-v' || ARGV[-2].to_s == '-q' || (ARGV[-2].to_s[0] == '-' && ARGV[-2].to_i.to_s == ARGV[-2].to_s)) && ARGV[-1].to_s[0] != '-' && ARGV[-1])
+      end
+
+      def get_app_opts
+        app, opt = nil, nil
+        filename = filename_argument
+        if filename
+          app, opt = try_file filename;
+          unless opt
+            puts "* Couldn't find #{filename}\n  testing for config.ru\n"
+            app, opt = try_file "config.ru"
+          end
+        else
+          app, opt = try_file "config.ru";
+        end
+
+        unless opt
+          puts "WARNING: Ruby application not found#{ filename ? " - missing both #{filename} and config.ru" : " - missing config.ru"}."
+          if Iodine::DEFAULT_HTTP_ARGS[:public]
+            puts "         Running only static file service."
+            opt = ::Rack::Server::Options.new.parse!([])
+          else
+            puts "For help run:"
+            puts "       iodine -?"
+            exit(0);
+          end
+        end
+        return app, opt
+      end
+
+      def perform_warmup
+        # load anything marked with `autoload`, since autoload isn't thread safe nor fork friendly.
+        Iodine.run do
+          Module.constants.each do |n|
+            begin
+              Object.const_get(n)
+            rescue Exception => _e
+            end
+          end
+          ::Rack::Builder.new(app) do |r|
+            r.warmup do |a|
+              client = ::Rack::MockRequest.new(a)
+              client.get('/')
+            end
+          end
+        end
+      end
+
+      def call
+        if ARGV[0] =~ /(\-\?)|(help)|(\?)|(h)|(\-h)$/
+          return print_help
+        end
+
+        app, opt = get_app_opts
+
+        perform_warmup if ARGV.index('-warmup')
+
+        Iodine::Rack.run(app, opt)
+      end
+
+      extend self
+    end
+  end
+end
 
 Iodine::Base::CLI.call

data/ext/iodine/defer.c

@@ -289,7 +289,7 @@ int defer_join_thread(void *p_thr) {
   if (!p_thr || !(*((pthread_t *)p_thr)))
     return -1;
   pthread_join(*((pthread_t *)p_thr), NULL);
-  *((pthread_t *)p_thr) = NULL;
+  *((pthread_t *)p_thr) = (pthread_t)NULL;
   defer_free_thread(p_thr);
   return 0;
 }

data/ext/iodine/facil.c

@@ -135,7 +135,7 @@ static const char *CLUSTER_CONNECTION_PROTOCOL_NAME =
     "cluster connection __facil_internal__";
 
 static inline int is_counted_protocol(protocol_s *p) {
-  return p->service != TIMER_PROTOCOL_NAME &&
+  return p && p->service != TIMER_PROTOCOL_NAME &&
          p->service != CLUSTER_LISTEN_PROTOCOL_NAME &&
          p->service != CLUSTER_CONNECTION_PROTOCOL_NAME;
 }
@@ -419,6 +419,10 @@ Initialization and Cleanup
 ***************************************************************************** */
 static spn_lock_i facil_libinit_lock = SPN_LOCK_INIT;
 
+/** Rounds up any size to the nearest page alignment (assumes 4096 bytes per
+ * page) */
+#define round_size(size) (((size) & (~4095)) + (4096 * (!!((size)&4095))))
+
 static void facil_cluster_cleanup(void); /* cluster data cleanup */
 
 static void facil_libcleanup(void) {
@@ -427,10 +431,10 @@ static void facil_libcleanup(void) {
   if (facil_data) {
     facil_external_root_cleanup();
     facil_cluster_cleanup();
-    defer_perform(); /* perform any lingering cleanup tasks */
-    munmap(facil_data,
-           sizeof(*facil_data) + ((size_t)facil_data->capacity *
-                                  sizeof(struct connection_data_s)));
+    // defer_perform(); /* perform any lingering cleanup tasks? */
+    size_t mem_size = sizeof(*facil_data) + ((size_t)facil_data->capacity *
+                                             sizeof(struct connection_data_s));
+    munmap(facil_data, round_size(mem_size));
     facil_data = NULL;
   }
   spn_unlock(&facil_libinit_lock);
@@ -447,7 +451,7 @@ static void facil_lib_init(void) {
   spn_lock(&facil_libinit_lock);
   if (facil_data)
     goto finish;
-  facil_data = mmap(NULL, mem_size, PROT_READ | PROT_WRITE,
+  facil_data = mmap(NULL, round_size(mem_size), PROT_READ | PROT_WRITE,
                     MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
   if (!facil_data || facil_data == MAP_FAILED) {
     perror("ERROR: Couldn't initialize the facil.io library");
@@ -1677,7 +1681,7 @@ static void facil_worker_cleanup(void) {
   facil_cluster_signal_children();
   for (int i = 0; i <= facil_data->capacity; ++i) {
     intptr_t uuid;
-    if (fd_data(i).protocol && is_counted_protocol(fd_data(i).protocol) &&
+    if (is_counted_protocol(fd_data(i).protocol) &&
         (uuid = sock_fd2uuid(i)) >= 0) {
       defer(deferred_on_shutdown, (void *)uuid, NULL);
     }
@@ -2059,7 +2063,7 @@ static int facil_attach_state(intptr_t uuid, protocol_s *protocol,
       spn_sub(&facil_data->connection_count, 1);
     }
     defer(deferred_on_close, (void *)uuid, old_protocol);
-  } else if (evio_isactive()) {
+  } else if (evio_isactive() && protocol) {
     return evio_add(sock_uuid2fd(uuid), (void *)uuid);
   }
   return 0;

data/ext/iodine/facil.h

@@ -564,8 +564,8 @@ void facil_cluster_set_handler(int32_t filter,
 
 Unknown `msg_type` values are silently ignored.
 
-The `msg_type` value can be any number less than 1,073,741,824. All values
-starting at 1,073,741,824 are reserved for internal use.
+The `msg_type` value can be any positive number less than 1,073,741,824. All
+negative values and values above 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.

data/ext/iodine/iodine.c

@@ -1,158 +1,32 @@
 #include "iodine.h"
-#include "iodine_helpers.h"
-#include "iodine_http.h"
-#include "iodine_protocol.h"
-#include "iodine_pubsub.h"
-#include "iodine_websockets.h"
-#include "rb-rack-io.h"
-#include <dlfcn.h>
-/*
-Copyright: Boaz segev, 2016-2017
-License: MIT
-
-Feel free to copy, use and enjoy according to the license provided.
-*/
 
-VALUE Iodine;
-VALUE IodineBase;
-
-VALUE iodine_force_var_id;
-VALUE iodine_channel_var_id;
-VALUE iodine_pattern_var_id;
-VALUE iodine_text_var_id;
-VALUE iodine_binary_var_id;
-VALUE iodine_engine_var_id;
-VALUE iodine_message_var_id;
-
-ID iodine_fd_var_id;
-ID iodine_cdata_var_id;
-ID iodine_timeout_var_id;
-ID iodine_call_proc_id;
-ID iodine_new_func_id;
-ID iodine_on_open_func_id;
-ID iodine_on_message_func_id;
-ID iodine_on_data_func_id;
-ID iodine_on_drained_func_id;
-ID iodine_on_shutdown_func_id;
-ID iodine_on_close_func_id;
-ID iodine_ping_func_id;
-ID iodine_buff_var_id;
-ID iodine_to_s_method_id;
-ID iodine_to_i_func_id;
-
-rb_encoding *IodineBinaryEncoding;
-rb_encoding *IodineUTF8Encoding;
-int IodineBinaryEncodingIndex;
-int IodineUTF8EncodingIndex;
+#include <ruby/version.h>
 
+#include "facil.h"
 /* *****************************************************************************
-Internal helpers
+OS specific patches
 ***************************************************************************** */
 
-static void iodine_run_task(void *block_) {
-  RubyCaller.call((VALUE)block_, iodine_call_proc_id);
-}
+#ifdef __APPLE__
+#include <dlfcn.h>
+#endif
 
-static void iodine_perform_deferred(void *block_, void *ignr) {
-  RubyCaller.call((VALUE)block_, iodine_call_proc_id);
-  Registry.remove((VALUE)block_);
-  (void)ignr;
+/** Any patches required by the running environment for consistent behavior */
+static void patch_env(void) {
+#ifdef __APPLE__
+  /* patch for dealing with the High Sierra `fork` limitations */
+  void *obj_c_runtime = dlopen("Foundation.framework/Foundation", RTLD_LAZY);
+  (void)obj_c_runtime;
+#endif
 }
 
 /* *****************************************************************************
-Published functions
+Constants and State
 ***************************************************************************** */
 
-/** Returns the number of total connections managed by Iodine. */
-static VALUE iodine_count(VALUE self) {
-  size_t count = facil_count(NULL);
-  return ULL2NUM(count);
-  (void)self;
-}
-
-/**
-Runs the required block after the specified number of milliseconds have passed.
-Time is counted only once Iodine started running (using {Iodine.start}).
-
-Tasks scheduled before calling {Iodine.start} will run once for every process.
-
-Always returns a copy of the block object.
-*/
-static VALUE iodine_run_after(VALUE self, VALUE milliseconds) {
-  (void)(self);
-  if (TYPE(milliseconds) != T_FIXNUM) {
-    rb_raise(rb_eTypeError, "milliseconds must be a number");
-    return Qnil;
-  }
-  size_t milli = FIX2UINT(milliseconds);
-  // requires a block to be passed
-  rb_need_block();
-  VALUE block = rb_block_proc();
-  if (block == Qnil)
-    return Qfalse;
-  Registry.add(block);
-  if (facil_run_every(milli, 1, iodine_run_task, (void *)block,
-                      (void (*)(void *))Registry.remove) == -1) {
-    perror("ERROR: Iodine couldn't initialize timer");
-    return Qnil;
-  }
-  return block;
-}
-/**
-Runs the required block after the specified number of milliseconds have passed.
-Time is counted only once Iodine started running (using {Iodine.start}).
-
-Accepts:
-
-milliseconds:: the number of milliseconds between event repetitions.
-
-repetitions:: the number of event repetitions. Defaults to 0 (never ending).
-
-block:: (required) a block is required, as otherwise there is nothing to
-perform.
-
-The event will repeat itself until the number of repetitions had been delpeted.
-
-Always returns a copy of the block object.
-*/
-static VALUE iodine_run_every(int argc, VALUE *argv, VALUE self) {
-  (void)(self);
-  VALUE milliseconds, repetitions, block;
-
-  rb_scan_args(argc, argv, "11&", &milliseconds, &repetitions, &block);
-
-  if (TYPE(milliseconds) != T_FIXNUM) {
-    rb_raise(rb_eTypeError, "milliseconds must be a number.");
-    return Qnil;
-  }
-  if (repetitions != Qnil && TYPE(repetitions) != T_FIXNUM) {
-    rb_raise(rb_eTypeError, "repetitions must be a number or `nil`.");
-    return Qnil;
-  }
-
-  size_t milli = FIX2UINT(milliseconds);
-  size_t repeat = (repetitions == Qnil) ? 0 : FIX2UINT(repetitions);
-  // requires a block to be passed
-  rb_need_block();
-  Registry.add(block);
-  if (facil_run_every(milli, repeat, iodine_run_task, (void *)block,
-                      (void (*)(void *))Registry.remove) == -1) {
-    perror("ERROR: Iodine couldn't initialize timer");
-    return Qnil;
-  }
-  return block;
-}
-
-static VALUE iodine_run(VALUE self) {
-  rb_need_block();
-  VALUE block = rb_block_proc();
-  if (block == Qnil)
-    return Qfalse;
-  Registry.add(block);
-  defer(iodine_perform_deferred, (void *)block, NULL);
-  return block;
-  (void)self;
-}
+VALUE IodineModule;
+VALUE IodineBaseModule;
+static ID call_id;
 
 /* *****************************************************************************
 Idling
@@ -163,6 +37,11 @@ Idling
 static spn_lock_i iodine_on_idle_lock = SPN_LOCK_INIT;
 static fio_ls_s iodine_on_idle_list = FIO_LS_INIT(iodine_on_idle_list);
 
+static void iodine_perform_deferred(void *block, void *ignr) {
+  IodineCaller.call((VALUE)block, call_id);
+  (void)ignr;
+}
+
 /**
 Schedules a single occuring event for the next idle cycle.
 
@@ -177,7 +56,7 @@ i.e.
 VALUE iodine_sched_on_idle(VALUE self) {
   rb_need_block();
   VALUE block = rb_block_proc();
-  Registry.add(block);
+  IodineStore.add(block);
   spn_lock(&iodine_on_idle_lock);
   fio_ls_push(&iodine_on_idle_list, (void *)block);
   spn_unlock(&iodine_on_idle_lock);
@@ -190,169 +69,141 @@ static void iodine_on_idle(void) {
   while (fio_ls_any(&iodine_on_idle_list)) {
     VALUE block = (VALUE)fio_ls_shift(&iodine_on_idle_list);
     defer(iodine_perform_deferred, (void *)block, NULL);
+    IodineStore.remove(block);
   }
   spn_unlock(&iodine_on_idle_lock);
 }
+
 /* *****************************************************************************
-Running the server
+Running Iodine
 ***************************************************************************** */
 
-#include "spnlock.inc"
-#include <pthread.h>
-
-static volatile int sock_io_thread = 0;
-static pthread_t sock_io_pthread;
 typedef struct {
-  size_t threads;
-  size_t processes;
-} iodine_start_settings_s;
-
-static void *iodine_io_thread(void *arg) {
-  (void)arg;
-  struct timespec tm;
-  while (sock_io_thread) {
-    sock_flush_all();
-    tm = (struct timespec){.tv_nsec = 0, .tv_sec = 1};
-    nanosleep(&tm, NULL);
-  }
+  int16_t threads;
+  int16_t workers;
+} iodine_start_params_s;
+
+static void *iodine_run_outside_GVL(void *params_) {
+  iodine_start_params_s *params = params_;
+  facil_run(.threads = params->threads, .processes = params->workers,
+            .on_idle = iodine_on_idle, .on_finish = iodine_defer_on_finish);
   return NULL;
 }
-void iodine_start_io_thread(void *a1, void *a2) {
-  (void)a1;
-  (void)a2;
-  pthread_create(&sock_io_pthread, NULL, iodine_io_thread, NULL);
-}
-static void iodine_join_io_thread(void) {
-  sock_io_thread = 0;
-  if (sock_io_pthread) {
-    pthread_join(sock_io_pthread, NULL);
-  }
-  sock_io_pthread = NULL;
-}
 
-static void *srv_start_no_gvl(void *s_) {
-  iodine_start_settings_s *s = s_;
-  sock_io_thread = 1;
-  iodine_start_io_thread(NULL, NULL);
-  fprintf(stderr, "\n");
-  if (s->processes == 1 || (s->processes == 0 && s->threads > 0)) {
-    /* single worker */
-    RubyCaller.call(Iodine, rb_intern("before_fork"));
-    RubyCaller.call(Iodine, rb_intern("after_fork"));
-  }
-  facil_run(.threads = s->threads, .processes = s->processes,
-            .on_idle = iodine_on_idle, .on_finish = iodine_join_io_thread);
-  return NULL;
-}
+/* *****************************************************************************
+Core API
+***************************************************************************** */
 
-static int iodine_review_rack_app(void) {
-  /* Check for Iodine::Rack.app and perform the C equivalent:
-   *  Iodine::HTTP.listen app: @app, port: @port, address: @address, log: @log,
-   *          max_msg: max_msg, max_body: max_body, public: @public, ping:
-   *          @ws_timeout, timeout: @timeout
-   */
-
-  VALUE rack = rb_const_get(Iodine, rb_intern("Rack"));
-  VALUE app = rb_ivar_get(rack, rb_intern("@app"));
-  VALUE www = rb_ivar_get(rack, rb_intern("@public"));
-  if ((app == Qnil || app == Qfalse) && (www == Qnil || www == Qfalse))
-    return 0;
-  VALUE opt = rb_hash_new();
-  Registry.add(opt);
-
-  rb_hash_aset(opt, ID2SYM(rb_intern("app")),
-               rb_ivar_get(rack, rb_intern("@app")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("port")),
-               rb_ivar_get(rack, rb_intern("@port")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("app")),
-               rb_ivar_get(rack, rb_intern("@app")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("address")),
-               rb_ivar_get(rack, rb_intern("@address")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("log")),
-               rb_ivar_get(rack, rb_intern("@log")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("max_msg")),
-               rb_ivar_get(rack, rb_intern("@max_msg")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("max_body")),
-               rb_ivar_get(rack, rb_intern("@max_body")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("public")),
-               rb_ivar_get(rack, rb_intern("@public")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("ping")),
-               rb_ivar_get(rack, rb_intern("@ws_timeout")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("timeout")),
-               rb_ivar_get(rack, rb_intern("@ws_timeout")));
-  rb_hash_aset(opt, ID2SYM(rb_intern("max_headers")),
-               rb_ivar_get(rack, rb_intern("@max_headers")));
-  if (rb_funcall2(Iodine, rb_intern("listen2http"), 1, &opt) == Qfalse) {
-    Registry.remove(opt);
-    return -1;
-  }
-  Registry.remove(opt);
-  return 0;
+/**
+ * Returns the number of worker threads that will be used when {Iodine.start}
+ * is called.
+ *
+ * Negative numbers are translated as fractions of the number of CPU cores.
+ * i.e., -2 == half the number of detected CPU cores.
+ *
+ * Zero values promise nothing (iodine will decide what to do with them).
+ */
+static VALUE iodine_threads_get(VALUE self) {
+  VALUE i = rb_ivar_get(self, rb_intern2("@threads", 8));
+  if (i == Qnil)
+    i = INT2NUM(0);
+  return i;
 }
 
 /**
-Starts the Iodine event loop. This will hang the thread until an interrupt
-(`^C`) signal is received.
-
-Returns the Iodine module.
-*/
-static VALUE iodine_start(VALUE self) {
-  /* re-register the Rack::Push namespace to point at Iodine */
-  if (rb_const_defined(rb_cObject, rb_intern("Rack"))) {
-    VALUE rack = rb_const_get(rb_cObject, rb_intern("Rack"));
-    if (rack != Qnil) {
-      if (rb_const_defined(rack, rb_intern("PubSub"))) {
-        rb_const_remove(rack, rb_intern("PubSub"));
-      }
-      rb_const_set(rack, rb_intern("PubSub"), Iodine);
-    }
+ * Sets the number of worker threads that will be used when {Iodine.start}
+ * is called.
+ *
+ * Negative numbers are translated as fractions of the number of CPU cores.
+ * i.e., -2 == half the number of detected CPU cores.
+ *
+ * Zero values promise nothing (iodine will decide what to do with them).
+ */
+static VALUE iodine_threads_set(VALUE self, VALUE val) {
+  Check_Type(val, T_FIXNUM);
+  if (NUM2SSIZET(val) >= (1 << 12)) {
+    rb_raise(rb_eRangeError, "requsted thread count is out of range.");
   }
-  /* for the special Iodine::Rack object and backwards compatibility */
-  if (iodine_review_rack_app()) {
-    fprintf(stderr, "ERROR: (iodine) cann't start Iodine::Rack.\n");
-    return Qnil;
-  }
-
-  VALUE rb_th_i = rb_iv_get(Iodine, "@threads");
-  VALUE rb_pr_i = rb_iv_get(Iodine, "@processes");
-
-  iodine_start_settings_s s = {
-      .threads = ((TYPE(rb_th_i) == T_FIXNUM) ? FIX2INT(rb_th_i) : 0),
-      .processes = ((TYPE(rb_pr_i) == T_FIXNUM) ? FIX2INT(rb_pr_i) : 0)};
-
-  RubyCaller.set_gvl_state(1);
-  RubyCaller.leave_gvl(srv_start_no_gvl, (void *)&s);
-
-  return self;
+  rb_ivar_set(self, rb_intern2("@threads", 8), val);
+  return val;
 }
 
-static VALUE iodine_is_running(VALUE self) {
-  return (facil_is_running() ? Qtrue : Qfalse);
-  (void)self;
+/**
+ *Returns the number of worker processes that will be used when {Iodine.start}
+ * is called.
+ *
+ * Negative numbers are translated as fractions of the number of CPU cores.
+ * i.e., -2 == half the number of detected CPU cores.
+ *
+ * Zero values promise nothing (iodine will decide what to do with them).
+ */
+static VALUE iodine_workers_get(VALUE self) {
+  VALUE i = rb_ivar_get(self, rb_intern2("@workers", 8));
+  if (i == Qnil)
+    i = INT2NUM(0);
+  return i;
 }
 
-/* *****************************************************************************
-Debug
-***************************************************************************** */
-
-/** Used for debugging purpuses. Lists GC protected objects */
-VALUE iodine_print_registry(VALUE self) {
-  Registry.print();
-  return Qnil;
-  (void)self;
+/**
+ * Sets the number of worker processes that will be used when {Iodine.start}
+ * is called.
+ *
+ * Negative numbers are translated as fractions of the number of CPU cores.
+ * i.e., -2 == half the number of detected CPU cores.
+ *
+ * Zero values promise nothing (iodine will decide what to do with them).
+ */
+static VALUE iodine_workers_set(VALUE self, VALUE val) {
+  Check_Type(val, T_FIXNUM);
+  if (NUM2SSIZET(val) >= (1 << 9)) {
+    rb_raise(rb_eRangeError, "requsted worker process count is out of range.");
+  }
+  rb_ivar_set(self, rb_intern2("@workers", 8), val);
+  return val;
 }
 
-/* *****************************************************************************
-Library Initialization
-***************************************************************************** */
+/** Prints the Iodine startup message */
+static void iodine_print_startup_message(iodine_start_params_s params) {
+  VALUE iodine_version = rb_const_get(IodineModule, rb_intern("VERSION"));
+  VALUE ruby_version = rb_const_get(IodineModule, rb_intern("RUBY_VERSION"));
+  facil_expected_concurrency(&params.threads, &params.workers);
+  fprintf(stderr,
+          "\nStarting up Iodine:\n"
+          " * Ruby v.%s\n * Iodine v.%s\n"
+          " * %d Workers X %d Threads per worker.\n"
+          "\n",
+          StringValueCStr(ruby_version), StringValueCStr(iodine_version),
+          params.workers, params.threads);
+  (void)params;
+}
 
-/** Any patches required by the running environment for consistent behavior */
-static void patch_env(void) {
-#ifdef __APPLE__
-  /* patch for dealing with the High Sierra `fork` limitations */
-  void *obj_c_runtime = dlopen("Foundation.framework/Foundation", RTLD_LAZY);
-  (void)obj_c_runtime;
-#endif
+/**
+ * This will block the calling (main) thread and start the Iodine reactor.
+ *
+ * When using cluster mode (2 or more worker processes), it is important that no
+ * other threads are active.
+ *
+ * For many reasons, `fork` should NOT be called while multi-threading, so
+ * cluster mode must always be initiated from the main thread in a single thread
+ * environment.
+ *
+ * For information about why forking in multi-threaded environments should be
+ * avoided, see (for example):
+ * http://www.linuxprogrammingblog.com/threads-and-fork-think-twice-before-using-them
+ *
+ */
+static VALUE iodine_start(VALUE self) {
+  if (facil_is_running()) {
+    rb_raise(rb_eRuntimeError, "Iodine already running!");
+  }
+  VALUE threads_rb = iodine_threads_get(self);
+  VALUE workers_rb = iodine_workers_get(self);
+  iodine_start_params_s params = {
+      .threads = NUM2SHORT(threads_rb), .workers = NUM2SHORT(workers_rb),
+  };
+  iodine_print_startup_message(params);
+  IodineCaller.leaveGVL(iodine_run_outside_GVL, &params);
+  return self;
 }
 
 /* *****************************************************************************
@@ -362,64 +213,47 @@ Here we connect all the C code to the Ruby interface, completing the bridge
 between Lib-Server and Ruby.
 ***************************************************************************** */
 void Init_iodine(void) {
-  // Set GVL for main thread
-  RubyCaller.set_gvl_state(1);
   // load any environment specific patches
   patch_env();
-  // initialize globally used IDs, for faster access to the Ruby layer.
-  iodine_buff_var_id = rb_intern("scrtbuffer");
-  iodine_call_proc_id = rb_intern("call");
-  iodine_cdata_var_id = rb_intern("iodine_cdata");
-  iodine_fd_var_id = rb_intern("iodine_fd");
-  iodine_new_func_id = rb_intern("new");
-  iodine_on_close_func_id = rb_intern("on_close");
-  iodine_on_data_func_id = rb_intern("on_data");
-  iodine_on_message_func_id = rb_intern("on_message");
-  iodine_on_open_func_id = rb_intern("on_open");
-  iodine_on_drained_func_id = rb_intern("on_drained");
-  iodine_on_shutdown_func_id = rb_intern("on_shutdown");
-  iodine_ping_func_id = rb_intern("ping");
-  iodine_timeout_var_id = rb_intern("@timeout");
-  iodine_to_i_func_id = rb_intern("to_i");
-  iodine_to_s_method_id = rb_intern("to_s");
-
-  iodine_binary_var_id = ID2SYM(rb_intern("binary"));
-  iodine_channel_var_id = ID2SYM(rb_intern("channel"));
-  iodine_engine_var_id = ID2SYM(rb_intern("engine"));
-  iodine_force_var_id = ID2SYM(rb_intern("encoding"));
-  iodine_message_var_id = ID2SYM(rb_intern("message"));
-  iodine_pattern_var_id = ID2SYM(rb_intern("pattern"));
-  iodine_text_var_id = ID2SYM(rb_intern("text"));
-
-  IodineBinaryEncodingIndex = rb_enc_find_index("binary");
-  IodineUTF8EncodingIndex = rb_enc_find_index("UTF-8");
-  IodineBinaryEncoding = rb_enc_find("binary");
-  IodineUTF8Encoding = rb_enc_find("UTF-8");
-
-  // The core Iodine module wraps facil.io functionality and little more.
-  Iodine = rb_define_module("Iodine");
-
-  // the Iodine singleton functions
-  rb_define_module_function(Iodine, "start", iodine_start, 0);
-  rb_define_module_function(Iodine, "running?", iodine_is_running, 0);
-  rb_define_singleton_method(Iodine, "count", iodine_count, 0);
-  rb_define_module_function(Iodine, "run", iodine_run, 0);
-  rb_define_module_function(Iodine, "run_after", iodine_run_after, 1);
-  rb_define_module_function(Iodine, "run_every", iodine_run_every, -1);
-  rb_define_module_function(Iodine, "on_idle", iodine_sched_on_idle, 0);
-
-  /// Iodine::Base is for internal use.
-  IodineBase = rb_define_module_under(Iodine, "Base");
-  rb_define_module_function(IodineBase, "db_print_registry",
-                            iodine_print_registry, 0);
-
-  // Initialize the registry under the Iodine core
-  Registry.init(Iodine);
-
-  /* Initialize the rest of the library. */
-  Iodine_init_protocol();
-  Iodine_init_pubsub();
-  Iodine_init_http();
-  Iodine_init_websocket();
-  Iodine_init_helpers();
+
+  // force the GVL state for the main thread
+  IodineCaller.set_GVL(1);
+
+  // Create the Iodine module (namespace)
+  IodineModule = rb_define_module("Iodine");
+  IodineBaseModule = rb_define_module_under(IodineModule, "Base");
+  call_id = rb_intern2("call", 4);
+
+  // register core methods
+  rb_define_module_function(IodineModule, "threads", iodine_threads_get, 0);
+  rb_define_module_function(IodineModule, "threads=", iodine_threads_set, 1);
+  rb_define_module_function(IodineModule, "workers", iodine_workers_get, 0);
+  rb_define_module_function(IodineModule, "workers=", iodine_workers_set, 1);
+  rb_define_module_function(IodineModule, "start", iodine_start, 0);
+  rb_define_module_function(IodineModule, "on_idle", iodine_sched_on_idle, 0);
+
+  // initialize Object storage for GC protection
+  iodine_storage_init();
+
+  // initialize concurrency related methods
+  iodine_defer_initialize();
+
+  // initialize the connection class
+  iodine_connection_init();
+
+  // intialize the TCP/IP related module
+  iodine_init_tcp_connections();
+
+  // initialize the HTTP module
+  iodine_init_http();
+
+  // initialize JSON helpers
+  iodine_init_json();
+
+  // initialize Rack helpers and IO
+  iodine_init_helpers();
+  IodineRackIO.init();
+
+  // initialize Pub/Sub extension (for Engines)
+  iodine_pubsub_init();
 }