celluloid 0.16.0 → 0.17.3

data/culture/gems/README.md

@@ -0,0 +1,39 @@
+# Motivation
+To achieve the higher level of modularity, Celluloid was split into small sub-projects that naturally depend on each other.
+Bundler can't handle circular dependencies properly and currently the only workaround is to list all celluloid-ish dependencies in both Gemfile and gemspec.
+This is error-prone and not efficient. Thus it was required to put some better workaround in place.
+
+# Configuration
+The list of gems and their properties are now defined in `dependencies.yml`.
+
+For example:
+
+```yml
+celluloid:
+  bundler:
+    github: celluloid/celluloid
+    branch: 0.17.0-prerelease
+celluloid-extras:
+  bundler:
+    github: celluloid/celluloid-extras
+celluloid-supervision:
+  bundler:
+    github: celluloid/celluloid-supervision
+celluloid-pool:
+  bundler:
+    github: celluloid/celluloid-pool
+celluloid-fsm:
+  bundler:
+    github: celluloid/celluloid-fsm
+timers:
+  gemspec:
+     - ~> 4.0.0
+  bundler:
+    github: celluloid/timers
+```
+
+# Modification of `gemspec` and `Gemfile`
+
+The injection of dependencies into `gemspec` and `Gemfile` is handled by `Celluloid::Sync.gems()`, which routes to either `Celluloid::Gems.gemspec` or `Celluloid::Gems.gemfile` depending on what is passed to it:
+
+* Discussed in [SYNC.md](../SYNC.md#how-do-you-install-it-in-gemfile-and-gemspec-then)

data/culture/gems/dependencies.yml

@@ -0,0 +1,85 @@
+bundler:
+  dependency: development
+
+nenv:
+  dependency: development
+
+dotenv:
+  dependency: development
+
+benchmark_suite:
+  dependency: development
+
+rubocop:
+  dependency: development
+
+transpec:
+  dependency: development
+
+pry:
+  dependency: development
+
+rake:
+  dependency: development
+
+rspec:
+  dependency: development
+
+guard-rspec:
+  dependency: development
+
+rspec-retry:
+  dependency: development
+
+coveralls:
+  dependency: development
+  gemfile:
+    require: false
+
+celluloid:
+  dependency: core
+  version: ">= 0.17.2"
+  gemfile:
+    github: celluloid/celluloid
+    branch: master
+    submodules: true
+
+celluloid-essentials:
+  dependency: module
+  gemfile:
+    github: celluloid/celluloid-essentials
+    branch: master
+    submodules: true
+
+celluloid-supervision:
+  dependency: module
+  gemfile:
+    github: celluloid/celluloid-supervision
+    branch: master
+    submodules: true
+
+celluloid-pool:
+  dependency: module
+  gemfile:
+    github: celluloid/celluloid-pool
+    branch: master
+    submodules: true
+
+celluloid-fsm:
+  dependency: module
+  gemfile:
+    github: celluloid/celluloid-fsm
+    branch: master
+    submodules: true
+
+celluloid-extras:
+  dependency: module
+  gemfile:
+    github: celluloid/celluloid-extras
+    branch: master
+    submodules: true
+
+timers:
+  version: ">= 4.1.1"
+  gemfile:
+    github: celluloid/timers

data/culture/gems/loader.rb

@@ -0,0 +1,101 @@
+require "yaml"
+
+module Celluloid
+  module Sync
+    module Gemfile
+      class << self
+        def [](dsl)
+          dsl.source("https://rubygems.org")
+          dsl.gemspec # Runs gemspec, but also @sets gem_name.
+          Gems.gemfile(dsl)
+        end
+      end
+    end
+    module Gemspec
+      class << self
+        def [](gem)
+          Gems.gemspec(gem)
+        end
+      end
+    end
+  end
+  module Gems
+    extend self
+    @gem_name = nil
+
+    undef gems rescue nil
+    def gems
+      File.expand_path("../dependencies.yml", __FILE__)
+    end
+
+    unless @dependencies ||= nil
+      @dependencies = YAML.load_file(gems) if File.exist?(gems)
+    end
+
+    unless @dependencies.is_a?(Hash) && @dependencies.any?
+      fail "Celluloid cannot find its dependencies."
+    end
+
+    undef core? rescue nil
+    def core?(name=@gem_name)
+      return false unless @dependencies[name].is_a? Hash
+      @dependencies[name]["dependency"] == "core"
+    end
+
+    undef separate? rescue nil
+    def separate?
+      !@dependencies.keys.include?(@gem_name)
+    end
+
+    undef gemspec rescue nil
+    def gemspec(gem)
+      @gem_name = gem.name
+      loader do |name, spec|
+        # Rules for dependencies, to avoid so-called circular dependency:
+        # - Only the core gem lists all the modules as runtime dependencies.
+        # - If this gem is not in the dependencies list, then it needs the core gem at runtime;
+        #   the module gems are development dependencies only. This is a depending separate gem.
+        #   There is the core gem, module gems, true dependencies, and separately depending gems.
+        # - If the dependency is a module, it is only a development dependency to other modules,
+        #   and even the core gem is a development dependency. It is not expected to be used alone.
+        meth = case spec["dependency"]
+               when "core", "module"
+                 # For the core gem, all modules are runtime dependencies.
+                 # For separate gems, only the core gem is a runtime dependency.
+                 if core? || (separate? && core?(name))
+                   :add_runtime_dependency
+                 else
+                   :add_development_dependency
+                 end
+               when "development"
+                 :add_development_dependency
+               else
+                 :add_dependency
+               end
+        gem.send(meth, name, spec["version"] || ">= 0")
+      end
+    end
+
+    undef gemfile rescue nil
+    def gemfile(dsl)
+      loader do |name, spec|
+        params = [name, spec["version"] || ">= 0"]
+        req = spec["gemfile"] || {}
+        params << req.each_with_object({}) { |(k, v), o| o[k.to_sym] = v }
+        current = dsl.dependencies.find { |d| d.name == name }
+        dsl.dependencies.delete(current) if current
+        dsl.gem(*params)
+      end
+    end
+
+    private
+
+    def loader
+      @dependencies.each do |name, spec|
+        next if name == @gem_name
+        spec ||= {}
+        yield name, spec
+      end
+    end
+  end
+end

data/culture/rubocop/README.md

@@ -0,0 +1,38 @@
+# About
+[RuboCop](https://github.com/bbatsov/rubocop) is a ruby static code analyzer.
+It's more than just a lint. It verifies the code against ruby best practices and performs code correctness analysis.
+Celluloid culture doesn't always agree with all rubocop default policies and so we provide a rubocop configuration file that overrides its default behavior.
+
+# Integration
+
+[Integrate `celluloid/culture`](../README.md#integration), then include `culture/rupocop/.rubocop.yml` in your default rubocop config.
+
+##### Add celluloid/culture as GIT submodule:
+
+* See instructions: [Integrate the `celluloid/culture` sub-module](../README.md#integration)
+
+##### Include `culture/rupocop/rubocop.yml` in the `.rubocop.yml` in the root of your project:
+```yml
+inherit_from:
+  - culture/rubocop/rubocop.yml
+```
+
+# How to add rubocop to your project
+
+The `rubocop` gem is automatically included by `Celluloid::Sync.gems` when that is [implemented](../SYNC.md).
+
+##### Add a 'rubocop' target in your `Rakefile`
+
+# Hints
+It's possible to use rubocop for autocorrection of minor problems.
+
+Always verify these changes by running:
+
+```sh
+bundle exec rubocop
+```
+
+Once you are ready to auto-corret the issues you are shown, run it with the `-a` option:
+```sh
+bundle exec rubocop -a
+```

data/culture/rubocop/lint.yml

@@ -0,0 +1,8 @@
+Lint/HandleExceptions:
+  Enabled: false
+
+Lint/LiteralInCondition:
+  Enabled: false
+
+Lint/UnusedBlockArgument:
+  Enabled: false

data/culture/rubocop/metrics.yml

@@ -0,0 +1,15 @@
+Metrics/MethodLength:
+  CountComments: false
+  Max: 20
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/CyclomaticComplexity:
+  Max: 9
+
+Metrics/PerceivedComplexity:
+  Max: 9
+
+Metrics/AbcSize:
+  Max: 20

data/culture/rubocop/rubocop.yml

@@ -0,0 +1,5 @@
+inherit_from:
+    - lint.yml
+    - metrics.yml
+    - style.yml
+    - perf.yml

data/culture/rubocop/style.yml

@@ -0,0 +1,57 @@
+Style/Documentation:
+  Enabled: false
+
+Style/ModuleFunction:
+  Enabled: false
+
+Style/AndOr:
+  Enabled: true
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/EachWithObject:
+  Enabled: true
+
+Style/InfiniteLoop:
+  Enabled: false
+
+Style/SpaceAroundEqualsInParameterDefault:
+  Enabled: false
+
+Style/SpaceInsideBlockBraces:
+  Enabled: false
+
+Style/AccessModifierIndentation:
+  Enabled: false
+
+Style/TrailingComma:
+  Enabled: true
+  EnforcedStyleForMultiline: comma
+
+Style/SpaceInsideBlockBraces:
+  Enabled: true
+  EnforcedStyle: space
+
+Style/SpaceInsideHashLiteralBraces:
+  Enabled: true
+  EnforcedStyle: no_space
+
+Style/EmptyLinesAroundAccessModifier:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Style/GlobalVars:
+  Enabled: false
+
+Style/FormatString:
+  EnforcedStyle: percent
+
+Style/TrailingUnderscoreVariable:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false

data/culture/spec/gems_spec.rb

@@ -0,0 +1,2 @@
+Rspec.describe Celluloid::Gems do
+end

data/culture/spec/sync_spec.rb

@@ -0,0 +1,2 @@
+Rspec.describe Celluloid::Sync do
+end

data/culture/sync.rb

@@ -0,0 +1,56 @@
+require "forwardable"
+
+module Celluloid
+  module Sync
+    class << self
+      undef gem_path rescue nil
+      def gem_path
+        File.expand_path("../../", __FILE__)
+      end
+
+      undef gem_name rescue nil
+      def gem_name
+        Dir["#{File.expand_path('../../', __FILE__)}/*.gemspec"].first.gsub(".gemspec", "").split("/").last
+      end
+
+      undef gem_name? rescue nil
+      def gem_name?
+        !gem_name.nil?
+      end
+
+      undef lib_path rescue nil
+      def lib_path
+        File.expand_path("../../lib", __FILE__)
+      end
+
+      undef lib_gempath rescue nil
+      def lib_gempath
+        "#{lib_path}/#{gem_name.split('-').join('/')}"
+      end
+
+      undef scenario rescue nil
+      def scenario
+        File.basename($PROGRAM_NAME)
+      end
+
+      undef bundler? rescue nil
+      def bundler?
+        scenario == "bundle"
+      end
+    end
+
+    fail "Missing gemspec." unless gem_name?
+    $LOAD_PATH.push(gem_path)
+    $LOAD_PATH.push(lib_path)
+
+    # TODO: This will likely need to be done differently if INSIDE a cut gem.
+    if scenario == "bundle"
+      `cd #{gem_path}/culture; git pull origin master` if ARGV.first == "update"
+    end
+
+    require("#{gem_path}/culture/gems/loader")
+    if File.exist?(version = "#{lib_gempath}/version.rb")
+      require(version)
+    end
+  end
+end

data/culture/tasks/rspec.rake

@@ -0,0 +1,5 @@
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:rcov) do |task|
+  task.rcov = true
+end

data/culture/tasks/rubocop.rake

@@ -0,0 +1,2 @@
+require "rubocop/rake_task"
+RuboCop::RakeTask.new

data/examples/basic_usage.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.push File.expand_path("../../lib", __FILE__)
+require "celluloid/autostart"
+
+class Counter
+  # This is all you have to do to turn any Ruby class into one which creates
+  # Celluloid actors instead of normal objects
+  include Celluloid
+
+  # Now just define methods like you ordinarily would
+  attr_reader :count
+
+  def initialize
+    @count = 0
+  end
+
+  def increment(n = 1)
+    @count += n
+  end
+end
+
+# Create objects just like you normally would. 'actor' is now a proxy object
+# which talks to a Celluloid actor running in its own thread
+actor = Counter.new
+
+# The proxy obeys normal method invocation the way we'd expect. This prints 0
+p actor.count
+
+# This increments @count by 1 and prints 1
+p actor.increment
+
+# By using actor.async, you can make calls asynchronously. This immediately
+# requests execution of method by sending a message, and we have no idea
+# whether or not that request will actually complete because we don't wait
+# for a response. Async calls immediately return nil regardless of how long
+# the method takes to execute. Therefore, this will print nil.
+p actor.async.increment 41
+
+# In practice, the asynchronous call made above will increment the count before
+# we get here. However, do not rely on this behavior! Asynchronous methods are
+# inherently uncoordinated. If you need to coordinate asynchronous activities,
+# you will need to use futures or FSMs. See the corresponding examples for those.
+# Signals can also be used to coordinate asynchronous activities.
+#
+# The following line could possibly print either 1 or 42, depending on if the
+# asynchronous call above completed. In practice, it prints 42 on all Ruby
+# implementations because the asynchronous call above will always execute
+p actor.count

data/examples/futures.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.push File.expand_path("../../lib", __FILE__)
+require "celluloid/autostart"
+require "digest/sha2"
+
+class Hasher
+  include Celluloid
+
+  def initialize(secret)
+    @hash = Digest::SHA2.hexdigest(secret)
+  end
+
+  # Add some data into our hash. This demonstrates a non-trivial computation
+  # of the same sort as, say, calculating Fibonacci numbers. Since Celluloid
+  # uses several threads, doing something like this won't grind our entire
+  # application to a halt
+  def add(data, n = 100_000)
+    string = @hash + data
+    n.times { string = Digest::SHA2.hexdigest(string) }
+    @hash = string
+  end
+end
+
+# Create the hasher
+hasher = Hasher.new("super secret initialization data")
+
+# Ask the hasher to perform a complex computation. However, since we're using
+# a future, this doesn't block the current thread
+future = hasher.future.add("some data to be hashed")
+
+# We've kicked off the hasher, but this thread can continue performing other
+# activities while the hasher runs in the background
+puts "The hasher is now running, but this thread is free to do whatever it wants"
+
+# Now let's ask for the return value from the hasher
+puts "Getting the hasher's return value... "
+p future.value

data/examples/ring.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.push File.expand_path("../../lib", __FILE__)
+require "celluloid/autostart"
+
+class Ring
+  include Celluloid
+
+  class Node
+    include Celluloid
+
+    def initialize(link)
+      @link = link
+    end
+
+    def around(n)
+      @link.async.around n
+    end
+  end
+
+  def initialize(size)
+    @node = Node.new_link current_actor
+
+    size.times do
+      @node = Node.new_link @node
+    end
+  end
+
+  # Go around the ring the given number of times
+  def run(n)
+    fail ArgumentError, "I can't go around a negative number of times" if n < 0
+
+    async.around n
+    wait :done
+  end
+
+  # Go around the ring the given number of times
+  def around(n)
+    if n.zero?
+      signal :done
+    else
+      @node.async.around n - 1
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  require "benchmark"
+  SIZE  = 512
+  TIMES = 10
+
+  puts "*** Creating a #{SIZE} node ring..."
+  puts Benchmark.measure {
+    $ring = Ring.new(SIZE)
+  }
+
+  puts "*** Sending a message around #{TIMES} times"
+  puts Benchmark.measure {
+    $ring.run(TIMES)
+  }
+end

data/examples/simple_pmap.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.push File.expand_path("../../lib", __FILE__)
+require "celluloid/autostart"
+
+module Enumerable
+  # Simple parallel map using Celluloid::Futures
+  def pmap(&block)
+    futures = map { |elem| Celluloid::Future.new(elem, &block) }
+    futures.map(&:value)
+  end
+end
+
+p 100.times.pmap { |n| n * 2 }

data/examples/stack.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.push File.expand_path("../../lib", __FILE__)
+require "celluloid/autostart"
+
+# This example builds on basic_usage.rb to show two things about #async: the
+# (new) fluent API and the preservation of causality order.
+class Stack
+  include Celluloid
+
+  attr_reader :ary
+
+  def initialize
+    @ary = []
+  end
+
+  def push(x)
+    @ary.push x
+  end
+  alias_method :<<, :push
+
+  def pop
+    @ary.pop
+  end
+
+  def show
+    p @ary
+  end
+end
+
+st = Stack.new
+
+# Schedule three calls to #push some integers on the stack. They will execute
+# in order because the calls originated as a sequence of method calls in a
+# single thread.
+st.async << 1 << 2 << 3
+
+# Schedule a call to show the stack after the three push calls execute.
+st.async.show
+
+# Schedule three calls to #pop from the stack.
+st.async.pop.pop.pop
+
+# The next (non-async) call is guaranteed to execute after methods previously
+# scheduled in this thread. The causal order of calls (order as requested) is
+# preserved in the execution order.
+st.show