async_io 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6987084439444f8b65360b694efe1367a3abda31
+  data.tar.gz: 875b9b38b82ed030e711d84790029f1d0034bbc5
+SHA512:
+  metadata.gz: 994b5606932c7a7e2b9c5d3052f1468a9a08a85448ab009801a00da31b7d8c09328747f95af1ef5d4d4624345bf0434a8caa27d9c3336ace26825e4b2d30c8d1
+  data.tar.gz: 24629df537bf4b3f7313a2fbb5340a3577d4733b24394cb42ac854407f532d13708f6c14a1dc12843ca744d8c0a60d03b178d2d89e8d10ccfda2fca1adcbcdba

data/lib/async_io/base.rb

@@ -0,0 +1,97 @@
+require 'thread'
+require 'async_io/worker'
+require 'async_io/rescuer'
+
+module AsyncIO
+  class Base
+    include AsyncIO::Rescuer
+
+    ##
+    # Default:
+    # Number of threads to be spanwed is 1
+    #
+    # NOTE: Any sort of exception raised while
+    # 'getting' a job done will not be raised at all.
+    # Instead it will be logged to a specified log file.
+    #
+    # Whenever an exception is raised, the thread that the
+    # exception was raised from is killed, so we need a
+    # way to prevent threads from being killed. Therefore it
+    # rescues all exceptions raised and logs them.
+    #
+    attr_reader   :queue, :threads
+    attr_accessor :logger
+    def initialize(n_threads=1)
+      @logger   = AsyncIO::Logger
+      @queue    = Queue.new
+      @threads  = []
+      n_threads.times { @threads << Thread.new { consumer } }
+    end
+
+    ##
+    # Ruby Queue#pop sets non_block to false.
+    # It waits until data is pushed on to
+    # the queue and then process it.
+    #
+    def consumer
+      rescuer do
+        while worker = queue.pop
+          worker.call
+        end
+      end
+    end
+    private(:consumer)
+
+    ##
+    # It creates a new Worker, pushes it onto the queue,
+    # whenever a 'job' (i.e a Ruby object ) is finished
+    # it calls the payload and passes the result of job
+    # to it.
+    #
+    # For example:
+    #
+    # def aget_user(uid, &payload)
+    #   worker(payload) do
+    #     User.find(ui)
+    #   end
+    # end
+    #
+    # It returns the worker created for a particular job
+    # which you could send message +done+ to it in order
+    # to retrieve its job done.
+    # see prediction_io/worker.rb
+    #
+    # For example:
+    # result = aget_user(1) { |u| Logger.info(u.name) }
+    #
+    # # job may take a while to be done...
+    #
+    # user = result.done
+    # user.name
+    # => "John"
+    #
+    # NOTE: Whenever you use the snippet above, if the job
+    # has not been finished yet you will get +false+
+    # whenever you send a message +job+ to it. Once
+    # job is finished you will be able to get its result.
+    #
+    def worker(payload, &job)
+      rescuer do
+        Worker.new(payload, job).tap { |w|
+          queue.push(w)
+        }
+      end
+    end
+
+    ##
+    # Perform any sort of task that needs to be
+    # asynchronously done.
+    # NOTE: It does not return anything, as it receives
+    # and empty job. ( i.e empty block of code )
+    #
+    def async(&payload)
+      worker(payload) { }
+    end
+
+  end
+end

data/lib/async_io/load.rb

@@ -0,0 +1 @@
+require 'async_io/async_io'

data/lib/async_io/rescuer.rb

@@ -0,0 +1,19 @@
+module AsyncIO
+  module Rescuer
+
+    ##
+    # Rescues any sort of exception raised and
+    # log it to a default logger, returns :rescued
+    # if any exception was raised.
+    #
+    def rescuer
+      begin
+        yield
+      rescue Exception => notice
+        AsyncIO::Logger.error("[-:AsyncIO::AsyncIO:-] - #{notice}\n")
+        :rescued
+      end
+    end
+
+  end
+end

data/lib/async_io/version.rb

@@ -0,0 +1,3 @@
+module AsyncIo
+  VERSION = "0.0.1"
+end

data/lib/async_io/worker.rb

@@ -0,0 +1,80 @@
+require 'ostruct'
+require 'timeout'
+require 'async_io/rescuer'
+
+module AsyncIO
+  class Worker
+    include AsyncIO::Rescuer
+
+    attr_reader :payload, :job
+    attr_reader :finished, :done
+
+    def initialize(payload, job)
+      @payload  = payload
+      @job      = job
+      @done     = false
+      @finished = false
+    end
+
+    ##
+    # It sends payload a message +call+
+    # and passes the result of a job, by sending
+    # job a message +call+ as well, as its argument.
+    # This allows us to do:
+    #
+    # aget_user(1) { |u| print u.name }
+    #=> Paul Clark Manson
+    #
+    # Or any other sort of task that you may
+    # need its result to be available within a block without
+    # needing to wait for it to finish and non blocking IO.
+    #
+    # A payload is a Ruby object must pass, for example:
+    #
+    # payload = lambda { |u| print u.name }
+    # payload = Object.new
+    # def payload.call(result); warn(result); end
+    #
+    # job is pre-definied inside a method, it can
+    # be anything, for example:
+    # worker(payload) do
+    #   User.find(uid)
+    # end
+    #
+    def call
+      try do
+        @finished = true
+        @done = job.call
+        payload.call(done)
+      end
+    end
+
+    ##
+    # Tries to get the first job done, when an exception
+    # is raised it then calls payload again passing a
+    # fallback as its argument.
+    #
+    def try
+      begin
+        yield
+      rescue Exception => notice
+        rescuer { payload.call(fallback(notice)) }
+      end
+    end
+
+    private
+
+      ##
+      # Instances of OpenStruct returns nil when the method
+      # called does not exist. This prevents another exception
+      # from being raised.
+      # It returns an instance of OpenStruct object with the
+      # exception rescued ( i.e notice ) and the worker that
+      # was assigned to this particular job.
+      #
+      def fallback(notice)
+        OpenStruct.new({ notice: notice, worker: self })
+      end
+
+  end
+end

data/lib/async_io.rb

@@ -0,0 +1,34 @@
+require 'async_io/load'
+
+module AsyncIO
+
+  def self.async_creator=(new_async)
+    @@async_creator = new_async
+  end
+
+  def self.async_creator
+    @@async_creator ||= Base.new(5)
+  end
+
+  ##
+  # Creates async jobs, if a payload (i.e ruby block)
+  # is not given it passes an empty payload to woker.
+  # That allows us to do:
+  #
+  # User.aget(1)
+  # User.aget(1) { |u| print u.id }
+  #
+  # The response will be a worker that was created for this
+  # particular job.
+  #
+  # NOTE: If you read PredictionIO::Worker you will see that
+  # it calls payload and passes job as its arguments. This is
+  # how it is available within a block later on.
+  # NOTE: You must pass a job ( i.e ruby block ).
+  #
+  def self.async(payload, &job)
+    payload = payload || ->(n) { n }
+    async_creator.worker(payload, &job)
+  end
+
+end

data/spec/async_io/base_spec.rb

@@ -0,0 +1,140 @@
+require 'spec_helper'
+require 'async_io/base'
+require 'stringio'
+
+module AsyncIO
+  Base.class_eval do
+    ##
+    # Returns queue's size and pops one
+    # item from queue.
+    def extract_size!
+      queue.size.tap { queue.pop }
+    end
+
+    public(:consumer)
+  end
+
+end
+
+describe AsyncIO::Base do
+
+  before        { Thread.stub(:new).and_return(double) }
+  let(:alien)   { AsyncIO::Base.new }
+  let(:logger)  { AsyncIO::Logger }
+
+  context "initialising" do
+    it "should have a queue" do
+      alien.queue.should respond_to :push
+    end
+
+    it "should create 1 thread as default" do
+      alien.threads.size.should eq(1)
+    end
+
+  end
+
+  context "#worker" do
+
+    it "should have a worker" do
+      alien.should respond_to :worker
+    end
+
+    it "should_not raise_error when no block is passed" do
+      expect {
+        alien.worker(:jason)
+      }.to_not raise_error
+    end
+
+    it "should not raise_error when block is passed" do
+      expect {
+        alien.worker(:lizza) { }
+      }.to_not raise_error
+    end
+
+    it "should push worker onto the queue" do
+      alien.worker(:paul) { }
+      alien.extract_size!.should eq(1)
+    end
+
+    it "should return worker" do
+      result = alien.worker(:blunt) { }
+      result.should be_instance_of AsyncIO::Worker
+    end
+  end
+
+  context "#async" do
+    it { alien.should respond_to :async }
+
+    ##
+    # NOTE: this snippet here can be a little tricky
+    # First we create a lambda ( -> its just Ruby syntatic sugar )
+    # Second we create a double ( a mock )
+    # Third we stub out the state of our original
+    # method and return the double
+    #
+    # Then we call the method +async+ which takes a block to be
+    # 'passed' an object.
+    #
+    # Last but not least we check if our object has received
+    # that message with that particular argument.
+    #
+    # Ruby allows us to do some cool stuff with coercion and
+    # closures while using blocks.
+    # The following might be helpul:
+    # robertsosinski.com/2008/12/21/understanding-ruby-blocks-procs-and-lambdas
+
+    #
+    it "should pass this payload block onto Worker" do
+      payload = -> { :im_an_async_job }
+
+      worker = double
+      alien.stub(:worker).
+        and_return(worker)
+
+      ##
+      # See the link below for a better understading how to
+      # pass/call blocks of code in Ruby.
+      # pragdave.pragprog.com/pragdave/2005/11/symbolto_proc.html
+      #
+      alien.async(&payload)
+
+      alien.should have_received(:worker).with(payload)
+    end
+  end
+
+  context "#consumer" do
+    it { alien.should respond_to :consumer }
+
+    it "should pop and consume items in a queue" do
+      bob = double
+
+      ##
+      # returns false to break the while loop.
+      #
+      bob.should_receive(:pop).and_return(false)
+      alien.stub(:queue).and_return(bob)
+
+      alien.consumer.should be_nil
+    end
+
+    it "should not raise any error" do
+      tob = -> { raise "Not going to be Raised" }
+      alien.queue.push(tob)
+
+      expect {
+        alien.consumer
+      }.to_not raise_error
+    end
+
+    it "should call a worker" do
+      duck = double
+      duck.should_receive(:call)
+
+      alien.stub(:queue).and_return([duck])
+
+      alien.consumer
+    end
+
+  end
+
+end

data/spec/async_io/rescuer_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+require 'async_io/rescuer.rb'
+
+class Guard
+  include AsyncIO::Rescuer
+
+  def initialize
+    @logger = AsyncIO::Logger
+  end
+
+end
+
+describe AsyncIO::Rescuer do
+  let(:logger) { AsyncIO::Logger }
+  let(:guard) { Guard.new }
+
+  it { guard.should respond_to :rescuer }
+
+  context "#rescuer" do
+
+    it "should rescue when an exception is raised" do
+      expect {
+        guard.rescuer { raise "hell" }
+      }.to_not raise_error
+    end
+
+    it "should not raise when no block" do
+      expect {
+        guard.rescuer
+      }.to_not raise_error
+    end
+
+    it "should not raise when block is present" do
+      expect {
+        guard.rescuer { :imma_block }
+      }.to_not raise_error
+    end
+  end
+
+  context "Logs", "whenever an exception is raised"  do
+
+    it "should write error to logger" do
+      guard.rescuer { raise "log me!" }
+      logger.read.should match /log me!/
+    end
+
+  end
+end
+

data/spec/async_io/worker_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+require 'async_io/worker'
+
+module AsyncIO
+  Worker.class_eval do
+    public(:fallback)
+  end
+
+  describe Worker do
+
+    let(:payload) { ->(r) { r } }
+    let(:job)     { -> { :am_a_dog } }
+    let(:worker)  { Worker.new(payload, job) }
+
+    context "initialising" do
+
+      it "must take a payload" do
+        worker.payload.should be_kind_of Proc
+      end
+
+      it "must take a job" do
+        worker.job.should be_kind_of Proc
+      end
+
+    end
+
+    it { worker.should respond_to :done }
+
+    it "should not be done as job is not finished" do
+      worker.done.should be_false
+    end
+
+    it "must call payload and pass job as its argument" do
+      worker.call.should eq(:am_a_dog)
+    end
+
+    context "Getting a job done" do
+      it "should set done to its last finished job" do
+        worker.call
+        worker.done.should eq(:am_a_dog)
+      end
+    end
+
+    describe "#try" do
+      it { worker.should respond_to :try }
+
+      context "failed" do
+        it "should call fallback" do
+          worker.should_receive(:fallback)
+          worker.try { raise "failed" }
+        end
+      end
+
+      context "success" do
+        it "should not call fallback" do
+          worker.should_not_receive(:fallback)
+          worker.try { :happy }
+        end
+      end
+
+      context "#fallback" do
+        let(:fallback) { worker.fallback("notice") }
+
+        it "should have a notice" do
+          fallback.notice.should eq("notice")
+        end
+
+        it "should have a worker" do
+          fallback.worker.should eq worker
+        end
+
+        it "should return nil when method not found" do
+          fallback.will_return_nil.should be_nil
+        end
+      end
+
+    end
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,30 @@
+module AsyncIO
+  CONFIG_PATH = File.expand_path("../support", __FILE__)
+
+  Logger = Object.new
+  def Logger.error(n); @n = n; end
+  def Logger.read; @n; end
+end
+
+RSpec.configure do |c|
+  c.treat_symbols_as_metadata_keys_with_true_values = true
+end
+
+class AsyncIO::FakeAsync
+  ##
+  # Calls payload and passes whatever
+  # job.call yields as its argument.
+  #
+  def self.async(payload, &job)
+    payload = payload || ->(n) { n }
+    payload.call(job.call)
+  end
+
+  def worker(payload, &job)
+    payload.call(job.call)
+  end
+
+end
+
+RSpec::Matchers.define(:be_rescued){ |e| match { |a| a === :rescued } }
+RSpec::Matchers.define(:be_deleted){ |e| match { |a| a === :deleted } }

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: async_io
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Antonio C Nalesso
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Perform asyncrhonous IO for ruby using blocks and threads just pure old
+  ruby code.
+email:
+- acnalesso@yahoo.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/async_io.rb
+- lib/async_io/base.rb
+- lib/async_io/load.rb
+- lib/async_io/rescuer.rb
+- lib/async_io/version.rb
+- lib/async_io/worker.rb
+- spec/async_io/base_spec.rb
+- spec/async_io/rescuer_spec.rb
+- spec/async_io/worker_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/acnalesso/async_io
+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.0.3
+signing_key: 
+specification_version: 4
+summary: Simple asynchronous IO for ruby.
+test_files:
+- spec/async_io/base_spec.rb
+- spec/async_io/rescuer_spec.rb
+- spec/async_io/worker_spec.rb
+- spec/spec_helper.rb
+has_rdoc: