fast_find 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9c5cd7c541e439cb4bd46acd6c28838e7867a369
+  data.tar.gz: 827db02601353683fd17828a779f71d5a282f80c
+SHA512:
+  metadata.gz: dd2cde72e12d19e762e9a6830f73c12024bab29cecdb7f439501627f0a4c306aafc7130bd2e3ac6344ea7e0b20b4c57c22510f2859cdfd5a2c37dc7935d93913
+  data.tar.gz: af278abe2c42f33cb905e227c389a4a8c0d73aa5c4b30eb7f08b479159a21049e59ba1353776888c72ac1a7dbef1135931b7439060adc07b804f4fd5c8fbadec

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.2

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Thomas Hurst
+
+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,87 @@
+# FastFind
+
+FastFind is a performance-oriented multi-threaded alternative to the standard
+`Find` module that ships with Ruby.  It should generally be a drop-in
+replacement.
+
+FastFind is expected to be marginally slower on MRI/YARV, since multithreaded
+`File#lstat` calls there appear to serialize.  However, using the FastFind-
+specific second argument to pass in the `File::Stat` object for each file may
+still prove a win.
+
+This code is considered experimental.  Beware of dog.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'fast_find', git: 'https://github.com/Freaky/fast_find.git'
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+Traditional Find-style:
+
+    FastFind.find(dir) {|entry| frob(entry) }
+    FastFind.find(dir, ignore_errors: false) { .. } # => explodes in your face
+    FastFind.find(dir) # => Enumerator
+
+Extended style using the second argument to get a `File::Stat`, or `Exception`
+object (if `ignore_errors` is false, this will be raised instead).
+
+    FastFind.find(dir) {|entry, stat| frob(entry, stat) }
+
+For increased performance and better scaling behaviour, it is recommended to use
+a single shared FastFind object.  Multiple concurrent calls to
+`FastFind::Finder#find` are safe and will share a persistant work pool.
+
+    Finder = FastFind::Finder.new
+    Finder.find(dir) { .. }
+
+You can call `Finder#shutdown` to close the work pool if you're done with the
+instance for the time being.  Ensure no other calls to its `#find` are in flight
+beforehand.  The pool is restarted the next time `#find` is called.
+
+Use the `concurrency` named argument to change the number of worker threads:
+
+    FastFind.find(dir, concurrency: 4)
+    FastFind::Finder.new(concurrency: 4)
+
+Defaults are `8` for Rubinius and JRuby, `1` for anything else.
+
+Note the yielded blocks are all executed in the parent thread, *not* in workers.
+
+`FastFind#prune` works.  So does `Find#prune`.
+
+## Performance
+
+Scanning a cached copy of the NetBSD CVS repository:
+
+jruby 9.0.1.0-SNAPSHOT (2.2.2) 2015-07-23 e88911e OpenJDK 64-Bit Server VM
+25.51-b03 on 1.8.0_51-b16 +jit [FreeBSD-amd64]:
+
+                   user     system      total        real
+    Find      32.890625  27.742188  60.632813 ( 47.518944)
+    FastFind  35.273438  41.742188  77.015625 (  8.140893)
+
+ruby 2.2.2p95 (2015-04-13 revision 50295) [x86_64-freebsd10.1]:
+
+                   user     system      total        real
+    Find      10.187500  22.351562  32.539062 ( 32.545201)
+    FastFind   9.039062  14.226562  23.265625 ( 23.277589)
+
+On MRI `Find` here is penalised because both `Find` and the benchmark code is
+performing a `File#lstat`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release` to create a git tag for the version, push git commits
+and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+	t.libs.push  'test'
+	t.pattern = 'test/test_*.rb'
+	t.warning = true
+	t.verbose = true
+end

data/bin/benchmark

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'find'
+require 'benchmark'
+
+require "bundler/setup"
+require 'fast_find'
+
+FastFinder = FastFind::Finder.new
+
+test_dirs = ARGV
+abort("Usage: #{$0} [dir1 [dir2[ ..]]]") if test_dirs.empty?
+
+Benchmark.bmbm do |b|
+	b.report("Find") do
+		files = Set.new
+		Find.find(*test_dirs) do |f|
+			files << [f, File.lstat(f)]
+		end
+	end
+
+	b.report("FastFind") do
+		files =  Set.new
+		FastFinder.find(*test_dirs) do |f, stat|
+			files << [f, stat]
+		end
+	end
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "fast_find"
+
+# 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

data/bin/setup

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

data/fast_find.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fast_find/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "fast_find"
+  spec.version       = FastFind::VERSION
+  spec.authors       = ["Thomas Hurst"]
+  spec.email         = ["tom@hur.st"]
+
+  spec.summary       = %q{High performance 'find' alternative.}
+  spec.description   = %q{FastFind is a find workalike which optionally passes
+                       in the File::Stat to the block, and can use multile
+                       threads to walk directories concurrently.}
+  spec.homepage      = "https://github.com/Freaky/fast_find"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.0"
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+end

data/lib/fast_find.rb

@@ -0,0 +1,158 @@
+#
+# fast_find.rb: A Find workalike optimized for performance.
+#
+
+require 'set'
+require 'thread'
+require 'fast_find/version'
+
+module FastFind
+	DEFAULT_CONCURRENCY = %w(jruby rbx).include?(RUBY_ENGINE) ? 8 : 1
+
+	def self.find(*paths, concurrency: DEFAULT_CONCURRENCY, ignore_error: true,
+	              &block)
+		Finder.new(concurrency: concurrency, one_shot: true)
+			.find(*paths, ignore_error: ignore_error, &block)
+	end
+
+	def self.prune
+		throw :prune
+	end
+
+	class Finder
+		def initialize(concurrency: DEFAULT_CONCURRENCY, one_shot: false)
+			@mutex       = Mutex.new
+			@queue       = Queue.new
+			@one_shot    = one_shot
+			@concurrency = concurrency
+			@walkers     = nil
+		end
+
+		def startup
+			@mutex.synchronize do
+				return if @walkers
+
+				@walkers = @concurrency.times.map { Walker.new.spawn(@queue) }
+			end
+		end
+
+		def shutdown
+			@mutex.synchronize do
+				return unless @walkers
+
+				@queue.clear
+				@walkers.each { @queue << nil }
+				@walkers.each(&:join)
+
+				@walkers = nil
+			end
+		end
+
+		def find(*paths, ignore_error: true, &block)
+			block or return enum_for(__method__, *paths, ignore_error: ignore_error)
+
+			results = Queue.new
+			pending = Set.new
+
+			startup
+
+			paths.map!(&:dup).each do |path|
+				path = path.to_path if path.respond_to? :to_path
+				results << [path, Util.safe_stat(path)]
+			end
+			results << [:initial, :finished]
+			pending << [:initial, :initial.encoding]
+
+			while result = results.deq
+				path, stat = result
+
+				if stat == :finished
+					pending.delete([path, path.encoding])
+
+					if pending.empty?
+						break
+					else
+						next
+					end
+				end
+
+				catch(:prune) do
+					yield_entry(result, block) if path.is_a? String
+
+					case stat
+					when Exception then raise stat unless ignore_error
+					when File::Stat
+						if stat.directory? and !pending.include?(pe = [path, path.encoding])
+							pending << pe
+							@queue << [path, results]
+						end
+					end
+				end
+			end
+		ensure
+			if one_shot?
+				@queue.clear
+				shutdown
+			end
+		end
+
+		private
+
+		def one_shot?() !!@one_shot end
+
+		def yield_entry(entry, block)
+			if block.arity == 2
+				block.call(entry[0].dup.taint, entry[1])
+			else
+				block.call entry[0].dup.taint
+			end
+		end
+	end
+
+	class Walker
+		def spawn(queue)
+			Thread.new do
+				@encoding = Encoding.find("filesystem")
+				while job = queue.deq
+					walk(job[0], job[1])
+				end
+			end
+		end
+
+		def walk(path, results)
+			enc = path.encoding == Encoding::US_ASCII ? @encoding : path.encoding
+
+			Dir.entries(path, encoding: enc).each do |entry|
+				next if entry == '.' or entry == '..'
+
+				stat(File.join(path, entry), results)
+			end
+		rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP,
+		       Errno::ENAMETOOLONG => e
+			error(e, results)
+		ensure
+			finish(path, results)
+		end
+
+		def stat(entry, results)
+			results << [entry, Util.safe_stat(entry)]
+		end
+
+		def finish(path, results)
+			results << [path, :finished]
+		end
+
+		def error(e, results)
+			results << [:exception, e]
+		end
+	end
+
+	module Util
+		def self.safe_stat(path)
+			File.lstat(path)
+		rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP,
+		       Errno::ENAMETOOLONG => e
+			e
+		end
+	end
+end

data/lib/fast_find/version.rb

@@ -0,0 +1,3 @@
+module FastFind
+  VERSION = "0.1.1"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: fast_find
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Thomas Hurst
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2015-08-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  name: bundler
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  name: rake
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: minitest
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |-
+  FastFind is a find workalike which optionally passes
+                         in the File::Stat to the block, and can use multile
+                         threads to walk directories concurrently.
+email:
+- tom@hur.st
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/benchmark
+- bin/console
+- bin/setup
+- fast_find.gemspec
+- lib/fast_find.rb
+- lib/fast_find/version.rb
+homepage: https://github.com/Freaky/fast_find
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.4.8
+signing_key:
+specification_version: 4
+summary: High performance 'find' alternative.
+test_files: []