deferral 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4478021f73e80fbf08a0d2830543684653ea7513c836c7c03ae798b9fe96798
+  data.tar.gz: 78d3092455e200432ca094fef131875060330fe72d9ea4498b5c7e2485d43d9b
+SHA512:
+  metadata.gz: 33bdfd6fcd268d83299f9f7c78fe377e14ee041d00a65d2b0c19b556dbe9cc9bece3370089546ce619b857c89b7bc894a1e73987ebe564c44b2c483a218d6c19
+  data.tar.gz: 6375625cb220f0aa1f138e8c776591e9e226ed752d3ef0bda2e9583ac33f3649386e18e9360b69df84fab346bf38cf72e591a3613f8a014b43891035f099c61b

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in deferral.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,94 @@
+# Deferral - introduce golang style "defer" in Ruby
+
+```ruby
+# gem install deferral
+
+require "deferral"
+
+def my_method_name
+  # ...
+  file = File.open("my_file", "r")
+  Deferral.defer { file.close }
+
+  file.write "data..."
+  # ...
+end # `file.close` is called at the end of method (even when exception thrown)
+
+# or end of blocks
+def my_method_name(list)
+  # ...
+  list.each do |item|
+    file = File.open(item, "r")
+    Deferral.defer { file.close }
+
+    file.write "data..."
+    # ...
+  end # `file.close` is called at the end of block
+end
+
+require "deferral/toplevel"
+using Deferral::TopLevel
+# it makes "defer" without module name available everywhere in this file
+
+# or enable everywhere! (DANGER!)
+require "deferral/kernel_ext"
+```
+
+This gem provides a feature to release resources safely, using golang style `defer` method.
+
+`Deferral.defer` method does:
+
+* accept a block argument to execute at the end of caller scope
+* execute specified blocks in reverse order when getting out from specified scope
+
+Resource release blocks are called even when any exception occurs.
+
+See also [with_resources gem](https://github.com/tagomoris/with_resources) for try-with-resources style resource allocator.
+
+### 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.
+
+This library uses/enables TracePoint, and it may collapse optimizations of your Ruby runtime.
+
+## API
+
+* `Deferral.defer(&block)`
+
+This method registers a block to be called at the end of caller scope (end of method or block). Registered blocks will be called in reverse order (LIFO: last-in, first-out) when this method is called twice or more in a scope.
+
+### Introduce `defer` to top-level namespace
+
+Top-level `defer` is available via 2 different ways. One is using Refinements, another is modifying `Kernel` in open-class way.
+
+```ruby
+require "deferral/toplevel"
+using Deferral::TopLevel
+
+def my_method
+  f = AnyResource.new
+  defer { f.close }
+  # ...
+end
+```
+
+Refinements is a feature of Ruby to apply Module modification in just a file (by `using` statement).
+`using Deferral::TopLevel` introduces top level `defer` in safer way than modifying `Kernel`.
+
+```ruby
+require "deferral/kernel_ext"
+
+# now, "defer" is available everywhere...
+```
+
+Requiring `deferral/kernel_ext` modifies `Kernel` module globally to add `deferral`. It's not recommended in most cases.
+
+* * * * *
+
+## Authors
+
+* Satoshi Tagomori <tagomoris@gmail.com>
+
+## License
+
+MIT (See License.txt)

data/Rakefile

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

data/deferral.gemspec

@@ -0,0 +1,27 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "deferral/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "deferral"
+  spec.version       = Deferral::VERSION
+  spec.authors       = ["TAGOMORI Satoshi"]
+  spec.email         = ["tagomoris@gmail.com"]
+
+  spec.summary       = %q{Provide golang style defer method in Ruby}
+  spec.description   = %q{Provide a method to release/collect resources in deferred way}
+  spec.homepage      = "https://github.com/tagomoris/deferral"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "test-unit"
+end

data/lib/deferral.rb

@@ -0,0 +1,48 @@
+require "deferral/version"
+require "deferral/stack_frame"
+require "digest"
+
+module Deferral
+  ### Can't add "suppressed" information, because TracePoint doesn't provide
+  ### an exception was rescued or not after it was raised.
+  # module ErrorExt
+  #   def suppressed
+  #     @suppressed ||= []
+  #   end
+  # end
+
+  def self.defer(&block)
+    raise ArgumentError, "release block is not specified" unless block
+
+    store = (Thread.current[:deferral_store] ||= {})
+    if !store.empty? && !store[:stack].empty?
+      store[:stack].last.add(block)
+      return
+    end
+
+    stack = store[:stack] = [StackFrame.new(:root)] # root stack frame as first "caller" position of this method
+    first_return = true
+
+    trace = TracePoint.new(:call, :return, :b_call, :b_return) do |tp|
+      if tp.event == :return && first_return # return from this method
+        first_return = false
+        next
+      end
+
+      case tp.event
+      when :call, :b_call
+        stack << StackFrame.new(tp.event)
+      when :return, :b_return
+        frame = stack.pop
+        frame.release!
+        if frame.root?
+          trace.disable
+        end
+      else
+        raise "unexpected TracePoint event:#{tp.event}"
+      end
+    end
+    stack.last.add(block)
+    trace.enable
+  end
+end

data/lib/deferral/kernel_ext.rb

@@ -0,0 +1,7 @@
+require_relative "../deferral"
+
+module Kernel
+  def defer(&block)
+    Deferral.defer(&block)
+  end
+end

data/lib/deferral/stack_frame.rb

@@ -0,0 +1,31 @@
+module Deferral
+  class StackFrame
+    attr_reader :type, :id
+
+    def initialize(type)
+      @type = type
+      @releases = []
+    end
+
+    def root?
+      @type == :root
+    end
+
+    def add(release)
+      @releases << release
+    end
+
+    def release!
+      return if @releases.empty?
+      @releases.reverse.each do |r|
+        begin
+          r.call
+        rescue Exception => e
+          # ignore all exceptions ...
+          # no way to add "suppressed" exceptions to the exception already thrown
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/deferral/toplevel.rb

@@ -0,0 +1,9 @@
+require_relative "../deferral"
+
+module Deferral::TopLevel
+  refine Kernel do
+    def defer(&block)
+      Deferral.defer(&block)
+    end
+  end
+end

data/lib/deferral/version.rb

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

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: deferral
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TAGOMORI Satoshi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-03-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !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: Provide a method to release/collect resources in deferred way
+email:
+- tagomoris@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- deferral.gemspec
+- lib/deferral.rb
+- lib/deferral/kernel_ext.rb
+- lib/deferral/stack_frame.rb
+- lib/deferral/toplevel.rb
+- lib/deferral/version.rb
+homepage: https://github.com/tagomoris/deferral
+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.7.3
+signing_key: 
+specification_version: 4
+summary: Provide golang style defer method in Ruby
+test_files: []