future-resource 0.0.2 → 1.0.0

data/.gitignore

@@ -2,3 +2,7 @@
 .bundle
 Gemfile.lock
 pkg/*
+tmp/*
+*.swp
+doc/*
+spec/reports

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--colour
+--tty

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-19mode # currently in active development, may or may not work for your project
+  - ruby-head
+notifications:
+  irc: "irc.freenode.org#adhearsion"

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# develop
+
+# 1.0.0 - 2012-03-13
+  * Feature: Better testing and documentation
+
 # 0.0.2
   * Feature: FutureResource#resource now takes an optional argument of the number of seconds to wait before timing out. On timeout, a Timeout::Error will be raised.
 

data/Gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source :rubygems
 
 # Specify your gem's dependencies in future-resource.gemspec
 gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :version => 2, :cli => '--format documentation' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec/" }
+end

data/Rakefile

@@ -1 +1,22 @@
 require 'bundler/gem_tasks'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'ci/reporter/rake/rspec'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rspec_opts = '--color'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  spec.rspec_opts = '--color'
+end
+
+task :default => :spec
+task :ci => ['ci:setup:rspec', :spec]
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/future-resource.gemspec

@@ -17,4 +17,11 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+
+  s.add_development_dependency 'bundler', [">= 1.0.0"]
+  s.add_development_dependency 'rspec', [">= 2.5.0"]
+  s.add_development_dependency 'ci_reporter', [">= 1.6.3"]
+  s.add_development_dependency 'yard', [">= 0.7.0"]
+  s.add_development_dependency 'rake', [">= 0"]
+  s.add_development_dependency 'guard-rspec'
 end

data/lib/future-resource/version.rb

@@ -1,3 +1,3 @@
 class FutureResource
-  VERSION = "0.0.2"
+  VERSION = "1.0.0"
 end

data/lib/future-resource.rb

@@ -2,16 +2,51 @@ require "thread"
 require "monitor"
 require "timeout"
 
+##
+# future-resource allows you to wait on a final value being set for a placeholder, which may occur asynchronously.
+#
+# @author Ben Langfeld
+# @author Jay Phillips
+#
+# @example false printed first, followed by a delay before :foo is printed
+#   fr = FutureResource.new
+#
+#   Thread.new do
+#     sleep 10
+#     fr.resource = :foo
+#   end
+#
+#   p fr.set_yet?
+#   p fr.resource
+#
 class FutureResource
+  ##
+  # Create a new FutureResource.
+  #
   def initialize
     @resource_lock          = Monitor.new
     @resource_value_blocker = @resource_lock.new_cond
   end
-
+  
+  ##
+  # Checks if the value of the resource placeholder has been set yet.
+  #
+  # @return [Boolean]
+  #
   def set_yet?
     !!@resource_lock.synchronize { defined? @resource }
   end
 
+  ##
+  # Returns the value of a specific resource, optionally waiting for `timeout` seconds before raising a Timeout::Error exception.
+  # When called on a not set resource without a timeout, raises a deadlock.
+  #
+  # @param [Integer] timeout number of seconds to wait for the resource to become ready
+  #
+  # @raise [Timeout::Error] if timeout expires and resource is not ready
+  #
+  # @return [Object]
+  #
   def resource(timeout = nil)
     Timeout::timeout timeout do
       @resource_lock.synchronize do
@@ -20,7 +55,14 @@ class FutureResource
       end
     end
   end
-
+  
+  ##
+  # Sets the value for the resource, making it available for all waiting and following reads.
+  # Resourcs values can only be set once.
+  #
+  # @param [Object] resource any value to be set for the resource
+  #
+  # @raise [FutureResource::ResourceAlreadySet] if resource is already set
   def resource=(resource)
     @resource_lock.synchronize do
       raise ResourceAlreadySetException if defined? @resource
@@ -30,6 +72,9 @@ class FutureResource
     end
   end
 
+  ##
+  # Raised when the program tries to set a value for the resource that is already set.
+  #
   class ResourceAlreadySetException < StandardError
     def initialize
       super "Cannot set this resource twice!"

data/spec/future-resource_spec.rb

@@ -0,0 +1,33 @@
+require 'future-resource'
+
+describe FutureResource do
+  it { should be_instance_of FutureResource }
+
+  it { should_not be_set_yet }
+
+  it "should set resource" do
+    subject.resource = :foo
+  end
+
+  describe "with a resource set" do
+    before { subject.resource = :foo }
+
+    it { should be_set_yet }
+
+    its(:resource) { should === :foo }
+
+    it "should raise ResourceAlreadySetException when setting value that is already set" do
+      expect {
+        subject.resource = :bar
+      }.to raise_error FutureResource::ResourceAlreadySetException
+    end
+  end
+
+  it "should receive the resource value from another thread" do
+    Thread.new do
+      sleep 1
+      subject.resource = :foo
+    end
+    subject.resource.should === :foo
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: future-resource
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,9 +10,74 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-08-17 00:00:00.000000000 +01:00
-default_executable: 
-dependencies: []
+date: 2012-03-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &2164502240 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *2164502240
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2164501200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: *2164501200
+- !ruby/object:Gem::Dependency
+  name: ci_reporter
+  requirement: &2164500260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.3
+  type: :development
+  prerelease: false
+  version_requirements: *2164500260
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &2164499560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :development
+  prerelease: false
+  version_requirements: *2164499560
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2164499040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2164499040
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: &2164514760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2164514760
 description: Sometimes a value is set asynchronously and you need to wait until it
   appears. Easy!
 email:
@@ -22,15 +87,18 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rspec
+- .travis.yml
 - CHANGELOG.md
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - future-resource.gemspec
 - lib/future-resource.rb
 - lib/future-resource/version.rb
-has_rdoc: true
+- spec/future-resource_spec.rb
 homepage: https://github.com/adhearsion/future-resource
 licenses: []
 post_install_message: 
@@ -51,8 +119,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: future-resource
-rubygems_version: 1.6.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Wait on resources being set in the future
-test_files: []
+test_files:
+- spec/future-resource_spec.rb
+has_rdoc: