with_resources 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2b79f87e6ba35615184c783feba8e563a5302c73
+  data.tar.gz: 952d7783252f8b56c9d3d64e2c09a4fe42ba4ded
+SHA512:
+  metadata.gz: a172db7c0cc1745e8827e7c4266555083381c16768350619847f50528438d1d280de472688b39d79ef2ba044f04fb75e0eebbf17c37f18a51fd04b500ba07c6a
+  data.tar.gz: 9983858d0bdd1723d055b676e1ce22ba77d2d229154eb9963488926b90cdaa6c5fdee5b4152fc14e6f7279371ddecfe116e20807a3a01edbe81beceee93cf042

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in with_resources.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2017- Satoshi Tagomori
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# with_resources: Add "with" statement in your Ruby script
+
+```ruby
+# gem install with_resources
+
+require "with_resources"
+
+WithResourecs.with(->(){
+    sock = TCPSocket.open("dest.example.com", port)
+    httpclient = MyHTTPClient.new(sock) 
+}) do |sock, httpclient|
+    # ...
+    # httpclient.close # will be called automatically
+    # sock.close
+end
+
+require "with_resources/toplevel"
+
+using WithResources::TopLevel
+# it makes "with" available in this file
+
+with(->(){ a = One.new; b = Another.new(a) }) do |a, b|
+    # ...
+end
+
+# or enable everywhere! (DANGER!)
+require "with_resources/kernel_ext"
+```
+
+This gem provides a feature to allocate/release resource objects safely.
+This feature is widely known as 'try-with-resources' (Java), 'with' statement (Python), 'using' statement (C#) and many others.
+
+`WithResources.with` method does:
+
+* accept a lambda argument to allocate resources
+* accept a block to be called
+* release allocated resources automatically after block is processed in reverse order of allocated order
+
+All allocated resources will be released even when any errors are raised in block, in `obj.close` or in allocating another resources.
+
+### Disclosure
+
+This library is a kind of PoC to introduce safe resource allocation in Ruby world. Take care about using this library in your production environment.
+
+## API
+
+* `WithResources.with(lambda_to_allocate, release_method: :close, &block)`
+
+All values assigned into local variable in `lambda_to_allocate` will be passed to `block` as block arguments. (Don't re-assign values into same local variable, neither undefine local variable, in that labmda.)
+
+It can accept `release_method` keyword argument to specify the method name to release resources. The specified method will be called in release stage, without any arguments. It's impossible to specify different method names for resources.
+
+### Introduce `with` to top-level namespace
+
+Top level `with` is available via 2 different ways. One is using Refinements, another is modifying `Kernel` in open-class way.
+
+```ruby
+require "with_resources/toplevel"
+using WithResources::TopLevel
+
+with(->(){ r = create_resource() }) do |r|
+    # ...
+end
+```
+
+Refinements is a feature of Ruby to apply Module modification in just a file (by `using` statement).
+`using WithResources::TopLevel` introduces top level `with` in safer way than modifying `Kernel`.
+
+```ruby
+require "with_resource/kernel_ext"
+
+# now, "with" is available everywhere...
+```
+
+Requiring `with_resource/kernel_ext` modifies `Kernel` module globally to add `with`. It's not recommended in most cases.
+
+## Performance
+
+Because of some magical hacks, `with` has performance overhead.
+
+The benchmark score below shows the difference of performances between standard `begin-ensure` and `with` (elasped seconds by 10,000 times). Benchmark script is available at `misc/bench.rb`.
+
+```
+       user     system      total        real
+begin  0.040000   0.000000   0.040000 (  0.037753)
+with   1.400000   0.010000   1.410000 (  1.423388)
+```
+
+It's not so huge overhead in actual application, but it might be better to use `with` in heavy loops.
+
+* * * * *
+
+## Authors
+
+* Satoshi Tagomori <tagomoris@gmail.com>
+
+## License
+
+MIT (See License.txt)

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.test_files = FileList['test/**/*.rb']
+  test.verbose = true
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "with_resources"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/with_resources.rb

@@ -0,0 +1,71 @@
+require "with_resources/version"
+
+module WithResources
+  module ErrorExt
+    def suppressed
+      @suppressed ||= []
+    end
+  end
+
+  def self.with(allocation, release_method: :close, &block)
+    var_names = []
+    vars = {}
+
+    allocation_block_path = nil
+    allocation_block_lineno = nil
+
+    trace = TracePoint.new(:line, :b_return) do |tp|
+      if tp.event == :line && !tp.path.end_with?("lib/with_resources.rb") && allocation_block_path.nil?
+        allocation_block_path = tp.path
+        allocation_block_lineno = tp.lineno
+      end
+      if tp.event == :line && tp.path == allocation_block_path && tp.lineno >= allocation_block_lineno
+        tp_binding = tp.binding
+        tp_variables = tp_binding.local_variables
+        if var_names.all?{|resource_var| tp_variables.include?(resource_var) }
+          # hit! this block is resource allocation block
+          tp_variables.each do |name|
+            unless var_names.include?(name)
+              var_names << name
+            end
+          end
+        end
+      end
+      if tp.event == :b_return && tp.path == allocation_block_path && tp.lineno >= allocation_block_lineno
+        tp_binding = tp.binding
+        var_names.each do |name|
+          vars[name] = tp_binding.local_variable_get(name)
+        end
+      end
+    end
+
+    error = nil
+    return_value = nil
+    begin
+      trace.enable do
+        allocation.call
+      end
+      return_value = block.call(*vars.values)
+    rescue => e
+      error = e
+      error.extend(ErrorExt)
+    ensure
+      vars.values.reverse.each do |v|
+        if v.respond_to?(release_method)
+          begin
+            v.send(release_method)
+          rescue => e
+            if error
+              error.suppressed << e
+            else
+              error = e
+              error.extend(ErrorExt)
+            end
+          end
+        end
+      end
+    end
+    raise error if error
+    return_value
+  end
+end

data/lib/with_resources/kernel_ext.rb

@@ -0,0 +1,7 @@
+require_relative "../with_resources"
+
+module Kernel
+  def with(alloc, &block)
+    WithResources.with(alloc, &block)
+  end
+end

data/lib/with_resources/toplevel.rb

@@ -0,0 +1,9 @@
+require_relative "../with_resources"
+
+module WithResources::TopLevel
+  refine Kernel do
+    def with(alloc, &block)
+      WithResources.with(alloc, &block)
+    end
+  end
+end

data/lib/with_resources/version.rb

@@ -0,0 +1,3 @@
+module WithResources
+  VERSION = "0.1.0"
+end

data/misc/bench.rb

@@ -0,0 +1,37 @@
+require "benchmark"
+
+require "with_resources/toplevel"
+using WithResources::TopLevel
+
+n = 100_000
+
+class Resource
+  def close
+    # do nothing
+  end
+end
+
+Benchmark.bm do |x|
+  x.report("begin") do
+    for i in 1..n
+      begin
+        a = Resource.new
+        begin
+          b = Resource.new
+        ensure
+          b.close
+        end
+      ensure
+        a.close
+      end
+    end
+  end
+
+  x.report("with") do
+    for i in 1..n
+      with(->(){ a = Resource.new; b = Resource.new }) do |a, b|
+        # nothing
+      end
+    end
+  end
+end

data/with_resources.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'with_resources/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "with_resources"
+  spec.version       = WithResources::VERSION
+  spec.authors       = ["TAGOMORI Satoshi"]
+  spec.email         = ["tagomoris@gmail.com"]
+
+  spec.summary       = %q{Introduce "with" statement.}
+  spec.description   = %q{The library to provide "with" statement to allocate and release resources safely.}
+  spec.homepage      = "https://github.com/tagomoris/with_resources"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "test-unit"
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: with_resources
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TAGOMORI Satoshi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  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: The library to provide "with" statement to allocate and release resources
+  safely.
+email:
+- tagomoris@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/with_resources.rb
+- lib/with_resources/kernel_ext.rb
+- lib/with_resources/toplevel.rb
+- lib/with_resources/version.rb
+- misc/bench.rb
+- with_resources.gemspec
+homepage: https://github.com/tagomoris/with_resources
+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.6.13
+signing_key: 
+specification_version: 4
+summary: Introduce "with" statement.
+test_files: []