mikka 1.0.1-java

data/.gitignore

@@ -0,0 +1,6 @@
+/*.gem
+/.bundle
+/Gemfile.lock
+/pkg/*
+/ext
+.DS_Store

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use jruby-1.6.3@mikka

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/README.mdown

@@ -0,0 +1,33 @@
+# Mikka
+
+Mikka is a thin Ruby wrapper around Akka. It makes Akka's Java API more pleasing to the Rubyist's eye.
+
+## Work in progress
+
+Mikka is a work in progress, but currently used in production. It currently mostly scratches my own itchs, but improvement suggestions and patches are welcome. 
+
+Check out the `examples` directory for the basics. Start with the `hello_world.rb` example, it is extensively documented and goes through the basics.
+
+If you make something that can serve as a useful illustration of some concept, please contribute by sending a patch.
+
+## Requirements
+
+Only tested in JRuby 1.6.3 and Ruby 1.9 mode (add `jruby --1.9` or set `JRUBY_OPTS='--1.9`).
+
+The required Akka and Scala JARs are loaded from the [akka-actor-jars](https://rubygems.org/gems/akka-actor-jars) and [scala-library-jars](https://rubygems.org/gems/scala-library-jars) wrapper gems.
+
+## Installation
+
+    gem install mikka
+
+## Contributors
+
+Theo Hultberg, [@iconara](http://twitter.com/iconara)
+
+## License
+
+Mikka is licensed under the Apache 2 license, the same as Akka. See http://akka.io/docs/akka/1.1.2/project/licenses.html
+
+## Mikka?
+
+Mikka is a glacier close to the Akka massive.

data/Rakefile

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+require 'bundler'
+
+
+Bundler::GemHelper.install_tasks

data/examples/hello_world.rb

@@ -0,0 +1,107 @@
+# encoding: utf-8
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'bundler/setup'
+require 'mikka'
+
+# 0.
+# The numbers at the top of the comment blocks follow the flow of the 
+# application, read them in order to see the sequence of events.
+
+# 1.
+# The simplest way to create an actor is to do it with a block. The block
+# will receive each message and execute in the scope of an actor object (so
+# `context` will be available -- more on that later).
+#
+# The variable `phil` will not refer directly to an actor instance, but to an
+# `ActorRef`. There are many reasons for this, and for the full picture refer
+# to the Akka documentation. The short explanation is that it makes it 
+# possible to restart and replace the actor without the clients knowing that
+# the actor instance was changed, and it makes remote actors transparent.
+phil = Mikka.actor do |msg|
+  # 8. 
+  # Ruby doesn't have pattern matching, but `case` is usually enough. If you
+  # Have separate classes for your messages you can match on class.
+  case msg
+  when Introduction
+    # 9.
+    # The `Introduction` class has a field called `to_whom` that contains a
+    # reference to an actor that someone want to introduce us to. Let's send
+    # that actor a `Greeting`. 
+    msg.to_whom << Greeting.new('Hello, dear sir.')
+  when Greeting
+    puts "Received greeting: #{msg.body}"
+    # 12.
+    # The reply got routed back to this actor. Now we want to shut down this
+    # actor too, so that the application can shut down.
+    context.exit
+  end
+end
+
+# 2.
+# If you need more control over your actor's life cycle, or want to create
+# more than one of the same you can can declare a subclass of Mikka::Actor.
+# The #receive method is called for each message the actor receives. You can
+# do things when the actor starts by implementing #pre_start, and when the 
+# actor stops by implementing #post_stop.
+#
+# Don't create instances of this class yourself, an error will be raised if
+# it's done in the wrong way, see below for how it's supposed to be done.
+class Replier < Mikka::Actor
+  def receive(msg)
+    case msg
+    when Greeting
+      puts "Received greeting: #{msg.body}"
+      # 10.
+      # To reply to a message without having to explicitly refer to the sender
+      # use #reply (you can, however, store the sender and reply later if you
+      # want, it is available through `context.sender.get`).
+      #
+      # A word of caution: the sender is not always set, for example when the
+      # message was sent from a non-actor context like in 6. Also, the Scala 
+      # API sets the sender implicitly in a way that is not possible in Java 
+      # or Ruby, and even if Mikka does it's best to emulate the Scala way,
+      # it's not foolproof. If you want to guard agains errors when replying
+      # you can use #reply_safe instead of #reply. It will return true if the
+      # message could be sent, and false otherwise.
+      context.reply(Greeting.new('Why, hello old chap.'))
+      # 11.
+      # Now we're through with this actor, so we shut it down.
+      context.exit
+    end
+  end
+end
+
+# 3.
+# This is how you create an actor reference from a subclass of Mikka::Actor.
+# Creating the instance this way makes sure that the actor is set up correctly
+# (refer to the Akka documentation as to why it works this way).
+sam = Mikka.actor_of(Replier)
+
+# 4.
+# Messages can be anything, but if your messages are more complex than a 
+# simple string or symbol you are best off declaring a proper class to 
+# encapsulate them. `Struct` is convenient in this case (but creates mutable
+# objects, consider using the `immutable_struct` gem instead).
+class Introduction < Struct.new(:to_whom); end
+class Greeting < Struct.new(:body); end
+
+# 5.
+# An actor must be started before it can be used!
+phil.start
+sam.start
+
+# 6.
+# And finally, this is how to send a message to an actor. In Erlang and Scala
+# it is done with !, but that operator is not overridable in Ruby, so we have
+# to make do with <<. The Akka Java API defines #send_one_way (actually
+# sendOneWay, but JRuby fixes the casing for us), which can also be used.
+#
+# Here we send a message to `phil`, the message is an object that contains a
+# reference to the actor `sam`.
+phil << Introduction.new(sam)
+
+# 7.
+# The application will keep running until the last actor is dead. If you want
+# to force shutdown you can use `Mikka.registry.shutdown_all`.

data/examples/load_balancing1.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'bundler/setup'
+require 'mikka'
+
+
+worker1 = Mikka.actor { |msg| puts "Worker 1 working on #{msg}" }
+worker2 = Mikka.actor { |msg| puts "Worker 2 working on #{msg}" }
+balancer = Mikka.load_balancer(:actors => [worker1, worker2])
+
+10.times do |i|
+  balancer << "item #{i}"
+end
+
+balancer << Mikka::Messages.broadcast("a message to everyone")
+balancer << Mikka::Messages.poison_pill
+
+Mikka.registry.shutdown_all

data/examples/load_balancing2.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'bundler/setup'
+require 'mikka'
+
+
+class Worker < Mikka::Actor
+  def receive(message)
+    puts "#{context.uuid} Work on #{message}"
+  end
+end
+
+balancer = Mikka.load_balancer(:type => Worker, :count => 4)
+
+10.times do |i|
+  balancer << "item #{i}"
+end
+
+balancer << Mikka::Messages.broadcast("a message to everyone")
+
+Mikka.registry.shutdown_all

data/examples/proc_example.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'bundler/setup'
+require 'mikka'
+
+
+actor = Mikka.actor do |message|
+  case message
+  when 'hi'
+    puts "hello yourself"
+  when 'goodbye'
+    puts "adieu"
+    context.exit
+  else
+    puts "sorry, come again?"
+  end
+end
+
+actor.start
+actor << 'hi'
+actor << 'hello'
+actor << 'goodbye'

data/examples/simple_example.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'bundler/setup'
+require 'mikka'
+
+
+class Stallone < Mikka::Actor
+  def receive(message)
+    context.exit if message == 'punch!'
+  end
+end
+
+stallone = Mikka.actor_of(Stallone).start
+stallone << 'punch!'

data/examples/supervision1.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'bundler/setup'
+require 'mikka'
+
+
+class Worker < Mikka::Actor
+  life_cycle :permanent
+  
+  def pre_start
+    puts "#{context.id} starting"
+  end
+  
+  def pre_restart(reason)
+    puts "#{context.id} restarting"
+  end
+  
+  def post_restart(reason)
+    puts "#{context.id} restarted"
+  end
+  
+  def post_stop
+    puts "#{context.id} stopped"
+  end
+  
+  def receive(message)
+    raise java.lang.Exception.new('Oh, shucks') if message == 'hard work'
+    puts "#{context.id} Work on #{message}"
+  end
+end
+
+class Manager < Mikka::Actor
+  fault_handling :strategy => :all_for_one, :trap => [java.lang.Exception], :max_retries => 3, :time_range => 3000
+  
+  def pre_start
+    @worker1 = Mikka.actor_of { Worker.new }
+    @worker2 = Mikka.actor_of { Worker.new }
+    @worker1.id = 'worker1'
+    @worker2.id = 'worker2'
+    context.start_link(@worker1)
+    context.start_link(@worker2)
+    @worker1 << 'simple work'
+    @worker2 << 'hard work'
+    @worker2 << 'simple work'
+    @worker2 << 'simple work'
+    @worker2 << 'hard work'
+    @worker2 << 'simple work'
+    @worker2 << 'simple work'
+    @worker2 << 'simple work'
+  end
+end
+
+manager = Mikka.actor_of(Manager).start

data/lib/akka.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+
+require 'java'
+require 'akka-actor-jars'
+
+
+module Akka
+  module Actor
+    include_package 'akka.actor'
+
+    import 'akka.actor.ActorRef'
+    import 'akka.actor.UntypedActor'
+
+    class UntypedActor
+      def self.create(*args)
+        new(*args)
+      end
+    end
+  end
+  
+  module Config
+    include_package 'akka.config'
+  end
+  
+  module Routing
+    include_package 'akka.routing'
+  end
+end

data/lib/mikka.rb

@@ -0,0 +1,161 @@
+# encoding: utf-8
+
+require 'java'
+require 'akka'
+
+
+module Mikka
+  import java.util.Arrays
+  
+  def self.actor_of(*args, &block)
+    Akka::Actor::Actors.actor_of(*args, &block)
+  end
+  
+  def self.actor(&block)
+    Akka::Actor::Actors.actor_of { ProcActor.new(&block) }
+  end
+  
+  def self.registry
+    Akka::Actor::Actors.registry
+  end
+  
+  def self.current_actor
+    Thread.current[:mikka_current_actor]
+  end
+  
+  module Messages
+    def self.broadcast(message)
+      Akka::Routing::Routing::Broadcast.new(message)
+    end
+  
+    def self.poison_pill
+      Akka::Actor::Actors.poison_pill
+    end
+  end
+  
+  module RubyesqueActorCallbacks
+    def receive(message); end
+    def pre_start; end
+    def post_stop; end
+    def pre_restart(reason); end
+    def post_restart(reason); end
+    
+    def onReceive(message); receive(message); end
+    def preStart; super; pre_start; end
+    def postStop; super; post_stop; end
+    def preRestart(reason); super; pre_restart(reason); end
+    def postRestart(reason); super; post_restart(reason); end
+  end
+  
+  module ImplicitSender
+    def capture_current_actor
+      Thread.current[:mikka_current_actor] = context
+      yield
+    ensure
+      Thread.current[:mikka_current_actor] = nil
+    end
+    
+    def self.included(mod)
+      mod.class_eval do
+        [:onReceive, :preStart, :postStop, :preRestart, :postRestart].each do |method_name|
+          actual_method_name = :"__actual_#{method_name}"
+          alias_method actual_method_name, method_name
+          define_method method_name do |*args|
+            capture_current_actor do
+              send(actual_method_name, *args)
+            end
+          end
+        end
+      end
+    end
+  end
+  
+  module SupervisionDsl
+    module ClassMethods
+      def fault_handling(config)
+        trap = config[:trap].map { |e| e.java_class }
+        max_retries = config.fetch(:max_retries, 5)
+        time_range = config.fetch(:time_range, 5000)
+        case config[:strategy]
+        when :all_for_one
+          @fault_handling_strategy = Akka::Config::Supervision::AllForOneStrategy.new(trap, max_retries, time_range)
+        when :one_for_one
+          @fault_handling_strategy = Akka::Config::Supervision::OneForOneStrategy.new(trap, max_retries, time_range)
+        else
+          raise ArgumentError, 'strategy must be one of :all_for_one or :one_for_one'
+        end
+      end
+    
+      def registered_fault_handling_strategy
+        @fault_handling_strategy
+      end
+    
+      def life_cycle(type)
+        @life_cycle = case type
+                      when :permanent then Akka::Config::Supervision.permanent
+                      when :temporary then Akka::Config::Supervision.temporary
+                      when :undefined then Akka::Config::Supervision.undefined_life_cycle
+                      else raise ArgumentError, 'type must be one of :permanent, :temporary or :undefined'
+                      end
+      end
+    
+      def registered_life_cycle
+        @life_cycle
+      end
+    end
+    
+    module InstanceMethods
+      def initialize(*args)
+        super
+        if self.class.registered_fault_handling_strategy
+          context.fault_handler = self.class.registered_fault_handling_strategy
+        end
+        if self.class.registered_life_cycle
+          context.life_cycle = self.class.registered_life_cycle
+        end
+      end
+    end
+    
+    def self.included(m)
+      m.extend(ClassMethods)
+      m.include(InstanceMethods)
+    end
+  end
+  
+  class Actor < Akka::Actor::UntypedActor
+    include SupervisionDsl
+    include RubyesqueActorCallbacks
+    include ImplicitSender
+  end
+  
+  class ProcActor < Actor
+    def initialize(&receive)
+      define_singleton_method(:receive, receive)
+    end
+  end
+  
+  def self.load_balancer(options={})
+    actors = options[:actors]
+    unless actors
+      type = options[:type]
+      count = options[:count]
+      raise ArgumentError, "Either :actors or :type and :count must be specified" unless type && count
+      actors = (0...count).map { actor_of(type) }
+    end
+    actors.each { |a| a.start }
+    actor_list = Arrays.as_list(actors.to_java)
+    actor_seq = Akka::Routing::CyclicIterator.new(actor_list)
+    actor_factory = proc { actor_seq }.to_function
+    Akka::Routing::Routing.load_balancer_actor(actor_factory)
+  end
+end
+
+module Akka
+  module Actor
+    module ActorRef
+      def <<(message)
+        send_one_way(message, Mikka.current_actor)
+      end
+    end
+  end
+end

data/lib/mikka/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Mikka
+  VERSION = '1.0.1'
+end

data/mikka.gemspec

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+$: << File.expand_path('../lib', __FILE__)
+
+require 'mikka/version'
+
+
+Gem::Specification.new do |s|
+  s.name        = 'mikka'
+  s.version     = Mikka::VERSION
+  s.platform    = 'java'
+  s.authors     = ['Theo Hultberg']
+  s.email       = ['theo@iconara.net']
+  s.homepage    = 'http://github.com/iconara/mikka'
+  s.summary     = %q{Mikka is a JRuby wrapper for Akka}
+  s.description = %q{Mikka adapts Akka's Java API to fit better with Ruby}
+
+  s.rubyforge_project = 'mikka'
+  
+  s.add_dependency 'akka-actor-jars', '~> 1.1.0'
+
+  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 = %w(lib)
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: mikka
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 1
+  version: 1.0.1
+platform: java
+authors: 
+- Theo Hultberg
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-07 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: akka-actor-jars
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :runtime
+  version_requirements: *id001
+description: Mikka adapts Akka's Java API to fit better with Ruby
+email: 
+- theo@iconara.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rvmrc
+- Gemfile
+- README.mdown
+- Rakefile
+- examples/hello_world.rb
+- examples/load_balancing1.rb
+- examples/load_balancing2.rb
+- examples/proc_example.rb
+- examples/simple_example.rb
+- examples/supervision1.rb
+- lib/akka.rb
+- lib/mikka.rb
+- lib/mikka/version.rb
+- mikka.gemspec
+has_rdoc: true
+homepage: http://github.com/iconara/mikka
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: mikka
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Mikka is a JRuby wrapper for Akka
+test_files: []
+