trenza 0.1.0

data/README.md

@@ -0,0 +1,70 @@
+# Trenza
+
+Trenza is the spanish word for *braid* or *plait*.
+
+> plait |plāt, plat| (noun) a single length of hair or other flexible material made up of three or more interlaced strands.
+
+![Trenza](http://dl.dropbox.com/u/521377/trenza_cinco.jpg)
+
+Trenza is also an experiment in dynamic programming inspired by the reading of Paolo Perrotta's *“Metaprogramming Ruby”* (an awesome book, by the way), and in evaluation models and strategies, inspired in my late adventures with Erlang and Haskell.
+
+Trenza provides two methods to every Ruby object: `lazy` and `parallel`. Those two methods return an object that behaves exactly the same way the old one, except that, instead or evaluating its methods right away when they're called, they do it in a *lazy* or *parallel* way.
+
+## *Lazy* objects
+
+*Lazy* objects defer the actual evaluation of its methods until the moment its really needed:
+
+    class Wadus
+      def calculate
+        # whatever
+      end
+    end
+    
+    wadus1 = Wadus.new.lazy
+    wadus2 = Wadus.new.lazy
+    
+    x = wadus1.calculate
+    y = wadus2.calculate
+    # no calculation is actually done
+    
+    puts x # now wadus1.calculate is run in order to print it
+           # wadus2.calculate never gets run since its not needed
+
+## *Parallel* objects
+
+*Parallel* objects are similar to *lazy* objects, but instead of deferring the whole evaluation of the method, they start it in the background and follow with your program. Whenever the actual return value is needed, then and only then will your program for the calculation to end (in case it hadn't ended already). This way your programs can become massively parallel without changing your programming style at all:
+
+    class Wadus
+      def calculate
+        # whatever
+      end
+    end
+
+    wadus1 = Wadus.new.parallel
+    wadus2 = Wadus.new.parallel
+
+    x = wadus1.calculate # calculation is started in the background, your program continues
+    y = wadus2.calculate # calculation is started in the background, your program continues
+
+    ...
+    
+    puts x + y # in case they hadn't finished already, now your program will wait for the
+               # calculations to finished, since the return values are needed
+
+Please note that Trenza uses the underlying Ruby's `Thread` class implementation, so the actual kind of parallelism achieved depends greatly on the Ruby implementation you're using. Check Ruby 1.8, Ruby 1.9 and JRuby documentation for further details.
+
+## Use cases
+
+Trenza is an experiment and might not have any practical uses apart from that. But if you find one, let me know!
+
+As for me, scripts with lots of I/O waiting (such as scripts that download files) seem a natural fit for `parallel` (see `examples/download.rb` for an example).
+
+## Usage
+
+Nothing special: install the gem, require it, call `lazy` or `parallel` when initializing your objects.
+
+## License
+
+Copyright © Sergio Gil, 2012
+
+Licensed under the [MIT license](http://porras.mit-license.org/).

data/examples/downloads.rb

@@ -0,0 +1,22 @@
+require 'open-uri'
+require 'trenza'
+
+
+class Download
+  def initialize(url)
+    @url = url
+  end
+  
+  def size
+    open(@url).read.size
+  end
+end
+
+urls = [
+  'http://google.es',
+  'http://amazon.es',
+  'http://bebanjo.com'
+]
+
+puts urls.map { |url| Download.new(url).parallel.size }.reduce(:+)
+

data/examples/slow_calculator.rb

@@ -0,0 +1,29 @@
+require 'trenza'
+require 'benchmark'
+
+class Calculator
+  def add(a, b)
+    result = a + b
+    sleep 0.01 * result
+    result
+  end
+end
+
+def try(calc)
+  z = calc.add(10, 10)
+  a = calc.add(5, 7)
+  b = calc.add(3, 4)
+  c = calc.add(1, 2)
+  d = calc.add(3, 5)
+  f = calc.add(c, d)
+  e = calc.add(a, b)
+  g = calc.add(e, f)
+  g.to_s
+end
+
+
+Benchmark.bm(10) do |bm|
+  bm.report("Regular")  { try Calculator.new          }
+  bm.report("Lazy")     { try Calculator.new.lazy     }
+  bm.report("Parallel") { try Calculator.new.parallel }
+end

data/lib/trenza/blank_slate.rb

@@ -0,0 +1,7 @@
+module Trenza
+  module BlankSlate
+    def self.included(base)
+      base.send(:instance_methods).each { |m| base.send(:undef_method, m) unless m.to_s =~ /^__/ || m.to_s == 'object_id'}
+    end
+  end
+end

data/lib/trenza/lazy.rb

@@ -0,0 +1,31 @@
+module Trenza
+  class Lazy
+    include BlankSlate
+  
+    def initialize(object)
+      @object = object
+    end
+
+    def method_missing(meth, *args, &blk)
+      MethodCall.new do
+        @object.send meth, *args, &blk
+      end
+    end
+
+    class MethodCall
+      include BlankSlate
+    
+      def initialize(&block)
+        @block = block
+      end
+    
+      def method_missing(meth, *args, &blk)
+        value.send meth, *args, &blk
+      end
+    
+      def value
+        @value ||= @block.call
+      end
+    end
+  end
+end

data/lib/trenza/parallel.rb

@@ -0,0 +1,27 @@
+module Trenza
+  class Parallel
+    include BlankSlate
+    
+    def initialize(object)
+      @object = object
+    end
+
+    def method_missing(meth, *args, &blk)
+      MethodCall.new do
+        @object.send meth, *args, &blk
+      end
+    end
+
+    class MethodCall
+      include BlankSlate
+    
+      def initialize(&block)
+        @thread = Thread.new(&block)
+      end
+    
+      def method_missing(meth, *args, &blk)
+        @thread.value.send(meth, *args, &blk)
+      end
+    end
+  end
+end

data/lib/trenza/proxy_builders.rb

@@ -0,0 +1,13 @@
+module Trenza
+  module ProxyBuilder
+    def parallel
+      Parallel.new(self)
+    end
+    
+    def lazy
+      Lazy.new(self)
+    end
+  end
+end
+
+include Trenza::ProxyBuilder

data/lib/trenza.rb

@@ -0,0 +1,4 @@
+require 'trenza/blank_slate'
+require 'trenza/lazy'
+require 'trenza/parallel'
+require 'trenza/proxy_builders'

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: trenza
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Sergio Gil
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-09 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: sgilperez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/trenza/blank_slate.rb
+- lib/trenza/lazy.rb
+- lib/trenza/parallel.rb
+- lib/trenza/proxy_builders.rb
+- lib/trenza.rb
+- examples/downloads.rb
+- examples/slow_calculator.rb
+homepage: http://github.com/porras/trenza
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Adds parallelism to any object in a transparent way
+test_files: []