hooker 1.0.1 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5b0d8be31cce91bd8b60f4e0bd5ceaa29ae29062
+  data.tar.gz: d3fcaef32aad0b808a9207dda29e1b7cf9567bb1
+SHA512:
+  metadata.gz: f4db4e60785200caf839f3b0560ad6c16a07e943d4fed0c65670c028734d615b59ecd26baf67b5bda25b5784749a022cb05354d6fbc5ae336f98db5f44c7e0bb
+  data.tar.gz: 9a1ad28dc7f66176f512b26e11c02511749cf00d716330438ef9178313f1814a70c2c32954e6130a45a1b1633f9d9ecf2fbd6796918199831f16c49e4f8f3aee

data/History.rdoc

@@ -1,3 +1,11 @@
+=== 1.1.0 (2013-12-6)
+* Thread safety: Hooker.with via thread-local and lock around common
+  structures. Note: It remains generally advisable to complete all
+  configurable application bootstrapping in the main thread whenever
+  possible.
+* Add Travis CI test setup (dev)
+* Upgrade to minitest ~> 4.7.4 (dev)
+
 === 1.0.1 (2012-9-12)
 * Ensure Errno::EISDIR when mistaken attempt to load a directory,
   i.e. "./config"

data/README.rdoc

@@ -1,6 +1,7 @@
 = Hooker
 
 * http://github.com/dekellum/hooker
+* {<img src="https://travis-ci.org/dekellum/hooker.png" />}[https://travis-ci.org/dekellum/hooker]
 
 == Description
 
@@ -17,24 +18,37 @@ and other ruby-based configuration files.
   Hooker.apply, Hooker.inject, Hooker.merge.
 * Hook Procs are executed only when applied by the extended
   application. Thus a single configuration source may include hook
-  Procs that are left unused in certain contexts. This is useful
+  Procs that are left un-executed in certain contexts. This is useful
   when configuring across several different (contextually loaded)
   modules from one source.
-* Optional or implicit scoping of keys, providing a two level
-  Hook [:scope, :key] hierarchy.
-* Provides an optional logging extension point Hooker.log_with
+* Optional or implicit scoping of keys, providing a two level Hook
+  <code>[:scope, :key]</code> hierarchy. The default scope is
+  <code>:default</code>.
+* Optional Hooker.log_with extension point
 * Can check and list hooks that were not applied, including the call
-  site of where added.
+  site of where added, allowing you to test your
+  configurations and avoid typos.
+* Thread safe (though you should strive to complete all configurable
+  bootstrapping in the main thread).
 
 == Synopsis
 
 Lets say an application has a 'Job' it would like to support
-hooks on:
+configuration hooks on. First arrange for any number of configuration
+sources to be loaded via Hooker.load_file. Then apply any loaded hook
+procs to an instance of your Job, like so:
 
+ require 'hooker'
+
+ Hooker.load_file( "config.rb" ) if File.exist?( "config.rb" )
  job = Hooker.apply( :job, Job.new )
 
-Then the following configuration of the job could optionally be loaded
-and applied to override Job defaults:
+You could also use Hooker.register_config with an OptionParser to
+support a <code>-c/--config FILE</code> flag for specifying the
+configuration source.
+
+If Job is to be configured via setters, then the configuration source
+might look like this:
 
  Hooker.with do |h|
    h.setup_job do |j|
@@ -43,8 +57,32 @@ and applied to override Job defaults:
    end
  end
 
-Hooker can be yielded to the config file via an alternative Module
-name, so as not to scare your mom, or to fully encapsulate its use:
+Alternatively, if Job takes a Hash on construction for configuration,
+use Hooker.merge like so:
+
+ opts = Hooker.merge( :job, { workers: 2 } ) #defaults
+ job = Job.new( opts )
+
+...and Hash syntax in the configuration source. Note that unlike JSON
+or YAML, the configuration remains fully interpreted for greater
+expressiveness, for example sharing variables across different
+configured objects:
+
+ Hooker.with do |h|
+   cpus = 3
+
+   h.setup_job do
+     { workers: cpus + 1,
+       timeout: 10 * 60 }
+   end
+
+   h.setup_connection_pool do
+     { size: cpus }
+   end
+ end
+
+Hooker can be yielded to the configuration source via an alternative
+Module.method name, to fully encapsulate its use:
 
  class Chaplain
    def self.configure( &block )
@@ -52,7 +90,7 @@ name, so as not to scare your mom, or to fully encapsulate its use:
    end
  end
 
-Supports the config:
+...supports the configuration source:
 
  Chaplain.configure do |c|
    c.setup_job do |j|
@@ -63,7 +101,7 @@ Supports the config:
 
 == License
 
-Copyright (c) 2011-2012 David Kellum
+Copyright (c) 2011-2013 David Kellum
 
 Licensed under the Apache License, Version 2.0 (the "License"); you
 may not use this file except in compliance with the License.  You

data/lib/hooker.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2011-2012 David Kellum
+# Copyright (c) 2011-2013 David Kellum
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you
 # may not use this file except in compliance with the License.  You may
@@ -15,6 +15,7 @@
 #++
 
 require 'hooker/base'
+require 'thread'
 
 # A registry of hooks, added and applied for indirect configuration
 # support.
@@ -24,19 +25,23 @@ module Hooker
 
     # Yields self under the given scope to block.
     def with( scp = :default )
-      prior, @scope = @scope, scp
+      prior = swap_scope( scp )
       yield self
     ensure
-      @scope = prior
+      swap_scope( prior )
     end
 
     # Add hook block by specified hook key. Will only be executed when
     # apply, inject, or merge is later called with the same key.
     # Multiple hook blocks for the same key will be called in the
     # order added.
-    def add( key, clr = nil, &block )
-      applied.delete( sk( key ) )
-      hooks[ sk( key ) ] << [ block, ( clr || caller.first ).to_s ]
+    def add( k, clr = nil, &block )
+      key = sk( k )
+      clr ||= caller.first
+      LOCK.synchronize do
+        applied.delete( key )
+        hooks[ key ] << [ block, clr.to_s ]
+      end
     end
 
     # Allow method setup_<foo> as alias for add( :foo )
@@ -51,24 +56,27 @@ module Hooker
     # Pass the specified initial value to each previously added Proc
     # with matching key and returns the mutated value.
     def apply( key, value )
-      applied << sk( key )
-      hooks[ sk( key ) ].each { |hook| hook[0].call( value ) }
-      value
+      sync_on_hooks( key ) do |hks|
+        hks.each { |hook| hook[0].call( value ) }
+        value
+      end
     end
 
     # Inject value (or nil) into the chain of previously added Procs,
     # which should implement binary operations, returning desired
     # value. Returns the last value from the last proc.
     def inject( key, value = nil )
-      applied << sk( key )
-      hooks[ sk( key ) ].inject( value ) { |v, hook| hook[0].call( v ) }
+      sync_on_hooks( key ) do |hks|
+        hks.inject( value ) { |v, hook| hook[0].call( v ) }
+      end
     end
 
     # Merge returned values from each added Proc to the initial value
     # (or empty Hash).
     def merge( key, value = {} )
-      applied << sk( key )
-      hooks[ sk( key ) ].inject( value ) { |v, hook| v.merge( hook[0].call ) }
+      sync_on_hooks( key ) do |hks|
+        hks.inject( value ) { |v, hook| v.merge( hook[0].call ) }
+      end
     end
 
     # Register to yield log messages to the given block.
@@ -109,14 +117,18 @@ module Hooker
     # hook key added but not applied.  Often this suggests a typo or
     # other mistake by the hook Proc author.
     def check_not_applied
-      ( hooks.keys - applied ).each do |rkey|
-        calls = hooks[ rkey ].map { |blk, clr| clr }
-        yield( rkey, calls )
+      LOCK.synchronize do
+        ( hooks.keys - applied ).each do |rkey|
+          calls = hooks[ rkey ].map { |blk, clr| clr }
+          yield( rkey, calls )
+        end
       end
     end
 
     private
 
+    LOCK = Mutex.new
+
     # Hash of hook keys to array of procs.
     def hooks
       @hooks ||= Hash.new { |h, k| h[k] = [] }
@@ -129,9 +141,11 @@ module Hooker
 
     # Clears all Hooker state.
     def clear
-      @hooks = nil
-      @applied = nil
-      @logger = nil
+      LOCK.synchronize do
+        @hooks = nil
+        @applied = nil
+        @logger = nil
+      end
     end
 
     def log( msg )
@@ -142,12 +156,32 @@ module Hooker
       if key.is_a?( Array ) && ( key.length == 2 )
         key
       else
-        [ @scope, key ]
+        [ scope, key ]
       end
     end
 
-  end
+    def scope
+      Thread.current[:hooker_scope] || :default
+    end
 
-  @scope = :default
+    def swap_scope( s )
+      old = scope
+      Thread.current[:hooker_scope] = s
+      old
+    end
+
+    def sync_on_hooks( k )
+      key = sk( k )
+      LOCK.synchronize do
+        begin
+          yield hooks[ key ]
+        ensure
+          applied << key
+        end
+      end
+
+    end
+
+  end
 
 end

data/lib/hooker/base.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2011-2012 David Kellum
+# Copyright (c) 2011-2013 David Kellum
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you
 # may not use this file except in compliance with the License.  You may
@@ -16,5 +16,5 @@
 
 module Hooker
   # Hooker version
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

data/test/setup.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2011-2012 David Kellum
+# Copyright (c) 2011-2013 David Kellum
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you
 # may not use this file except in compliance with the License.  You

data/test/test_hooker.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env jruby
 #.hashdot.profile += jruby-shortlived
 #--
-# Copyright (c) 2011-2012 David Kellum
+# Copyright (c) 2011-2013 David Kellum
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you
 # may not use this file except in compliance with the License.  You
@@ -21,6 +21,7 @@ TESTDIR = File.dirname( __FILE__ )
 require File.join( TESTDIR, "setup" )
 
 require 'hooker'
+require 'thread'
 
 # An alternative entry point from top level
 class Chaplain
@@ -112,6 +113,9 @@ class TestContext < MiniTest::Unit::TestCase
 
     assert_equal( [ [ :test_scope, :not_used ] ], not_used_keys )
     assert_equal( 2, not_used_calls.length )
+    not_used_calls.each_with_index do |cl, i|
+      assert_match( /test_check_not_applied/, cl, i )
+    end
 
     Hooker.log_not_applied
   end
@@ -147,4 +151,22 @@ class TestContext < MiniTest::Unit::TestCase
     end
   end
 
+  def test_threaded_with
+    Hooker.with( :t1 ) { |h| h.add( :common ) { :t1 } }
+    Hooker.with( :t2 ) { |h| h.add( :common ) { :t2 } }
+
+    threads = 11.times.map do |i|
+      Thread.new do
+        Hooker.with( i.even? ? :t1 : :t2 ) do
+          sleep( rand * 0.100 )
+          Hooker.inject( :common )
+        end
+      end
+    end
+
+    11.times do |i|
+      assert_equal( i.even? ? :t1 : :t2, threads[i].value, "thread #{i}" )
+    end
+  end
+
 end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hooker
 version: !ruby/object:Gem::Version
-  prerelease:
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - David Kellum
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2012-09-13 00:00:00.000000000 Z
+date: 2013-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -17,14 +16,12 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.3'
-    none: false
+        version: 4.7.4
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.3'
-    none: false
+        version: 4.7.4
   prerelease: false
   type: :development
 - !ruby/object:Gem::Dependency
@@ -33,14 +30,12 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.0'
-    none: false
+        version: '2.1'
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.0'
-    none: false
+        version: '2.1'
   prerelease: false
   type: :development
 description: Hooker provides a simple registry of hooks or extension points, enabling decoupled run time configuration in terse but straight ruby syntax. Inspiration includes Emacs Hook Functions and other ruby-based configuration files.
@@ -65,6 +60,7 @@ files:
 - test/test_load_dir/placeholder
 homepage: http://github.com/dekellum/hooker
 licenses: []
+metadata: {}
 post_install_message:
 rdoc_options:
 - --main
@@ -73,27 +69,18 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2
-  none: false
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2
-  none: false
 requirements: []
 rubyforge_project:
-rubygems_version: 1.8.24
+rubygems_version: 2.1.9
 signing_key:
-specification_version: 3
+specification_version: 4
 summary: Hooker provides a simple registry of hooks or extension points, enabling decoupled run time configuration in terse but straight ruby syntax.
 test_files: []
-...