ever 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ba6404ba736a8c3c519cba46a8bf8a9df85ecc4a9532790c15821bff12f348e
+  data.tar.gz: 162398e3f59e7a638cf7de58b47e0a05c746f4be49e46f62bbd23b60305a1f77
+SHA512:
+  metadata.gz: a3e8236c119bdb97b0c5aa0b26f60cbc40f740201218de11494b2368e0c60e7ab3dc4b0235751b903483dc441fcc55f07bc9da61e6c06e5a26135656e909cfc8
+  data.tar.gz: aeef774232228911357f7c472a937695f319615d31f0bf11d93554177c3b184a32003b4489a5193ca803d90dbb67cfda5a64417e6c6045be11f73bc98d341b21

data/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        ruby: [2.6, 2.7, 3.0]
+
+    name: >-
+      ${{matrix.os}}, ${{matrix.ruby}}
+
+    runs-on: ${{matrix.os}}
+    steps:
+    - uses: actions/checkout@v1
+    - uses: actions/setup-ruby@v1
+      with:
+        ruby-version: ${{matrix.ruby}}
+    - name: Install dependencies
+      run: |
+        gem install bundler
+        bundle install
+    - name: Compile C-extension
+      run: bundle exec rake compile
+    - name: Run tests
+      run:  bundle exec rake test

data/.gitignore

@@ -0,0 +1,57 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+*.so

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1 2021-08-30
+
+- First working version

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,25 @@
+PATH
+  remote: .
+  specs:
+    ever (0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    http_parser.rb (0.7.0)
+    minitest (5.14.4)
+    rake (13.0.6)
+    rake-compiler (1.1.1)
+      rake
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  ever!
+  http_parser.rb (= 0.7.0)
+  minitest (= 5.14.4)
+  rake-compiler (= 1.1.1)
+
+BUNDLED WITH
+   2.2.26

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Digital Fabric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,167 @@
+# Ever - a callback-less event reactor for Ruby
+
+[![Gem Version](https://badge.fury.io/rb/ever.svg)](http://rubygems.org/gems/ever)
+[![Ever Test](https://github.com/digital-fabric/ever/workflows/Tests/badge.svg)](https://github.com/digital-fabric/ever/actions?query=workflow%3ATests)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/digital-fabric/ever/blob/master/LICENSE)
+
+Ever is a [libev](http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod)-based event reactor for Ruby with a callback-less design. Events are emitted to an application-provided block inside a tight loop without registering and invoking callbacks.
+
+## Features
+
+- Simple, minimalistic API
+- Zero dependencies
+- Callback-less API for getting events
+- Events for I/O readiness
+- Events for one-shot or recurring timers
+- Cross-thread signalling and emitting of events
+
+## Rationale
+
+I'm planning to add a compatibility mode to [Tipi](https://github.com/digital-fabric/tipi), a new [Polyphony](https://github.com/digital-fabric/polyphony)-based web server for Ruby. In this mode, Tipi will not be using Polyphony, but will employ multiple worker threads for handling concurrent requests. The problem is that we have X number of threads that need to be able to deal with Y number of concurrent connections.
+
+After coming up with a bunch of different ideas for how to achieve this, I settled on the following design:
+
+- The main thread runs a libev-based event reactor, and deals with accepting connections and distributing events.
+- One or more worker threads wait for jobs to execute.
+- When a new connection is accepted, the main thread starts watching for I/O readiness.
+- When a connection is ready for reading, the main thread puts the connection on the job queue.
+- A worker thread pulls the connection from the job queue and tries to read an incoming request. If the request is not complete, the connection is watched again for read readiness.
+- When the request is complete, the worker threads continues to run the Rack app, gets the response, and tries to write the response. If the response cannot be written, the connection is watched for write readiness.
+- When the response has been written, the connection is watched again for read readiness in preparation for the next request.
+
+(A working sketch for this design is included [here as an example](https://github.com/digital-fabric/ever/blob/main/examples/http_server.rb).)
+
+What's interesting about this design is that any number of worker threads can (theoretically) handle any number of concurrent requests, since each worker thread is not tied to a specific connection, but rather work on each connection in the queue as it becomes ready (for reading or writing).
+
+## Installing
+
+If you're using bundler just add it to your `Gemfile`:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'ever'
+```
+
+You can then run `bundle install` to install it. Otherwise, just run `gem install ever`.
+
+## Usage
+
+Start by creating an instance of Ever::Loop:
+
+```ruby
+require 'ever'
+
+evloop = Ever::Loop.new
+```
+
+### Setting up event watchers
+
+All events are identified using an application-provided key. This means that your app should provide a unique key for each event you wish to watch. To watch for I/O readiness, use `Loop#watch_io(key, io, read_write, oneshot)` where:
+
+- `key`: unique event key (this can be *any* value, and in many cases you can just use the `IO` instance.)
+- `io`: `IO` instance to watch.
+- `read_write`: `false` for read, `true` for write.
+- `oneshot`: `true` for one-shot event monitoring, `false` otherwise.
+
+Example:
+
+```ruby
+result = socket.read_nonblock(16384, exception: false)
+case result
+when :wait_readable
+  evloop.watch_io(socket, socket, false, true)
+else
+  ...
+end
+```
+
+To setup up timers, use `Loop#watch_timer(key, duration, interval)` where:
+
+- `key`: unique event key
+- `duration`: timer duration in seconds.
+- `interval`: recurring interval in seconds. `0` for a one-shot timer.
+
+```ruby
+evloop.watch_timer(:timer, 1, 1)
+evloop.each do |key|
+  case key
+  when :timer
+    puts "Got timer event"
+  end
+end
+```
+
+### Stopping watchers
+
+To stop a specific watcher, use `Loop#unwatch(key)` and provide the key previously provided to `#watch_io` or `#watch_timer`:
+
+```ruby
+evloop.watch_timer(:timer, 1, 1)
+count = 0
+evloop.each do |key|
+  case key
+  when :timer
+    puts "Got timer event"
+    count += 1
+    evloop.unwatch(:timer) if count == 10
+  end
+end
+```
+
+### Processing events
+
+To process events as they happen, use `Loop#each`, which will block waiting for events and will yield events as they happen. The application-provided block will be called with the event key for each event:
+
+```ruby
+evloop.each do |key|
+  distribute_event(key)
+end
+```
+
+Alternatively you can use `Loop#next_event` to process events one by one, or using a custom loop. Note that while this method can block, it can also return `nil` in case no event was generated.
+
+### Emitting custom events
+
+You can emit events using `Loop#emit(key)`. In case the event loop is currently polling for events, it immediately return and the emitted event will be available.
+
+### Signalling the event loop
+
+You can signal the event loop in order to stop it from blocking by using `Loop#signal`.
+
+### Stopping the event loop
+
+An event loop that is currently blocking on `Loop#each` can be stopped using `Loop#stop` or by calling `Loop#emit(:stop)`.
+
+### Signal handling
+
+The created event loop will not trap signals by itself. You can setup signal traps and emit events that tell the app what to do. Here's an example:
+
+```ruby
+evloop = Ever::Loop.new
+trap('SIGINT') { evloop.stop }
+evloop.each { |key| handle_event(key) }
+```
+
+## API Summary
+
+|Method|Description|
+|------|-----------|
+|`Loop.new()`|create a new event loop.|
+|`Loop#each(&block)`|Handle events in an infinite loop.|
+|`Loop#next_event()`|Wait for an event and return its key.|
+|`Loop#watch_io(key, io, read_write, oneshot)`|Watch an IO instance for readiness.|
+|`Loop#watch_timer(key, duration, interval)`|Setup a one-shot/recurring timer.|
+|`Loop#unwatch(key)`|Stop watching specific event key.|
+|`Loop#emit(key)`|Emit a custom event.|
+|`Loop#signal()`|Signal the event loop, causing it to break if currently blocking.|
+|`Loop#stop()`|Stop an event loop currently blocking in `#each`.|
+
+## Performance
+
+I did not yet explore all the performance implications of this new design, but [a sketch I made for an HTTP server](https://github.com/digital-fabric/ever/blob/main/examples/http_server.rb) shows it performing consistently at >60000 reqs/seconds on my development machine.
+
+## Contributing
+
+Issues and pull requests will be gladly accepted. If you have found this gem
+useful, please let me know.

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/clean'
+
+require 'rake/extensiontask'
+Rake::ExtensionTask.new('ever_ext') do |ext|
+  ext.ext_dir = 'ext/ever'
+end
+
+task :recompile => [:clean, :compile]
+task :default => [:compile, :test]
+
+task :test do
+  exec 'ruby test/test_loop.rb'
+end
+
+CLEAN.include '**/*.o', '**/*.so', '**/*.so.*', '**/*.a', '**/*.bundle', '**/*.jar', 'pkg', 'tmp'

data/ever.gemspec

@@ -0,0 +1,26 @@
+require_relative './lib/ever/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'ever'
+  s.version     = Ever::VERSION
+  s.licenses    = ['MIT']
+  s.summary     = 'Callback-less event reactor for Ruby'
+  s.author      = 'Sharon Rosner'
+  s.email       = 'sharon@noteflakes.com'
+  s.files       = `git ls-files`.split
+  s.homepage    = 'https://digital-fabric.github.io/ever'
+  s.metadata    = {
+    "source_code_uri" => "https://github.com/digital-fabric/ever",
+    "homepage_uri" => "https://github.com/digital-fabric/ever",
+    "changelog_uri" => "https://github.com/digital-fabric/ever/blob/master/CHANGELOG.md"
+  }
+  s.rdoc_options = ["--title", "ever", "--main", "README.md"]
+  s.extra_rdoc_files = ["README.md"]
+  s.extensions = ["ext/ever/extconf.rb"]
+  s.require_paths = ["lib"]
+  s.required_ruby_version = '>= 2.6'
+
+  s.add_development_dependency  'rake-compiler',        '1.1.1'
+  s.add_development_dependency  'minitest',             '5.14.4'
+  s.add_development_dependency  'http_parser.rb',       '0.7.0'
+end

data/examples/http_server.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'ever'
+require 'http/parser'
+require 'socket'
+
+class Connection
+  attr_reader :io, :parser, :request_complete,
+              :request_headers, :request_body
+  attr_accessor :response
+
+  def initialize(io)
+    @io = io
+    @parser = Http::Parser.new(self)
+    setup_read_request
+  end
+
+  def setup_read_request
+    @request_complete = nil
+    @request_headers = nil
+    @request_body = +''
+  end
+
+  def on_headers_complete(headers)
+    @request_headers = headers
+  end
+
+  def on_body(chunk)
+    @request_body << chunk
+  end
+
+  def on_message_complete
+    @request_complete = true
+  end
+end
+
+$job_queue = Queue.new
+$evloop = Ever::Loop.new
+
+worker = Thread.new do
+  while (job = $job_queue.shift)
+    handle_connection(job)
+  end
+end
+
+def handle_connection(conn)
+  if !conn.request_complete
+    handle_read_request(conn)
+  else
+    handle_write_response(conn)
+  end
+end
+
+def handle_read_request(conn)
+  result = conn.io.read_nonblock(16384, exception: false)
+  case result
+  when :wait_readable
+    $evloop.emit([:watch_io, conn, false, true])
+  when :wait_writable
+    $evloop.emit([:watch_io, conn, true, true])
+  when nil
+    $evloop.emit([:close, conn])
+  else
+    conn.parser << result
+    if conn.request_complete
+      conn.response = handle_request(conn.request_headers, conn.request_body)
+      handle_write_response(conn)
+    else
+      $evloop.emit([:watch_io, conn, false, true])
+    end
+  end
+rescue HTTP::Parser::Error, SystemCallError, IOError
+  $evloop.emit([:close, conn])
+end
+
+def handle_request(headers, body)
+  response_body = "Hello, world!"
+  "HTTP/1.1 200 OK\nContent-Length: #{response_body.bytesize}\n\n#{response_body}"
+end
+
+def handle_write_response(conn)
+  result = conn.io.write_nonblock(conn.response, exception: false)
+  case result
+  when :wait_readable
+    $evloop.emit([:watch_io, conn, false, true])
+  when :wait_writable
+    $evloop.emit([:watch_io, conn, true, true])
+  when nil
+    $evloop.emit([:close, conn])
+  else
+    conn.setup_read_request
+    $evloop.emit([:watch_io, conn, false, true])
+  end
+end
+
+def setup_connection(io)
+  conn = Connection.new(io)
+  $evloop.emit([:watch_io, conn, false, true])
+end
+
+server = TCPServer.new('0.0.0.0', 1234)
+puts "Listening on port 1234..."
+trap('SIGINT') { $evloop.stop }
+$evloop.watch_io(:accept, server, false, false)
+
+$evloop.each do |event|
+  case event
+  when :accept
+    socket = server.accept
+    setup_connection(socket)
+  when Connection
+    $job_queue << event
+  when Array
+    cmd = event[0]
+    case cmd
+    when :watch_io
+      $evloop.watch_io(event[1], event[1].io, event[2], event[3])
+    when :close
+      conn = event[1]
+      conn.io.close
+    end
+  end
+end