myna_eventmachine 1.0.0 → 1.1.0

data/README.md

@@ -1,16 +1,50 @@
 # Myna Ruby/EventMachine Client
 
-This is a Ruby client for the v1 Myna API, using EventMachine for asychronous goodness.
+This is a Ruby client for the v1 [Myna](http://mynaweb.com) API, using EventMachine for asychronous goodness. Tested in Ruby 1.9.2
 
-Tested in Ruby 1.9.2
+## Installation
+
+`gem install myna_eventmachine`
+
+## Usage
+
+You can get a suggestion from Myna without authorizing:
+
+```ruby
+expt = Myna.experiment('45923780-80ed-47c6-aa46-15e2ae7a0e8c')
+suggestion = expt.suggest.get
+# suggestion has two attributes: choice and token
+# suggestion.choice is a string, the choice made by Myna
+# suggestion.token is a string, the token you send back to Myna when you reward
+puts("Choice is #{suggestion.choice}")
+expt.reward(suggestion.token, 1.0)
+```
+
+To create an experiment, add and delete variants, and so on, you must authorize first:
+
+```ruby
+myna = Myna.authorize('email', 'password')
+# Create an experiment
+expt = myna.create('My funky new experiment').get
+expt.create_variant('My new variant')
+expt.create_variant('My other new variant')
+```
+
+For more detail, see [the wiki](https://github.com/myna/ruby-eventmachine-client/wiki)
 
 ## Development Notes
 
 The easiest way to install the dependencies is to install [Bundler](http://gembundler.com/) and then run `bundle install`
 
-Run `rake test` to run the tests.
+Rake commands:
+
+- `test` to run the tests.
+- `build` to build a Gem
+- `install` to install the Gem locally
+- `release` to push the Gem to RubyGems
 
 
 ## TODO
 
-Futures need to handle failures, and need to rigourously trap exceptions and propagate them
+- Futures need to handle failures, and need to rigourously trap exceptions and propagate them.
+- Some RDoc or equivalent might be useful

data/lib/myna/future.rb

@@ -26,45 +26,83 @@ require 'thread'
 
 
 module Future
+
+  def Future.run
+    future = Future.new
+    future.run(yield)
+    future
+  end
+
   class Future
     def initialize()
       @lock = Mutex.new
       @signal = ConditionVariable.new
       @value = nil
-      @delivered = false
+      @result = false # false, :success, or :failure
       @listeners = []
     end
 
-    def deliver(value)
+    def set(value, result)
       @lock.synchronize {
-        if @delivered
-          raise ArgumentError, "This future has already been delivered a value"
+        if @result
+          raise ArgumentError, "This future has already been completed with a value"
         else
           @value = value
-          @delivered = true
+          @result = result
           @signal.broadcast
         end
       }
-      @listeners.each do |block|
-        block.call(value)
+
+      if result == :success
+        @listeners.each do |block|
+          block.call(value)
+        end
+      end
+    end
+
+    def succeed(value)
+      self.set(value, :success)
+    end
+
+    def fail(value)
+      self.set(value, :failure)
+    end
+
+    def run
+      begin
+        self.succeed(yield)
+      rescue => exn
+        self.fail(exn)
       end
     end
 
     def get
+      def handle_value
+        case @result
+        when :success
+          @value
+        when :failure
+          raise @value
+        else
+          raise ArgumentError, "Attempted to handle_value when result #{@result} is not :success or :failure"
+        end
+      end
+
       @lock.synchronize {
-        if !@delivered
+        if @result
+          handle_value
+        else
           @signal.wait(@lock)
           @signal.broadcast
+          handle_value
         end
-
-        @value
       }
     end
 
     def on_complete(&block)
       return_value = false
       @lock.synchronize {
-        if @delivered
+        if @result == :success
           return_value = true
         else
           @listeners.push(block)
@@ -82,7 +120,9 @@ module Future
     def map(&block)
       future = Future.new
       self.on_complete do |value|
-        future.deliver(block.call(value))
+        future.run do
+          block.call(value)
+        end
       end
       future
     end

data/lib/myna/myna.rb

@@ -35,14 +35,14 @@ module Myna
     future = Future::Future.new
 
     if EventMachine::reactor_running?
-      future.deliver(true)
+      future.succeed(true)
     else
       Thread.new do
         EventMachine::run {}
       end
 
       EventMachine::next_tick do
-        future.deliver(true)
+        future.succeed(true)
       end
     end
 
@@ -78,8 +78,8 @@ module Myna
         client = EventMachine::HttpRequest.new(uri)
 
         http = yield(client)
-        http.errback  { future.deliver(Response::NetworkError.new) }
-        http.callback { future.deliver(Response.parse(http.response)) }
+        http.errback  { future.succeed(Response::NetworkError.new) }
+        http.callback { future.succeed(Response.parse(http.response)) }
       end
 
       future
@@ -118,6 +118,10 @@ module Myna
     end
   end
 
+  def Myna.experiment(uuid)
+    Myna::Experiment.new(uuid)
+  end
+
   # The simple API for unauthorized access
   class Experiment
     def initialize(uuid, host = UnauthorizedHost)
@@ -143,11 +147,11 @@ module Myna
   end
 
   def Myna.authorize(email, password, host = AuthorizedHost)
-    ExperimentFactory.new(email, password, host)
+    AuthorizedMyna.new(email, password, host)
   end
 
   # The more complex API for authorized access
-  class ExperimentFactory
+  class AuthorizedMyna
     def initialize(email, password, host = AuthorizedHost)
       @email    = email
       @password = password

data/lib/myna/version.rb

@@ -0,0 +1,27 @@
+# Copyright 2011 by Untyped Ltd. All Rights Reserved\
+#
+# 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.
+#
+# No portion of this Software shall be used in any application which does not
+# use the ReportGrid platform to provide some subset of its functionality.
+#
+# 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.
+#
+
+module Myna
+  VERSION = "1.1.0"
+end

data/lib/myna.rb

@@ -0,0 +1,26 @@
+# Copyright 2011 by Untyped Ltd. All Rights Reserved\
+#
+# 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.
+#
+# No portion of this Software shall be used in any application which does not
+# use the ReportGrid platform to provide some subset of its functionality.
+#
+# 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.
+#
+
+require 'myna/myna'
+require 'myna/response'

data/test/test_future.rb

@@ -33,7 +33,7 @@ describe Future do
         v + 3
       end
 
-      f1.deliver(1)
+      f1.succeed(1)
       f2.get.must_equal 4
     end
 
@@ -45,10 +45,18 @@ describe Future do
 
       Thread.new do
         sleep(1)
-        f1.deliver(1)
+        f1.succeed(1)
       end
 
       f2.get.must_equal 4
     end
   end
+
+  describe "Future.fail" do
+    it "must cause an exception to be raised on get" do
+      # Not implemented
+      # Also test Future.run and future.run
+      true.must_equal false
+    end
+  end
 end

data/test/test_suggest.rb

@@ -36,13 +36,13 @@ describe Myna do
 
   describe "suggest" do
     it "must return a suggestion for a valid experiment" do
-      expt = Myna::Experiment.new('45923780-80ed-47c6-aa46-15e2ae7a0e8c')
+      expt = Myna.experiment('45923780-80ed-47c6-aa46-15e2ae7a0e8c')
       ans = expt.suggest
       ans.get.must_be_kind_of Response::Suggestion
     end
 
     it "must return an error for an invalid experiment" do
-      expt = Myna::Experiment.new('bogus')
+      expt = Myna.experiment('bogus')
       ans = expt.suggest
       ans.get.must_be_kind_of Response::ApiError
     end
@@ -50,7 +50,7 @@ describe Myna do
 
   describe "reward" do
     it "must succeed when given correct token and amount" do
-      expt = Myna::Experiment.new('45923780-80ed-47c6-aa46-15e2ae7a0e8c')
+      expt = Myna.experiment('45923780-80ed-47c6-aa46-15e2ae7a0e8c')
       suggestion = expt.suggest.get
 
       ans = expt.reward(suggestion.token, 0.5)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: myna_eventmachine
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -22,9 +22,11 @@ files:
 - Gemfile.lock
 - README.md
 - Rakefile
+- lib/myna.rb
 - lib/myna/future.rb
 - lib/myna/myna.rb
 - lib/myna/response.rb
+- lib/myna/version.rb
 - myna_eventmachine.gemspec
 - test/test_authorized.rb
 - test/test_future.rb