README.markdown in in_threads-1.3.1 vs README.markdown in in_threads-1.4.0
- old
+ new
@@ -1,41 +1,99 @@
[](https://rubygems.org/gems/in_threads)
[](https://travis-ci.org/toy/in_threads)
[](https://codeclimate.com/github/toy/in_threads)
[](https://gemnasium.com/toy/in_threads)
-[](http://inch-ci.org/github/toy/in_threads)
+[](https://inch-ci.org/github/toy/in_threads)
# in_threads
-Easily execute ruby code in parallel.
+Easily execute Ruby code in parallel.
+```ruby
+urls.in_threads(20).map do |url|
+ HTTP.get(url)
+end
+```
+
## Installation
- gem install in_threads
+Add the gem to your Gemfile...
+```ruby
+gem 'in_threads'
+```
+
+...and install it with [Bundler](http://bundler.io).
+
+```sh
+$ bundle install
+```
+
+Or, if you don't use Bundler, install it globally:
+
+```sh
+$ gem install in_threads
+```
+
## Usage
-By default there is maximum of 10 simultaneous threads
+Let's say you have a list of web pages to download.
- urls.in_threads.map do |url|
- url.fetch
- end
+```ruby
+urls = [
+ "https://google.com",
+ "https://en.wikipedia.org/wiki/Ruby",
+ "https://news.ycombinator.com",
+ "https://github.com/trending"
+]
+```
- urls.in_threads.each do |url|
- url.save_to_disk
- end
+You can easily download each web page one after the other.
- numbers.in_threads(2).map do |number|
- # whery long and complicated formula
- # using only 2 threads
- end
+```ruby
+urls.each do |url|
+ HTTP.get(url)
+end
+```
-You can use any Enumerable method, but some of them can not use threads (`inject`, `reduce`) or don't use blocks (`to_a`, `entries`, `drop`, `take`, `first`, `include?`, `member?`) or have both problems depending on usage type (`min`, `max`, `minmax`, `sort`)
+However, this is slow, especially for a large number of web pages. Instead,
+download the web pages in parallel with `in_threads`.
- urls.in_threads.any?(&:ok?)
- urls.in_threads.all?(&:ok?)
- urls.in_threads.none?(&:error?)
- urls.in_threads.grep(/example\.com/, &:fetch)
+```ruby
+require 'in_threads'
+urls.in_threads.each do |url|
+ HTTP.get(url)
+end
+```
+
+By calling `in_threads`, the each web page is downloaded in its own thread,
+reducing the time by almost 4x.
+
+By default, no more than 10 threads run at any one time. However, this can be
+easily overriden.
+
+```ruby
+# Read all XML files in a directory
+Dir['*.xml'].in_threads(100).each do |file|
+ File.read(file)
+end
+```
+
+Predicate methods (methods that return `true` or `false` for each object in a
+collection) are particularly well suited for use with `in_threads`.
+
+```ruby
+# Are all URLs valid?
+urls.in_threads.all? { |url| HTTP.get(url).status == 200 }
+
+# Are any URLs invalid?
+urls.in_threads.any? { |url| HTTP.get(url).status == 404 }
+```
+
+You can call any `Enumerable` method, but some (`#inject`, `#reduce`, `#max`,
+`#min`, `#sort`, `#to_a`, and others) cannot run concurrently, and so will
+simply act as if `in_threads` wasn't used.
+
## Copyright
-Copyright (c) 2010-2015 Ivan Kuchin. See LICENSE.txt for details.
+Copyright (c) 2010-2017 Ivan Kuchin. See LICENSE.txt for details.