zactor 0.0.5 → 0.0.6

data/.rake_tasks~

@@ -0,0 +1,19 @@
+build
+console[script]
+gemcutter:release
+gemspec
+gemspec:debug
+gemspec:generate
+gemspec:release
+gemspec:validate
+git:release
+install
+rcov
+release
+spec
+version
+version:bump:major
+version:bump:minor
+version:bump:patch
+version:write
+yard

data/.yardopts

@@ -0,0 +1 @@
+-m markdown -e ruby-interface/yard

data/Gemfile

@@ -1,13 +1,17 @@
 source "http://rubygems.org"
 
 group :development do
-  gem "rspec", "~> 2.3.0"
+  gem "rspec", ">= 2"
   gem "yard", "~> 0.6.0"
   gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.5.2"
   gem "rcov", ">= 0"
   gem "bluecloth"
   gem "rr"
+  gem "guard-rspec"
+  gem "growl"
+  gem "ruby-debug19"
+  gem "em-spec", :git => "https://github.com/mloughran/em-spec.git", :branch => 'rspec2'
 end
 
+
 gemspec

data/Gemfile.lock

@@ -1,33 +1,80 @@
+GIT
+  remote: https://github.com/mloughran/em-spec.git
+  revision: fc888b289a424fa93848ffdac3dc4b24fdd34950
+  branch: rspec2
+  specs:
+    em-spec (0.2.2)
+
 PATH
   remote: .
   specs:
-    zactor (0.0.5)
+    zactor (0.0.6)
       activesupport (> 0.1)
-      i18n (> 0.1)
+      bson (> 0.1)
+      bson_ext (> 0.1)
+      em-zeromq (> 0.1)
+      ffi (> 0.1)
+      ffi-rzmq (> 0.1)
+      ruby-interface (> 0)
 
 GEM
   remote: http://rubygems.org/
   specs:
     activesupport (3.0.7)
+    archive-tar-minitar (0.5.2)
     bluecloth (2.1.0)
+    bson (1.2.4)
+    bson_ext (1.2.4)
+    columnize (0.3.2)
+    configuration (1.2.0)
     diff-lcs (1.1.2)
-    git (1.2.5)
+    em-zeromq (0.2.1)
+      eventmachine (>= 1.0.0.beta.3)
+      ffi-rzmq (>= 0.7.2)
+    eventmachine (1.0.0.beta.3)
+    ffi (1.0.7)
+      rake (>= 0.8.7)
+    ffi-rzmq (0.7.2)
+    growl (1.0.3)
+    guard (0.3.0)
+      open_gem (~> 1.4.2)
+      thor (~> 0.14.6)
+    guard-rspec (0.2.0)
+      guard (>= 0.2.2)
     i18n (0.5.0)
-    jeweler (1.5.2)
-      bundler (~> 1.0.0)
-      git (>= 1.2.5)
-      rake
+    launchy (0.3.7)
+      configuration (>= 0.0.5)
+      rake (>= 0.8.1)
+    linecache19 (0.5.11)
+      ruby_core_source (>= 0.1.4)
+    open_gem (1.4.2)
+      launchy (~> 0.3.5)
     rake (0.8.7)
     rcov (0.9.9)
     rr (1.0.2)
-    rspec (2.3.0)
-      rspec-core (~> 2.3.0)
-      rspec-expectations (~> 2.3.0)
-      rspec-mocks (~> 2.3.0)
-    rspec-core (2.3.1)
-    rspec-expectations (2.3.0)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
       diff-lcs (~> 1.1.2)
-    rspec-mocks (2.3.0)
+    rspec-mocks (2.5.0)
+    ruby-debug-base19 (0.11.24)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby-interface (0.0.2)
+      activesupport (> 0.1)
+      i18n (> 0.1)
+      ruby-interface
+    ruby_core_source (0.1.4)
+      archive-tar-minitar (>= 0.5.2)
+    thor (0.14.6)
     yard (0.6.5)
 
 PLATFORMS
@@ -36,9 +83,12 @@ PLATFORMS
 DEPENDENCIES
   bluecloth
   bundler (~> 1.0.0)
-  jeweler (~> 1.5.2)
+  em-spec!
+  growl
+  guard-rspec
   rcov
   rr
-  rspec (~> 2.3.0)
+  rspec (>= 2)
+  ruby-debug19
   yard (~> 0.6.0)
   zactor!

data/Guardfile

@@ -0,0 +1,12 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(/^spec\/(.*)_spec.rb/)
+  watch(/^lib\/(.*)\.rb/)                              { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(/^spec\/spec_helper.rb/)                       { "spec" }
+  
+  # watch(/^lib\/zactor.rb/)                             { "spec/lib/actor_spec.rb" }
+  
+  watch(/^app\/(.*)\.rb/)                              { |m| "spec/app/#{m[1]}_spec.rb" }
+end

data/README.md

@@ -1,93 +1,167 @@
-RubyInterface
-=============
+Что это
+=======
+Zactor позволяет любой руби-объект научить общаться с другими объектами посредством отправки и получения сообщений. При этом неважно где именно расположен объект, в том же процессе, в соседнем, или на другой физической машине.
 
-Простенький патерн определения интерфейсов в руби. В противовес стандартным миксинам, для каждого интерфейса создается свой класс и соответсвенно экземпляр класса для каждого объекта с интерфейсом.
+Zactor использует zmq как бекенд для сообщений, eventmachine и em-zeromq для асинхронной работы с zmq, RubyInterface для описания себя, BSON для сериализации данных.
 
-    module Tree
-      extend RubyInterface
-      interface :tree do
-        include Enumerable
-        attr_accessor :parent
-    
-        def childs
-          @childs ||= []
-        end
-    
-        def each(&blk)
-          blk.call(owner)
-          childs.each { |v| v.tree.each(&blk) }
-        end
-    
-        def set_parent(parent)
-          parent.tree.childs << owner
-          @parent = parent
-        end
-      end
-    end
+Каждый zactor-объект имеет свой identity, который генерируется автоматически, либо задается вручную и постоянен. Совокупность identity, host и port на которых был рожден этот объект, это достаточная информация для того что бы отправить этому объекту сообщение из другого объекта. Выглядит примерно так:
+   
+        zactor.actor =>
+        {"identity"=>"actor.2154247120-0.0.0.0:8000", "host"=>"0.0.0.0:8000"}
+  
+Ипользование
+============
+
+Для начала нужно стартануть Zactor.
+  
+    Zactor.start 8000
+  
+Процесс забиндится на 0.0.0.0:8000, через эту точку будет происходить общение между zactor-процессами. Стартоваться должен в запущенном EM-контексте.
+
+В каждый zactor-активный класс нужно делать include Zactor, после чего у класса и его экземпляров для доступа к функциями Zactor появится метод zactor. После создания объекта нужно выполнить zactor.init
 
     class A
-      include Tree
+      include Zactor
+  
+      def initialize
+        zactor.init
+      end
     end
+  
+Для отправки сообщений другому объекту нам нужно знать его идентификатор. Идентификатор можно получить тремя способами:
 
-При разработке интерфейса не нужно задумываться о конфликтах имен переменных, методов, можно делать все что угодно. Аргументом к методу interface передается название метода, по которому этот интерфейс будет доступен.
-
-    a = A.new
-    b = A.new
+* Непосрдественной передачей. При инициализации или в любом другом месте, это исключительно внутренняя логика приложения. Идентификатор объекта можно получить вызвав zactor.actor
+* При получении сообщения. В сообщении всегда содержится информация об отправителе
+* Если объект имеет заранее известный identity, то мы можем получить его полный идентификатор вызвав Zactor.get_actor с identity и хостом, на котором он запущен
+  
+    actor = Zactor.get_actor "broker", :host => "0.0.0.0:8001"
+  
+Получив идентификатор можно отправлять ему сообщения
+  
+    zactor.send_request actor, :show_me, :boobs
 
-    a.tree.set_parent b
-    b.tree.childs # => [a]
-    b.tree.map { |o| o } # => [b, a]
-    
-А при использовании методов относящихся к интерфейсу мы явно видим к какому же интерфейсу он относится. Всем профит!
+  
+Каждый класс может определять какие именно ивенты он может получать и что с ними делать
+ 
+    include Zactor
 
-В интерфейсе доступен метод owner, возвращающий родительский объект. У класса интерфейса есть <tt>interface_base</tt>, возвращающий класс, куда интерфейс был заинклужен.
+    zactor do
+      event(:show_me) do |o, msg, what|
+        case what
+        when :boobs
+          do_it
+        else
+          do_smth_else
+        end
+      end
+    end
+  
+Рассмотрим пример банального ping-pong
 
-Помимо инстанс метода, создается так же класс-метод. В него можно передать блок, который выполнится в скоупе класса интерфейса. Сам метод возвращает класс интерфейса.
+    class A
+      include Zactor
 
-    module StateMachine
-      extend RubyInterface
-      interface :state_machine do
-        def self.state(name)
-          puts "New state #{name}"
+      def initialize
+        zactor.init
+        ping Zactor.get_actor("b")
+      end
+  
+      def ping(actor) 
+        puts "Ping!"
+        zactor.send_request actor, :ping do |res|
+          puts res
         end
       end
     end
 
-    class A
-      include StateMachine
+
+    class B
+      include Zactor
+  
+      zactor do
+        identity "b"
+    
+        event(:ping) do |o, msg|
+          msg.reply "Pong!"
+        end
+      end
   
-      state_machine do
-        state(:parked) # => New state parked
-        state(:idling) # => New state idling
+      def initialize
+        zactor.init
       end
+
+    end
+
+    EM.run do
+      Zactor.start 8000
+  
+      a = A.new
+      b = B.new
     end
+  
+A посылает сообщение :ping для B, а B отвечает "Pong!"
+
+В коллбэк определенный в event передается объект получившый сообщение, объект сообщения ({Zactor::Message}) и далее переданные в запросе аргументы (если они есть). У {Zactor::Message} есть два основных метода: sender, возвращающий идентификатор отправителя и reply, который посылает ответ на запрос.
+
+Важный момент, identity должно задаваться ДО zactor.init и после этого не может меняться.
+
+ZMQ
+===
+
+При Zactor.start стартует брокер, по одному на каждый процесс, через него проходят все сообщения данного процесса, принимает сообщения через SUB-сокет, отправляет через PUB. SUB подписан на все сообщения. Каждый zactor-объект создает по паре сокетов, PUB подключается к SUB-брокера, а SUB к PUB-брокера. SUB подписывается на сообщения содержащие его identity.
+
+![ZMQ](images/zmq1.png)
+
+Рассмотрим жизнь сообщения на примере с ping-ping. В случае с b в том же процессе:
+
+<div class=wsd wsd_style="default"><pre>
+A[PUB]->Broker[SUB]: Посылаем запрос :ping
+Broker[SUB]->Broker[PUB]: Перебрасываем запрос в PUB сокет
+Broker[PUB]->B[SUB]: Передаем получателю сообщение
+B[PUB]->Broker[SUB]: Отправляем ответ "Pong!"
+Broker[SUB]->Broker[PUB]: Перебрасываем запрос в PUB сокет
+Broker[PUB]->A[SUB]: Отправитель получает ответ
+</pre></div><script type="text/javascript" src="http://www.websequencediagrams.com/service.js"></script>
+
+В случае с b в другом процессе:
+
+<div class=wsd wsd_style="default"><pre>
+A[PUB for App2]->App2 Broker[SUB]: Посылаем запрос :ping
+App2 Broker[SUB]->App2 Broker[PUB]: Перебрасываем запрос в PUB сокет
+App2 Broker[PUB]->B[SUB]: Передаем получателю сообщение
+B[PUB for App1]->App1 Broker[SUB]: Отправляем ответ "Pong!"
+App1 Broker[SUB]->App1 Broker[PUB]: Перебрасываем запрос в PUB сокет
+App1 Broker[PUB]->A[SUB]: Отправитель получает ответ
+</pre></div><script type="text/javascript" src="http://www.websequencediagrams.com/service.js"></script>
+
+Балансировка
+============
+
+Так как это ZMQ, мы можем очень просто изменить тип получения сообщения. Например, добавив балансер. Теперь можно запускать процессы со ссылкой на этот балансер.
+
+    Zactor.start :balancer => "0.0.0.0:4000"
     
-При наследовании класса с интерфейсом, создается новый класс интерфейса и наследуется от предыдущего, т.е. повторяет иерархию класса, в который он включен.
+У нас получится примерно следующая схема:
 
-Если в блоке <tt>interface</tt> вызывается метод <tt>interfaced</tt>, то исполнение блока, передаваемого <tt>interfaced</tt> 
-происходит после добавления интерфейса в класс, в контексте этого класса.
+![ZMQ](images/zmq2.png)
 
-Пример:
-   
-     module A
-       extend RubyInterface
-       interface :int do
-         interfaced do
-           def baz
-             self.class.int_interface.foo
-           end
-         end
-     
-         def self.foo
-           "bar"
-         end
-       end
-     end
-     
-     class B
-       include A
-     end
-     
-     B.new.baz # => "bar"
-
-В каждом модуле может быть определено произвольное количество интерфейсов
+Теперь наш ping можно отправлять в балансер, а отвечать будет один из подключенных воркеров.
+
+    ping Zactor.get_actor("b", :host => "0.0.0.0:4000")
+    
+
+Протокол обмена
+===============
+
+
+Perfomance
+==========
+
+А хрен его знает, толком не мерялось ничего :)
+
+TODO
+====
+
+* Сделать событие отваливания объектов. Наверное, что-то вроде простого аналога link в эрланге.
+* Добавить таймауты для запросов с коллбэками. Сейчас они будут висеть бесконечно и засрут память.
+* Доступ к отправителю в колллбэке запроса. В случае с балансировкой он будет не тем же, кому мы посылали сообщение

data/Rakefile

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 require 'rubygems'
 require 'bundler'
 begin

data/VERSION

@@ -0,0 +1 @@
+0.0.3

data/examples/chat/client.rb

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+
+# ruby client.rb SELF_PORT SERVER LOGIN
+# ruby client.rb 6001 0.0.0.0:8000 lolo
+require 'bundler'
+ENV['BUNDLE_GEMFILE'] = File.join(File.dirname(__FILE__), '..', '..', 'Gemfile')
+
+Bundler.setup(:default)
+
+require 'zactor'
+class Client
+  include Zactor
+  
+  zactor do
+    event(:message) do |o, msg, text|
+      puts text
+    end
+  end
+  
+  def initialize(login)
+    @login = login
+    @persons = {}
+  end
+  
+  def start(server)
+    zactor.init 
+    @server = Zactor.get_actor("server", :host => server)
+    connect
+  end
+  
+  def connect
+    puts "Подключаемся"
+    zactor.send_request(@server, :new_client, @login) do
+      puts "Поключились!"
+      zactor.link(@server) { connect }
+    end.timeout(5) { puts "Проблемы с подключением..." }
+  end
+  
+  def send_message(text)
+    if text =~ /(\w+) -> (.+)/
+      send_personal($1, $2)
+    else
+      zactor.send_request(@server, :message, text)
+    end
+  end
+  
+  def send_personal(login, text)
+    if client = @persons[login]
+      zactor.send_request(client, :message, "(personally) #{@login}:" + "#{text}")
+    else
+      zactor.send_request(@server, :client_request, login) do |res, client|
+        case res
+        when :ok
+          @persons[login] = client
+          zactor.link(client) { @persons.delete login }
+          zactor.send_request(client, :message, "(personally) #{@login}:" + "#{text}")
+        else
+          puts "Ошибка отправки сообщения"
+        end
+      end
+    end
+  end
+  
+  def stop
+    zactor.finish
+    EM.stop
+  end
+  
+  module KeyboardInput
+    include EM::Protocols::LineText2
+    attr_accessor :client
+    def receive_line(data)
+      client.send_message data
+    end
+  end
+   
+end
+
+client = Client.new ARGV[2]
+
+Signal.trap('INT') { client.stop } 
+Signal.trap('TERM') { client.stop }
+
+EM.run do
+  Zactor.start ARGV[0]#, :debug => true
+  client.start ARGV[1]
+  EM.open_keyboard(Client::KeyboardInput) { |c| c.client = client }
+end