future_proof 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15ccb48d47e099121a7d5f7244f78df5e3a9ac5a
-  data.tar.gz: a54c4d62b82764b907c03fb3882f2acb2fa194a8
+  metadata.gz: f4a0d0a882b8da1f1bf03f83a78fdd5c358312cb
+  data.tar.gz: 7cc74e59ce7c4433bda42268b342702dbba72fd8
 SHA512:
-  metadata.gz: 3994b096ae89e3cfe08f0a7358ee336ca38606b161ae8b5ffd8232ccb0b8e0efc75e53fa0aa85952be798f6da6b2fd4771e8f021b5fa9a134e0f6f2f9300e23b
-  data.tar.gz: a2d931e05870443e7a741df982193d8499eaeae9fffc04f6641cef25fec39067f5d4807e94289743e9946dcfd31667a10e9de2a10a52e09e13c588cfd421398d
+  metadata.gz: a325925c0458a6a4ce764e449b66890ac998ba0c6eff8ca18837596d6fb1f91da74c04841566cd53489297a0cc6069a8e9d6e04d9f17a0057614a594fec563c9
+  data.tar.gz: 2ec4705cff77ce7254edb1fc7c6aeb123915199e549c9e50875821f60b931028a5882a4526bf1294d571d377470680b196d9571717f3c6e3748aebcc26df0150

data/lib/future_proof/exceptionable.rb

@@ -1,8 +1,11 @@
 module FutureProof
+
+  # Module +Exceptionable+ provides methods to read values with exceptions
   module Exceptionable
 
   private
 
+    # Returns value or raises exception if its an exception instance
     def raise_or_value(value)
       value.is_a?(StandardError) ? raise(value) : value
     end

data/lib/future_proof/future.rb

@@ -1,23 +1,52 @@
 module FutureProof
+  
+  # Class +Futures+ can be used to create Procs
+  # that should be executed inside a Thread.
   class Future
+
+    # Initializes new +Future+.
+    #
+    # @example Initialize +Future+
+    #   FutureProof::Future.new { |a, b| a + b }
     def initialize(&block)
       @block = block
     end
 
+    # Executes +Future+ in a thread with given params.
+    #
+    # @param [Array<Object>] *args proc arguments
+    #
+    # @exmaple call +Future+
+    #   future.call(2, 2)
     def call(*args)
       thread(*args)
     end
 
+    # Return a result of a +Future+.
+    #
+    # @param [Array<Object>] *args proc arguments if they were not suplied before.
+    #
+    # @note It requires list of arguments if +Future+ was not called before.
+    #
+    # @exmaple Get value of +Future+
+    #   future.value
     def value(*args)
       thread(*args).value
     end
 
+    # Return true if Future is done working.
+    #
+    # @exmaple Get state of +Future+
+    #   future.complete?
+    #
+    # @return [true, galse] true if +Future+ is done working.
     def complete?
       !thread.alive?
     end
 
   private
 
+    # Thread that +Future+ is wrapped around.
     def thread(*args)
       @thread ||= Thread.new { @block.call *args }
     end

data/lib/future_proof/future_array.rb

@@ -1,4 +1,8 @@
 module FutureProof
+
+  # +FutureArray+ should be used to raise exceptions
+  # if specific values are exception instances
+  # on a direct access with #[], #first, #last, #each, #sort and so on.
   class FutureArray
     include Enumerable
     include FutureProof::Exceptionable
@@ -7,10 +11,14 @@ module FutureProof
       @arry = Array.new arg
     end
 
+    # Acces +FutureArray+ value by index.
     def [](index)
       raise_or_value @arry[index]
     end
 
+    # Array of values.
+    #
+    # @note raises an exception if any value if an exception.
     def all
       map { |a| a }
     end
@@ -21,6 +29,9 @@ module FutureProof
       end
     end
 
+    # Iterates through array elements.
+    #
+    # @note raises an error if any value is an exception.
     def each
       @arry.each { |a| yield raise_or_value(a) }
     end

data/lib/future_proof/future_queue.rb

@@ -1,4 +1,7 @@
 module FutureProof
+
+  # +FutureQueue+ is designed to handle exceptions that happen in a threads.
+  # It raises an exception when user tries to access "exceptional" value.
   class FutureQueue < Queue
 
     include FutureProof::Exceptionable
@@ -8,6 +11,11 @@ module FutureProof
       super()
     end
 
+    # Pushes value into a queue by executing it.
+    # If execution results in an exception
+    # then exception is stored itself.
+    #
+    # @note allowed only when queue is running.
     def push(*values, &block)
       raise_future_proof_exception if finished?
       value = if block_given?
@@ -22,36 +30,58 @@ module FutureProof
       super(value)
     end
 
+    # Pops value or raises an exception.
+    #
+    # @return [Object] first value of queue.
+    #
+    # @note allowed only when queue is running.
     def pop
       raise_future_proof_exception if finished?
       raise_or_value super
     end
 
+    # Returns +FutureArray+ with all values.
+    #
+    # @return [FutureProof::FutureArray] Array with values.
+    #
+    # @note allowed only when queue is stopped.
     def values
       raise_future_proof_exception unless finished?
       @values ||= FutureProof::FutureArray.new(instance_variable_get(:@que).dup)
     end
 
+    # Returns +FutureArray+ with all values.
+    #
+    # @return [Object] value in a queue.
+    #
+    # @note allowed only when queue is stopped.
+    # @note raises an exception if it happened during execution.
     def [](index)
       raise_future_proof_exception unless finished?
       values[index]
     end
 
+    # Stops queue.
     def stop!
       @finished = true
     end
 
+    # Starts queue.
     def start!
       @values   = nil
       @finished = false
     end
 
-  private
-
+    # Checks if queue is stopped.
+    #
+    # @return [true, false] true if queue is not working.
     def finished?
       @finished
     end
 
+  private
+
+    # Raises an exception if queue is accessed in the wrong state.
     def raise_future_proof_exception
       raise FutureProof::FutureProofException.new 'Queu is not accessible in the state given!'
     end

data/lib/future_proof/thread_pool.rb

@@ -1,7 +1,12 @@
 require 'thread'
 
 module FutureProof
+
+  # +ThreadPool+ could be used to schedule and group threads.
   class ThreadPool
+    # Initializes a new thread pool.
+    #
+    # @params [FixNum] size the size of the pool thread.
     def initialize(size)
       @size    = size
       @threads = []
@@ -9,10 +14,21 @@ module FutureProof
       @values  = FutureProof::FutureQueue.new
     end
 
+    # Submits a task to a thread pool.
+    #
+    # @param [Array<Object>] *args job arguments.
+    #
+    # @example
+    #   thread_pool.submit(25, 2) { |a, b| a ** b }
+    #
+    # @note Does not start the execution until #perform is called.
     def submit(*args, &block)
       @queue.push [block, args]
     end
 
+    # Starts execution of the thread pool.
+    #
+    # @note Can be restarted after finalization.
     def perform
       unless @threads.any? { |t| t.alive? }
         @values.start!
@@ -30,25 +46,27 @@ module FutureProof
       end
     end
 
+    # Flags that after all pool jobs are processed thread pool should stop the reactor.
     def finalize
       @size.times { @queue.push :END_OF_WORK }
     end
 
+    # Calls #finalize and block programm flow until all jobs are processed.
     def wait
       finalize
       @threads.map &:join
     end
 
+    # Calls #wait and returns array of all calculated values.
+    #
+    # @return [FutureProof::FutureArray] instance of FutureArray with all values.
     def values
       wait
       @values.stop!
       @values.values
     end
 
-    def finalize
-      @size.times { @queue.push :END_OF_WORK }
-    end
-
+    # Commands to remove all pool tasks and finishes the execution after all running tasks are completed.
     def finalize!
       @queue.clear
       finalize

data/lib/future_proof/version.rb

@@ -1,3 +1,3 @@
 module FutureProof
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/spec/future_proof/thread_pool_spec.rb

@@ -71,7 +71,11 @@ describe FutureProof::ThreadPool do
   end
 
   describe 'exceptions' do
-    before { thread_pool.submit(24, 0, &task) }
+    before do
+      thread_pool.submit 24, 0 do |a, b|
+        a / b
+      end
+    end
 
     context 'without asking for specific value' do
       it 'should not raise exceptions' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: future_proof
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Nikita Cernovs
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-18 00:00:00.000000000 Z
+date: 2013-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler