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.

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:

executor = JFuture::ExecutorFactory.create(name: :my_pool)

Let us pick some calls and make them concurrent

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:

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

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

people = JFuture.new(executor: :my_pool) { Person.all }

people = JFuture.new(executor: executor) { Person.all }

Timeouts

Read access timeout on future object can be set as:

people = JFuture.new(executor: executor, access_timeout_millis: 100) { Person.all }
people.do_something # timer is triggered on access

on timeout throws exception:

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)

people.is_done?  # true / false

Async callbacks on future completion:

restaurant = JFuture.new {Restaurant.find(id)} # get future object
restaurant.on_complete {|restaurant| puts restaurant.name} # set up an async callback

by chaining:

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.

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

Chaining with on_complete

.on_complete returns a JFuture object of the result of on_complete block. Its therefore possible to create a chain with .on_complete:

JFuture.new { Restaurant.all[0]}.on_complete{|res| res.name}.on_complete{|res|  puts res}

Its recommended to avoid chaining when possible as it blocks as many workers as the links in the chain. The workers get unblocked in the order of the chain links. Its possible to specify the executor and access_timeout_millis for the .on_complete as well.

JFuture.new(executor: :db_pool, access_timeout_millis: 100){ Restaurant.all[0]}.on_complete(executor: :default,  access_timeout_millis: 200){|res| res.name}.on_complete{|res|  puts res; puts res}

While the `executor` specified for `.on_complete` will be used to run the `block` of `.on_complete`, the `access_timeout_millis` will apply to the consumer of the result of the `.on_complete` when it tries to read the result of on complete (`access_timeout_millis` always applies to the consumer of the JFuture object) JFuture objects for each link in the chain are created and consumed in one shot. So the timer for each of the timeouts starts almost at the same time. Hence the timeouts in the chain should be in increasing order (i.e. cumulative of the timeout of the previous link in the chain) 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.

j_future

Development