bigcommerce-multitrap 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0f6b5bf04d0745286817f5a37fadaf83bd98a0785e6e315225768862d2ce158b
+  data.tar.gz: 2372b5016ab0893e62d0daaf938387303f428536c5bfb9f8b7506fd0765ba4fd
+SHA512:
+  metadata.gz: 62e88d91945e55594e7dd966bd2346b726f815c8bdd957b67804d38098980e9afe4fb51620cb49b8fd4e56d67cd5f9e4222d3a8283e5713c6a0d8d1f48d74b3d
+  data.tar.gz: a17fb32de84c9939d26d11832f206e64a036712f78975660e83407d872b8903a7fb5b5abcf13e8608adf8688629809286f15289079db920ccb2893a6c8534b1a

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+Multitrap changelog
+===================
+
+### v0.1.0 (August, 9, 2015)
+
+* Added support for JRuby
+* Added support for Rubinius
+* Added support for CRuby 1.9
+* Added support for symbols as signal keys ([#1](https://github.com/kyrylo/multitrap/issues/1))
+* Added support for previously defined signals ([#2](https://github.com/kyrylo/multitrap/issues/2))
+* Changed order of execution of handlers (FIFO now)
+
+### v0.0.1 (September 7, 2014)
+
+* Initial release

data/README.md

@@ -0,0 +1,160 @@
+Multitrap
+=========
+
+[![CircleCI](https://circleci.com/gh/bigcommerce/multitrap.svg?style=svg&circle-token=dc30a5b0d61a77d3547b795cca663e9309cf8cc0)](https://circleci.com/gh/bigcommerce/multitrap)
+
+Introduction
+------------
+
+By default, all Ruby implementations allow you to attach only one signal handler
+per signal (via `Signal.trap` aka `trap`). This is not very useful, if you want
+to perform multiple actions. Whenever you define a new signal handler, it sends
+shivers down your spine, because you never know if you're overwriting someone
+else's handler (usually, the handler of a library you depend on). Well, now you
+don't have to worry about that anymore, because Multitrap solved this problem
+for you! Define as many handlers as you wish and be sure they will all execute.
+
+Examples
+--------
+
+### Basic example
+
+To use Multitrap just `require` it. No additional configuration is
+needed. Internally, the library _redefines_ `trap`. The last defined signal
+handler executes first.
+
+```ruby
+require 'bigcommerce/multitrap'
+
+trap(:INT) { puts 111 }
+trap(:INT) { puts 222 }
+trap(:INT) { puts 333 }
+
+Process.kill(:INT, $$)
+
+# Outputs:
+# 333
+# 222
+# 111
+```
+
+### Nested traps
+
+The library aims to be compatible with every Ruby implementation. For example,
+JRuby doesn't support nested traps, but Rubinius and CRuby do. Multitrap obeys
+this behaviour.
+
+```ruby
+require 'bigcommerce/multitrap'
+
+a = nil
+
+trap(:INT) do
+  a = 1
+  trap(:INT) do
+    a = 2
+  end
+end
+
+puts a #=> nil
+
+# On JRuby `a` will always be equal to 1.
+Process.kill(:INT, $$)
+puts a #=> 1
+
+# CRuby and Rubinius will continue executing nested traps.
+Process.kill(:INT, $$)
+puts a #=> 2
+
+Process.kill(:INT, $$)
+puts a #=> 2
+```
+
+### Return value
+
+With Multitrap, the `trap` method returns a hash with callbacks.
+
+```ruby
+require 'pp'
+require 'bigcommerce/multitrap'
+
+trap(:INT) {}
+trap(:HUP) {}
+3.times do
+  trap(:USR1) {}
+end
+handlers = trap(:USR2) {}
+
+puts handlers
+#=> {"INT"=>[#<Proc:0x00556161d34da8@test.rb:4>],
+     "HUP"=>[#<Proc:0x00556161d34420@test.rb:5>],
+     "USR1"=>
+      [#<Proc:0x00556161d36a68@test.rb:7>,
+       #<Proc:0x00556161d33750@test.rb:7>,
+       #<Proc:0x00556161d33048@test.rb:7>],
+     "USR2"=>[#<Proc:0x00556161d32ad0@test.rb:9>]}
+```
+
+You can access this hash to modify the handlers at runtime (but be extremely
+careful about that). For example, imagine if you write a test for your program's
+`:INT` signal handler and use RSpec. RSpec defines its own `:INT` handler and
+with the default `trap` you would simply overwrite it. With Multitrap you can
+remove the handler from the hash and then append it later.
+
+```ruby
+require 'spec_helper'
+require 'multitrap'
+
+RSpec.describe MyLibrary do
+  it "works" do
+    a = nil
+    handlers = trap(:INT) { a = 1 }
+
+    # Store the RSpecs handler. Usually, it's the first element in the array.
+    rspec_handler = handlers['INT'].shift
+
+    Process.kill(:INT, $$)
+    expect(a).to eq(1)
+
+    # Restore the handler.
+    handlers['INT'].unshift(rspec_handler)
+  end
+end
+```
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'multitrap'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install multitrap
+
+Limitations
+-----------
+
+### Rubies
+
+* CRuby 1.9.2 >=
+* Rubinius 2.5.8 >= (may work on older versions, untested)
+* JRuby 9.0.0.0 >= (shouldn't work on older versions)
+
+Roadmap
+-------
+
+### Provide consistency
+
+I'm not sure we need this, but it would be possible to remove inconsistencies
+with respect to nested traps on all Ruby platforms.
+
+License
+-------
+
+The project uses the MIT License. See LICENSE.txt file for more information.

data/bigcommerce-multitrap.gemspec

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |s|
+  s.name         = 'bigcommerce-multitrap'
+  s.version      = File.read('VERSION')
+  s.date         = Time.now.strftime('%Y-%m-%d')
+  s.summary      = 'Allows Signal.trap to have multiple callbacks'
+  s.authors      = ['Kyrylo Silin', 'Shaun McCormick']
+  s.email        = %w[silin@kyrylo.org shaun.mccormick@bigcommerce.com]
+  s.homepage     = 'https://github.com/kyrylo/multitrap'
+  s.licenses     = 'MIT'
+
+  s.files         = Dir['README.md', 'CHANGELOG.md', 'CODE_OF_CONDUCT.md', 'lib/**/*', 'bigcommerce-multitrap.gemspec']
+  s.require_paths = ['lib']
+  s.test_files   = s.files.grep(%r{^(test|spec|features)/})
+
+  s.add_development_dependency 'pry', '~> 0.12'
+  s.add_development_dependency 'rake', '~> 13.0'
+  s.add_development_dependency 'rspec', '~> 3.9'
+  s.add_development_dependency 'rspec_junit_formatter', '>= 0.4'
+  s.add_development_dependency 'rspec-wait', '~> 0.0.9'
+end

data/lib/bigcommerce-multitrap.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'bigcommerce/multitrap'

data/lib/bigcommerce/multitrap.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'thread'
+
+module Bigcommerce
+  module Multitrap
+    # The VERSION file must be in the root directory of the library.
+    VERSION_FILE = File.expand_path('../../../VERSION', __FILE__)
+
+    VERSION = File.exist?(VERSION_FILE) ? File.read(VERSION_FILE).chomp : '(could not find VERSION file)'
+
+    def self.jruby?
+      RUBY_ENGINE == 'jruby'
+    end
+
+    def self.mri?
+      RUBY_ENGINE == 'ruby'
+    end
+
+    def self.rbx?
+      RUBY_ENGINE == 'rbx'
+    end
+  end
+end
+
+require_relative 'multitrap/trap'
+require_relative 'multitrap/patched_trap'
+require_relative 'multitrap/core_ext'

data/lib/bigcommerce/multitrap/core_ext.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+case RUBY_ENGINE
+when 'ruby'
+  [Kernel, Kernel.singleton_class, Signal, Signal.singleton_class].each do |klass|
+    klass.__send__(:include, Bigcommerce::Multitrap::PatchedTrap)
+  end
+when 'rbx'
+  Signal.__send__(:include, Bigcommerce::Multitrap::PatchedTrap)
+  Signal.singleton_class.__send__(:include, Bigcommerce::Multitrap::PatchedTrap)
+when 'jruby'
+  Signal.singleton_class.__send__(:include, Bigcommerce::Multitrap::PatchedTrap)
+end

data/lib/bigcommerce/multitrap/patched_trap.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Multitrap
+    module PatchedTrap
+      def self.included(mod)
+        original_trap = Signal.method(:trap)
+
+        mod.instance_eval do
+          define_method(:trap) do |*args, &block|
+            if args.size < 1
+              if Bigcommerce::Multitrap.rbx?
+                raise ArgumentError, "method 'trap': given 0, expected 2"
+              elsif Bigcommerce::Multitrap.jruby?
+                raise ArgumentError, "wrong number of arguments (0 for 1)"
+              else
+                raise ArgumentError, "wrong number of arguments (0 for 1..2)"
+              end
+            end
+
+            if block.nil?
+              if Bigcommerce::Multitrap.rbx? && !args[1].respond_to?(:call)
+                raise ArgumentError, "Handler must respond to #call (was #{args[1].class})"
+              elsif args[1].nil?
+                raise ArgumentError, 'tried to create Proc object without a block'
+              end
+            end
+
+            Bigcommerce::Multitrap::Trap.trap(original_trap, *args, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bigcommerce/multitrap/trap.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Multitrap
+    class Trap
+      OWN_MRI_FRAME = %r{/lib/multitrap/trap.rb:[0-9]{1,3}:in `block in store_trap'}
+
+      OWN_RBX_FRAME = %r{/lib/multitrap/trap.rb:[0-9]{1,3}:in `store_trap'}
+
+      TRAVIS_FRAME = %r{lib/jruby\.jar!/jruby/kernel/signal\.rb}
+
+      RESERVED_SIGNALS = %w|BUS SEGV ILL FPE VTALRM|
+
+      KNOWN_SIGNALS = Signal.list.keys - RESERVED_SIGNALS
+
+      def self.trap(original_trap, *args, &block)
+        @@multitrap ||= new(original_trap)
+
+        signal = args[0]
+        command = args[1]
+
+        @@multitrap.store_trap(signal, command, &block)
+      end
+
+      def self.__clear_all_handlers!
+        @@multitrap ||= nil
+        @@multitrap && @@multitrap.__clear_all_handlers!
+      end
+
+      def initialize(original_trap)
+        @original_trap = original_trap
+        @trap_list = create_trap_list
+      end
+
+      def store_trap(signal, command, &block)
+        signal = signal.to_s
+        command ||= block
+
+        trap_is_nested = nested_trap?
+
+        if trap_is_nested
+          # JRuby doesn't support nested traps.
+          return if Multitrap.jruby?
+          @trap_list[signal].pop
+        end
+
+        @trap_list[signal] << command
+
+        prev_trap_handler = @original_trap.call(signal) do |signo|
+          @trap_list[signal].reverse_each do |trap_handler|
+            trap_handler.call(signo || Signal.list[signal]) if trap_handler.respond_to?(:call)
+          end
+        end
+
+        if !trap_is_nested &&
+           @trap_list[signal].size == 1 &&
+           !default_handler?(prev_trap_handler) &&
+           !default_handler_path?(prev_trap_handler)
+          @trap_list[signal].unshift(prev_trap_handler)
+        end
+
+        @trap_list
+      end
+
+      def __clear_all_handlers!
+        @trap_list.keys.select {|s| KNOWN_SIGNALS.include?(s) }.each do |signal|
+          @original_trap.call(signal, 'DEFAULT')
+        end
+
+        @trap_list = create_trap_list
+      end
+
+      private
+
+      define_method(:nested_trap?) do
+        case RUBY_ENGINE
+        when 'ruby'
+          caller.any? { |stackframe| stackframe =~ OWN_MRI_FRAME }
+        when 'rbx'
+          caller.grep(OWN_RBX_FRAME).size > 1
+        when 'jruby'
+          if caller.any? { |stackframe| stackframe =~ TRAVIS_FRAME }
+            caller.grep(OWN_RBX_FRAME).size > 1
+          else
+            caller.grep(OWN_MRI_FRAME).size > 1
+          end
+        else
+          raise NotImplementedError, 'unsupported Ruby engine'
+        end
+      end
+
+      def create_trap_list
+        Hash.new { |h, k| h[k] = [] }
+      end
+
+      def default_handler?(prev)
+        %w[DEFAULT SYSTEM_DEFAULT IGNORE].any? { |h| h == prev }
+      end
+
+      def default_handler_path?(prev)
+        [%r{Proc:.+@kernel/loader\.rb:[0-9]{1,4}},
+         %r{Proc:.+@uri:classloader:/jruby/kernel/signal.rb:[0-9]{1,4}}].any? do |h|
+          h =~ prev.to_s
+         end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: bigcommerce-multitrap
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Kyrylo Silin
+- Shaun McCormick
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: rspec-wait
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+description: 
+email:
+- silin@kyrylo.org
+- shaun.mccormick@bigcommerce.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- bigcommerce-multitrap.gemspec
+- lib/bigcommerce-multitrap.rb
+- lib/bigcommerce/multitrap.rb
+- lib/bigcommerce/multitrap/core_ext.rb
+- lib/bigcommerce/multitrap/patched_trap.rb
+- lib/bigcommerce/multitrap/trap.rb
+homepage: https://github.com/kyrylo/multitrap
+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: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: Allows Signal.trap to have multiple callbacks
+test_files: []