asynchronize 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f84e1c57b42abe8917434680f2a3889a4edc2608af231513f3b24bbe77d2e2c
-  data.tar.gz: 8dabfe07d60a388bf73a2b7c2c3b36a8d941bf0f8502bd425b4736c2ec81fc2f
+  metadata.gz: 912acc8b2e852aa7ccdd7fc09193f46fa64730f74972e9a955b8ba2bf3e40f1f
+  data.tar.gz: c6b91b991495bb45ce6580596c9919a4a376437f3c441706c63f84a62941c77e
 SHA512:
-  metadata.gz: 23744ccb079b4e39828a9d11a46be4a56e97869f88a9e99661685fc405fa609ed92a046ce22b3642670028ccf951c5558246269418967826741184cfbf43c206
-  data.tar.gz: 2442aaf5bcc17538b569c00fd28b76fdfb9451d25160b47b1763e7237238d22309c49acac4c141745226e4a07f665e0feb691748d0303ea480dd75a7e06d6052
+  metadata.gz: 86f7e988a2b97f36bb951045fca9214fd81b53239ae6a2fe5c0330a01f6f81c51bfcdb73052e2ac07bf434ec47dd362005274fa54243f8b3be9e4ec74fe53a96
+  data.tar.gz: 274687d5e6b292d4f6bbf85515c95f9d4eb84bef5b8c9b5a51f6fd363ed99000ee7e36ff30672d6b714009077a637b3ecc43746a726631164b12d44d7ac1b563

data/lib/asynchronize.rb

@@ -1,83 +1,89 @@
+##
+# Include this module to allow a declarative syntax for defining asynch methods
+#
+#   Defines only one method on the including class: `asynchronize`
+#
 module Asynchronize
-  require 'set'
   def self.included(base)
     base.class_eval do
-      # The methods we have already asynchronized
-      @asynced_methods = Set.new
-      # The methods that should be asynchronized.
-      @methods_to_async = Set.new
-      # Originally used a single value here, but that's not thread safe.
-      # ...Though you probably have other problems if you have multiple
-      # threads adding methods to your class.
-      @methods_asyncing = Set.new
-
       ##
       # Call to asynchronize a method.
-      #   That method will be added to a list of methods to asynchronize.
-      #   If the method already exists, it will be redefined to an asynchronous
-      #   version. If it does not, method_missing will redefine it when it does.
-      #   If the method is redefined afterwards, method_missing will also
-      #   asynchronize that version.
+      #
+      #   This does two things
+      #   1. Creates and prepends a module named Asynchronized.
+      #   2. Scopes that module to the calling class.
+      #   3. Defines each of the passed methods on that module.
+      #
+      #   Additional notes:
+      #   - The new methods wrap the old method within Thread.new.
+      #   - Subsequent calls only add methods to the existing Module.
+      #   - Will silently fail if the method has already been asynchronized
       #
       # @param methods [Symbol] The methods to be asynchronized.
       # @example To add any number of methods to be asynchronized.
       #   asynchronize :method1, :method2, :methodn
+      #
       def self.asynchronize(*methods)
-        @methods_to_async.merge(methods.map {|m| m.hash})
-        methods.each do |method|
-          # If it's not defined yet, we'll get it with method_added
-          Asynchronize.create_new_method(method, self) if method_defined?(method)
-        end
-      end
-
-      # Save the old method_added so we don't overwrite it.
-      if self.methods.include?(:method_added)
-        singleton_class.send(:alias_method, :old_method_added, :method_added)
-        singleton_class.send(:undef_method, :method_added)
-      end
-
-      ##
-      # Will asynchronize a method if it has not been asynchronized already, and
-      #   it is in the list of methods to asynchronize. If method missing was
-      #   already defined, it will call the previous method_missing before
-      #   anything else Ruby calls this automatically when defining a method; it
-      #   should not be called directly.
-      def self.method_added(method)
-        # Return if this is an inherited class that hasn't included asynchronize
-        return if @methods_asyncing.nil?
-        # Return if we're already processing this method
-        return if @methods_asyncing.include?(method.hash)
-        @methods_asyncing.add(method.hash)
-        self.old_method_added(method) if self.methods.include?(:old_method_added)
-        return unless @methods_to_async.include?(method.hash)
-        # This will delete from @methods_asyncing
-        Asynchronize.create_new_method(method, self)
+        return if methods.empty?
+        async_container = Asynchronize._get_container_for(self)
+        Asynchronize._define_methods_on_object(methods, async_container)
       end
     end
   end
 
+  private
   ##
-  # Responsible for actually creating the new methods and removing the old.
-  def self.create_new_method(method, klass)
-    klass.instance_eval do
-      old_method = instance_method(method)
-      return if @asynced_methods.include?(old_method.hash)
-      undef_method(method)
-
-      @methods_asyncing.add(method.hash)
-      define_method(method, Asynchronize._build_new_method(old_method))
-      @methods_asyncing.delete(method.hash)
-      @asynced_methods.add(instance_method(method).hash)
+  # Define methods on object
+  #
+  #   For each method in the methods array
+  #
+  #   - If method already defined, go to the next.
+  #   - If method does not exist, create it and go to the next.
+  #
+  # @param methods [Array<Symbol>] The methods to be bound.
+  # @param obj [Object] The object for the methods to be defined on.
+  #
+  def self._define_methods_on_object(methods, obj)
+    methods.each do |method|
+      next if obj.methods.include?(method)
+      obj.send(:define_method, method, _build_method)
     end
   end
 
-  private
-  def self._build_new_method(old_method)
+  ##
+  # Build Method
+  #
+  #  This always returns the same Proc object. In it's own method for clarity.
+  #
+  # @return [Proc] The actual asynchronous method defined.
+  #
+  def self._build_method
     return Proc.new do |*args, &block|
-      return Thread.new(old_method, args, block) do |told_method, targs, tblock|
-        Thread.current[:return_value] = told_method.bind(self).call(*targs)
-        tblock.call(Thread.current[:return_value]) unless tblock.nil?
+      return Thread.new(args, block) do |thread_args, thread_block|
+        Thread.current[:return_value] = super(*thread_args)
+        thread_block.call(Thread.current[:return_value]) if thread_block
       end
     end
   end
+
+  ##
+  # Container setup
+  #
+  #   Creates the container module that will hold our asynchronous wrappers.
+  #
+  #   - If the container module is defined, return it.
+  #   - If the container module is not defined, create, prepend, and return it.
+  #
+  # @param obj [Class] The Class to prepend our module to
+  # @return [Module] The already prepended module to define our methods on.
+  #
+  def self._get_container_for(obj)
+    if obj.const_defined?('Asynchronized')
+      return obj.const_get('Asynchronized')
+    else
+      async_container = obj.const_set('Asynchronized', Module.new)
+      obj.prepend async_container
+      return async_container
+    end
+  end
 end

data/readme.md

@@ -2,12 +2,13 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/30d40e270a3d7a0775a9/maintainability)](https://codeclimate.com/github/kennycoc/asynchronize/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/30d40e270a3d7a0775a9/test_coverage)](https://codeclimate.com/github/kennycoc/asynchronize/test_coverage)
 # Asynchronize
-### The easiest way to make multiple methods asynchronous.
+### A declarative syntax for creating multithreaded methods.
 
 Find yourself writing the same boilerplate for all your asynchronous methods?
 Get dry with asynchronize.
 
-Just install with `gem install asynchronize` or add to your Gemfile and `bundle`
+Just add to your Gemfile and `bundle` or install globally with
+`gem install asynchronize`
 
 ## Usage
 Create a class with asynchronized methods
@@ -15,7 +16,7 @@ Create a class with asynchronized methods
 require 'asynchronize'
 class Test
   include Asynchronize
-  # This can be called anywhere.
+  # Can be called before or after the definitions. I prefer it at the top of classes.
   asynchronize :my_test, :my_other_test
   def my_test
     return 'test'
@@ -31,20 +32,25 @@ You can manage the thread yourself; the returned value will be in the thread
 variable `:return_value` once it returns.
 ```Ruby
 thread = Test.new.my_test
-thread.join
-puts thread[:return_value] # > test
+puts thread.join[:return_value] # > test
 ```
 
-Or for convenience, you can just pass it a block.
-The return value, will still be in the thread variable `:return_value`
+Or to stay asynchronous when processing the result, you can pass it a block.
+It will still return the thread, and the return value will still be in the
+thread variable `:return_value`
 ```Ruby
-Test.new.my_test do |return_value|
+thread = Test.new.my_test do |return_value|
   puts return_value # > test
 end
+thread.join[:return_value] # > also test
 ```
 
+As you can see, it's just a regular thread. Make sure you call `Thread#join` to
+ensure it completes before your process exits, and to catch any exceptions that
+may have been thrown!
+
 ## Inspiration
-I got tired of writing this over and over.
+While working on another project, I found myself writing this way too often:
 ```Ruby
 def method_name(args)
   Thread.new(args) do |targs|
@@ -52,63 +58,75 @@ def method_name(args)
   end
 end
 ```
-It's extra typing, adds an unneeded extra layer of nesting, and just feels
-dirty. I couldn't find an existing library that wasn't trying to solve other
-problems I didn't have. Now, just call asynchronize to make any method
-asynchronous.
+It's extra typing, and adds an unneeded extra layer of nesting. I couldn't find
+an existing library that wasn't trying add new layers of abstraction to
+memorize; sometimes you just want a normal thread. Now, just call asynchronize
+to make any method asynchronous.
 
 ## Versioning Policy
-Once I feel like this is ready for production code, version 1.0.0, this project
-will follow [Semantic Versioning](https://semver.org) until then, the patch
-number (0.0.x) will be updated for any changes that do not affect the public
-interface. Versions that increment the minor number will have at least one of
-the following. A new feature will be added, some feature will be deprecated, or
-some previously deprecated feature will be removed. Deprecated features will be
-removed on the very next version that increments the minor version number.
+
+Beginning with version 1.0.0, this project will follow [Semantic Versioning]
+(https://semver.org) until then, the patch number (0.0.x) will be
+updated for any changes that do not affect the public interface. Versions that
+increment the minor number will have at least one of the following. A new
+feature will be added, some feature will be deprecated, or some previously
+deprecated feature will be removed. Deprecated features will be removed on the
+very next version that increments the minor version number.
 
 ## FAQ
 ### Doesn't metaprogramming hurt performance?
-Not at all! We're actually totally redefining the methods, so the method itself
-is exactly as efficient as it would have been had you wrote it that way
-originally.
+Not at all! It actually works just like inheritance, so it won't be a problem.
 
 ### So, how does it work?
-When you `include Asynchronize` it does two things.
-1. It defines the asynchronize method for your class
-2. It defines method_added on your class.
+When you `include Asynchronize` it creates an `asynchronize` method on your
+class. The first time you call this method with any arguments, it creates a new
+module with the methods you define. It uses `Module#prepend` to cause method
+calls on the original object to be sent to it instead, and uses super to call
+your original method inside it's own thread.
 
-When you call asynchronize, it creates a set containing all of the methods you
-want asynchronized. If they already exist, they are modified; otherwise,
-method_added checks for them with every new method you add to the class. This
-way, you can call asynchronize any time, and know that the methods will be
-asynchronized when you use them.
-
-### So, does that mean I can't use asynchronize if I already use method_added?
-We check for and alias your old method_added. It will be called before
-anything else. Of course, if you define method_added after including
-Asynchronize, you have to do the same and be careful to not overwrite ours!
+This implementation allows you to call asynchronize at the top of the class and
+then define the methods below. Since it changes how you interact with those
+method's return values, I thought it was important to allow this.
 
 ### Why do I need another gem? My code's bloated enough as it is?
 It's super tiny. Just a light wrapper around the existing language features.
-Seriously, it's just around fifty lines of code. Actually, according to
-[cloc](https://www.npmjs.com/package/cloc) there's almost four times as many
-lines in the tests as the source. You should read it, I'd love feedback!
+Seriously, it's just around forty lines of code as of version 0.3.0. Actually,
+according to [cloc](https://www.npmjs.com/package/cloc) there's almost four
+times as many lines in the tests as the source. You should read it, I'd love
+feedback!
 
 ### Do you accept contributions?
-Absolutely! If your use case isn't compatible with the project, you find a
-bug, or just want to donate some tests; make an issue or send a PR please.
-To run the test suite, just run `bundle` then `rake` from the project directory.
+Absolutely!
+1. Fork it (https://github.com/kennycoc/asynchronize/fork)
+2. Create your feature branch (git checkout -b my-new-feature)
+3. Commit your changes (git commit -am 'Add some feature')
+4. Push to the branch (git push origin my-new-feature)
+5. Create a new pull request.
+
+It's just `bundle` to install dependencies, and `rake` to run the tests.
 
 ### What's the difference between asynchronize and promises/async..await?
-Those projects and similar ones aim to create an entirely new abstraction to use
-for doing things asynchronously. This project simply aims to make the existing
-language features easier to use with less typing. Just define a regular method,
+Those and other similar projects aim to create an entirely new abstraction to
+use for interacting with threads. This project aims to be a light convenience
+wrapper around the existing language features. Just define a regular method,
 then interact with it's result like a regular thread.
 
 ### What versions are supported?
-In theory, this should work for all versions of Ruby. So far, Travis only tests
-for MRI 2.2.2 and 2.5.1. I plan on verifying and adding older versions and other
-implementations as I am able.
+Ruby 2.3 and up. Unfortunately, Ruby versions prior to 2.0 do not support
+`Module#prepend` and are not supported. Ruby versions prior to 2.3 have a bug
+preventing usage of `super` with `define_method`. I'm unable to find a suitable
+workaround for this issue. (`method(__method__).super_method.call` causes
+problems when a method inherits from the asynchronized class.)
+
+Luckily, all major Ruby implementations support Ruby language version 2.3. So I
+don't see this as a huge problem. If anyone wants support for older versions,
+and knows how to workaround this issue, feel free to submit a pull request.
+
+We explicitly test against the following versions:
+ - Matz Ruby 2.5.1
+ - Matz Ruby 2.3.4
+ - JRuby 9.1.13 (language version 2.3.3)
+ - Rubinius 3.105 (language version 2.3.1)
 
 ## License
 MIT

data/spec/spec.rb

@@ -16,29 +16,15 @@ class BasicSpec < Minitest::Test
     end
 
     describe "when we asynchronize a method" do
-      it "should not be the same method" do
-        original_method = Test.instance_method :test
-        Test.asynchronize :test
-        new_method = Test.instance_method(:test)
-        original_method.wont_equal(new_method, "The method was not overwritten")
-      end
       it "should not return a thread unless we asynchronize it" do
         Test.new.test.class.wont_equal(Thread, "The method was not overwritten")
       end
-      it "should be the same method if we call a second time" do
-        Test.asynchronize :test
-        original_method = Test.instance_method :test
-        Test.asynchronize :test
-        new_method = Test.instance_method :test
-        original_method.must_equal(new_method,
-          "Asynchronized Inception has occurred")
-      end
       it "should not throw an error if the specified method does not exist" do
         Test.asynchronize :notamethod
       end
       it "should not create a method if the specified method does not exist" do
         Test.asynchronize :notamethod
-        Test.method_defined?(:notamethod).must_equal false
+        Test.methods(false).wont_include(:notamethod)
       end
       it "should not affect methods on other classes when called before" do
         Test.asynchronize :test
@@ -105,35 +91,6 @@ class BasicSpec < Minitest::Test
       end
     end
 
-    describe "when there is an existing method_added" do
-      before do
-        class MethodAddedTest
-          @running = false
-          def self.method_added(method)
-            return if @running
-            @running = true
-            old_method = instance_method(method)
-            undef_method(method)
-            define_method(method) do
-              return old_method.bind(self).call + 1
-            end
-            @running = false
-          end
-          include Asynchronize
-          asynchronize :test
-          def test
-            return 4
-          end
-        end
-      end
-      after do
-        BasicSpec.send(:remove_const, :MethodAddedTest)
-      end
-      it "should call that method_added before, and only once." do
-        MethodAddedTest.new.test.join[:return_value].must_equal 5
-      end
-    end
-
     describe "when inheriting from another class" do
       before do
         class ChildClassTest < Test
@@ -165,5 +122,14 @@ class BasicSpec < Minitest::Test
         ChildClassTest.new.test.must_equal 6
       end
     end
+
+    describe "when asynchronize is called with no arguments" do
+      it "should not define an Asynchronized container" do
+        Test.asynchronize
+        Test.ancestors.find do |a|
+          a.name.split('::').include? 'Asynchronized'
+        end.must_be_nil
+      end
+    end
   end
 end

metadata

@@ -1,17 +1,74 @@
 --- !ruby/object:Gem::Specification
 name: asynchronize
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kenneth Cochran
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-04 00:00:00.000000000 Z
-dependencies: []
-description: Take any synchronous method, and run it asynchronously, without cluttering
-  your code with repetetive boilerplate.
+date: 2018-06-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: Sometimes you just want a regular thread without the overhead of a whole
+  new layer of abstraction. Asynchronize provides a declarative syntax to wrap any
+  method in a Thread.
 email: kenneth.cochran101@gmail.com
 executables: []
 extensions: []
@@ -26,7 +83,7 @@ homepage: https://github.com/kennycoc/asynchronize
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message: Making something cool with asynchronize? Let me know at https://github.com/kennycoc/asynchronize
 rdoc_options: []
 require_paths:
 - lib
@@ -34,7 +91,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -45,7 +102,7 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Easily make multiple methods asynchronous with one line of code.
+summary: A declarative syntax for creating multithreaded methods.
 test_files:
 - spec/spec.rb
 - spec/minitest_helper.rb