dcell 0.0.0 → 0.0.1

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+tmp/*
+zookeeper/*

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format documentation
+--backtrace
+--default_path spec

data/CHANGES.md

@@ -0,0 +1,8 @@
+0.0.1
+-----
+
+* Initial release
+
+0.0.0
+-----
+* Vapoware release to claim the "dcell" gem name >:D

data/Gemfile

@@ -1,4 +1,6 @@
 source "http://rubygems.org"
 
+gem 'celluloid', :git => 'git://github.com/tarcieri/celluloid'
+
 # Specify your gem's dependencies in dcell.gemspec
 gemspec

data/README.md

@@ -0,0 +1,209 @@
+DCell
+=====
+
+DCell is a simple and easy way to build distributed applications in Ruby.
+Somewhat similar to DRb, DCell lets you easily expose Ruby objects as network
+services, and call them remotely just like you would any other Ruby object.
+However, unlike DRb all objects in the system are concurrent. You can create
+and register several available services on a given node, obtain handles to
+them, and easily pass these handles around the network just like any other
+objects.
+
+DCell is a distributed extension to Celluloid, which provides concurrent
+objects for Ruby with many of the features of Erlang, such as the ability
+to supervise objects and restart them when they crash, and also link to
+other objects and receive event notifications of when they crash. This makes
+it easier to build robust, fault-tolerant distributed systems.
+
+You can read more about Celluloid at: http://celluloid.github.com
+
+Supported Platforms
+-------------------
+
+DCell works on Ruby 1.9.2/1.9.3, JRuby 1.6 (in 1.9 mode), and Rubinius 2.0.
+
+To use JRuby in 1.9 mode, you'll need to pass the "--1.9" command line
+option to the JRuby executable, or set the "JRUBY_OPTS=--1.9" environment
+variable:
+
+    export JRUBY_OPTS=--1.9
+
+(Note: I'd recommend putting the above in your .bashrc/.zshrc/etc in
+general. 1.9 is the future, time to embrace it)
+
+Celluloid works on Rubinius in either 1.8 or 1.9 mode.
+
+All components, including the 0MQ bindings, Redis, and Zookeeper adapters
+are all certified to work on the above platforms. The 0MQ binding is FFI.
+The Redis adapter is pure Ruby. The Zookeeper adapter uses an MRI-style
+native extension but also supplies a pure-Java backend for JRuby.
+
+Prerequisites
+-------------
+
+DCell requires 0MQ. On OS X, this is available through Homebrew by running:
+
+    brew install zeromq
+
+DCell keeps the state of all connected nodes and global configuration data
+in a service it calls the "registry". There are presently two supported
+registry services:
+
+* Redis (Fast and Loose): Redis is a persistent data structures server.
+  It's simple and easy to use for development and prototyping, but lacks a
+  good distribution story.
+
+* Zookeeper (Serious Business): Zookeeper is a high-performance coordination
+  service for distributed applications. It exposes common services such as
+  naming, configuration management, synchronization, and group management.
+  Unfortunately, it has slightly more annoying client-side dependencies and is
+  more difficult to deploy than Redis.
+
+You may pick either one of these services to use as DCell's registry. The
+default is Redis.
+
+To install a local copy of Redis on OS X with Homebrew, run:
+
+    brew install redis
+
+To install a local copy Zookeeper for testing purposes, run:
+
+    rake zookeeper:install
+
+and to start it run:
+
+    rake zookeeper:start
+
+Configuration
+-------------
+
+The simplest way to configure and start DCell is with the following:
+
+    require 'dcell'
+
+    DCell.start
+
+This configures DCell with all the default options, however there are many
+options you can override, e.g.:
+
+    DCell.start :id => "node42", :addr => "tcp://127.0.0.1:2042"
+
+DCell identifies each node with a unique node ID, that defaults to your
+hostname. Each node needs to be reachable over 0MQ, and the addr option
+specifies the 0MQ address where the host can be reached. When giving a tcp://
+URL, you *must* specify an IP address and not a hostname.
+
+To join a cluster you'll need to provide the location of the registry server.
+This can be done through the "registry" configuration key:
+
+	DCell.start :id => "node24", :addr => "tcp://127.0.0.1:2042",
+	  :registry => {
+	    :adapter => 'redis',
+	    :host    => 'mycluster.example.org',
+	    :port    => 6379
+	  }
+
+When configuring DCell to use Redis, use the following options:
+
+- **adapter**: "redis" (*optional, alternatively "zk"*)
+- **host**: hostname or IP address of the Redis server (*optional, default localhost*)
+- **port**: port of the Redis server (*optional, default 6379*)
+- **password**: password to the Redis server (*optional*)
+
+Usage
+-----
+
+You've now configured a single node in a DCell cluster. You can obtain the
+DCell::Node object representing the local node by calling DCell.me:
+
+    >> DCell.start
+     => #<Celluloid::Supervisor(DCell::Application):0xed6>
+    >> DCell.me
+     => #<DCell::Node[cryptosphere.local] @addr="tcp://127.0.0.1:7777">
+
+DCell::Node objects are the entry point for locating actors on the system.
+DCell.me returns the local node. Other nodes can be obtained by their
+node IDs:
+
+    >> node = DCell::Node["cryptosphere.local"]
+     => #<DCell::Node[cryptosphere.local] @addr="tcp://127.0.0.1:7777">
+
+DCell::Node.all returns all connected nodes in the cluster:
+
+    >> DCell::Node.all
+     => [#<DCell::Node[test_node] @addr="tcp://127.0.0.1:21264">, #<DCell::Node[cryptosphere.local] @addr="tcp://127.0.0.1:7777">]
+
+DCell::Node is a Ruby Enumerable. You can iterate across all nodes with
+DCell::Node.each.
+
+Once you've obtained a node, you can look up services it exports and call them
+just like you'd invoke methods on any other Ruby object:
+
+	>> node = DCell::Node["cryptosphere.local"]
+	 => #<DCell::Node[cryptosphere.local] @addr="tcp://127.0.0.1:7777">
+    >> time_server = node[:time_server]
+     => #<Celluloid::Actor(TimeServer:0xee8)>
+    >> time_server.time
+     => "The time is: 2011-11-10 20:23:47 -0800"
+
+You can also find all available services on a node with DCell::Node#all:
+
+	>> node = DCell::Node["cryptosphere.local"]
+	 => #<DCell::Node[cryptosphere.local] @addr="tcp://127.0.0.1:7777">
+	>> node.all
+	 => [:time_server]
+
+Registering Actors
+------------------
+
+All services exposed by DCell must take the form of registered Celluloid actors.
+What follows is an extremely brief introduction to creating and registering
+actors, but for more information, you should definitely [read the Celluloid
+documentation](http://celluloid.github.com).
+
+DCell exposes all Celluloid actors you've registered directly onto the network.
+The best way to register an actor is by supervising it. Below is an example of
+how to create an actor and register it on the network:
+
+    class TimeServer
+      include Celluloid
+
+      def time
+        "The time is: #{Time.now}"
+      end
+    end
+
+Now that we've defined the TimeServer, we're going to supervise it and register
+it in the local registry:
+
+	>> TimeServer.supervise_as :time_server
+	 => #<Celluloid::Supervisor(TimeServer):0xee4>
+
+Supervising actors means that if they crash, they're automatically restarted
+and registered under the same name. We can access registered actors by using
+Celluloid::Actor#[]:
+
+	>> Celluloid::Actor[:time_server]
+	 => #<Celluloid::Actor(TimeServer:0xee8)>
+	>> Celluloid::Actor[:time_server].time
+	 => "The time is: 2011-11-10 20:17:48 -0800"
+
+This same actor is now available using the DCell::Node#[] syntax:
+
+    >> node = DCell.me
+     => #<DCell::Node[cryptosphere.local] @addr="tcp://127.0.0.1:1870">
+    >> node[:time_server].time
+     => "The time is: 2011-11-10 20:28:27 -0800"
+
+Globals
+-------
+
+DCell provides a registry global for storing configuration data and actors you
+wish to publish globally to the entire cluster:
+
+	>> actor = Celluloid::Actor[:dcell_server]
+	 => #<Celluloid::Actor(DCell::Server:0xf2e) @addr="tcp://127.0.0.1:7777">
+	>> DCell::Global[:sweet_server] = actor
+	 => #<Celluloid::Actor(DCell::Server:0xf2e) @addr="tcp://127.0.0.1:7777">
+	>> DCell::Global[:sweet_server]
+	 => #<Celluloid::Actor(DCell::Server:0xf2e) @addr="tcp://127.0.0.1:7777">

data/Rakefile

@@ -1 +1,4 @@
 require "bundler/gem_tasks"
+Dir["tasks/**/*.task"].each { |task| load task }
+
+task :default => :spec

data/benchmarks/messaging.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+
+require 'benchmark'
+
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+require 'dcell'
+DCell.setup
+DCell.run!
+
+RECEIVER_PORT = 12345
+
+$receiver_pid = Process.spawn Gem.ruby, File.expand_path("../receiver.rb", __FILE__)
+STDERR.print "Waiting for test node to start up..."
+
+socket = nil
+30.times do
+  begin
+    socket = TCPSocket.open("127.0.0.1", RECEIVER_PORT)
+    break if socket
+  rescue Errno::ECONNREFUSED
+    STDERR.print "."
+    sleep 1
+  end
+end
+
+if socket
+  STDERR.puts " done!"
+  socket.close
+else
+  STDERR.puts " FAILED!"
+  raise "couldn't connect to test node!"
+end
+
+class AsyncPerformanceTest
+  include Celluloid
+
+  def initialize(progenator, n = 10000)
+    @n = n
+    @receiver = progenator.spawn_async_receiver(n, current_actor)
+  end
+
+  def run
+    @n.times { @receiver.increment! }
+    wait :complete
+  end
+
+  def complete
+    signal :complete
+  end
+end
+
+receiver = DCell::Node['benchmark_receiver']
+progenator = receiver[:progenator]
+
+test = AsyncPerformanceTest.new progenator
+time = Benchmark.measure { test.run }.real
+messages_per_second = 1 / time * 10000
+
+puts "messages_per_second: #{"%0.2f" % messages_per_second}"
+
+Process.kill 9, $receiver_pid
+Process.wait $receiver_pid rescue nil
+
+exit 0

data/benchmarks/receiver.rb

@@ -0,0 +1,37 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+require 'dcell'
+DCell.setup :id => 'benchmark_receiver', :addr => 'tcp://127.0.0.1:12345'
+
+class AsyncReceiver
+  include Celluloid
+  attr_reader :count
+
+  def initialize(n, actor)
+    @n, @actor = n, actor
+    @count = 0
+  end
+
+  def increment
+    @count += 1
+    @actor.complete! if @count == @n
+    @count
+  end
+end
+
+class Progenator
+  include Celluloid
+
+  def spawn_async_receiver(n, actor)
+    AsyncReceiver.new(n, actor)
+  end
+end
+
+class BenchmarkApplication < Celluloid::Application
+  supervise DCell::Application
+  supervise Progenator, :as => :progenator
+end
+
+BenchmarkApplication.run

data/dcell.gemspec

@@ -10,12 +10,19 @@ Gem::Specification.new do |s|
   s.homepage    = "http://github.com/tarcieri/dcell"
   s.summary     = "An asynchronous distributed object framework based on Celluloid"
   s.description = "DCell is an distributed object framework based on Celluloid built on 0MQ and Zookeeper"
-  
+
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  
-  s.add_dependency "celluloid"
+
+  s.add_dependency "celluloid", ">= 0.6.2"
+  s.add_dependency "ffi"
   s.add_dependency "ffi-rzmq"
+  s.add_dependency "redis"
+  s.add_dependency "redis-namespace"
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rspec", ">= 2.7.0"
+  #s.add_development_dependency "zk"
 end

data/lib/celluloid/README

@@ -0,0 +1,8 @@
+Ideally DCell would use Celluloid::IO to monitor 0MQ sockets. Unfortunately,
+ffi-rzmq presently does not present an API for obtaining an IO object from a
+0MQ socket.
+
+This directory contains a temporary workaround Celluloid::ZMQ which uses
+a ZMQ::Poller to monitor for 0MQ activity. This implementation is hardly
+anywhere near ideal but it works and provides a temporary solution until
+ffi-rzmq implements an API for retrieving IO objects.

data/lib/celluloid/zmq.rb

@@ -0,0 +1,28 @@
+require 'ffi-rzmq'
+
+require 'celluloid'
+require 'celluloid/zmq/mailbox'
+require 'celluloid/zmq/reactor'
+
+module Celluloid
+  # Actors which run alongside 0MQ operations
+  # This is a temporary hack (hopefully) until ffi-rzmq exposes IO objects for
+  # 0MQ sockets that can be used with Celluloid::IO
+  module ZMQ
+    def self.included(klass)
+      klass.send :include, ::Celluloid
+      klass.use_mailbox Celluloid::ZMQ::Mailbox
+    end
+
+    # Wait for the given IO object to become readable
+    def wait_readable(socket)
+      # Law of demeter be damned!
+      current_actor.mailbox.reactor.wait_readable(socket)
+    end
+
+    # Wait for the given IO object to become writeable
+    def wait_writeable(socket)
+      current_actor.mailbox.reactor.wait_writeable(socket)
+    end
+  end
+end

data/lib/celluloid/zmq/mailbox.rb

@@ -0,0 +1,13 @@
+module Celluloid
+  module ZMQ
+    # A Celluloid mailbox for Actors that wait on 0MQ sockets
+    class Mailbox < Celluloid::IO::Mailbox
+      def initialize
+        @messages = []
+        @lock  = Mutex.new
+        @waker = Celluloid::IO::Waker.new
+        @reactor = Reactor.new(@waker)
+      end
+    end
+  end
+end

data/lib/celluloid/zmq/reactor.rb

@@ -0,0 +1,74 @@
+module Celluloid
+  module ZMQ
+    # React to incoming 0MQ and Celluloid events. This is kinda sorta supposed
+    # to resemble the Reactor design pattern.
+    class Reactor
+      def initialize(waker)
+        @waker = waker
+        @poller = ::ZMQ::Poller.new
+        @readers = {}
+        @writers = {}
+
+        # FIXME: The way things are presently implemented is super ghetto
+        # The ZMQ::Poller should be able to wait on the waker somehow
+        # but I can't get it to work :(
+        #result = @poller.register(nil, ::ZMQ::POLLIN, @waker.io.fileno)
+        #
+        #unless ::ZMQ::Util.resultcode_ok?(result)
+        #  raise "couldn't register waker with 0MQ poller"
+        #end
+      end
+
+      # Wait for the given ZMQ socket to become readable
+      def wait_readable(socket)
+        monitor_zmq socket, @readers, ::ZMQ::POLLIN
+      end
+
+      # Wait for the given ZMQ socket to become writeable
+      def wait_writeable(socket)
+        monitor_zmq socket, @writers, ::ZMQ::POLLOUT
+      end
+
+      # Monitor the given ZMQ socket with the given options
+      def monitor_zmq(socket, set, type)
+        if set.has_key? socket
+          raise ArgumentError, "another method is already waiting on #{socket.inspect}"
+        else
+          set[socket] = Fiber.current
+        end
+
+        @poller.register socket, type
+        Fiber.yield
+
+        @poller.deregister socket, type
+        socket
+      end
+
+      # Run the reactor, waiting for events, and calling the given block if
+      # the reactor is awoken by the waker
+      def run_once
+        # FIXME: This approach is super ghetto. Find some way to make the
+        # ZMQ::Poller wait on the waker's file descriptor
+        if @poller.size == 0
+          readable, _ = select [@waker.io]
+          yield if readable and readable.include? @waker.io
+        else
+          if ::ZMQ::Util.resultcode_ok? @poller.poll(100)
+            @poller.readables.each do |sock|
+              fiber = @readers.delete sock
+              fiber.resume if fiber
+            end
+
+            @poller.writables.each do |sock|
+              fiber = @writers.delete sock
+              fiber.resume if fiber
+            end
+          end
+
+          readable, _ = select [@waker.io], [], [], 0
+          yield if readable and readable.include? @waker.io
+        end
+      end
+    end
+  end
+end