j_future 0.0.1-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d3b8dbfabd5a6e294509d71902e15bce2bf06177
+  data.tar.gz: 8d8fc608cb785e0ebfa1f119bac804b184def594
+SHA512:
+  metadata.gz: b63fdccd5b652bc3b7f96200bb071bebfbd856cf3d8411e455c168a23b6e2f7c6501cef840f0ac3dacc3221be168dfd248d190bc7ed2b2f3850828510a329960
+  data.tar.gz: a6ae8f5245ef4dd7b3a1a601b887211fa08eb427378d7f3ede7bb186a311d86ed514683a3f5894a8933c237337686f5cf1a6c657c99eec25f0d4d47e55f2ee00

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,98 @@
+future
+======
+
+A seemless proxy future object framework for jruby to do work in parallel
+
+Usage
+-----
+
+First, create a thread pool executor to execute the tasks. Ideally this should be done in the application initializer.
+``` ruby
+executor = JFuture::ExecutorFactory.create
+```
+
+Its is recommended that you give a name for the executor (default name is `:default`). Below we create a thread pool executor with all available options:
+``` ruby
+executor = JFuture::ExecutorFactory.create(name: :my_pool)
+```
+
+Let us pick some calls and make them concurrent
+``` ruby
+people = Person.all  # call to database
+people.do_something  # use result by calling methods on it
+cars = Car.all   	 # call to database
+cars.do_something    # use result by calling methods on it
+```
+change the above to execute in parallel:
+``` ruby
+people = JFuture.new(executor: :my_pool) { Person.all }  # makes async call to database and returns the result as a future object
+cars = JFuture.new(executor: :my_pool) { Car.all }  	    # makes async call to database and returns the result as a future object
+people.do_something  									# waits on the future object to be popluated and only then is the method call executed
+cars.do_something    									# waits on the future object to be popluated and only then is the method call executed
+```
+
+
+ExecutorFactory options with defaults
+-------------------------------------
+``` ruby
+executor = JFuture::ExecutorFactory.create(core_pool_size: 20,
+          max_pool_size: 20,
+          keep_alive_millis: 120000,
+          queue_size: 10,
+          name: :default,
+          thread_factory: DaemonThreadFactory.new)
+```
+
+Submit task to an executor
+--------------------------
+```JFuture.new``` can take either the name of executor or a reference to an executor
+``` ruby
+people = JFuture.new(executor: :my_pool) { Person.all }
+```
+or
+``` ruby
+people = JFuture.new(executor: executor) { Person.all }
+```
+Timeouts
+--------
+Read access timeout on future object can be set as:
+``` ruby
+people = JFuture.new(executor: executor, access_timeout_millis: 100) { Person.all }
+people.do_something # timer is triggered on access
+```
+on timeout throws exception:
+``` ruby
+Java::JavaUtilConcurrent::TimeoutException
+```
+is_done? check
+--------------
+Check if the future is populated without blocking on it(any method other than is_done? is guranteed to block)
+``` ruby
+people.is_done?  # true / false
+```
+
+Async callbacks on future completion:
+-------------------------------------
+``` ruby
+restaurant = JFuture.new {Restaurant.find(id)} # get future object
+restaurant.on_complete {|restaurant| puts restaurant.name} # set up an async callback
+```
+by chaining:
+``` ruby
+JFuture.new {Restaurant.find(id)}.on_complete {|result| puts result.name}
+```
+The timeout on future applies to the on_complete as well. It will throw a Java::JavaUtilConcurrent::TimeoutException on time out. This error can be handled by adding a rescue block for the error inside on_complete block.
+``` ruby
+JFuture.new(access_timeout_millis: 1) {Restaurant.find(id)}.on_complete do
+  begin
+    puts restaurant.name
+  rescue Java::JavaUtilConcurrent::TimeoutException
+    puts 'task timed out'
+  end
+end
+```
+Note:
+-----
+The `access_timeout_millis` only applies to the thread blocking on future object. the worker thread which computes the future will be blocked for as long as it takes to compute the future object without any timeout applicable to it. So, only pass things into future that will complete.
+The callback and future object computation are scheduled as separate tasks possibly taking up different threads. While deciding the number of workers for the executor keep in mind that blocked task with callback results in two blocked workers.
+

data/j_future.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require "./lib/j_future/version"
+
+Gem::Specification.new do |s|
+  s.name        = 'j_future'
+  s.version     = JFuture::VERSION
+  s.platform    = 'java'
+  s.authors     = ['Sumanth K N']
+  s.email       = ['kn.sumanth@gmail.com']
+  s.homepage    = 'https://github.com/kn-sumanth/j_future'
+  s.description = s.summary = %q{simple future object framework for jruby}
+
+  s.files         = `git ls-files`.split("\n")
+  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.license = 'MIT'
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'minitest', '>= 5.0.0'
+  s.add_development_dependency 'rake'
+end

data/lib/j_future/callable.rb

@@ -0,0 +1,12 @@
+class JFuture < ::BasicObject
+  class Callable
+    include Java::JavaUtilConcurrent::Callable
+    def initialize(arg = nil, &block)
+      @block = block
+      @arg = arg
+    end
+    def call
+      @block.call @arg
+    end
+  end
+end

data/lib/j_future/daemon_thread_factory.rb

@@ -0,0 +1,10 @@
+class JFuture < ::BasicObject
+  class DaemonThreadFactory
+    include Java::JavaUtilConcurrent::ThreadFactory
+    def newThread(runnable)
+      thread = Java::JavaUtilConcurrent::Executors.defaultThreadFactory().newThread(runnable)
+      thread.setDaemon(true)
+      thread
+    end
+  end
+end

data/lib/j_future/executor_factory.rb

@@ -0,0 +1,28 @@
+class JFuture < ::BasicObject
+  class ExecutorFactory
+    @@executor_map = {}
+    def self.create(core_pool_size: 20,
+          max_pool_size: 20,
+          keep_alive_millis: 120000,
+          queue_size: 10,
+          name: :default,
+          thread_factory: DaemonThreadFactory.new)
+
+      work_queue = queue_size.to_i > 0 ?
+                    Java::JavaUtilConcurrent::LinkedBlockingQueue.new(queue_size.to_i) :
+                    Java::JavaUtilConcurrent::SynchronousQueue.new
+      executor = Java::JavaUtilConcurrent::ThreadPoolExecutor.new(
+                    core_pool_size.to_i,
+                    max_pool_size.to_i,
+                    keep_alive_millis.to_i,
+                    MILLIS,
+                    work_queue,
+                    thread_factory)
+      @@executor_map[name] = executor
+    end
+
+    def self.get_executor(name = :default)
+      @@executor_map[name]
+    end
+  end
+end

data/lib/j_future/version.rb

@@ -0,0 +1,3 @@
+class JFuture < ::BasicObject
+  VERSION = "0.0.1"
+end

data/lib/j_future.rb

@@ -0,0 +1,46 @@
+require 'java'
+require_relative 'j_future/version'
+require_relative 'j_future/callable'
+require_relative 'j_future/daemon_thread_factory'
+require_relative 'j_future/executor_factory'
+class JFuture < ::BasicObject
+  MILLIS = ::Java::JavaUtilConcurrent::TimeUnit::MILLISECONDS
+  METHODS = [:is_done?, :on_complete]
+
+  def initialize(executor: :default, access_timeout_millis: nil, &block)
+    @access_timeout_millis = access_timeout_millis
+    callable = Callable.new(&block)
+    if (executor.is_a? ::Java::JavaUtilConcurrent::AbstractExecutorService)
+      @executor = executor
+    else
+      @executor = ExecutorFactory.get_executor(executor)
+    end
+    @future = @executor.submit callable
+  end
+
+  def respond_to?(id, *args)
+    return true if METHODS.include?(id)
+    if @access_timeout_millis.nil?
+      @future.get.respond_to?(id, *args)
+    else
+      @future.get(@access_timeout_millis.to_i, MILLIS).respond_to?(id, *args)
+    end
+  end
+
+  def is_done?
+    @future.isDone
+  end
+
+  def on_complete(&block)
+    callback = Callable.new(self, &block)
+    @executor.submit callback
+  end
+
+  def method_missing(name, *args, &block)
+    if @access_timeout_millis.nil?
+      @future.get.send(name, *args, &block)
+    else
+      @future.get(@access_timeout_millis.to_i, MILLIS).send(name, *args, &block)
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: j_future
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: java
+authors:
+- Sumanth K N
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2017-02-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: bundler
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+  name: minitest
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: rake
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: simple future object framework for jruby
+email:
+- kn.sumanth@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- j_future.gemspec
+- lib/j_future.rb
+- lib/j_future/callable.rb
+- lib/j_future/daemon_thread_factory.rb
+- lib/j_future/executor_factory.rb
+- lib/j_future/version.rb
+homepage: https://github.com/kn-sumanth/j_future
+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: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.4.8
+signing_key:
+specification_version: 4
+summary: simple future object framework for jruby
+test_files: []