revactor 0.1.0

data/CHANGES

@@ -0,0 +1,3 @@
+0.1.0:
+
+* Initial release

data/LICENSE

@@ -0,0 +1,58 @@
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README

@@ -0,0 +1,338 @@
+= Revactor
+
+Revactor is an Actor model implementation for Ruby 1.9 built on top of the
+Rev high performance event library.  Revactor is primarily designed for 
+writing Erlang-like network services and tools.
+
+You can load Revactor into your Ruby 1.9 application with:
+
+  require 'revactor'
+
+If you'd like to learn more about the Actor model, more information is
+available on the Revactor web site:
+
+http://revactor.org/philosophy
+
+More information about Rev is available on Rubyforge:
+
+http://rev.rubyforge.org/rdoc
+
+== Anatomy
+
+Revactor is built out of several parts which interoperate to let you build
+network servers painlessly while still guaranteeing correct operation:
+
+* Actors - Actors are the main concurrency primitive used by Revactor.
+
+* Revactor::TCP - This module provides an API duck typed to the Ruby
+  Sockets API.  However, rather than blocking calls actually blocking,
+  they defer to the underlying event loop.  Actor-focused means of
+  receiving data are also provided.
+
+* Filters - Applied to all incoming data directly when it's received, Filters
+  can preprocess or postprocess data before it's even delivered to an Actor.
+  This is useful for handling protocol framing or other streaming transforms.
+
+* Behaviors - These are patterns for implementing Actors which accomplish
+  specific tasks.  Right now only the Server behavior is supported.
+
+== Actors
+
+Actors add mailboxes to Ruby's Fiber mechanism.  They multitask cooperatively,
+meaning that many of the worries surrounding threaded programming disappear.
+Any sequence of operations you do in an Actor are executed in the order
+you specify.  You don't (generally) have to worry about another Actor doing 
+something in the background as you frob a particular data structure.
+
+Unfortunately, in Ruby 1.9, Actors are not first-class citizens.  This means
+you will need to jump from the non-Actor world to the Actor world before you
+can do anything with Actors.  This is accomplished by running Actor.start:
+
+  # Not in Actor world
+  Actor.start do
+    # In Actor world, yay
+    ...
+  end
+  # Won't get called until all Actors have processes their entire mailbox
+  # and aren't waiting for any events.
+
+Ideally, what you place in Actor.start is a small startup routine which
+spawns all the Actors your application needs to get started and nothing else.
+
+Once you're in Actor world, you can begin making Actors and sending them
+events.  You create Actors with Actor.spawn:
+
+  myactor = Actor.spawn { puts "I'm an Actor!" }
+
+When you spawn an Actor it's scheduled to run after the current Actor either
+completes or calls Actor.receive.  Speaking of which, Actor.receive is used
+to receive messages:
+
+  myactor = Actor.spawn do
+    Actor.receive do |filter|
+      filter.when(:dog) { puts "I got a dog!" }
+    end
+  end
+
+You can send a message to an actor using its #send method or <<
+
+Calling: 
+
+  myactor << :dog
+
+prints:
+
+  "Yay, I got a dog!"
+
+== Mailboxes
+
+So, Actors can receive messages.  But where do those messages go?  The answer
+is every Actor has a mailbox.  The mailbox is sort of like a message queue,
+but you don't have to read it sequentially.  You can apply filters to it, and
+change the filterset at any time.
+
+When you call Actor.receive, it yields a filter object and lets you register
+message patterns you're interested in, then it sleeps and waits for messages.
+Each time the current actor receives a message, it's scanned by the filter,
+and if a match occurs the appropriate action is given.
+
+Matching is performed by the Filter#when method, which takes a pattern to match
+against a message and a block to call if the message matches.  The pattern is
+compared to the message using ===, the same thing Ruby uses for case statements.
+You can think of the filter as a big case statement.
+
+Understanding the === statement is a bit strange, so here's a short guide:
+
+You can pass #when a class to match against the message.  Obviously passing it
+Object will match all messages.
+
+You can pass #when a regexp to match against the message.
+
+Revactor installs the Case gem by default.  This is useful for matching against
+messages stored in Arrays, or in fixed-size arrays called Tuples.  Case can
+be used as follows:
+
+  filter.when(Case[:foobar, Object, Object]) { ... }
+
+This will look for messages which are Arrays or Tuples with three members,
+whose first member is the symbol :foobar.  As you can probably guess, Case[]
+matches against an Array or Tuple with the same number of members, and
+matches each member of the given tuple with ===.  Once again, Object is a 
+wildcard, so the other members of the message can be anything.
+
+Want more complex pattern matching?  Case lets you use a block to match any
+member by using a guard, ala:
+
+  filter.when(Case[:foobar, Case.guard { |n| n > 100 }, Object]) { ... }
+
+This will look for an Array / Tuple with three members, whose first member is
+the symbol :foobar and whose second member is greater than 100.
+
+You can also specify how long you wish to wait for a message before timing out.
+This is accomplished with Filter#after:
+
+  filter.after(0.5) { raise 'it timed out ;_;' }
+
+The #after method takes a duration in seconds to wait (in the above example it
+waits a half second) before the receive operation times out.
+
+Actor.receive returns whatever value the evaluated action returned.  This means
+you don't have to depend on side effects to extract values from receive, 
+instead you can just interpret its return value.
+
+== Revactor::TCP
+
+The TCP module lets you perform TCP operations on top of the Actor model.  For
+those of you familiar with Erlang, it implements something akin to gen_tcp.
+Everyone else, read on!
+
+Perhaps the best part of Revactor::TCP is you don't really need to know 
+anything about the Actor model to use it.  For the most part it's duck typed
+to the Ruby Socket API and can operate as a drop-in replacement.
+
+To make an outgoing connection, call:
+
+  sock = Revactor::TCP.connect(host, port)
+
+This will resolve the hostname for host (if it's not an IPv4 or IPv6 address),
+make the connection, and return a socket to it.  The best part is: this call
+will "block" until the connection is established, and raise exceptions if the
+connection fails.  It works just like the Sockets API.
+
+However, it's not actually blocking.  Underneath this call is using the
+Actor.receive method to wait for events.  This means other Actors can run in
+the background while the current one is waiting for a connection.
+
+Furthermore, the Actor making this call can receive other events and they
+will remain undisturbed in the mailbox.  The connect method filters for
+messages specifically related to making an outgoing connection.
+
+To listen for incoming connections, there's a complimentary method:
+
+  listener = Revactor::TCP.listen(addr, port)
+
+This will listen for incoming connections on the given address and port.  It
+returns a listen socket with a #accept method:
+
+  sock = listener.accept
+
+Like TCP.connect, this method will block waiting for connections, but in
+actuality is calling Actor.receive waiting for messages related to incoming
+connections.
+
+Now that you have a handle on a Revactor TCP socket, there's several ways you
+can begin using it.  The first is using a standard imperative sockets API:
+
+  data = sock.read(1024)
+
+This call will "block" until it reads a kilobyte from the socket.  However,
+you may not be interested in a specific amount of data, just whenever data
+is available on the socket.  In that case, you can just call the #read method
+without any argument:
+
+  data = sock.read
+
+There's also a corresponding command to write to the socket.  Like read this
+command will also "block" until all data has been written out to the socket:
+
+  sock.write data
+
+For Actors that want to deal with both incoming TCP data and messages from
+other Actors, Revactor's TCP sockets also support an approach called
+active mode.  Active mode automatically delivers incoming data as a message
+to what's known as the Socket's controller.  You can assign the Socket's
+controller whenever you want:
+
+  sock.controller = Actor.current
+
+Once you've done this, you can turn on active mode to begin receiving messages:
+
+  sock.active = true
+  Actor.receive do |filter|
+    filter.when(Case[:tcp, sock, Object]) do |_, _, data|
+      ...
+    end
+
+    filter.when(Case[:somethingelse, Object]) do |_, message|
+      ...
+    end
+  end
+
+(note: _ is an idiom which means ignore/discard a variable)
+
+With active mode, the controller will receive all data as quickly as it can be
+read off the socket.  If the Actor processing incoming message can't process
+them as quickly as they're being read, then they'll begin piling up in the
+mailbox until the controller is able to catch up (if ever).
+
+In order to prevent this from happening, sockets can be set active once:
+
+  sock.active = :once
+
+This means read the next incoming message, then fall back to active = false.
+The underlying system will stop monitoring the socket for incoming data,
+and you're free to spend as much time as you'd like handling it.  Once
+you're ready for the next message, just set active to :once again.
+
+== Filters
+
+Not to be confused with Mailbox filters, Revactor's TCP sockets can each have
+a filter chain.  Filters are specified when a connection is created:
+
+  sock = Revactor::TCP.connect('irc.efnet.org', 6667, :filter => :line)
+
+Filters transform data as it's read or written off the wire.  In this case
+we're connecting to an IRC server, and the IRC protocol is framed using a
+newline delimiter.
+
+The line filter will scan incoming messages for a newline, and buffer until
+it encounters one.  When it finds one, it will reassemble the entire message
+from the buffer and deliver it to you in one fell swoop.
+
+With the line filter on, receiving messages off IRC is easy:
+
+  message = sock.read
+
+This will provide you with the entire next message, with the newline delimiter
+already removed.
+
+If the filter name is a symbol, Revactor will look under its filters directory
+for a class of the cooresponding name.  Alternatively you can pass the name of
+a class you created yourself which responds to the methods encode and decode:
+
+  sock = Revactor::TCP.connect(host, port, :filter => MyFilter)
+
+Filter chains can be specified by passing an array:
+
+  sock = Revactor::TCP.connect(host, port, :filter => [MyFilter, :line])
+
+You can pass arguments to your filter's initialize method by passing an array
+with a class name as a member of a filter chain:
+
+  sock = Revactor::TCP.connect(host, port, :filter => [[Myfilter, 42], :line])
+
+In addition to the line filter, Revactor bundles a :packet filter.  This filter
+constructs messages with a length prefix that specifies the size of the
+remaining message.  This is a simple and straightforward way to frame
+discrete messages on top of a streaming protocol like TCP, and is used for,
+among other things, DRb.
+
+== Behaviors
+
+Behaviors are kind of like design patterns for Actors.  Often you just want
+an Actor to hold some state and service calls which query or mutate that state.
+This behavior is wrapped up as a Server.
+
+To begin implementing a server, look at Revactor::Behavior::Server, which is
+a module demonstrating the API.  Servers are implemented using a set of
+callbacks which are called in response to certain events.
+
+Servers should implement a number of principles, including transactional
+semantics, however due to the side effect potential of mutable state in
+Ruby this isn't possible to achieve.
+
+Future versions of Revactor may attempt to address this, and also change the
+present implementation (which is effectively a carbon copy of Erlang's 
+gen_server) to be more Ruby-like.
+
+== Mongrel
+
+Revactor includes complete support for running Mongrel on top of Actors and
+Revactor::TCP.  The implementation monkeypatches two methods in the
+Mongrel::HttpServer class.  Initial benchmarks show better throughput
+and concurrency than threaded Mongrel running on Ruby 1.8 or 1.9.
+
+To use Mongrel on top of Revactor, just:
+
+  require 'revactor/mongrel'
+
+Then call Mongrel within an Actor.start block.  The semantics are the same.
+The only difference is that Actors, not Threads, are being used for 
+concurrency.
+
+== Roadmap
+
+Revactor is still in its infancy.  Erlang and its Open Telcom Platform are an
+extremely feature rich platform, and many features can be borrowed and
+incorporated into Revactor.
+
+The first and foremost feature to be added is the concept of linked Actors.
+This idea is somewhat difficult to explain for the uninitiated, but the general
+concept is that interdependent Actors are linked in a graph.  When one Actor
+dies, it kills all linked Actors is well.  However, special Actors trap the
+exit messages from the Actors they're linked with.  These Actors are generally
+supervisors and restart any linked Actor graphs which crash.
+
+Next on the agenda is implementing DRb.  This should be possible simply by
+monkeypatching the existing DRb implementation to run on top of Revactor::TCP.
+Once DRb has been implemented it should be fairly trivial to implement
+distributed Actor networks over TCP using DRb as the underlying message
+passing protocol.
+
+Long term items include implementation of more Filters, Behaviors, and protocol
+modules.  These include an HTTP client (subclassed from the client in Rev),
+an HTTP server adapter (using the Mongrel parser), and the gen_fsm behavior from
+Erlang.  Additional areas of concern are addressing the problems of mutable 
+state in conjunction with Server and FSM behaviors.  A possible solution is
+to implement a tuple which stores immutable collections of primitive types
+like numbers, strings, and symbols, but this approach is likely to be slow.

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+load 'revactor.gemspec'
+
+# Default Rake task
+task :default => :rdoc
+
+# RDoc
+Rake::RDocTask.new(:rdoc) do |task|
+  task.rdoc_dir = 'doc'
+  task.title    = 'Revactor'
+  task.options = %w(--title Revactor --main README --line-numbers)
+  task.rdoc_files.include('bin/**/*.rb')
+  task.rdoc_files.include('lib/**/*.rb')
+  task.rdoc_files.include('README')
+end
+
+# Gem
+Rake::GemPackageTask.new(GEMSPEC) do |pkg|
+  pkg.need_tar = true
+end
+
+# RSpec
+begin
+require 'spec/rake/spectask'
+
+SPECS = FileList['spec/**/*_spec.rb']
+
+Spec::Rake::SpecTask.new(:spec) do |task|
+  task.spec_files = SPECS
+end
+
+namespace :spec do
+  Spec::Rake::SpecTask.new(:print) do |task|
+    task.spec_files = SPECS
+    task.spec_opts="-f s".split
+  end
+
+  Spec::Rake::SpecTask.new(:rcov) do |task|
+    task.spec_files = SPECS
+    task.rcov = true
+    task.rcov_opts = ['--exclude', 'spec']
+  end
+end
+
+rescue LoadError
+end

data/examples/echo_server.rb

@@ -0,0 +1,39 @@
+# An example echo server, written using Revactor::TCP
+# This implementation creates a new actor for each
+# incoming connection.
+
+require File.dirname(__FILE__) + '/../lib/revactor'
+
+HOST = 'localhost'
+PORT = 4321
+
+# Before we can begin using actors we have to call Actor.start
+# Future versions of Revactor will hopefully eliminate this
+Actor.start do
+  # Create a new listener socket on the given host and port
+  listener = Revactor::TCP.listen(HOST, PORT)
+  puts "Listening on #{HOST}:#{PORT}"
+
+  # Begin receiving connections
+  loop do
+    # Accept an incoming connection and start a new Actor
+    # to handle it
+    Actor.spawn(listener.accept) do |sock|
+      puts "#{sock.remote_addr}:#{sock.remote_port} connected"
+
+      # Begin echoing received data
+      loop do
+        begin
+          # Write everything we read
+          sock.write sock.read
+        rescue EOFError
+          puts "#{sock.remote_addr}:#{sock.remote_port} disconnected"
+
+          # Break (and exit the current actor) if the connection
+          # is closed, just like with a normal Ruby socket
+          break
+        end
+      end
+    end
+  end
+end

data/examples/google.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require 'cgi'
+require File.dirname(__FILE__) + '/../lib/revactor'
+
+Actor.start do
+  term = ARGV[0] || 'foobar'
+  sock = Revactor::TCP.connect("www.google.com", 80)
+
+  sock.write [
+    "GET /search?q=#{CGI.escape(term)} HTTP/1.0",
+    "Host: www.google.com",
+    "\r\n"
+  ].join("\r\n")
+
+  loop do
+    begin
+      STDOUT.write sock.read
+      STDOUT.flush
+    rescue EOFError
+      break
+    end
+  end
+end

data/examples/mongrel.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/revactor/mongrel'
+
+ADDR = '127.0.0.1'
+PORT = 8080
+
+Actor.start do
+  server = Mongrel::HttpServer.new(ADDR, PORT)
+  server.register '/', Mongrel::DirHandler.new(".")
+  server.run
+
+  puts "Running on #{ADDR}:#{PORT}"
+end