iodine 0.1.21 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 52bb724586bb147b6db24a2a5c5ca7192ac27cc3
-  data.tar.gz: 685c1496be7ec7c13181910c9748d91814345ec0
+  metadata.gz: dc57eb293b5e744b8e465473d80aa8b4de9cc72b
+  data.tar.gz: cd6912e062d3899887e82b11013479e8e51b28ec
 SHA512:
-  metadata.gz: 72420d26e15261d76f196f4d9df9262b675747c468e3b9119adf68ec2bc3e0e5d6a4e57c48421731fb9263c42d542dfceb66c765176cfc4566730bfb8f54f3be
-  data.tar.gz: 535428c459b044ed1ab7ea3caccc4540e01acb32fdb7d57e910ba61f5b87162796052cd494b32ea7274a71b5f0d863a5f5ab7885faed60f32282c26d9b2b3743
+  metadata.gz: 4b254cf30bad1f9c58ff57308e2dab077ea0e48016ce1623374b2aeb2f37141fdbfcb04b38ad1dd946bd3b0c90202672da48aa8466d5bfd6f9ef415cc3aaba5f
+  data.tar.gz: b8e557f7ecf8a96a5a4cebe7d7cb6f9b3b3450c29fe2bfef9cc01f93662dabb9134cf87a43ca295b7ae77c7fdf7a6e53ec5c06f97e08d777feebb7bc92dbde3e

data/.gitignore

@@ -7,7 +7,8 @@
 /pkg/
 /spec/reports/
 /tmp/
+/old_stuff/
+*.bundle
+*.so
 
 .ruby-version
-
-*.bundle

data/.travis.yml

@@ -1,4 +1,25 @@
 language: ruby
+os:
+  - linux
+  # - osx
+before_install:
+  - gem install bundler -v 1.10.6
 rvm:
-  - 2.2.3
-before_install: gem install bundler -v 1.10.6
+  - 2.2.4
+  - 2.3.0
+  - 2.3.1
+  - 2.2.2
+notifications:
+  email: false
+sudo: required
+dist: trusty
+addons:
+  apt:
+    sources:
+      - ubuntu-toolchain-r-test
+    packages:
+      - gcc-4.9
+      - gcc-5
+# compiler:
+#   - clang
+#   - gcc

data/CHANGELOG.md

@@ -6,8 +6,16 @@ Please notice that this change log contains changes for upcoming releases as wel
 
 ## Changes:
 
+Change log v.0.2.0
+
+This version is a total rewrite. The API is totally changed, nothing stayed.
+
+Iodine is now written in C, as a C extension for Ruby. The little, if any, ruby code written is just the fluff and feathers.
+
 ***
 
+### deprecation of the 0.1.x version line
+
 Change log v.0.1.21
 
 **Optimization**: Minor optimizations. i.e. - creates 1 less Time object per request (The logging still creates a Time object unless disabled using `Iodine.logger = nil`).
@@ -90,7 +98,7 @@ Change log v.0.1.13
 
 Change log v.0.1.12
 
-**Update**: Passing a hash as the cookie value will allow to set cookie parameters using the {Response#set_cookie} options. i.e.: `cookies['key']= {value: "lock", max_age: 20}`. 
+**Update**: Passing a hash as the cookie value will allow to set cookie parameters using the {Response#set_cookie} options. i.e.: `cookies['key']= {value: "lock", max_age: 20}`.
 
 **Security**: set the HttpOnly flag for session id cookies.
 
@@ -223,4 +231,3 @@ I tested this new gem during the 0.0.x version releases, and I feel that version
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/README.md

@@ -1,296 +1,349 @@
-# Iodine
+# Iodine - a C kqueue/epoll EventMachine alternative (pre-release)
+[![Build Status](https://travis-ci.org/boazsegev/iodine.svg?branch=master)](https://travis-ci.org/boazsegev/iodine)
 [![Gem Version](https://badge.fury.io/rb/iodine.svg)](https://badge.fury.io/rb/iodine)
 [![Inline docs](http://inch-ci.org/github/boazsegev/iodine.svg?branch=master)](http://www.rubydoc.info/github/boazsegev/iodine/master/frames)
 [![GitHub](https://img.shields.io/badge/GitHub-Open%20Source-blue.svg)](https://github.com/boazsegev/iodine)
 
-Iodine makes writing Object Oriented evented server applications easy to write.
+Iodine 0.2.0 (pre-release) makes writing Object Oriented **Network Services** easy to write.
 
-In fact, it's so fun to write network protocols that mix and match together, that Iodine includes a built in Http, Http/2 (experimental) and Websocket server that act's a a great demonstration of the power behind Ruby and the Object Oriented approach.
+Iodine is an **evented** framework with a simple API that builds off a low level [C code library](https://github.com/boazsegev/c-server-tools) with support for **epoll** and **kqueue** - this means that:
 
-To use Iodine, you just set up your tasks - including a single server, if you want one. Iodine will start running once your application is finished and it won't stop runing until all the scheduled tasks have completed.
+* Iodine can handle **thousands of concurrent connections** (tested with 20K connections).
 
-Iodine is used by [the Plezi Ruby framework for real-time applications](http://www.plezi.io).
+    That's right, Iodine isn't subject to the 1024 connection limit imposed by native Ruby and `select`/`poll` based applications.
 
-## Notice! and limitations...
+    This makes Iodine ideal for writing HTTP/2 and Websocket servers (which is what started this whole thing).
 
-Iodine 0.1.x is implemented in Ruby, using a `select` system call.
+* Iodine supports only **Linux/Unix** based systems (i.e. OS X, Ubuntu, FreeBSD etc'). This allows us to:
 
-`select` is limited to 1024 open connections! after 1024 connection, `select` could cause "undefined behavior", including a possible "crash"... sometimes it's not important... some hosting environments only allow 1024 connections anyway... EventMachine crashes on my system after 1024 connections too...
+     * Optimize our code for the production environment.
 
-...but websockets are connection hungry beasts.
+     * Have our testing and development machines behave the same as our ultimate production environment.
 
-Hence, a move to kqueue/epoll is required.
+     * Catch any issues (read: bugs) while in development - just ask AT&T about how important this is ;-)
 
-Iodine 0.2.x will include (hopefully), a kpoll / epoll implementation for Linux/BSD server environments, such as Heroku dynos (which run a flavor of unbuto 14).
+Iodine is a C extension for Ruby, developed for Ruby MRI 2.2.2 and up... it should support the whole Ruby 2.0 family, but Rack requires Ruby 2.2.2, and so Iodine matches this requirement.
 
-However, it is unlikely that Iodine's beautiful API could survive this shift.
+## Iodine::Rack - an HTTP and Websockets server
 
-The 0.1.x API should be considered deprecated while a new API is under development (assuming I will manage to link some decent C code to Ruby)... I satrted out by displiking EventMachine's API, now it seems they might not have had a choice.
+Iodine includes a light and fast HTTP and Websocket server written in C that was written according to the [Rack interface specifications](http://www.rubydoc.info/github/rack/rack/master/file/SPEC).
 
+### Running the web server
 
-## Installation
-
-Add this line to your application's Gemfile:
+Using the Iodine server is easy, simply add Iodine as a gem to your Rack application:
 
 ```ruby
-gem 'iodine'
+# notice that the `git` is required since Iodine 2.0 hadn't been released just yet.
+gem 'iodine', :git => 'https://github.com/boazsegev/iodine.git'
 ```
 
-And then execute:
+To get the most out of Iodine, consider the amount of CPU cores available and the concurrency level the application requires.
 
-    $ bundle
+Puma's model of 16 threads and 4 processes is easily adopted and proved to provide a good enough balance for most use-cases. Use:
 
-Or install it yourself as:
+```bash
+bundler exec iodine -p $PORT -t 16 - w 4
+```
 
-    $ gem install iodine
+### Static file serving support
 
-## Simple Usage: Running tasks and shutting down
+Iodine supports static file serving that allows the server to serve static files directly, with no Ruby layer (all from C-land).
 
-This mode of operation is effective if you have a `cron`-job that periodically initiates an Iodine Ruby script. It allows the script to easily initiate a task's stack and perform the tasks concurrently.
+This means that Iodine won't lock Ruby's GVL when sending static files (nor log these requests). The files will be sent directly, allowing for true native concurrency.
 
-Iodine starts to work once you app is finished setting all the tasks up (upon exit).
+To setup native static file service, setup the public folder's address **before** starting the server.
 
-To see how that works, open your `irb` terminal an try this:
+This can be done when starting the server from the command line:
 
+```bash
+bundler exec iodine -p $PORT -t 16 - w 4 -www /my/public/folder
+```
+
+Or by adding a single line to the application. i.e. (a `config.ru` example):
 
 ```ruby
 require 'iodine'
+Iodine::Rack.public = '/my/public/folder'
+out = [404, {"Content-Length" => "10".freeze}.freeze, ["Not Found.".freeze].freeze].freeze
+app = Proc.new { out }
+run app
+```
 
-# Iodine supports shutdown hooks
-Iodine.on_shutdown { puts "Done!" }
-# The last hook is the first scheduled for execution
-Iodine.on_shutdown { puts "Finishing up :-)" }
-
-# Setup tasks using the `run` or `callback` methods
-Iodine.run do
-    # tasks can create more tasks...
-    Iodine.run { puts "Task 2 completed!" }
-    puts "Task 1 completed!"
-end
-
-# set concurrency level (defaults to a single thread).
-Iodine.threads = 5
+### Special HTTP `Upgrade` support
 
-# Iodine will start executing tasks once your script is done.
-exit
-```
+Iodine's HTTP server includes special support for the Upgrade directive using Rack's `env` Hash, allowing the application to focus on services and data while Iodine takes care of the network layer.
 
-In this mode, Iodine will continue running until all the tasks have completed and then it will quit. Timer-based tasks will be ignored.
+Upgrading an HTTP connection can be performed either using Iodine's Websocket Protocol support with `env['upgrade.websocket']` or by implementing your own protocol directly over the TCP/IP layer - be it a websocket flavor or something completely different - using `env['upgrade.tcp']`.
 
-## Simple Usage: Task polling
+#### Websockets
 
-This mode of operation is effective if you want Iodine to periodically initiate new tasks such as when you are not able to use `cron`.
+When an HTTP Upgrade request is received, Iodine will set the Rack Hash's upgrade property to `true`, so that: `env[upgrade.websocket?] == true`
 
-To initiate this mode, simply set: `Iodine.protocol = :timers` OR create a TimedEvent.
+To "upgrade" the HTTP request to the Websockets protocol, simply provide Iodine with a Websocket Callback Object instance or class: `env['upgrade.websocket'] = MyWebsocketClass` or `env['upgrade.websocket'] = MyWebsocketClass.new(args)`
 
-In example form:
+Iodine will adopt the object, providing it with network functionality (methods such as `write`, `each`, `defer` and `close` will become available) and invoke it's callbacks on network events.
 
+Here is a simple example we can run in the terminal (`irb`) or easily paste into a `config.ru` file:
 
 ```ruby
 require 'iodine'
+class WebsocketEcho
+  def on_message data
+    write data
+  end
+end
+Iodine::Rack.app= Proc.new do |env|
+  if env['upgrade.websocket?'.freeze] && env["HTTP_UPGRADE".freeze] =~ /websocket/i.freeze
+    env['iodine.websocket'.freeze] = WebsocketEcho # or: WebsocketEcho.new
+    [100,{}, []] # It's possible to set cookies for the response.
+  else
+    [200, {"Content-Length" => "12"}, ["Welcome Home"] ]
+  end
+end
+Iodine.start
+```
 
-# set concurrency level (defaults to a single thread).
-Iodine.threads = 5
+#### TCP/IP (raw) sockets
 
-# set Iodine to keep listening to TimedEvent(s).
-Iodine.protocol = :timers
+Upgrading to a custom protocol (i.e., in order to implement your own Websocket protocol with special extensions) is performed almost the ame way, using `env['upgrade.tcp']`. In the following (terminal) example, we'll use an echo server without (direct socket echo):
 
-# perform a periodical task every ten seconds
-Iodine.run_every 10 do
-   Iodine.run { sleep 5; puts " * this could have been a long task..." }
-   puts "I could be polling a database to schedule more tasks..."
+```ruby
+require 'iodine'
+class MyProtocol
+  def on_message data
+    # regular socket echo - NOT websockets - notice the upgrade code
+    write data
+  end
 end
-
-# Iodine will start running once your script is done and it will never stop unless stopped.
-exit
+Iodine::Rack.app = Proc.new do |env|
+  if env['upgrade.tcp?'.freeze] && env["HTTP_UPGRADE".freeze] =~ /echo/i.freeze
+    env['upgrade.tcp'.freeze] = MyProtocol
+    # no HTTP response will be sent when the status code is 0 (or less).
+    # to upgrade AFTER a response, set a valid response status code.
+    [1000,{}, []]
+  else
+    [200, {"Content-Length" => "12"}, ["Welcome Home"] ]
+  end
+end
+Iodine.start
 ```
 
-In this mode, Iodine will continue running until it receives a kill signal (i.e. `^C`). Once the kill signal had been received, Iodine will start shutting down, allowing up to ~20-25 seconds to complete any pending tasks (timeout).
+#### A few notes
+
+This design has a number of benefits, some of them related to better IO handling, resource optimization (no need for two IO polling systems) etc'. This also allows us to use middleware without interfering with connection upgrades and provides up with backwards compatibility.
 
-## Server Usage: an Http and Websocket server
+Iodine::Rack imposes a few restrictions for performance and security reasons, such as that the headers (both sending and receiving) must be less then 8Kb in size. These restrictions shouldn't be an issue and are similar to limitations imposed by Apache.
 
-Using Iodine and leveraging Ruby's Object Oriented approach, is super fun to write our own network protocols and servers... This is Ioding itself includes an _optional_ Http and websocket server. Say "Hello World":
+Here's a small HTTP and Websocket broadcast server with Iodine::Rack, which can be used directly from `irb`:
 
 ```ruby
-# require the 'iodine/http' module if you want to use Iodine's Http server.
-require 'iodine/http'
-# returning a string will automatically append it to the response.
-Iodine::Http.on_http { |request, response| "Hello World!" }
-```
+require 'iodine'
 
-Iodine's Http server includes comes right out of the box with Websocket support as well as an experimental support for Http/2 (it's just a start, no `push` support just yet, but you can try it out).
+# Our server controller and websockets handler
+class My_Broadcast
 
-Here's a quick chatroom server (use [www.websocket.org](http://www.websocket.org/echo.html) to check it out):
+  # handle HTTP requests (a class callback, emulating a Proc)
+  def self.call env
+    if env["HTTP_UPGRADE".freeze] =~ /websocket/i.freeze
+      env['upgrade.websocket'.freeze] = self.new(env)
+      [0,{}, []]
+    end
+    [200, {"Content-Length" => "12".freeze}, ["Hello World!".freeze]]
+  end
 
-```ruby
-# require the 'iodine/http' module if you want to use Iodine's Websocket server.
-require 'iodine/http'
-# create an object that will follow the Iodine Websocket API.
-class WSChatServer < Iodine::Http::WebsocketHandler
-  def on_open
-     @nickname = request.params[:nickname] || "unknown"
-     broadcast "#{@nickname} has joined the chat!"
-     write "Welcome #{@nickname}, you have joined the chat!"
+  def initialize env
+    @env = env # allows us to access the HTTP request data during the Websocket session
   end
+
+  # handles websocket data (an instance  callback)
   def on_message data
-     broadcast "#{@nickname} >> #{data}"
-     write ">> #{data}"
-  end
-  def on_broadcast data
-     write data
-  end
-  def on_close
-     broadcast "#{@nickname} has left the chat!"
+    # data is the direct buffer and will be recycled once we leave this scope.
+    # we'll copy it to prevent corruption when broadcasting the data asynchronously.
+    data_copy = data.dup
+    # We'll broadcast the data asynchronously to all open websocket connections.
+    each {|ws| ws.write data_copy } # (limited to current process)
+    close if data =~ /^bye[\r\n]/i
   end
 end
 
-Iodine::Http.on_websocket WSChatServer
+# static file serving is as easy as (also supports simple byte serving):
+Iodine::Rack.public = "www/public"
+
+# start the server while setting the app at the same time
+Iodine::Rack.run My_Broadcast
 ```
 
-### Security and limits
+Of course, if you still want to use Rack's `hijack` API, Iodine will support you - but be aware that you will need to implement your own reactor and thread pool for any sockets you hijack, as well as a socket buffer for non-blocking `write` operations (why do that when you can write a protocol object and have the main reactor manage the socket?).
+
+### How does it compare to other servers?
+
+Since the HTTP and Websocket parsers are written in C (with no RegExp), they're fairly fast.
 
-Nobody wants their server to crash... Security measures are a fact of life as an internet entity. It is not only the theoretical malicious attacker from which a server must protect itself, but also from the unaware user or client.
+Also, Iodine's core and parsers are running outside of Ruby's global lock, meaning that they enjoy true concurrency before entering the Ruby layer (your application) - this offers Iodine a big advantage over other servers.
 
-Mostly, it is assumed that Iodine will run behind a proxy (i.e. within a Heroku Dyno or viaduct.io process), as such it is assumed that the proxy will protect the Iodine Http server from undue stress.
+Another assumption Iodine makes is that it is behind a load balancer / proxy (which is the normal way Ruby applications are deployed) - this allows Iodine to disregard header validity checks (we're not checking for invalid characters) which speeds up the parsing process even more.
 
-Having said that, Iodine is built with certain security measures in mind:
+I'm not posting any data because Iodine is still under development and things are somewhat dynamic - but you can compare the performance for yourself using `wrk` or `ab`:
 
-- Iodine will not accept IO data (neither from new connections nor form existing ones) while still answering existing requests and performing tasks. This safeguards against task overloading and DoS attacks causing a global crash, allowing the server to resume normal operation once a DoS attack had run it's course (and potentially allowing legitimate requests to be answered while the attack is still underway).
+```bash
+$ wrk -c200 -d4 -t12 http://localhost:3000/
+# or
+$ ab -n 100000 -c 200 -k http://127.0.0.1:3000/
+```
 
-- Iodine will limit the query length, header count and header data size as well as well as react to header overloading by immediate disconnections. Iodine's limits are hardcoded to be slightly more than double those of common Proxies, so this counter-measure will only take effect should an attacker manage to bypass the Proxy.
+Create a simple `config.ru` file with a hello world app:
 
-- Iodine limits every Http request body-size (file upload data, form data, etc') to ~0.5GB. This setting can be changed using `Iodine::Http.max_body_size`. This safeguard is meant to prevent Ruby from crashing due to insufficient memory (an error Iodine cannot, and should not, recover from).
+```ruby
+App = Proc.new do |env|
+   [200,
+     {   "Content-Type" => "text/html".freeze,
+         "Content-Length" => "16".freeze },
+     ['Hello from Rack!'.freeze]  ]
+end
 
-   It is recommended that this number will be lowered substantially whenever possible, by using `Iodine::Http.max_body_size = new_value`
+run App
+```
 
-   Do be aware that, at the moment, file upload data must passed through the memory on it's way to the temporary file. The parser's memory consumption will hopefully decrese in future releases, however, it is always recomended that large data be avoided when possible or handled using download/upload management protocols and services.
+Then start comparing servers:
 
-## Server Usage: Plug in your network protocol
+```bash
+$ rackup -p 3000 -E production -s iodine
+```
 
-Iodine is designed to help write network services (Servers) where each script is intended to implement a single server.
+vs.
 
-This is not a philosophy based on any idea or preferences, but rather a response to real-world design where each Ruby script is usually assigned a single port for network access (hence, a single server).
+```bash
+$ rackup -p 3000 -E production -s <Other_Server_Here>
+```
 
-To help you write your network service, Iodine starts you off with the `Iodine::Protocol`. All network protocols should inherit from this class (or implement it's essencial functionality).
+Puma has ~16 threads by default, so when comparing against Puma, consider using an equal number of threads:
 
-Here's a quick Echo server:
+```bash
+# (t - threads, w - worker processes)
+$ RACK_ENV=production iodine -p 3000 -t 16 -w 4
+```
 
-```ruby
-require 'iodine'
+vs.
 
-# inherit from ::Iodine::Protocol
-class EchoServer < Iodine::Protocol
-    # The protocol class will call this withing a Mutex,
-    # making sure the IO isn't accessed while being initialized.
-	def on_open
-		Iodine.info "Opened connection."
-		set_timeout 5
-	end
-    # The protocol class will call this withing a Mutex, after reading the data from the IO.
-    # This makes this thread-safe per connection.
-	def on_message data
-		write("-- Closing connection, goodbye.\n") && close if data =~ /^(bye|close|exit|stop)/i
-		write(">> #{data.chomp}\n")
-	end
-	# Iodine makes sure this is called only once.
-	def on_close
-		Iodine.info "Closed connection."
-	end
-	# The is called whenever timeout is reached.
-	# By default, ping will close the connection.
-	# but we can do better...
-	def ping
-	    # `write` will automatically close the connection if it fails.
-		write "-- Are you still there?\n"
-	end
-end
+```bash
+# (t - threads, w - worker processes)
+$ RACK_ENV=production puma -p 3000 -w 4 -q
+```
+
+Review the `iodine -?` help for more data.
+
+Remember to compare the memory footprint after running some requests - it's not just speed that C is helping with, it's also memory management and object pooling (i.e., Iodine uses a buffer packet pool management).
 
+## Can I try before before I buy?
 
-Iodine.protocol = EchoServer
+Well, it is **free** and **open source**, no need to buy.. and of course you can try it out.
 
-# if running this code within irb:
-exit
+It's installable just like any other gem on MRI, run:
+
+```
+$ gem install iodine
 ```
 
-In this mode, Iodine will continue running until it receives a kill signal (i.e. `^C`). Once the kill signal had been received, Iodine will start shutting down, allowing up to ~20-25 seconds to complete any pending tasks (timeout).
+If building the native C extension fails, please notice that some Ruby installations, such as on Ubuntu, require that you separately install the development headers (`ruby.h` and friends). I have no idea why they do that, as you will need the development headers for any native gems you want to install - so hurry up and get it.
 
-## Server Usage: IP address & port, SSL/TLS and other command line options
+If you have the development headers but still can't compile the Iodine extension, [open an issue](https://github.com/boazsegev/iodine/issues) with any messages you're getting and I be happy to look into it.
 
-Iodine automatically respects certain command line options that make it easier to use the same script over and over again with different results and making writing a `Procfile` (or similar setup files) a breeze.
+## Mr. Sandman, write me a server
 
-Let `./script.rb` be an Iodine ruby script, may an easy one such as our Hello World:
+Girls love flowers, or so my ex used to keep telling me... but I think code is the way to really show that something is hot!
+
+I mean, look at this short and sweet echo server - No HTTP, just use `telnet`... but it's so elegant I could cry:
 
 ```ruby
-#!/usr/bin/env ruby
 
-# script.rb
-require 'iodine/http'
+require 'iodine'
 
-Iodine::Http.on_http do |request, response|
-  response << "Hello World!"
+# an echo protocol with asynchronous notifications.
+class EchoProtocol
+  # `on_message` is an optional alternative to the `on_data` callback.
+  # `on_message` has a 1Kb buffer that recycles itself for memory optimization.
+  def on_message buffer
+    # writing will never block and will use a buffer written in C when needed.
+    write buffer
+    # close will be performed only once all the data in the write buffer
+    # was sent. use `force_close` to close early.
+    close if buffer =~ /^bye[\r\n]/i
+    # use buffer.dup to save the data from being recycled once we return.
+    data = buffer.dup
+    # run asynchronous tasks with ease
+    run do
+      sleep 1
+      puts "Echoed data: #{data}"
+    end
+  end
 end
 
+# listen on port 3000 for the echo protocol.
+Iodine.listen 3000, EchoProtocol
+Iodine.threads = 1
+Iodine.processes = 1
+Iodine.start
+
 ```
 
-Here are different command line options that Iodine recognizes automatically when running our script:
+## I loved Iodine 0.1.x - is this an upgrade?
 
-| purpose                                         | flag   | example                                  |
---------------------------------------------------|:------:|------------------------------------------|
-|  Set the server's port.                         | `-p`   | `ruby ./script.rb -p 4000`               |
-|  Limit the server's binding to a specific IP.   | `-ip`  | `ruby ./script.rb -p 4000 -ip 127.0.0.1` |
-|  Use SSL/TLS on a specific port.                | `ssl`  | `ruby ./script.rb -p 3030 ssl`           |
-|  Try out the experimental Http2 extention.      | `http2`|  `ruby ./script.rb -p 3030 ssl http2`    |
+This is **not** an upgrade, this is a **full rewrite**.
 
-## Server Usage: Running more than one server
+Iodine 0.1.x was written in Ruby and had tons of bells and whistles and a somewhat different API. It also inherited the `IO.select` limit of 1024 concurrent connections.
 
-On some machines, Iodine will allow you to run more than a single server, by forking the main process while still running the script. This is more of a hack to be used in development environments, since runnig multiple instances of the script is the prefered way to use Iodine in production.
+Iodine 0.2.x is written in C, doesn't have as many bells and whistles (i.e., no Websocket Client) and has a stripped down API (simpler to learn). The connection limit is calculated on startup, according to the system's limits. Connection overflows are terminated with an optional busy message, so the system won't crash.
 
-i.e.:
+## Why not EventMachine?
 
-```ruby
-require 'iodine/http'
+You can go ahead and use EventMachine if you like. They're doing amazing work on that one and it's been used a lot in Ruby-land... really, tons of good developers and people on that project, I'm sure...
 
-# We'll use a simple hello world with a slight "tweek" for this example.
-Iodine::Http.on_http do |request, response|
-  response << "Hello World!"
-  response << " We're on SSL/TLS!" if request.ssl?
-end
+But me, I prefer to make sure my development software runs the exact same code as my production software. So here we are.
 
-Iodine.ssl = false
+Also, I don't really understand all the minute details of EventMachine's API, it kept crashing my system every time I reached ~1024 active connections... I'm sure I just don't know how to use EventMachine, but that's just that.
 
-Process.fork do
-   Iodine.ssl = true
-   Iodine.port = 3030
-   # # we can also change network behavior, so we could have used:
-   # Iodine::Http.on_http { "Hello World! We're on SSL/TLS! - no `if` required ;-)" } 
-end if Process.respond_to? :fork
+Besides, you're here - why not take Iodine out for a spin and see for yourself?
 
-# if using irb
-exit
-```
+## Can I contribute?
 
-## Cuncurrency?
+Yes, please, here are some thoughts:
 
-Iodine maintains the idea of: "yes" to concurrency between objects but "no" to concurrency within objects.
+* I'm really not good at writing automated tests and benchmarks, any help would be appreciated. I keep testing manually and that's less then ideal (and it's mistake prone).
 
-Iodine applies this concept when running in Task mode (or timer mode), by defaulting to single threaded mode, preventing multi-threading race conditions in an unknown environment. Also, each task runs in a single thread from the thread-pool, so unless it tries to set or manipulate global data, it's safe from race conditions.
+* If we can write a Java wrapper for [the C libraries](https://github.com/boazsegev/c-server-tools), it would be nice... but it could be as big a project as the whole gem, as a lot of minor details are implemented within the bridge between these two languages.
 
-Iodine applies this concept when running in Server mode by locking the Protocol instance whenever Iodine calls for actions related to that Protocol.
+* Bug reports and pull requests are welcome on GitHub at https://github.com/boazsegev/iodine.
 
-For instance, in Iodine's implementation for the Websocket protocol: Websocket messages to different connections can run concurrently, however multiple messages to the same connection are only executed one at a time, maintaining their order (lately a fix in version 0.1.8 made sure that also websocket broadcasting will be executed within the Protocol lock, preventing concurrency within the same connection).
+* If you love the project or thought the code was nice, maybe helped you in your own project, drop me a line. I'd love to know.
 
-The exception to the rule is the `ping` implementation. Your protocol's `ping` method will execute in parallel with other parts of your protocol's code. Pinging is a machanism that is often time sensitive and is required to maintain an open connection. For this reason, if your code is working hard on a long task, a ping will still occure automatically in the background and offset any connection timeout. 
+## License
 
-If your code is short and efficient (no blocking tasks), it is best to run Iodine in a single threaded mode (you get better performance AND safer code, as long as you don't block):
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
-      Iodine.threads = 1
+---
 
-## Contributing
+## "I'm also writing a Ruby extension in C"
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/boazsegev/iodine.
+Really?! That's great!
 
+We could all use some more documentation around the subject and having an eco-system for extension tidbits would be nice.
 
-## License
+Here's a few things you can use from this project and they seem to be handy to have (and easy to port):
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+* Iodine is using a [Registry](https://github.com/boazsegev/iodine/blob/0.2.0/ext/core/rb-registry.h) to keep dynamic Ruby objects that are owned by C-land from being collected by the garbage collector in Ruby-land...
+
+    Some people use global Ruby arrays, adding and removing Ruby objects to the array, but that sounds like a performance hog to me.
+
+    This one is a simple binary tree with a Ruby GC callback. Remember to initialize the Registry (`Registry.init(owner)`) so it's "owned" by some Roby-land object, this allows it to bridge the two worlds for the GC's mark and sweep.
+
+    I'm attaching it to one of Iodine's library classes, just in-case someone adopts my code and decides the registry should be owned by the global Object class.
+
+* I was using a POSIX thread pool library ([`libasync.h`](https://github.com/boazsegev/c-server-tools/blob/master/lib/libasync.c)) until I realized how many issues Ruby has with non-Ruby threads... So now there's a Ruby-thread port for this library at ([`rb-libasync.h`](https://github.com/boazsegev/iodine/blob/master/ext/iodine/rb-libasync.h)).
+
+    Notice that all the new threads are free from the GVL - this allows true concurrency... but, you can't make Ruby API calls in that state.
+
+    To perform Ruby API calls you need to re-enter the global lock (GVL), albeit temporarily, using `rb_thread_call_with_gvl` and `rv_protect` (gotta watch out from Ruby `longjmp` exceptions).
+
+* Since I needed to call Ruby methods while multi-threading and running outside the GVL, I wrote [`RubyCaller`](https://github.com/boazsegev/iodine/blob/0.2.0/ext/core/rb-call.h) which let's me call an object's method and wraps all the `rb_thread_call_with_gvl` and `rb_protect` details in a secret hidden place I never have to see again. It also keeps track of the thread's state, so if we're already within the GVL, we won't enter it "twice" (which will crash Ruby sporadically).
 
+These are nice code snippets that can be easily used in other extensions. They're easy enough to write, I guess, but I already did the legwork, so enjoy.