branch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7c72ad76f5d6090801c0cd8b5f6a5c6652390034
+  data.tar.gz: 58d91717c99e5bc49be2c78eb3928cede01b7687
+SHA512:
+  metadata.gz: ac7ed88f7af8615dd991413660823fdd3144b4aa310419583563b58e5194f6df7115f8a980dd62447f22f71e1d8f19e23c01e0845cd7b6e2437f8fdb24067aaf
+  data.tar.gz: db6744d098f641eed0d2d8cacad99b8d90799d532bd4f5a4bc9e20b85a833c90b014f308ce6c0cbffabb19f517a74eda532d35d5958cda1fa9a0f78d8937b2a3

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Branch Changelog
+
+## v0.1.0
+
+**February 11, 2014**
+
+* `new` Initial version

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+=====================
+
+Copyright (c) 2014 Andrey 'lolmaus' Mikhaylov
+
+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,126 @@
+Branch
+======
+
+**Run blocks asynchronously with little effort. A Ruby equivalent for JS `setTimeout`.**
+
+This tiny lib was written to slightly reduce the amount of scaffolding required to do threads in Ruby. It is aimed at simpler use cases, for more complicated scenarios using vanilla thread syntax is recommended.
+
+I hope Branch
 can save some frustration for people who discover that implementing a straightforward JS `setTimeout(function() { ... }, 0)` with Ruby is much more complicated and less intuitive. On the other hand, Branch is not an escape from getting to know how threads work.
+
+
+How it works
+------------
+
+1. First of all, wrap your code with the `Branch.new { ... }` wrapper.
+2. Within that wrapper, the `branch { ... }` method is available. It starts the passed block in a new asynchronous thread.
+3. The end of the `Branch.new { ... }` wrapper will wait for all the threads to finish. In other words, the end of wrapper synchonizes your code. If you start another `Branch.new { ... }` afterwards, it will start sequentially after the previous branch is complete.
+4. To start a thread with a delay, use `branch(2) { ... }`. This example will be executed after two seconds, without blocking the main thread.
+5. If you need to synchronize a certain operation in order to prevent a race condition (JS coders beware!), you can use a mutex like this:
+  
+  ```rb
+  branch do |mutexes|
+    mutexes[:meaningful_mutex_name].synchronize { ... }
+  end
+  ```
+
+6. You don't need to instantiate mutexes manually. To reuse a mutex in another thread, simply access the `mutexes` hash with the same key. You can use anything for keys, e. g. integers, but a meaningful symbol is recommended.
+7. Within a `branch`, you can use as many mutexes as you need.
+
+
+
+Example usage
+-------------
+
+Please look into these pieces of code to see how Branch usage compares to vanilla syntax
+
+
+### Simple example
+
+#### Vanilla threads
+
+Requires a fair amount of scaffolding:
+
+* A thread array is to be defined manually.
+* Each thread should be added to that array.
+* Threads should be joined so that the main script doesn't exit before all threads finish.
+
+```rb
+threads = []
+puts "Starting threads"
+threads << Thread.new { sleep 5; puts "Thread 1 finished." }
+threads << Thread.new { sleep 2; puts "Thread 2 finished." }
+threads << Thread.new { sleep 1; puts "Thread 3 finished." }
+puts "All threads started."
+threads.each { |t| t.join }
+puts "All threads complete."
+```
+
+
+#### Branch equivalent
+
+All the scaffolding you need is you need is a `Branch.new { }` wrapper.
+
+```ruby
+Branch.new do
+  puts "Starting threads"
+  branch { sleep 5; puts "Thread 1 finished." }
+  branch { sleep 2; puts "Thread 2 finished." }
+  branch { sleep 1; puts "Thread 3 finished." }
+  puts "All threads started."
+end
+puts "All threads complete."
+```
+
+
+
+
+### Thread synchronization with multiple mutexes
+
+All mutexes have to be instantiated manually.
+
+#### Vanilla threads
+
+```rb
+threads = []
+
+mutex_array_access         = Mutex.new
+mutex_database_transaction = Mutex.new
+mutex_coffee_brewing       = Mutex.new
+
+10.times do
+  threads << Thread.new do
+    
+    # Imitating a time-consuming operation
+    sleep rand(1..5)
+    
+    mutex_array_access        .synchronize { shared_array << 'foo' if shared_array.length < 5 }
+    mutex_database_transaction.synchronize { DB::send('foo', 888) { |foo| foo.bar }}
+    mutex_coffee_brewing      .synchronize { coffee_machine.clean.fill('water').make_coffee }
+     
+  end
+end
+
+threads.each { |t| t.join }
+```
+
+
+#### Branch equivalent
+
+Mutexes are instantiated automatically when they're first used and will persist throughuout the `Branch.new{ }` wrapper.
+
+```ruby
+Branch.new do
+  10.times do
+    branch do |mutexes|
+      
+      # Imitating a time-consuming operation
+      sleep rand(1..5)
+    
+      mutexes[:array_access]        .synchronize { shared_array << 'foo' if shared_array.length < 5 }
+      mutexes[:database_transaction].synchronize { DB::send('foo', 888) { |foo| foo.bar }}
+      mutexes[:coffee_brewing]      .synchronize { coffee_machine.clean.fill('water').make_coffee }
+      
+    end
+  end
+end
+```

data/lib/branch.rb

@@ -0,0 +1,33 @@
+class Branch
+
+  VERSION = "0.1.0"
+  DATE = "2014-07-31"
+  
+  def initialize(&block)
+    @threads = []
+    @mutexes = Hash.new { |hash, key| hash[key] = Mutex.new }
+    
+    # Executing the passed block within the context
+    # of this class' instance.
+    instance_eval &block if block_given?
+    
+    # Waiting for all threads to finish
+    @threads.each { |thr| thr.join }
+  end
+  
+  # This method will be available within a block
+  # passed to `Branch.new`.
+  def branch(delay = false, &block)
+    
+    # Starting a new thread 
+    @threads << Thread.new do
+    
+      # Implementing the timeout functionality
+      sleep delay if delay.is_a? Numeric
+      
+      # Executing the block passed to `branch`,
+      # providing mutexes into the block.
+      block.call @mutexes
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: branch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- lolmaus (Andrey Mikhaylov)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-31 00:00:00.000000000 Z
+dependencies: []
+description: Run blocks asynchronously with little effort, a Ruby equivalent for JS
+  setTimeout
+email:
+- lolmaus@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/branch.rb
+homepage: https://github.com/lolmaus/branch
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: This gem tries to reduce the amount of scaffolding required to be built manually
+  in order to fire a couple of threads.
+test_files: []