auto_reloader 0.2.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fe07852820635d96113ac46d70341b88a25bc229
-  data.tar.gz: c269465db561170e62fbc72edfb39e056550b8dd
+  metadata.gz: b42889c4bcc15ca1ea692a102bcb218407d0c035
+  data.tar.gz: 691c8f940b95e40ecb067b51d86bcd7f479589d0
 SHA512:
-  metadata.gz: 2a4fabc3d94d9f355d523635cfa560413e487c05cee3422739ce353cbdc68bb1a6913a2cba5ab7e919c0d3b158fdf992f911d4fe850d8dcfa54e8c6d2d27a919
-  data.tar.gz: 407453e32124a922ae721c3cd543f13e335fe2e39b892f2b8888a40988b258d8a8fe8a95135d936580b0eb736af8d5080a6f61c1ef76de256766426eb17ee01c
+  metadata.gz: d5bfbc0440e93e598cd4c433564e570bdfcfc7b0d9e37aa7aad9bf14135b5ba0b25a9a1b2478729a937654373a736701428c654125bb9e6e5d51a3f2c8de9130
+  data.tar.gz: 23ba39d8a90edb4b96da5facb262bba884f02a86aa6be21271230e24d580c9735ec78444dd13fb99360da88265ca119010821dfbda62874f9d98fb7a09db2e82

data/README.md

@@ -77,6 +77,27 @@ Listen.to(File.expand_path('config', __dir__)) do |added, modified, removed|
 end
 ```
 
+## Thread-safety
+
+In order for the automatic constants and required files detection to work correctly it should
+process a single require at a time. If your code has multiple threads requiring code, then it
+might cause a race condition that could cause unexpected bugs to happen in AutoReloader. This
+is the default behavior because it's not common to call require from multiple threads in the
+development environment but adding a monitor around require could create a dead-lock which is
+a more serious issue.
+
+For example, if requiring a file would start a web server and block, if the web server is
+started in a separate thread (which could be joined so that the require doesn't return), then
+it wouldn't be able to require new files because the lock was acquired by another thread and
+won't be released while the web server is running.
+
+If you are sure that no require should block in your application (which is also common), you're
+encouraged to call `AutoReloader.sync_require!`. Or pass `sync_require: true` to
+`AutoReloader.activate`. You may even control this behavior dynamically so that you call
+`AutoReloader.async_require!` before the blocking require and then reenable the sync behavior.
+The sync behavior will ensure no race conditions that would break the automatic detection
+mechanism would ever happen.
+
 ## Known Caveats
 
 In order to work transparently AutoReloader will override `require` and `require_relative` when

data/lib/auto_reloader/version.rb

@@ -1,3 +1,3 @@
 class AutoReloader
-  VERSION = '0.2.6'
+  VERSION = '0.3.0'
 end

data/lib/auto_reloader.rb

@@ -15,7 +15,7 @@ class AutoReloader
   attr_reader :reloadable_paths, :default_onchange, :default_delay
 
   def_delegators :instance, :activate, :reload!, :reloadable_paths, :reloadable_paths=,
-    :unload!, :force_next_reload
+    :unload!, :force_next_reload, :sync_require!, :async_require!
 
   module RequireOverride
     def require(path)
@@ -35,13 +35,13 @@ class AutoReloader
 
   ActivatedMoreThanOnce = Class.new RuntimeError
   def activate(reloadable_paths: [], onchange: true, delay: nil, watch_paths: nil,
-              watch_latency: 1)
+              watch_latency: 1, sync_require: false)
     @activate_lock.synchronize do
       raise ActivatedMoreThanOnce, 'Can only activate Autoreloader once' if @reloadable_paths
       @default_delay = delay
       @default_onchange = onchange
       @watch_latency = watch_latency
-      @require_lock = Monitor.new # monitor is like Mutex, but reentrant
+      sync_require! if sync_require
       @reload_lock = Mutex.new
       @top_level_consts_stack = []
       @unload_constants = Set.new
@@ -53,6 +53,25 @@ class AutoReloader
     end
   end
 
+  # when concurrent threads require files race conditions may prevent the automatic detection
+  # of constants created by a given file. Calling sync_require! will ensure only a single file
+  # is required at a single time. However, if a required file blocks (think of a web server)
+  # then any requires by a separate thread would be blocked forever (or until the web server
+  # shutdowns). That's why require is async by default even though it would be vulnerable to
+  # race conditions.
+  def sync_require!
+    @require_lock ||= Monitor.new # monitor is like Mutex, but reentrant
+  end
+
+  # See the documentation for sync_require! to understand the reasoning. Async require is the
+  # default behavior but could lead to race conditions. If you know your requires will never
+  # block it may be a good idea to call sync_require!. If you know what require will block you
+  # can call async_require!, require it, and then call sync_require! which will generate a new
+  # monitor.
+  def async_require!
+    @require_lock = nil
+  end
+
   def reloadable_paths=(paths)
     @reloadable_paths = paths.map{|rp| File.expand_path(rp).freeze }.freeze
     setup_listener if @watch_paths
@@ -61,7 +80,7 @@ class AutoReloader
   def require(path, &block)
     was_required = false
     error = nil
-    @require_lock.synchronize do
+    maybe_synchronize do
       @top_level_consts_stack << Set.new
       old_consts = Object.constants
       prev_consts = new_top_level_constants = nil
@@ -90,6 +109,10 @@ class AutoReloader
     was_required
   end
 
+  def maybe_synchronize(&block)
+    @require_lock ? @require_lock.synchronize(&block) : yield
+  end
+
   def require_relative(path, fullpath)
     require(fullpath){ Kernel.require fullpath }
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: auto_reloader
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.3.0
 platform: ruby
 authors:
 - Rodrigo Rosenfeld Rosas