going 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e654db8fb9029e5b32303e284551f9182960c418
-  data.tar.gz: 62605bb00f54efe7dc250850f1341f10991cecb5
+  metadata.gz: 0d24f3e696f0f5be0f6cd9fb1267f32f9f5ed2df
+  data.tar.gz: 2504de315ea4e0db31e5772152a495a870fadb34
 SHA512:
-  metadata.gz: ed12b04c91fd266ef44da9ef91b36f62b117d7cb869d3a8af21f831e6dfee4cc2c361aaa6e768d90f264e1cc2c97f3ae256a3445c19a3313d90966384fa16918
-  data.tar.gz: d8a8b37ecc0f747f322ca779e08d59e8683dd62c11f873862ba80d7211de40f9667acfef1310b4206dd20ed1fda8ec5cbf096ac59e4c7ce9ea0f96cce60876c8
+  metadata.gz: 11e3bd89f64c0bbf2312bb1cbc80ee31145f2619b50f934e0fbcee30147dcdbd8b70d70e163bcf4e906e5a70bda53bc504795b43d86def996e54effc1cbd5c3c
+  data.tar.gz: 6c1f571f54a90a484be36d8d03936de988b836a4b9d18f3aca081dbb9f40a38e33784173f3e00ef9f234bd82ca4b08c561e7893ef7cddec34e49f1357567d460

data/Gemfile

@@ -1,4 +1,6 @@
 source 'https://rubygems.org'
 
+gem 'pry-byebug'
+
 # Specify your gem's dependencies in going.gemspec
 gemspec

data/README.md

@@ -1,6 +1,6 @@
 # Going [![Build Status](https://travis-ci.org/jridgewell/Going.svg)](https://travis-ci.org/jridgewell/Going)
 
-Go for Ruby
+A Ruby implementation of Go Channels.
 
 ## Installation
 
@@ -20,7 +20,260 @@ Or install it yourself as:
 
 ## Usage
 
-Brings Go's Channel and Goroutines to Ruby.
+Wording stolen from the [Go Language
+Specification](https://golang.org/ref/spec) and [Effective Go
+Document](https://golang.org/doc/effective_go.html), and converted over
+into the equivalent Ruby code.
+
+### Channels
+
+Unbuffered channels combine communication — the exchange of a value —
+with synchronization — guaranteeing that two calculations ("goroutines",
+or threads) are in a known state.
+
+There are lots of nice idioms using channels. Here's one to get us
+started. A channel can allow the launching goroutine to wait for the
+sort to complete.
+
+```ruby
+list = [3, 2, 1]
+c = Going::Channel.new  # Allocate a channel.
+
+# Start the sort in a goroutine; when it completes, signal on the channel.
+Going.go do
+    list.sort!
+    c.push 1  # Send a signal; value does not matter.
+end
+
+# doSomethingForAWhile
+c.receive   # Wait for sort to finish; discard sent value.
+```
+
+Receivers always block until there is data to receive. If the channel is
+unbuffered, the sender blocks until the receiver has received the value.
+If the channel has a buffer, the sender blocks only until the value has
+been copied to the buffer; if the buffer is full, this means waiting
+until some receiver has retrieved a value.
+
+A buffered channel can be used like a semaphore, for instance to limit
+throughput. In this example, incoming requests are passed to `handle`,
+which sends a value into the channel, processes the request, and then
+receives a value from the channel to ready the "semaphore" for the next
+consumer. The capacity of the channel buffer limits the number of
+simultaneous calls to process.
+
+```ruby
+sem = Going::Channel.new(MaxOutstanding)
+
+def handle(request)
+    sem.push 1    # Wait for active queue to drain.
+    process r     # May take a long time.
+    sem.receive   # Done; enable next request to run.
+end
+
+def serve(request_queue)
+    request_queue.each do |req|
+        Going.go do
+            handle req  # Don't wait for handle to finish.
+        end
+    end
+end
+```
+
+Once `MaxOutstanding` handlers are executing `process`, any more will
+block trying to send into the filled channel buffer, until one of the
+existing handlers finishes and receives from the buffer.
+
+This design has a problem, though: `serve` creates a new goroutine for
+every incoming request, even though only `MaxOutstanding` of them can
+run at any moment. As a result, the program can consume unlimited
+resources if the requests come in too fast. We can address that
+deficiency by changing `serve` to gate the creation of the goroutines.
+Here's an obvious solution.
+
+```ruby
+def serve(request_queue) {
+    request_queue.each do |req|
+        sem.push 1
+        Going.go do
+            process req
+            sem.receive
+        end
+    end
+end
+```
+
+Going back to the general problem of writing the server, another
+approach that manages resources well is to start a fixed number of
+`handle` goroutines all reading from the request channel. The number of
+goroutines limits the number of simultaneous calls to process. This
+`serve` function also accepts a channel on which it will be told to
+exit; after launching the goroutines it blocks receiving from that
+channel.
+
+```ruby
+def handle(request_queue)
+    request_queue.each do |req|
+        process req
+    end
+end
+
+def serve(request_queue, quit) {
+    # Start handlers
+    MaxOutstanding.times do
+        Going.go do
+            handle request_queue
+        end
+    end
+    quit.receive  # Wait to be told to exit.
+end
+```
+
+### Close
+
+For a channel `ch`, the method `ch.close` records that no more values
+will be sent on the channel. Sending to a closed channel causes an
+exception to be thrown. After calling `#close`, and after any previously
+sent values have been received, receive operations will throw the
+`:close` symbol.
+
+```ruby
+ch = Going::Channel.new 2
+
+# Push an initial value into the buffered channel
+ch.push 1
+
+# Close the channel, preventing any futher message
+ch.close
+
+begin
+    ch.push 2
+rescue
+    # Sending to a closed channel causes an exception
+end
+
+# You may receive already sent values
+ch.receive # => 1
+
+# Closed channels throw when there are no more messages
+catch :close do
+    ch.receive
+end
+```
+
+### Size
+
+For a channel `ch`, the method `ch.size` returns the number of completed
+send operations on the channel. For an unbuffered channel, that number
+is always 0.
+
+```ruby
+unbuffered_channel = Going::Channel.new
+unbuffered_channel.size # => 0
+
+Going.go do
+    unbuffered_channel.push 'message'
+end
+# after the goroutine has blocked on send
+unbuffered_channel.size # => 0
+
+
+buffered_channel = Going::Channel.new 2
+buffered_channel.size # => 0
+
+buffered_channel.push 'message'
+buffered_channel.size # => 1
+
+buffered_channel.push 'message'
+buffered_channel.size # => 2
+
+buffered_channel.receive
+buffered_channel.size # => 1
+```
+
+### Capacity
+
+For a channel `ch`, the method `ch.capacity` returns the buffer size of
+the channel. For an unbuffered channel, that number is 0.
+
+```ruby
+unbuffered_channel = Going::Channel.new
+unbuffered_channel.capacity # => 0
+
+
+buffered_channel = Going::Channel.new 2
+buffered_channel.capacity # => 2
+
+buffered_channel.push 'message'
+buffered_channel.capacity # => 2
+```
+
+### Select Statements
+
+A "select" statement chooses which of a set of possible send or receive
+operations will proceed. It acts similar to a "case" statement but
+with the cases all referring to communication operations.
+
+Execution of a "select" statement proceeds in several steps:
+
+1. For all the cases in the statement, the channel operands of receive
+   operations and the channel and right-hand-side expressions of send
+   statements are evaluated exactly once, in source order, upon entering
+   the "select" statement. The result is a set of channels to receive
+   from or send to, and the corresponding values to send. Any side
+   effects in that evaluation will occur irrespective of which (if any)
+   communication operation is selected to proceed. Expressions on the
+   left-hand side of a receive statement with a variable assignment are
+   not evaluated.
+
+2. If one or more of the communications can proceed, a single one that
+   can proceed is chosen in source order.  Otherwise, if there is a
+   default case, that case is chosen. If there is no default case, the
+   "select" statement blocks until at least one of the communications
+   can proceed.
+
+3. Unless the selected case is the default case, the respective
+   communication operation is executed.
+
+4. If the selected case is a receive statement with a variable
+   assignment, the corresponding block is executed with the received
+   message as the first parameter. A second, optional, hash is
+   also passed, with a single key `ok`. `ok` will equal `true` if the
+   channel is not closed, or `false` if the channel is closed.
+
+5. If the selected case is a send statement, the corresponding block is
+   executed.
+
+```ruby
+Going.select do
+  channel.receive { |msg|
+    # do something with `msg`.
+  }
+
+  channel2.push(1) {
+    # do something after pushing
+  }
+
+  channel3.receive { |msg, ok: true|
+    if ok
+      # do something with msg
+    else
+      # channel3 was closed, msg is `nil`
+    end
+  }
+
+  timeout(5) {
+    # 5 second passed and no channel operations succeeded.
+  }
+
+  default {
+    # An immediately executing block, if nothing has succeeded yet
+  }
+end
+```
+
+
+## Obligatory Sieve of Eratosthenes Example
 
 ```ruby
 require 'going'

data/lib/going.rb

@@ -27,8 +27,13 @@ module Going
   #
   def self.select(&blk)
     fail 'a block must be passed' unless block_given?
+
     select = SelectStatement.new_instance
     select.select(&blk)
     SelectStatement.reset
+
+    select.call_completion_block
+
+    nil
   end
 end

data/lib/going/channel.rb

@@ -124,6 +124,22 @@ module Going
       size == 0
     end
 
+    #
+    # Calls the given block once for each message until the channel is closed,
+    # passing that message as a parameter.
+    #
+    # Note that this is a destructive action, since each message is `shift`ed.
+    #
+    def each
+      return enum_for(:each) unless block_given?
+
+      catch :close do
+        loop do
+          yield self.shift
+        end
+      end
+    end
+
     def inspect
       inspection = [:capacity, :size].map do |attr|
         "#{attr}: #{send(attr).inspect}"

data/lib/going/select_helper.rb

@@ -21,7 +21,7 @@ module Going
       Channel.new do |ch|
         Going.go do
           sleep seconds
-          ch.receive
+          ch.shift
         end
         ch.push(nil, &blk)
       end

data/lib/going/select_statement.rb

@@ -52,7 +52,6 @@ module Going
 
       wait
       cleanup
-      call_completion_block
     end
 
     def when_complete(*args, &callback)
@@ -88,6 +87,10 @@ module Going
       end
     end
 
+    def call_completion_block
+      on_complete.call(*args) if on_complete
+    end
+
     private
 
     attr_reader :semaphore, :once_mutex, :complete_mutex, :when_completes
@@ -113,9 +116,5 @@ module Going
     def cleanup
       when_completes.each(&:call)
     end
-
-    def call_completion_block
-      on_complete.call(*args) if on_complete
-    end
   end
 end

data/lib/going/version.rb

@@ -1,3 +1,3 @@
 module Going
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/going/channel_spec.rb

@@ -285,4 +285,26 @@ describe Going::Channel do
       end
     end
   end
+
+  describe '#each' do
+    it 'yields for each message until channel is closed' do
+      Going.go do
+        10.times do |i|
+          channel.push i
+        end
+        channel.close
+      end
+
+      i = 0
+      channel.each do |message|
+        expect(message).to eq(i)
+        i += 1
+      end
+      expect(i).to eq(10)
+    end
+
+    it 'returns an enumerator if no block is given' do
+      expect(channel.each).to be_an Enumerator
+    end
+  end
 end

data/spec/going/select_statement_spec.rb

@@ -102,6 +102,14 @@ describe Going::SelectStatement do
       expect(buffered_channel.size).to eq(0)
     end
 
+    it 'calls succeeding block after the select_statement has been evaluated' do
+      Going.select do |s|
+        s.default do
+          expect(Going::SelectStatement.instance).to be_nil
+        end
+      end
+    end
+
     context 'buffered channels' do
       it 'succeeds when blocked push is now under capacity' do
         buffered_channel.push 1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: going
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Justin Ridgewell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-28 00:00:00.000000000 Z
+date: 2014-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler