actor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA1: 
+  metadata.gz: 692bbec40fb07dccc05300db738a52d61779194d
+  data.tar.gz: fd21f5720cca18985abda493c3bdc55886b4ec71
+SHA512: 
+  metadata.gz: 27afa42688e8e9608dac5ecbffda7a677ef46d94ab192f5dbe8f9b10c88ab1f2a2ca5d0be40844e22fe603ecffa8806459602a8ad556053f5c8ec6282de07b59
+  data.tar.gz: 975d6e1f537467f2cd21c2efe9397c9dd0519337ed236b163ad6da55a6cf59a654b366bd4b4b59b4a08e0bfd28e4429a197fadff45c5a39572506f21ed681cf6

data/.gitignore

@@ -0,0 +1,34 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+/html/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+.rvmrc
+
+.idea/

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+cache: bundler
+
+gemfile:
+  - gemfiles/Gemfile.travis
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - jruby-19mode
+  - rbx-2

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in actor.gemspec
+gemspec path: File.expand_path('../', __FILE__)
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Max
+
+MIT License
+
+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,114 @@
+# Actor
+
+[![Build Status](https://travis-ci.org/maxgale/actor.svg?branch=master)](https://travis-ci.org/maxgale/actor)
+
+The actor gem provides a completely implicit implementation of the actor pattern. The goal of the library is to provide
+an easy way to implement fast, concurrent code without having to worry about race conditions or unexpected side-effects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'actor'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install actor
+
+## Usage
+
+### Actors
+
+    require 'actor/base'
+
+    class MyActor
+      include Actor::Base
+
+      def example_method
+        'hi'
+      end
+    end
+
+    my_actor = MyActor.new
+
+That's it! Now any interations with `my_actor` will be executed concurrently. It's also worth noting that there are no
+return values. Instead, code is executed via message passing. Instead, there are callbacks.
+
+### Callbacks
+
+    my_actor.before_action :example_method do
+      # Code here is executed before :example_method is executed by the actor
+      puts 'before'
+    end
+
+    my_actor.after_action :example_method do |result|
+      # Code here is executed after :example_method is executed by the actor
+      puts 'after'
+      puts result
+    end
+
+    my_actor.example_method
+
+    => before
+    => after
+    => hi
+
+### Timers
+
+Another useful feature is the timer. The timer is an object that periodically executes a block of code.
+
+    require 'actor/timer'
+
+    # Create a timer the executes every 1/30th of a second. Only executes twice.
+    Actor::Timer.new 0.033, 2 do
+      puts 'hi'
+    end
+
+    => hi
+    => hi
+
+Passing in `0` as the number of iterations to the timer causes it to execute indefinitely. You can also pause, resume,
+and wait for timers to finish execution.
+
+    my_timer = Timer.new 0.033, 0 do
+      # Do periodic work
+    end
+
+    my_timer.pause # Temporarily stop work
+
+    my_timer.resume # Resume the work
+
+    my_timer.wait # Since `iterations = 0`, this will block forever
+
+## Gotchas
+
+Unfortunately, there are a few "gotchas" when using this gem.
+
+1. `Actor::Base` overrides the including class's `:new` method and renames it to `:__actor_new`. This sets up the
+possibility of naming conflicts.
+1. `Actor::Base` overrides `:send`, making it impossible to use `:send` without concurrent execution and callbacks.
+1. All actors are wrapped in a proxy class.  This proxy forwards all methods to the
+instance to be executed in a concurrent way. This means it is impossible to execute code normally when handling the
+proxy. You can access the underlying instance by calling `:__proxy_target`  on the proxy. Note: No callbacks are not
+triggered when accessing the instance directly (unless you use send).
+1. The timer period is counted from the end of the last block to the start of the next block. This means that the timer
+firing is very approximate and definitely not designed for blocking code.
+
+## Todo
+
+1. Using a thread pool would be nice.
+2. Benchmarks comparing MRI 2.1.2 vs. Rubinisu 2.2.6.
+3. Benchmarks comparing of this gem vs. Celluloid
+5. Add a way of using actors over a network via RPC
+
+## Contributing
+
+1. Fork it ( https://github.com/maxgale/actor/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/gem_tasks'
+require 'rdoc/task'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new :spec do |task|
+  task.rspec_opts = %w(--color --format nested)
+end
+
+RDoc::Task.new :rdoc do |rdoc|
+  rdoc.rdoc_files.include "lib/**/*.rb"
+  rdoc.options << "--all"
+end
+
+task default: [:spec, :rdoc]

data/actor.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'actor/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "actor"
+  spec.version       = Actor::VERSION
+  spec.authors       = ["Max Gale"]
+  spec.email         = ["maxgale4@gmail.com"]
+  spec.summary       = %q{A simple implementation of the actor pattern}
+  spec.homepage      = "https://github.com/maxgale/actor"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.3"
+  spec.add_development_dependency "rspec", "~> 2.14"
+  spec.add_development_dependency "rdoc", "~> 4.1"
+end

data/gemfiles/Gemfile.travis

@@ -0,0 +1,5 @@
+platforms :rbx do
+  gem 'rubysl', '~> 2.0'
+end
+
+eval_gemfile File.expand_path('../../Gemfile', __FILE__)

data/lib/actor.rb

@@ -0,0 +1,11 @@
+require 'actor/base'
+require 'actor/proxy'
+require 'actor/timer'
+require 'actor/version'
+
+##
+# Module containing actor functionality. See Actor::Base, Actor::Proxy, and
+# Actor::Timer for specific functionality.
+module Actor
+  
+end

data/lib/actor/base.rb

@@ -0,0 +1,89 @@
+require 'set'
+require 'actor/proxy'
+
+module Actor
+  ##
+  # Module that actors should include
+  module Base
+    ##
+    # Adds a new message to the queue. Args and block are optional
+    #
+    # * *Args*:
+    #   - +method_name+: symbol representation of the action (method) to preform
+    #   - +args+: the arguments to pass to the action when it is executed
+    #   - +block+: the block to pass to the action when it is executed
+    def send method_name, *args, &block
+      @mailbox << [method_name, args, block]
+    end
+
+    ##
+    # Adds a listener that is called before the including object performs 
+    # the specified action.
+    #
+    # * *Args*:
+    #   - +action+: the action (symbol) the hook into
+    #   - +block+: the block to execute before the specified action
+    def before_action action, &block
+      @audience[:before][action] ||= Set.new
+      @audience[:before][action] << block
+    end
+
+    ##
+    # Adds a listener that is called after the including object performs 
+    # the specified action.
+    #
+    # * *Args*:
+    #   - +action+: the action the hook into
+    #   - +block+: the block to execute after the specified action
+    # * *Yields*: the value returned by the action
+    def after_action action, &block
+      @audience[:after][action] ||= Set.new
+      @audience[:after][action] << block
+    end
+
+    ##
+    # Adds a hook before object initialization to automatically sets up the
+    # thread that executes actions and sets up the callback data structures.
+    #
+    # * *Args*:
+    #   - +klass+: the class whose initialization is hooked into.
+    def self.included klass
+      class << klass
+        alias_method :__actor_new, :new
+        
+        ##
+        # Hooks into the initialization of the object to initialize the
+        # mailbox. Also starts the thread executing async method calls
+        def new *args
+          instance = __actor_new *args
+          instance.instance_variable_set :@audience, {}
+          instance.instance_variable_set :@mailbox, Queue.new
+            
+          audience = {}
+          audience[:before] = {}
+          audience[:after] = {}
+          instance.instance_variable_set :@audience, audience
+
+          Thread.new do
+            loop do
+              mailbox = instance.instance_variable_get :@mailbox
+              method_name, args, block = mailbox.pop
+              
+              if audience[:before][method_name]
+                audience[:before][method_name].each { |callback| callback.call }
+              end
+
+              result = instance.method(method_name).call *args, &block
+              
+              if audience[:after][method_name]
+                audience[:after][method_name].each { |callback| callback.yield result }
+              end
+            end
+          end
+
+          Proxy.new instance
+        end
+      end
+    end
+  end
+end

data/lib/actor/proxy.rb

@@ -0,0 +1,46 @@
+module Actor
+  ##
+  # The proxy class wraps an object and invokes all of its method using :send
+  class Proxy < BasicObject
+    ##
+    # Create a new proxy
+    #
+    # * *Args*:
+    #   - +proxy_target+: the instance to proxy
+    def initialize proxy_target
+      @proxy_target = proxy_target
+    end
+    
+    ##
+    # Proxies the method call to the proxy target using :send
+    def method_missing name, *args, &block
+      @proxy_target.send name, *args, &block
+    end
+    
+    ##
+    # Get the proxy target of this proxy
+    #
+    # * *Returns*: the proxy target
+    def __proxy_target
+      @proxy_target
+    end
+
+    ##
+    # Overrides the proxy equals to pass the equality check to the proxy target
+    def == other
+      @proxy_target == other
+    end
+
+    ##
+    # Overrides the proxy equals to pass the equality check to the proxy target
+    def != other
+      @proxy_target != other
+    end
+
+    ##
+    # Overrides the proxy equals to pass the equality check to the proxy target
+    def equal? other
+      @proxy_target.equal? other
+    end
+  end
+end

data/lib/actor/timer.rb

@@ -0,0 +1,46 @@
+module Actor
+  ##
+  # Simple timer implementation
+  class Timer
+    ##
+    # Create a new timer that fires every <period> seconds. The number of
+    # iterations specifies how many times the timer should fire.
+    #
+    # * *Args*:
+    #   - +period+: the time, in seconds, between firing the timer.
+    #   - +iterations+: the number times the timer should fire. 0 iterations
+    # means fire infinitely
+    def initialize period, iterations, &block
+      @pause_queue = Queue.new
+
+      i = iterations == 0 ? 1.0 / 0.0 : iterations
+      @timer_thread = Thread.new do
+        (1..i).step do
+          sleep unless @pause_queue.empty?
+          block.call
+          sleep period
+        end
+      end
+    end
+
+    ##
+    # Pauses the timer. The currently executing iteration is finished before
+    # the time is paused
+    def pause
+      @pause_queue << :paused
+    end
+
+    ##
+    # Resumes the timer
+    def resume
+      @pause_queue.clear
+      @timer_thread.wakeup
+    end
+
+    ##
+    # Block the current thread until the timer has finished executing
+    def wait
+      @timer_thread.join
+    end
+  end
+end

data/lib/actor/version.rb

@@ -0,0 +1,5 @@
+module Actor
+  ##
+  # Version number (semantic versioning)
+  VERSION = "0.1.0"
+end

data/spec/base_spec.rb

@@ -0,0 +1,82 @@
+require 'spec_helper'
+
+describe Actor::Base do
+  before :each do 
+    @actor_class = Class.new do
+      include Actor::Base
+
+      def action
+      end
+    end
+  end
+
+  it 'initializes mailbox on creation' do
+    proxy = @actor_class.new
+    actor = proxy.__proxy_target
+    
+    expect(actor.instance_variable_get :@mailbox).not_to be nil
+  end
+
+  it 'initializes mailbox on creation of subclass' do
+    child_actor = Class.new(@actor_class).new.__proxy_target
+    expect(child_actor.instance_variable_get :@mailbox).not_to be nil
+  end
+
+  it 'receives proxied messages' do
+    Thread.stub :new
+
+    proxy = @actor_class.new
+    actor = proxy.__proxy_target
+    
+    proxy.message1
+    proxy.message2 :arg1, :arg2
+
+    messages = actor.instance_variable_get :@mailbox
+    expect(messages.size).to be 2
+    expect(messages.pop).to eq [:message1, [], nil]
+    expect(messages.pop).to eq [:message2, [:arg1, :arg2], nil]
+  end
+
+  it 'processes messages' do
+    proxy = @actor_class.new
+    actor = proxy.__proxy_target
+
+    actor.should_receive :message1
+    actor.should_receive(:message2).with :arg1
+    actor.should_receive(:message3).with :arg1, :arg2
+
+    proxy.message1
+    proxy.message2 :arg1
+    proxy.message3 :arg1, :arg2
+    
+    # Sleep because threads are lame.
+    sleep 0.1
+
+    messages = actor.instance_variable_get :@mailbox
+    expect(messages.size).to be 0
+  end
+
+  it 'executes before/after callbacks' do    
+    proxy = @actor_class.new
+    actor = proxy.__proxy_target
+        
+    proxy.before_action :action do 
+      actor.before_method
+    end
+
+    ret_value = nil
+    proxy.after_action :action do |result|
+      ret_value = result
+      actor.after_method
+    end
+    
+    actor.should_receive(:before_method).ordered
+    actor.should_receive(:action).ordered.and_return('ret_value')
+    actor.should_receive(:after_method).ordered
+  
+    proxy.action
+    sleep 0.1
+
+    expect(ret_value).to eq 'ret_value'
+  end
+end

data/spec/proxy_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe Actor::Proxy do
+  before :each do
+    @target = Object.new
+    @proxy = Actor::Proxy.new @target
+  end
+
+  it 'sets the proxy target' do
+    expect(@proxy.instance_eval '@proxy_target').to be @target
+  end
+
+  it 'preserves equality' do
+    expect(@proxy).to eq @target
+    expect(@proxy != @target).to be false
+    expect(@proxy.equal? @target).to be true
+  end
+
+  it 'gets the proxy target' do
+    expect(@proxy.__proxy_target).to be @target
+  end
+
+  it 'forwards messages via send' do
+    @target.should_receive(:send).with :method, :to_s
+    @proxy.method :to_s
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'actor'
+
+Thread.abort_on_exception = true

data/spec/timer_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+describe Actor::Timer do
+  it 'executes for the given number of iterations' do
+    iterations = 0
+    Actor::Timer.new 0.033, 30 do
+      iterations += 1
+    end.wait
+
+    expect(iterations).to be 30
+  end
+
+  it 'fires every period' do
+    deltas = []
+    last_time = Time.now - 0.033
+
+    Actor::Timer.new 0.033, 30 do
+      deltas << (Time.now - last_time).to_f
+      last_time = Time.now
+    end.wait
+
+    deltas.each { |delta| expect(delta).to be_within(0.01).of(0.033) }
+  end
+
+  it 'pauses and resumes' do
+    long_pointless_sum = 0
+    timer = Actor::Timer.new 0.033, 3000 do
+      long_pointless_sum += 1
+    end
+
+    timer.pause
+    timer.pause # Verify that two messages get queued
+    post_pause_sum = long_pointless_sum
+    sleep 1
+
+    pause_queue = timer.instance_variable_get(:@pause_queue)
+
+    expect(long_pointless_sum).to be post_pause_sum
+    expect(timer.instance_variable_get(:@timer_thread).status).to eq 'sleep'
+    expect(pause_queue.pop).to be :paused
+    expect(pause_queue.pop).to be :paused
+    expect(pause_queue).to be_empty
+
+    pause_queue.should_receive :clear
+    timer.resume
+    sleep 1
+
+    expect(long_pointless_sum).to be > post_pause_sum
+  end
+
+  it 'blocks the calling thread when waiting' do
+    side_effect = false
+    Actor::Timer.new 0.01, 1 do 
+      sleep 1
+      side_effect = true
+    end.wait
+
+    expect(side_effect).to be true
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: actor
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Max Gale
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2014-05-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.6"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "10.3"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.14"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "4.1"
+  type: :development
+  version_requirements: *id004
+description: 
+email: 
+- maxgale4@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- actor.gemspec
+- gemfiles/Gemfile.travis
+- lib/actor.rb
+- lib/actor/base.rb
+- lib/actor/proxy.rb
+- lib/actor/timer.rb
+- lib/actor/version.rb
+- spec/base_spec.rb
+- spec/proxy_spec.rb
+- spec/spec_helper.rb
+- spec/timer_spec.rb
+homepage: https://github.com/maxgale/actor
+licenses: 
+- MIT
+metadata: {}
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - &id005 
+    - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id005
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A simple implementation of the actor pattern
+test_files: 
+- spec/base_spec.rb
+- spec/proxy_spec.rb
+- spec/spec_helper.rb
+- spec/timer_spec.rb