├── .github
    ├── ISSUE_TEMPLATE.md
    ├── PULL_REQUEST_TEMPLATE.md
    └── workflows
    │   └── ci.yml
├── .gitignore
├── .rubocop.yml
├── Appraisals
├── Gemfile
├── LICENSE.txt
├── README.md
├── Rakefile
├── TESTING.md
├── docs
    ├── Gemfile
    ├── _config.yml
    ├── _layouts
    │   └── default.html
    ├── api.md
    ├── example.md
    ├── features.md
    ├── images
    │   └── rocket
    │   │   └── rocket-icon-256.png
    ├── implement.md
    ├── index.md
    ├── javascripts
    │   └── main.js
    ├── stylesheets
    │   ├── github-light.css
    │   ├── normalize.css
    │   ├── print.css
    │   ├── pygment_trac.css
    │   ├── stylesheet.css
    │   └── table.css
    └── why.md
├── gemfiles
    ├── rails_5.1.gemfile
    ├── rails_5.2.gemfile
    ├── rails_6.0.gemfile
    ├── rails_6.1.gemfile
    └── rails_7.0.gemfile
├── lib
    ├── parallel_minion.rb
    └── parallel_minion
    │   ├── minion.rb
    │   ├── railtie.rb
    │   └── version.rb
├── parallel_minion.gemspec
└── test
    ├── config
        └── database.yml
    ├── minion_scope_test.rb
    ├── minion_test.rb
    └── test_helper.rb


/.github/ISSUE_TEMPLATE.md:
--------------------------------------------------------------------------------
 1 | ### Environment
 2 | 
 3 | Provide at least:
 4 | * Ruby Version.
 5 | * Parallel Minion Version.
 6 | * Application/framework names and versions (e.g. Rails, Sinatra, Puma, etc.).
 7 | * Full Stack Trace, if an exception is being raised.
 8 | 
 9 | ### Expected Behavior
10 | 
11 | * Describe your expectation of how Parallel Minion should behave.
12 | * Ideally, provide a standalone Ruby script or a link to an example repository that helps reproduce the issue.
13 | 
14 | ### Actual Behavior
15 | 
16 | * Describe or show the actual behavior.
17 | * Provide text or screen capture showing the behavior.
18 | 
19 | ### Pull Request
20 | 
21 | * Consider submitting a Pull Request with a fix for the issue.
22 | * Or, even a Pull request that only includes a test that reproduces the problem. 
23 | 


--------------------------------------------------------------------------------
/.github/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
1 | ### Issue # (if available)
2 | 
3 | 
4 | ### Description of changes
5 | 
6 | 
7 | By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
8 | 


--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
 1 | name: build
 2 | 
 3 | on:
 4 |   - push
 5 |   - pull_request
 6 | 
 7 | jobs:
 8 |   test:
 9 |     name: "Test: Rails ${{ matrix.rails }} on Ruby ${{ matrix.ruby }}"
10 |     runs-on: ubuntu-latest
11 |     strategy:
12 |       fail-fast: false
13 |       matrix:
14 |         include:
15 |           - rails: 5.1
16 |             ruby: 2.5
17 | 
18 |           - rails: 5.2
19 |             ruby: 2.5
20 |           - rails: 5.2
21 |             ruby: 2.6
22 |           - rails: 5.2
23 |             ruby: jruby
24 | 
25 |           - rails: "6.0"
26 |             ruby: 2.6
27 |           - rails: "6.0"
28 |             ruby: 2.7
29 |           - rails: "6.0"
30 |             ruby: "3.0"
31 |           - rails: "6.0"
32 |             ruby: jruby
33 | 
34 |           - rails: "6.1"
35 |             ruby: "3.0"
36 |           - rails: "6.1"
37 |             ruby: jruby
38 | 
39 |           - rails: "6.1"
40 |             ruby: "3.1"
41 |           - rails: "7.0"
42 |             ruby: "3.1"
43 | 
44 |     env:
45 |       BUNDLE_GEMFILE: gemfiles/rails_${{ matrix.rails }}.gemfile
46 |       DISPLAY: ":99.0"
47 | 
48 |     steps:
49 |       - uses: actions/checkout@v2
50 |       - name: Set up Ruby
51 |         uses: ruby/setup-ruby@v1
52 |         with:
53 |           ruby-version: ${{ matrix.ruby }}
54 |           # runs 'bundle install' and caches installed gems automatically
55 |           bundler-cache: true
56 | 
57 |       - name: Gemfile
58 |         run: echo $BUNDLE_GEMFILE
59 | 
60 |       - name: Ruby Version
61 |         run: ruby --version
62 | 
63 |       - name: Run Tests
64 |         run: bundle exec rake test
65 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | .DS_Store
 2 | *.gem
 3 | .idea/*
 4 | test.rb
 5 | *.sqlite3
 6 | Gemfile.lock
 7 | 
 8 | *.log
 9 | 
10 | *.lock
11 | /docs/_site
12 | .rakeTasks
13 | 


--------------------------------------------------------------------------------
/.rubocop.yml:
--------------------------------------------------------------------------------
  1 | AllCops:
  2 |   TargetRubyVersion: 2.5
  3 |   SuggestExtensions: false
  4 |   NewCops: enable
  5 |   Exclude:
  6 |     - ".git/**/*"
  7 |     - "docs/**/*"
  8 |     - "gemfiles/*"
  9 | #
 10 | # RuboCop built-in settings.
 11 | #   For documentation on all settings see: https://docs.rubocop.org/en/stable
 12 | #
 13 | 
 14 | # Trailing periods.
 15 | Layout/DotPosition:
 16 |   EnforcedStyle: trailing
 17 | 
 18 | # Turn on auto-correction of equals alignment.
 19 | Layout/EndAlignment:
 20 |   AutoCorrect: true
 21 | 
 22 | # Prevent accidental windows line endings
 23 | Layout/EndOfLine:
 24 |   EnforcedStyle: lf
 25 | 
 26 | # Use a table layout for hashes
 27 | Layout/HashAlignment:
 28 |   EnforcedHashRocketStyle: table
 29 |   EnforcedColonStyle: table
 30 | 
 31 | # Soften limits
 32 | Layout/LineLength:
 33 |   Max: 128
 34 |   Exclude:
 35 |     - "**/test/**/*"
 36 | 
 37 | # Match existing layout
 38 | Layout/SpaceInsideHashLiteralBraces:
 39 |   EnforcedStyle: no_space
 40 | 
 41 | # TODO: Soften Limits for phase 1 only
 42 | Metrics/AbcSize:
 43 |   Max: 40
 44 | 
 45 | # Support long block lengths for tests
 46 | Metrics/BlockLength:
 47 |   Exclude:
 48 |     - "test/**/*"
 49 |     - "**/*/cli.rb"
 50 |   AllowedMethods:
 51 |     - "aasm"
 52 |     - "included"
 53 | 
 54 | # Soften limits
 55 | Metrics/ClassLength:
 56 |   Max: 250
 57 |   Exclude:
 58 |     - "test/**/*"
 59 | 
 60 | # TODO: Soften Limits for phase 1 only
 61 | Metrics/CyclomaticComplexity:
 62 |   Max: 15
 63 | 
 64 | # Soften limits
 65 | Metrics/MethodLength:
 66 |   Max: 50
 67 | 
 68 | # Soften limits
 69 | Metrics/ModuleLength:
 70 |   Max: 250
 71 | 
 72 | Metrics/ParameterLists:
 73 |   CountKeywordArgs: false
 74 | 
 75 | # TODO: Soften Limits for phase 1 only
 76 | Metrics/PerceivedComplexity:
 77 |   Max: 21
 78 | 
 79 | # Initialization Vector abbreviation
 80 | Naming/MethodParameterName:
 81 |   AllowedNames: ['iv', '_', 'io', 'ap']
 82 | 
 83 | # Does not allow Symbols to load
 84 | Security/YAMLLoad:
 85 |   AutoCorrect: false
 86 | 
 87 | # Needed for testing DateTime
 88 | Style/DateTime:
 89 |   Exclude: ["test/**/*"]
 90 | 
 91 | # TODO: Soften Limits for phase 1 only
 92 | Style/Documentation:
 93 |   Enabled: false
 94 | 
 95 | # One line methods
 96 | Style/EmptyMethod:
 97 |   EnforcedStyle: expanded
 98 | 
 99 | # Ruby 3 compatibility feature
100 | Style/FrozenStringLiteralComment:
101 |   Enabled: false
102 | 
103 | Style/NumericPredicate:
104 |   AutoCorrect: true
105 | 
106 | # Incorrectly changes job.fail to job.raise
107 | Style/SignalException:
108 |   Enabled: false
109 | 
110 | # Since English may not be loaded, cannot force its use.
111 | Style/SpecialGlobalVars:
112 |   Enabled: false
113 | 
114 | # Make it easier for developers to move between Elixir and Ruby.
115 | Style/StringLiterals:
116 |   EnforcedStyle: double_quotes
117 | 


--------------------------------------------------------------------------------
/Appraisals:
--------------------------------------------------------------------------------
 1 | appraise "rails_5.1" do
 2 |   gem "activerecord", "~> 5.1.5"
 3 |   gem "sqlite3", "~> 1.3.0", platform: :ruby
 4 |   gem "activerecord-jdbcsqlite3-adapter", "~> 51.0", platform: :jruby
 5 | end
 6 | 
 7 | appraise "rails_5.2" do
 8 |   gem "activerecord", "~> 5.2.0"
 9 |   gem "sqlite3", "~> 1.3.0", platform: :ruby
10 |   gem "activerecord-jdbcsqlite3-adapter", "~> 52.0", platform: :jruby
11 | end
12 | 
13 | appraise "rails_6.0" do
14 |   gem "activerecord", "~> 6.0.0"
15 |   gem "activerecord-jdbcsqlite3-adapter", "~> 60.0", platform: :jruby
16 |   gem "sqlite3", "~> 1.4.0", platform: :ruby
17 | end
18 | 
19 | appraise "rails_6.1" do
20 |   gem "activerecord", "~> 6.1.0"
21 |   gem "activerecord-jdbcsqlite3-adapter", "~> 61.0", platform: :jruby
22 |   gem "sqlite3", "~> 1.4.0", platform: :ruby
23 | end
24 | 
25 | appraise "rails_7.0" do
26 |   gem "activerecord", "~> 7.0"
27 |   gem "sqlite3", "~> 1.4.0", platform: :ruby
28 | end
29 | 


--------------------------------------------------------------------------------
/Gemfile:
--------------------------------------------------------------------------------
 1 | source "https://rubygems.org"
 2 | 
 3 | gemspec
 4 | 
 5 | gem "activerecord", "~> 6.1.0"
 6 | gem "minitest"
 7 | gem "rake"
 8 | gem "sqlite3", "~> 1.4.0", platform: :ruby
 9 | 
10 | gem "amazing_print"
11 | gem "appraisal"
12 | 


--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
  1 | Apache License
  2 |                            Version 2.0, January 2004
  3 |                         http://www.apache.org/licenses/
  4 | 
  5 |    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  6 | 
  7 |    1. Definitions.
  8 | 
  9 |       "License" shall mean the terms and conditions for use, reproduction,
 10 |       and distribution as defined by Sections 1 through 9 of this document.
 11 | 
 12 |       "Licensor" shall mean the copyright owner or entity authorized by
 13 |       the copyright owner that is granting the License.
 14 | 
 15 |       "Legal Entity" shall mean the union of the acting entity and all
 16 |       other entities that control, are controlled by, or are under common
 17 |       control with that entity. For the purposes of this definition,
 18 |       "control" means (i) the power, direct or indirect, to cause the
 19 |       direction or management of such entity, whether by contract or
 20 |       otherwise, or (ii) ownership of fifty percent (50%) or more of the
 21 |       outstanding shares, or (iii) beneficial ownership of such entity.
 22 | 
 23 |       "You" (or "Your") shall mean an individual or Legal Entity
 24 |       exercising permissions granted by this License.
 25 | 
 26 |       "Source" form shall mean the preferred form for making modifications,
 27 |       including but not limited to software source code, documentation
 28 |       source, and configuration files.
 29 | 
 30 |       "Object" form shall mean any form resulting from mechanical
 31 |       transformation or translation of a Source form, including but
 32 |       not limited to compiled object code, generated documentation,
 33 |       and conversions to other media types.
 34 | 
 35 |       "Work" shall mean the work of authorship, whether in Source or
 36 |       Object form, made available under the License, as indicated by a
 37 |       copyright notice that is included in or attached to the work
 38 |       (an example is provided in the Appendix below).
 39 | 
 40 |       "Derivative Works" shall mean any work, whether in Source or Object
 41 |       form, that is based on (or derived from) the Work and for which the
 42 |       editorial revisions, annotations, elaborations, or other modifications
 43 |       represent, as a whole, an original work of authorship. For the purposes
 44 |       of this License, Derivative Works shall not include works that remain
 45 |       separable from, or merely link (or bind by name) to the interfaces of,
 46 |       the Work and Derivative Works thereof.
 47 | 
 48 |       "Contribution" shall mean any work of authorship, including
 49 |       the original version of the Work and any modifications or additions
 50 |       to that Work or Derivative Works thereof, that is intentionally
 51 |       submitted to Licensor for inclusion in the Work by the copyright owner
 52 |       or by an individual or Legal Entity authorized to submit on behalf of
 53 |       the copyright owner. For the purposes of this definition, "submitted"
 54 |       means any form of electronic, verbal, or written communication sent
 55 |       to the Licensor or its representatives, including but not limited to
 56 |       communication on electronic mailing lists, source code control systems,
 57 |       and issue tracking systems that are managed by, or on behalf of, the
 58 |       Licensor for the purpose of discussing and improving the Work, but
 59 |       excluding communication that is conspicuously marked or otherwise
 60 |       designated in writing by the copyright owner as "Not a Contribution."
 61 | 
 62 |       "Contributor" shall mean Licensor and any individual or Legal Entity
 63 |       on behalf of whom a Contribution has been received by Licensor and
 64 |       subsequently incorporated within the Work.
 65 | 
 66 |    2. Grant of Copyright License. Subject to the terms and conditions of
 67 |       this License, each Contributor hereby grants to You a perpetual,
 68 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 69 |       copyright license to reproduce, prepare Derivative Works of,
 70 |       publicly display, publicly perform, sublicense, and distribute the
 71 |       Work and such Derivative Works in Source or Object form.
 72 | 
 73 |    3. Grant of Patent License. Subject to the terms and conditions of
 74 |       this License, each Contributor hereby grants to You a perpetual,
 75 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 76 |       (except as stated in this section) patent license to make, have made,
 77 |       use, offer to sell, sell, import, and otherwise transfer the Work,
 78 |       where such license applies only to those patent claims licensable
 79 |       by such Contributor that are necessarily infringed by their
 80 |       Contribution(s) alone or by combination of their Contribution(s)
 81 |       with the Work to which such Contribution(s) was submitted. If You
 82 |       institute patent litigation against any entity (including a
 83 |       cross-claim or counterclaim in a lawsuit) alleging that the Work
 84 |       or a Contribution incorporated within the Work constitutes direct
 85 |       or contributory patent infringement, then any patent licenses
 86 |       granted to You under this License for that Work shall terminate
 87 |       as of the date such litigation is filed.
 88 | 
 89 |    4. Redistribution. You may reproduce and distribute copies of the
 90 |       Work or Derivative Works thereof in any medium, with or without
 91 |       modifications, and in Source or Object form, provided that You
 92 |       meet the following conditions:
 93 | 
 94 |       (a) You must give any other recipients of the Work or
 95 |           Derivative Works a copy of this License; and
 96 | 
 97 |       (b) You must cause any modified files to carry prominent notices
 98 |           stating that You changed the files; and
 99 | 
100 |       (c) You must retain, in the Source form of any Derivative Works
101 |           that You distribute, all copyright, patent, trademark, and
102 |           attribution notices from the Source form of the Work,
103 |           excluding those notices that do not pertain to any part of
104 |           the Derivative Works; and
105 | 
106 |       (d) If the Work includes a "NOTICE" text file as part of its
107 |           distribution, then any Derivative Works that You distribute must
108 |           include a readable copy of the attribution notices contained
109 |           within such NOTICE file, excluding those notices that do not
110 |           pertain to any part of the Derivative Works, in at least one
111 |           of the following places: within a NOTICE text file distributed
112 |           as part of the Derivative Works; within the Source form or
113 |           documentation, if provided along with the Derivative Works; or,
114 |           within a display generated by the Derivative Works, if and
115 |           wherever such third-party notices normally appear. The contents
116 |           of the NOTICE file are for informational purposes only and
117 |           do not modify the License. You may add Your own attribution
118 |           notices within Derivative Works that You distribute, alongside
119 |           or as an addendum to the NOTICE text from the Work, provided
120 |           that such additional attribution notices cannot be construed
121 |           as modifying the License.
122 | 
123 |       You may add Your own copyright statement to Your modifications and
124 |       may provide additional or different license terms and conditions
125 |       for use, reproduction, or distribution of Your modifications, or
126 |       for any such Derivative Works as a whole, provided Your use,
127 |       reproduction, and distribution of the Work otherwise complies with
128 |       the conditions stated in this License.
129 | 
130 |    5. Submission of Contributions. Unless You explicitly state otherwise,
131 |       any Contribution intentionally submitted for inclusion in the Work
132 |       by You to the Licensor shall be under the terms and conditions of
133 |       this License, without any additional terms or conditions.
134 |       Notwithstanding the above, nothing herein shall supersede or modify
135 |       the terms of any separate license agreement you may have executed
136 |       with Licensor regarding such Contributions.
137 | 
138 |    6. Trademarks. This License does not grant permission to use the trade
139 |       names, trademarks, service marks, or product names of the Licensor,
140 |       except as required for reasonable and customary use in describing the
141 |       origin of the Work and reproducing the content of the NOTICE file.
142 | 
143 |    7. Disclaimer of Warranty. Unless required by applicable law or
144 |       agreed to in writing, Licensor provides the Work (and each
145 |       Contributor provides its Contributions) on an "AS IS" BASIS,
146 |       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 |       implied, including, without limitation, any warranties or conditions
148 |       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 |       PARTICULAR PURPOSE. You are solely responsible for determining the
150 |       appropriateness of using or redistributing the Work and assume any
151 |       risks associated with Your exercise of permissions under this License.
152 | 
153 |    8. Limitation of Liability. In no event and under no legal theory,
154 |       whether in tort (including negligence), contract, or otherwise,
155 |       unless required by applicable law (such as deliberate and grossly
156 |       negligent acts) or agreed to in writing, shall any Contributor be
157 |       liable to You for damages, including any direct, indirect, special,
158 |       incidental, or consequential damages of any character arising as a
159 |       result of this License or out of the use or inability to use the
160 |       Work (including but not limited to damages for loss of goodwill,
161 |       work stoppage, computer failure or malfunction, or any and all
162 |       other commercial damages or losses), even if such Contributor
163 |       has been advised of the possibility of such damages.
164 | 
165 |    9. Accepting Warranty or Additional Liability. While redistributing
166 |       the Work or Derivative Works thereof, You may choose to offer,
167 |       and charge a fee for, acceptance of support, warranty, indemnity,
168 |       or other liability obligations and/or rights consistent with this
169 |       License. However, in accepting such obligations, You may act only
170 |       on Your own behalf and on Your sole responsibility, not on behalf
171 |       of any other Contributor, and only if You agree to indemnify,
172 |       defend, and hold each Contributor harmless for any liability
173 |       incurred by, or claims asserted against, such Contributor by reason
174 |       of your accepting any such warranty or additional liability.
175 | 
176 |    END OF TERMS AND CONDITIONS
177 | 
178 |    APPENDIX: How to apply the Apache License to your work.
179 | 
180 |       To apply the Apache License to your work, attach the following
181 |       boilerplate notice, with the fields enclosed by brackets "{}"
182 |       replaced with your own identifying information. (Don't include
183 |       the brackets!)  The text should be enclosed in the appropriate
184 |       comment syntax for the file format. We also recommend that a
185 |       file or class name and description of purpose be included on the
186 |       same "printed page" as the copyright notice for easier
187 |       identification within third-party archives.
188 | 
189 |    Copyright 2013, 2014, 2015 Reid Morrison
190 | 
191 |    Licensed under the Apache License, Version 2.0 (the "License");
192 |    you may not use this file except in compliance with the License.
193 |    You may obtain a copy of the License at
194 | 
195 |        http://www.apache.org/licenses/LICENSE-2.0
196 | 
197 |    Unless required by applicable law or agreed to in writing, software
198 |    distributed under the License is distributed on an "AS IS" BASIS,
199 |    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 |    See the License for the specific language governing permissions and
201 |    limitations under the License.
202 | 
203 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Parallel Minion
 2 | [![Gem Version](https://img.shields.io/gem/v/parallel_minion.svg)](https://rubygems.org/gems/parallel_minion) [![Build Status](https://github.com/reidmorrison/parallel_minion/workflows/build/badge.svg)](https://github.com/reidmorrison/parallel_minion/actions?query=workflow%3Abuild) [![Downloads](https://img.shields.io/gem/dt/parallel_minion.svg)](https://rubygems.org/gems/parallel_minion) [![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](http://opensource.org/licenses/Apache-2.0) ![](https://img.shields.io/badge/status-Production%20Ready-blue.svg)
 3 | 
 4 | Wrap Ruby code with a minion so that it is run on a parallel thread.
 5 | 
 6 | ## Description
 7 | 
 8 | Parallel Minion allows you to take existing blocks of code and wrap them in a minion
 9 | so that they can run asynchronously in a separate thread.
10 | The minion then passes back the result to the caller when or if requested.
11 | If any exceptions were thrown during the minion processing, it will be re-raised
12 | in the callers thread so that no additional work needs to be done when converting
13 | existing code to use minions.
14 | 
15 | ## Example
16 | 
17 | ```ruby
18 | minion = ParallelMinion::Minion.new(
19 |   10.days.ago,
20 |   description: 'Doing something else in parallel',
21 |   timeout:     1000
22 | ) do |date|
23 |   MyTable.where('created_at <= ?', date).count
24 | end
25 | 
26 | # Do other work here...
27 | 
28 | # Retrieve the result of the minion
29 | count = minion.result
30 | 
31 | puts "Found #{count} records"
32 | ```
33 | 
34 | ## Documentation
35 | 
36 | For complete documentation see: http://reidmorrison.github.io/parallel_minion
37 | 
38 | ## Production Use
39 | 
40 | Parallel Minion is being used in a high performance, highly concurrent
41 | production environment running JRuby with Ruby on Rails on a Puma web server.
42 | Significant reduction in the time it takes to complete rails request processing
43 | has been achieved by moving existing blocks of code into Minions.
44 | 
45 | ## Installation
46 | 
47 |     gem install parallel_minion
48 | 
49 | ## Meta
50 | 
51 | * Code: `git clone git://github.com/reidmorrison/parallel_minion.git`
52 | * Home: <https://github.com/reidmorrison/parallel_minion>
53 | * Bugs: <http://github.com/reidmorrison/parallel_minion/issues>
54 | * Gems: <https://rubygems.org/gems/parallel_minion>
55 | 
56 | This project uses [Semantic Versioning](http://semver.org/).
57 | 
58 | ## Author
59 | 
60 | [Reid Morrison](https://github.com/reidmorrison) :: @reidmorrison
61 | 
62 | ## License
63 | 
64 | Copyright 2013, 2014, 2015, 2016, 2017 Reid Morrison
65 | 
66 | Licensed under the Apache License, Version 2.0 (the "License");
67 | you may not use this file except in compliance with the License.
68 | You may obtain a copy of the License at
69 | 
70 |     http://www.apache.org/licenses/LICENSE-2.0
71 | 
72 | Unless required by applicable law or agreed to in writing, software
73 | distributed under the License is distributed on an "AS IS" BASIS,
74 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
75 | See the License for the specific language governing permissions and
76 | limitations under the License.
77 | 


--------------------------------------------------------------------------------
/Rakefile:
--------------------------------------------------------------------------------
 1 | # Setup bundler to avoid having to run bundle exec all the time.
 2 | require "rubygems"
 3 | require "bundler/setup"
 4 | 
 5 | require "rake/testtask"
 6 | require_relative "lib/parallel_minion/version"
 7 | 
 8 | task :gem do
 9 |   system "gem build parallel_minion.gemspec"
10 | end
11 | 
12 | task publish: :gem do
13 |   system "git tag -a v#{ParallelMinion::VERSION} -m 'Tagging #{ParallelMinion::VERSION}'"
14 |   system "git push --tags"
15 |   system "gem push parallel_minion-#{ParallelMinion::VERSION}.gem"
16 |   system "rm parallel_minion-#{ParallelMinion::VERSION}.gem"
17 | end
18 | 
19 | Rake::TestTask.new(:test) do |t|
20 |   t.pattern = "test/**/*_test.rb"
21 |   t.verbose = true
22 |   t.warning = false
23 | end
24 | 
25 | # By default run tests against all appraisals
26 | if !ENV["APPRAISAL_INITIALIZED"] && !ENV["TRAVIS"]
27 |   require "appraisal"
28 |   task default: :appraisal
29 | else
30 |   task default: :test
31 | end
32 | 


--------------------------------------------------------------------------------
/TESTING.md:
--------------------------------------------------------------------------------
 1 | ## Installation
 2 | 
 3 | Install all needed gems to run the tests:
 4 | 
 5 |     appraisal install
 6 | 
 7 | The gems are installed into the global gem list.
 8 | The Gemfiles in the `gemfiles` folder are also re-generated.
 9 | 
10 | ## Run Tests
11 | 
12 | For all supported Rails/ActiveRecord versions:
13 | 
14 |     rake
15 | 
16 | Or for specific version one:
17 | 
18 |     appraisal rails_6.0 rake
19 | 
20 | Or for one particular test file
21 | 
22 |     appraisal rails_6.0 ruby test/minion_test.rb
23 | 
24 | Or down to one test case
25 | 
26 |     appraisal rails_6.0 ruby test/minion_test.rb -n "/raise exception/"
27 | 


--------------------------------------------------------------------------------
/docs/Gemfile:
--------------------------------------------------------------------------------
1 | source 'https://rubygems.org'
2 | gem 'github-pages'
3 | 


--------------------------------------------------------------------------------
/docs/_config.yml:
--------------------------------------------------------------------------------
1 | markdown: kramdown
2 | 


--------------------------------------------------------------------------------
/docs/_layouts/default.html:
--------------------------------------------------------------------------------
 1 | <!DOCTYPE html>
 2 | <html lang="en-us">
 3 | <head>
 4 |   <meta charset="UTF-8">
 5 |   <meta name="description" content="Pragmatic approach to parallel and asynchronous processing in Ruby">
 6 |   <title>Parallel Minion</title>
 7 |   <meta name="viewport" content="width=device-width, initial-scale=1">
 8 |   <link rel="stylesheet" type="text/css" href="stylesheets/normalize.css" media="screen">
 9 |   <link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700' rel='stylesheet' type='text/css'>
10 |   <link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen">
11 |   <link rel="stylesheet" type="text/css" href="stylesheets/github-light.css" media="screen">
12 |   <link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen"/>
13 |   <link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print"/>
14 |   <link rel="stylesheet" type="text/css" href="stylesheets/table.css" media="print"/>
15 | </head>
16 | <body>
17 | <section class="page-header">
18 |   <table style="width:100%">
19 |     <td>
20 |     <td>
21 |       <a href="http://rocketjob.io/">
22 |         <img src="images/rocket/rocket-icon-256.png" alt="Rocket Job" class="header-image">
23 |       </a>
24 |     </td>
25 |     <td>
26 |       <a href="index.html" class="btn">Home</a>
27 |       <a href="features.html" class="btn">Features</a>
28 |       <a href="api.html" class="btn">API</a>
29 |       <a href="example.html" class="btn">Example</a>
30 |       <a href="implement.html" class="btn">How to implement</a>
31 |       <a href="why.html" class="btn">Why?</a>
32 |       <a href="https://github.com/reidmorrison/parallel_minion" class="btn">GitHub</a>
33 | 
34 |       <h1 class="project-name">Parallel Minion</h1>
35 |       <h2 class="project-tagline">Pragmatic approach to parallel and asynchronous processing in Ruby.</h2>
36 |     </td>
37 |     </tr>
38 |   </table>
39 | 
40 | </section>
41 | 
42 | <section class="main-content">
43 |   {{content}}
44 | </section>
45 | </body>
46 | </html>
47 | 
48 | 


--------------------------------------------------------------------------------
/docs/api.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | layout: default
  3 | ---
  4 | 
  5 | ## ParallelMinion::Minion
  6 | 
  7 | ### Create a new minion
  8 | 
  9 | Create a new thread in which to run the minion and then:
 10 | 
 11 | - log the time for the thread to complete processing
 12 | - log the exception without stack trace whenever an exception is thrown in the thread
 13 | - Re-raise any unhandled exception in the calling thread when it retrieves the result
 14 | - copy the logging tags from the current thread
 15 | - copy the specified ActiveRecord scopes to the new thread
 16 | 
 17 | #### Any number of arguments can be passed to the initializer
 18 | These arguments are passed into the supplied block in the order they are listed
 19 |    It is recommended to duplicate and/or freeze objects passed as arguments
 20 |    so that they are not modified at the same time by multiple threads
 21 | 
 22 | The _last_ parameter passed to the initializer must be a hash consisting of:
 23 | 
 24 | - `:description` `[String]`
 25 |     - Description for this task that the Minion is performing
 26 |     - Put in the log file along with the time take to complete the task
 27 | 
 28 | - `:timeout` `[Integer]`
 29 |     - Maximum amount of time in milli-seconds that the task may take to complete
 30 |       before #result times out
 31 |     - Set to `Minion::INFINITE` to give the thread an infinite amount of time to complete
 32 |     - Default: `Minion::INFINITE`
 33 |     - Notes:
 34 |         - `:timeout` does not affect what happens to the Minion running the
 35 |            the task, it only affects how long #result will take to return.
 36 |         - The Minion will continue to run even after the timeout has been exceeded
 37 |         - If `:enabled` is false, or ParallelMinion::Minion.enabled is false,
 38 |           then :timeout is ignored and assumed to be Minion::INFINITE
 39 |           since the code is run in the calling thread when the Minion is created
 40 | 
 41 | - `:enabled` `[Boolean]`
 42 |     - Whether the minion should run in a separate thread
 43 |     - Not recommended in Production, but is useful for debugging purposes
 44 |     - Default: ParallelMinion::Minion.enabled?
 45 | 
 46 | - Proc / lambda
 47 |     - A block of code must be supplied that the Minion will execute
 48 |     - This block will be executed within the scope of the minion
 49 |       instance and _not_ within the scope of where the Proc/lambda was
 50 |       originally created.
 51 |     - This is done to force all parameters to be passed in explicitly
 52 |       and should be read-only or copies of the original data to prevent
 53 |       multiple minions from trying to write to the same objects
 54 | 
 55 | The overhead for moving the task to a Minion (separate thread) vs running it
 56 | sequentially is about 0.3 ms if performing other tasks in-between starting
 57 | the task and requesting its result.
 58 | 
 59 | The following call adds 0.5 ms to total processing time vs running the
 60 | same code in-line:
 61 | 
 62 | ```ruby
 63 |    ParallelMinion::Minion.new(description: 'Count', timeout: 5) { 1 }.result
 64 | ```
 65 | 
 66 | Note: The above timings are based on JRuby with it's thread-pool enabled
 67 | 
 68 | #### Example:
 69 | 
 70 | ```ruby
 71 | ParallelMinion::Minion.new(10.days.ago, description: 'Doing something else in parallel', timeout: 1000) do |date|
 72 |   MyTable.where('created_at <= ?', date).count
 73 | end
 74 | ```
 75 | 
 76 | ### Disabling Minions
 77 | 
 78 | In the event that strange problems are occurring in production and no one is
 79 | sure if it is due to running the minion tasks in parallel, a simple configuration
 80 | setting can disable minions. This setting will make all minion tasks run in
 81 | the same thread that they were called from. When disabled, the block supplied
 82 | to the minion will be executed inline before continuing to process subsequent steps.
 83 | 
 84 | It may also be useful to disable minions on a single production server to compare
 85 | its performance to that of the servers running with minions active. Great for
 86 | proving the performance benefits of minions.
 87 | 
 88 | To disable minions / make them run in the calling thread, add the following
 89 | lines to config/environments/production.rb:
 90 | 
 91 | ```ruby
 92 |   # Make minions run immediately in the current thread
 93 |   config.parallel_minion.enabled = false
 94 | ```
 95 | 
 96 | If running outside of Rails, add the following line in you code:
 97 | 
 98 | ```ruby
 99 |   # Make minions run immediately in the current thread
100 |   ParallelMinion::Minion.enabled = false
101 | ```
102 | 


--------------------------------------------------------------------------------
/docs/example.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | layout: default
  3 | ---
  4 | 
  5 | ## Example
  6 | 
  7 | For example, in the code below there are several steps that are performed
  8 | sequentially and does not yet use minions:
  9 | 
 10 | ```ruby
 11 | # Contrived example to show how to do parallel code execution
 12 | # with (unreal) sample durations in the comments
 13 | 
 14 | def process_request(request)
 15 |   # Count number of entries in a table.
 16 |   #   Average response time 150ms
 17 |   person_count = Person.where(state: 'FL').count
 18 | 
 19 |   # Count the number of requests for this user (usually more complex with were clauses etc.)
 20 |   #   Average response time 320ms
 21 |   request_count = Requests.where(user_id: request.user.id).count
 22 | 
 23 |   # Call an external provider
 24 |   #   Average response time 1800ms ( Sometimes "hangs" when supplier does not respond )
 25 |   inventory = inventory_supplier.check_inventory(request.product.id)
 26 | 
 27 |   # Call another provider for more info on the user
 28 |   #   Average response time 1500ms
 29 |   user_info = user_supplier.more_info(request.user.name)
 30 | 
 31 |   # Build up the reply
 32 |   reply = MyReply.new(user_id: request.user.id)
 33 | 
 34 |   reply.number_of_people   = person_count
 35 |   reply.number_of_requests = request_count
 36 |   reply.user_details       = user_info.details
 37 |   if inventory.product_available?
 38 |     reply.available        = true
 39 |     reply.quantity         = 100
 40 |   else
 41 |     reply.available = false
 42 |   end
 43 | 
 44 |   reply
 45 | end
 46 | ```
 47 | The average response time when calling #process_request is around 3,780 milli-seconds.
 48 | 
 49 | The first step could be to run the supplier calls in parallel.
 50 | Through log analysis we have determined that the first supplier call takes on average
 51 | 1,800 ms and we have decided that it should not wait longer than 2,200 ms for a response.
 52 | 
 53 | ```ruby
 54 | # Now with a single parallel call
 55 | 
 56 | def process_request(request)
 57 |   # Count number of entries in a table.
 58 |   #   Average response time 150ms
 59 |   person_count = Person.where(state: 'FL').count
 60 | 
 61 |   # Count the number of requests for this user (usually more complex with were clauses etc.)
 62 |   #   Average response time 320ms
 63 |   request_count = Requests.where(user_id: request.user.id).count
 64 | 
 65 |   # Call an external provider
 66 |   #   Average response time 1800ms ( Sometimes "hangs" when supplier does not respond )
 67 |   inventory_minion = ParallelMinion::Minion.new(request.product.id, description: 'Inventory Lookup', timeout: 2200) do |product_id|
 68 |     inventory_supplier.check_inventory(product_id)
 69 |   end
 70 | 
 71 |   # Call another provider for more info on the user
 72 |   #   Average response time 1500ms
 73 |   user_info = user_supplier.more_info(request.user.name)
 74 | 
 75 |   # Build up the reply
 76 |   reply = MyReply.new(user_id: request.user.id)
 77 | 
 78 |   reply.number_of_people   = person_count
 79 |   reply.number_of_requests = request_count
 80 |   reply.user_details       = user_info.details
 81 | 
 82 |   # Get inventory result from Inventory Lookup minion
 83 |   inventory = inventory_minion.result
 84 | 
 85 |   if inventory.product_available?
 86 |     reply.available        = true
 87 |     reply.quantity         = 100
 88 |   else
 89 |     reply.available = false
 90 |   end
 91 | 
 92 |   reply
 93 | end
 94 | ```
 95 | 
 96 | The above changes drop the average processing time from 3,780 milli-seconds to
 97 | 2,280 milli-seconds.
 98 | 
 99 | By moving the supplier call to the top of the function call it can be optimized
100 | to about 1,970 milli-seconds.
101 | 
102 | We can further parallelize the processing to gain even greater performance.
103 | 
104 | ```ruby
105 | # Now with two parallel calls
106 | 
107 | def process_request(request)
108 |   # Call an external provider
109 |   #   Average response time 1800ms ( Sometimes "hangs" when supplier does not respond )
110 |   inventory_minion = ParallelMinion::Minion.new(request.product.id, description: 'Inventory Lookup', timeout: 2200) do |product_id|
111 |     inventory_supplier.check_inventory(product_id)
112 |   end
113 | 
114 |   # Count the number of requests for this user (usually more complex with were clauses etc.)
115 |   #   Average response time 320ms
116 |   request_count_minion = ParallelMinion::Minion.new(request.user.id, description: 'Request Count', timeout: 500) do |user_id|
117 |     Requests.where(user_id: user_id).count
118 |   end
119 | 
120 |   # Leave the current thread some work to do too
121 | 
122 |   # Count number of entries in a table.
123 |   #   Average response time 150ms
124 |   person_count = Person.where(state: 'FL').count
125 | 
126 |   # Call another provider for more info on the user
127 |   #   Average response time 1500ms
128 |   user_info = user_supplier.more_info(request.user.name)
129 | 
130 |   # Build up the reply
131 |   reply = MyReply.new(user_id: request.user.id)
132 | 
133 |   reply.number_of_people   = person_count
134 |   # The request_count is retrieved from the request_count_minion first since it
135 |   # should complete before the inventory_minion
136 |   reply.number_of_requests = request_count_minion.result
137 |   reply.user_details       = user_info.details
138 | 
139 |   # Get inventory result from Inventory Lookup minion
140 |   inventory = inventory_minion.result
141 | 
142 |   if inventory.product_available?
143 |     reply.available        = true
144 |     reply.quantity         = 100
145 |   else
146 |     reply.available = false
147 |   end
148 | 
149 |   reply
150 | end
151 | ```
152 | 
153 | The above #process_request method should now take on average 1,810 milli-seconds
154 | which is significantly faster than the 3,780 milli-seconds it took to perform
155 | the exact same request prior to using minions.
156 | 
157 | The exact breakdown of which calls to do in the main thread versus a minion is determined
158 | through experience and trial and error over time. The key is logging the duration
159 | of each call which minion does by default so that the exact processing breakdown
160 | can be fine-tuned over time.
161 | 


--------------------------------------------------------------------------------
/docs/features.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: default
 3 | ---
 4 | 
 5 | ## Features:
 6 | 
 7 | Exceptions
 8 | 
 9 | - Any exceptions raised in minions are captured and propagated back to the
10 |   calling thread when #result is called
11 | - Makes exception handling simple with a drop-in replacement for existing code
12 | - Avoids having to implement more complex actors and supervisors required
13 |   by some concurrency frameworks
14 | 
15 | Timeouts
16 | 
17 | - Timeout when a minion does not return within a specified time
18 | - Timeouts are a useful feature when one of the minions fails to respond in a
19 |   reasonable amount of time. For example when a call to a remote service hangs
20 |   we can send back a partial response of other work that was completed rather
21 |   than just "hanging" or failing completely.
22 | 
23 | Logging
24 | 
25 | - Built-in support to log the duration of all minion tasks to make future analysis
26 |   of performance issues much easier
27 | - Logs any exceptions thrown to assist with problem diagnosis
28 | - Logging tags from the current thread are propagated to the minions thread
29 | - The name of the thread in log entries is set to the description supplied for
30 |   the minion to make it easy to distinguish any log entries written in the minion
31 | 
32 | Rails Support
33 | 
34 | - When used in a Rails environment the current scope of specified Active Record
35 |   models can be propagated to the minions thread
36 | - Returns any used database connections to their relevant pools when the minion
37 |   completes
38 | 


--------------------------------------------------------------------------------
/docs/images/rocket/rocket-icon-256.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/reidmorrison/parallel_minion/3810ba3e25ad5e52f32e6a24a759a806389b38c0/docs/images/rocket/rocket-icon-256.png


--------------------------------------------------------------------------------
/docs/implement.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: default
 3 | ---
 4 | 
 5 | ## Implementation Approach
 6 | 
 7 | Before implementing minions to parallelize existing code the following information
 8 | needs to be gathered
 9 | 
10 | 1. Identify how long existing parts of the code are taking to run.
11 | 
12 | 2. Determine dependencies between the blocks of code. For example, which blocks
13 | of code must be completed before the current block can be run.
14 | 
15 | ### Measuring duration
16 | 
17 | To measure the time it takes to complete blocks of code Semantic Logger has a great
18 | API for just this purpose. It measures how long the block takes to run and then logs
19 | it to your log file.
20 | 
21 | If running rails, add the `rails_semantic_logger` gem to your Gemfile, then:
22 | 
23 | ```ruby
24 | Rails.logger.benchmark_info('Counting rows') do
25 |    MyTable.where('created_at <= ?', date).count
26 | end
27 | ```
28 | 
29 | If not running Rails, then install the `semantic_logger` gem, then:
30 | 
31 | ```ruby
32 | require 'semantic_logger'
33 | 
34 | # Set the global default log level
35 | SemanticLogger.default_level = :trace
36 | 
37 | # Log to a file, and use the colorized formatter
38 | SemanticLogger.add_appender('development.log', &SemanticLogger::Appender::Base.colorized_formatter)
39 | 
40 | # Create an instance of a logger
41 | # Add the application/class name to every log message
42 | logger = SemanticLogger['MyClass']
43 | 
44 | logger.benchmark_info('Counting rows') do
45 |    # Put code here that is being measured to determine if it should be parallelized
46 | end
47 | ```
48 | 


--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: default
 3 | ---
 4 | 
 5 | Minions are short-lived tasks defined using blocks of code in Ruby. Their only
 6 | purpose is to run a block of code in a separate thread and then to return its result
 7 | on completion.
 8 | 
 9 | Parallel Minion is a pragmatic approach to handing work off to minions (threads) so that tasks
10 | that would normally be performed sequentially can now be executed in parallel.
11 | This allows Ruby and Rails applications to quickly perform several tasks at the same
12 | time so that latency (overall processing time) is reduced.
13 | 
14 | Parallel Minion was created for a large Rails application that had been running for
15 | quite some time. The business needed the application to reduce latency times.
16 | The time to process key requests has already been reduced by over 30%. Latency will
17 | be reduced further as minions are used throughout the code-base.
18 | 
19 | ### Example
20 | 
21 | ```ruby
22 | minion = ParallelMinion::Minion.new(10.days.ago, description: 'Doing something else in parallel', timeout: 1000) do |date|
23 |   MyTable.where('created_at <= ?', date).count
24 | end
25 | 
26 | # Do other work here...
27 | 
28 | # Retrieve the result of the minion
29 | count = minion.result
30 | 
31 | puts "Found #{count} records"
32 | ```
33 | 
34 | ### Installation
35 | 
36 |     gem install parallel_minion
37 | 
38 | ### Notes:
39 | 
40 | - Generally it makes sense to move a block of code into a minion if it takes longer
41 | than 30ms to run. This due to the overhead of moving the block of code into
42 | a separate thread.
43 | 
44 | - On JRuby it takes about 10ms to create a new thread, to reduce this time, enable
45 | JRuby's built-in thread-pooling by adding the following line to .jrubyrc,
46 | or setting the appropriate command line option:
47 | 
48 | ```ruby
49 | thread.pool.enabled=true
50 | ```
51 | 
52 | - Rails 4.0, 4.1 users need to apply a patch in order to fix a performance
53 | problem in the Active Record connection pooling logic. Include
54 | the following [Code](https://gist.github.com/reidmorrison/e5e6b0bf01d6837624d4)
55 | before Rails starts. A good place is in application.rb
56 | 
57 | ### Dependencies
58 | 
59 | Parallel Minion uses Semantic Logger due to it's high concurrency logging capabilities
60 | and built-in benchmarking api's
61 | 
62 | - `semantic_logger`
63 | 
64 | ### Compatibility
65 | 
66 | ParallelMinion works with Ruby 1.9, Ruby 2.0, Ruby 2.1, JRuby 1.7
67 | 


--------------------------------------------------------------------------------
/docs/javascripts/main.js:
--------------------------------------------------------------------------------
1 | console.log('This would be the main JS file.');
2 | 


--------------------------------------------------------------------------------
/docs/stylesheets/github-light.css:
--------------------------------------------------------------------------------
  1 | /*
  2 |    Copyright 2014 GitHub Inc.
  3 | 
  4 |    Licensed under the Apache License, Version 2.0 (the "License");
  5 |    you may not use this file except in compliance with the License.
  6 |    You may obtain a copy of the License at
  7 | 
  8 |        http://www.apache.org/licenses/LICENSE-2.0
  9 | 
 10 |    Unless required by applicable law or agreed to in writing, software
 11 |    distributed under the License is distributed on an "AS IS" BASIS,
 12 |    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 |    See the License for the specific language governing permissions and
 14 |    limitations under the License.
 15 | 
 16 | */
 17 | 
 18 | .pl-c /* comment */ {
 19 |   color: #969896;
 20 | }
 21 | 
 22 | .pl-c1      /* constant, markup.raw, meta.diff.header, meta.module-reference, meta.property-name, support, support.constant, support.variable, variable.other.constant */,
 23 | .pl-s .pl-v /* string variable */ {
 24 |   color: #0086b3;
 25 | }
 26 | 
 27 | .pl-e  /* entity */,
 28 | .pl-en /* entity.name */ {
 29 |   color: #795da3;
 30 | }
 31 | 
 32 | .pl-s .pl-s1 /* string source */,
 33 | .pl-smi      /* storage.modifier.import, storage.modifier.package, storage.type.java, variable.other, variable.parameter.function */ {
 34 |   color: #333;
 35 | }
 36 | 
 37 | .pl-ent /* entity.name.tag */ {
 38 |   color: #63a35c;
 39 | }
 40 | 
 41 | .pl-k /* keyword, storage, storage.type */ {
 42 |   color: #a71d5d;
 43 | }
 44 | 
 45 | .pl-pds              /* punctuation.definition.string, string.regexp.character-class */,
 46 | .pl-s                /* string */,
 47 | .pl-s .pl-pse .pl-s1 /* string punctuation.section.embedded source */,
 48 | .pl-sr               /* string.regexp */,
 49 | .pl-sr .pl-cce       /* string.regexp constant.character.escape */,
 50 | .pl-sr .pl-sra       /* string.regexp string.regexp.arbitrary-repitition */,
 51 | .pl-sr .pl-sre       /* string.regexp source.ruby.embedded */ {
 52 |   color: #183691;
 53 | }
 54 | 
 55 | .pl-v /* variable */ {
 56 |   color: #ed6a43;
 57 | }
 58 | 
 59 | .pl-id /* invalid.deprecated */ {
 60 |   color: #b52a1d;
 61 | }
 62 | 
 63 | .pl-ii /* invalid.illegal */ {
 64 |   background-color: #b52a1d;
 65 |   color: #f8f8f8;
 66 | }
 67 | 
 68 | .pl-sr .pl-cce /* string.regexp constant.character.escape */ {
 69 |   color: #63a35c;
 70 |   font-weight: bold;
 71 | }
 72 | 
 73 | .pl-ml /* markup.list */ {
 74 |   color: #693a17;
 75 | }
 76 | 
 77 | .pl-mh        /* markup.heading */,
 78 | .pl-mh .pl-en /* markup.heading entity.name */,
 79 | .pl-ms        /* meta.separator */ {
 80 |   color: #1d3e81;
 81 |   font-weight: bold;
 82 | }
 83 | 
 84 | .pl-mq /* markup.quote */ {
 85 |   color: #008080;
 86 | }
 87 | 
 88 | .pl-mi /* markup.italic */ {
 89 |   color: #333;
 90 |   font-style: italic;
 91 | }
 92 | 
 93 | .pl-mb /* markup.bold */ {
 94 |   color: #333;
 95 |   font-weight: bold;
 96 | }
 97 | 
 98 | .pl-md /* markup.deleted, meta.diff.header.from-file */ {
 99 |   background-color: #ffecec;
100 |   color: #bd2c00;
101 | }
102 | 
103 | .pl-mi1 /* markup.inserted, meta.diff.header.to-file */ {
104 |   background-color: #eaffea;
105 |   color: #55a532;
106 | }
107 | 
108 | .pl-mdr /* meta.diff.range */ {
109 |   color: #795da3;
110 |   font-weight: bold;
111 | }
112 | 
113 | .pl-mo /* meta.output */ {
114 |   color: #1d3e81;
115 | }
116 | 
117 | 


--------------------------------------------------------------------------------
/docs/stylesheets/normalize.css:
--------------------------------------------------------------------------------
  1 | /*! normalize.css v3.0.2 | MIT License | git.io/normalize */
  2 | 
  3 | /**
  4 |  * 1. Set default font family to sans-serif.
  5 |  * 2. Prevent iOS text size adjust after orientation change, without disabling
  6 |  *    user zoom.
  7 |  */
  8 | 
  9 | html {
 10 |   font-family: sans-serif; /* 1 */
 11 |   -ms-text-size-adjust: 100%; /* 2 */
 12 |   -webkit-text-size-adjust: 100%; /* 2 */
 13 | }
 14 | 
 15 | /**
 16 |  * Remove default margin.
 17 |  */
 18 | 
 19 | body {
 20 |   margin: 0;
 21 | }
 22 | 
 23 | /* HTML5 display definitions
 24 |    ========================================================================== */
 25 | 
 26 | /**
 27 |  * Correct `block` display not defined for any HTML5 element in IE 8/9.
 28 |  * Correct `block` display not defined for `details` or `summary` in IE 10/11
 29 |  * and Firefox.
 30 |  * Correct `block` display not defined for `main` in IE 11.
 31 |  */
 32 | 
 33 | article,
 34 | aside,
 35 | details,
 36 | figcaption,
 37 | figure,
 38 | footer,
 39 | header,
 40 | hgroup,
 41 | main,
 42 | menu,
 43 | nav,
 44 | section,
 45 | summary {
 46 |   display: block;
 47 | }
 48 | 
 49 | /**
 50 |  * 1. Correct `inline-block` display not defined in IE 8/9.
 51 |  * 2. Normalize vertical alignment of `progress` in Chrome, Firefox, and Opera.
 52 |  */
 53 | 
 54 | audio,
 55 | canvas,
 56 | progress,
 57 | video {
 58 |   display: inline-block; /* 1 */
 59 |   vertical-align: baseline; /* 2 */
 60 | }
 61 | 
 62 | /**
 63 |  * Prevent modern browsers from displaying `audio` without controls.
 64 |  * Remove excess height in iOS 5 devices.
 65 |  */
 66 | 
 67 | audio:not([controls]) {
 68 |   display: none;
 69 |   height: 0;
 70 | }
 71 | 
 72 | /**
 73 |  * Address `[hidden]` styling not present in IE 8/9/10.
 74 |  * Hide the `template` element in IE 8/9/11, Safari, and Firefox < 22.
 75 |  */
 76 | 
 77 | [hidden],
 78 | template {
 79 |   display: none;
 80 | }
 81 | 
 82 | /* Links
 83 |    ========================================================================== */
 84 | 
 85 | /**
 86 |  * Remove the gray background color from active links in IE 10.
 87 |  */
 88 | 
 89 | a {
 90 |   background-color: transparent;
 91 | }
 92 | 
 93 | /**
 94 |  * Improve readability when focused and also mouse hovered in all browsers.
 95 |  */
 96 | 
 97 | a:active,
 98 | a:hover {
 99 |   outline: 0;
100 | }
101 | 
102 | /* Text-level semantics
103 |    ========================================================================== */
104 | 
105 | /**
106 |  * Address styling not present in IE 8/9/10/11, Safari, and Chrome.
107 |  */
108 | 
109 | abbr[title] {
110 |   border-bottom: 1px dotted;
111 | }
112 | 
113 | /**
114 |  * Address style set to `bolder` in Firefox 4+, Safari, and Chrome.
115 |  */
116 | 
117 | b,
118 | strong {
119 |   font-weight: bold;
120 | }
121 | 
122 | /**
123 |  * Address styling not present in Safari and Chrome.
124 |  */
125 | 
126 | dfn {
127 |   font-style: italic;
128 | }
129 | 
130 | /**
131 |  * Address variable `h1` font-size and margin within `section` and `article`
132 |  * contexts in Firefox 4+, Safari, and Chrome.
133 |  */
134 | 
135 | h1 {
136 |   font-size: 2em;
137 |   margin: 0.67em 0;
138 | }
139 | 
140 | /**
141 |  * Address styling not present in IE 8/9.
142 |  */
143 | 
144 | mark {
145 |   background: #ff0;
146 |   color: #000;
147 | }
148 | 
149 | /**
150 |  * Address inconsistent and variable font size in all browsers.
151 |  */
152 | 
153 | small {
154 |   font-size: 80%;
155 | }
156 | 
157 | /**
158 |  * Prevent `sub` and `sup` affecting `line-height` in all browsers.
159 |  */
160 | 
161 | sub,
162 | sup {
163 |   font-size: 75%;
164 |   line-height: 0;
165 |   position: relative;
166 |   vertical-align: baseline;
167 | }
168 | 
169 | sup {
170 |   top: -0.5em;
171 | }
172 | 
173 | sub {
174 |   bottom: -0.25em;
175 | }
176 | 
177 | /* Embedded content
178 |    ========================================================================== */
179 | 
180 | /**
181 |  * Remove border when inside `a` element in IE 8/9/10.
182 |  */
183 | 
184 | img {
185 |   border: 0;
186 | }
187 | 
188 | /**
189 |  * Correct overflow not hidden in IE 9/10/11.
190 |  */
191 | 
192 | svg:not(:root) {
193 |   overflow: hidden;
194 | }
195 | 
196 | /* Grouping content
197 |    ========================================================================== */
198 | 
199 | /**
200 |  * Address margin not present in IE 8/9 and Safari.
201 |  */
202 | 
203 | figure {
204 |   margin: 1em 40px;
205 | }
206 | 
207 | /**
208 |  * Address differences between Firefox and other browsers.
209 |  */
210 | 
211 | hr {
212 |   box-sizing: content-box;
213 |   height: 0;
214 | }
215 | 
216 | /**
217 |  * Contain overflow in all browsers.
218 |  */
219 | 
220 | pre {
221 |   overflow: auto;
222 | }
223 | 
224 | /**
225 |  * Address odd `em`-unit font size rendering in all browsers.
226 |  */
227 | 
228 | code,
229 | kbd,
230 | pre,
231 | samp {
232 |   font-family: monospace, monospace;
233 |   font-size: 1em;
234 | }
235 | 
236 | /* Forms
237 |    ========================================================================== */
238 | 
239 | /**
240 |  * Known limitation: by default, Chrome and Safari on OS X allow very limited
241 |  * styling of `select`, unless a `border` property is set.
242 |  */
243 | 
244 | /**
245 |  * 1. Correct color not being inherited.
246 |  *    Known issue: affects color of disabled elements.
247 |  * 2. Correct font properties not being inherited.
248 |  * 3. Address margins set differently in Firefox 4+, Safari, and Chrome.
249 |  */
250 | 
251 | button,
252 | input,
253 | optgroup,
254 | select,
255 | textarea {
256 |   color: inherit; /* 1 */
257 |   font: inherit; /* 2 */
258 |   margin: 0; /* 3 */
259 | }
260 | 
261 | /**
262 |  * Address `overflow` set to `hidden` in IE 8/9/10/11.
263 |  */
264 | 
265 | button {
266 |   overflow: visible;
267 | }
268 | 
269 | /**
270 |  * Address inconsistent `text-transform` inheritance for `button` and `select`.
271 |  * All other form control elements do not inherit `text-transform` values.
272 |  * Correct `button` style inheritance in Firefox, IE 8/9/10/11, and Opera.
273 |  * Correct `select` style inheritance in Firefox.
274 |  */
275 | 
276 | button,
277 | select {
278 |   text-transform: none;
279 | }
280 | 
281 | /**
282 |  * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
283 |  *    and `video` controls.
284 |  * 2. Correct inability to style clickable `input` types in iOS.
285 |  * 3. Improve usability and consistency of cursor style between image-type
286 |  *    `input` and others.
287 |  */
288 | 
289 | button,
290 | html input[type="button"], /* 1 */
291 | input[type="reset"],
292 | input[type="submit"] {
293 |   -webkit-appearance: button; /* 2 */
294 |   cursor: pointer; /* 3 */
295 | }
296 | 
297 | /**
298 |  * Re-set default cursor for disabled elements.
299 |  */
300 | 
301 | button[disabled],
302 | html input[disabled] {
303 |   cursor: default;
304 | }
305 | 
306 | /**
307 |  * Remove inner padding and border in Firefox 4+.
308 |  */
309 | 
310 | button::-moz-focus-inner,
311 | input::-moz-focus-inner {
312 |   border: 0;
313 |   padding: 0;
314 | }
315 | 
316 | /**
317 |  * Address Firefox 4+ setting `line-height` on `input` using `!important` in
318 |  * the UA stylesheet.
319 |  */
320 | 
321 | input {
322 |   line-height: normal;
323 | }
324 | 
325 | /**
326 |  * It's recommended that you don't attempt to style these elements.
327 |  * Firefox's implementation doesn't respect box-sizing, padding, or width.
328 |  *
329 |  * 1. Address box sizing set to `content-box` in IE 8/9/10.
330 |  * 2. Remove excess padding in IE 8/9/10.
331 |  */
332 | 
333 | input[type="checkbox"],
334 | input[type="radio"] {
335 |   box-sizing: border-box; /* 1 */
336 |   padding: 0; /* 2 */
337 | }
338 | 
339 | /**
340 |  * Fix the cursor style for Chrome's increment/decrement buttons. For certain
341 |  * `font-size` values of the `input`, it causes the cursor style of the
342 |  * decrement button to change from `default` to `text`.
343 |  */
344 | 
345 | input[type="number"]::-webkit-inner-spin-button,
346 | input[type="number"]::-webkit-outer-spin-button {
347 |   height: auto;
348 | }
349 | 
350 | /**
351 |  * 1. Address `appearance` set to `searchfield` in Safari and Chrome.
352 |  * 2. Address `box-sizing` set to `border-box` in Safari and Chrome
353 |  *    (include `-moz` to future-proof).
354 |  */
355 | 
356 | input[type="search"] {
357 |   -webkit-appearance: textfield; /* 1 */ /* 2 */
358 |   box-sizing: content-box;
359 | }
360 | 
361 | /**
362 |  * Remove inner padding and search cancel button in Safari and Chrome on OS X.
363 |  * Safari (but not Chrome) clips the cancel button when the search input has
364 |  * padding (and `textfield` appearance).
365 |  */
366 | 
367 | input[type="search"]::-webkit-search-cancel-button,
368 | input[type="search"]::-webkit-search-decoration {
369 |   -webkit-appearance: none;
370 | }
371 | 
372 | /**
373 |  * Define consistent border, margin, and padding.
374 |  */
375 | 
376 | fieldset {
377 |   border: 1px solid #c0c0c0;
378 |   margin: 0 2px;
379 |   padding: 0.35em 0.625em 0.75em;
380 | }
381 | 
382 | /**
383 |  * 1. Correct `color` not being inherited in IE 8/9/10/11.
384 |  * 2. Remove padding so people aren't caught out if they zero out fieldsets.
385 |  */
386 | 
387 | legend {
388 |   border: 0; /* 1 */
389 |   padding: 0; /* 2 */
390 | }
391 | 
392 | /**
393 |  * Remove default vertical scrollbar in IE 8/9/10/11.
394 |  */
395 | 
396 | textarea {
397 |   overflow: auto;
398 | }
399 | 
400 | /**
401 |  * Don't inherit the `font-weight` (applied by a rule above).
402 |  * NOTE: the default cannot safely be changed in Chrome and Safari on OS X.
403 |  */
404 | 
405 | optgroup {
406 |   font-weight: bold;
407 | }
408 | 
409 | /* Tables
410 |    ========================================================================== */
411 | 
412 | /**
413 |  * Remove most spacing between table cells.
414 |  */
415 | 
416 | table {
417 |   border-collapse: collapse;
418 |   border-spacing: 0;
419 | }
420 | 
421 | td,
422 | th {
423 |   padding: 0;
424 | }
425 | 


--------------------------------------------------------------------------------
/docs/stylesheets/print.css:
--------------------------------------------------------------------------------
  1 | html, body, div, span, applet, object, iframe,
  2 | h1, h2, h3, h4, h5, h6, p, blockquote, pre,
  3 | a, abbr, acronym, address, big, cite, code,
  4 | del, dfn, em, img, ins, kbd, q, s, samp,
  5 | small, strike, strong, sub, sup, tt, var,
  6 | b, u, i, center,
  7 | dl, dt, dd, ol, ul, li,
  8 | fieldset, form, label, legend,
  9 | table, caption, tbody, tfoot, thead, tr, th, td,
 10 | article, aside, canvas, details, embed, 
 11 | figure, figcaption, footer, header, hgroup, 
 12 | menu, nav, output, ruby, section, summary,
 13 | time, mark, audio, video {
 14 |   margin: 0;
 15 |   padding: 0;
 16 |   border: 0;
 17 |   font-size: 100%;
 18 |   font: inherit;
 19 |   vertical-align: baseline;
 20 | }
 21 | /* HTML5 display-role reset for older browsers */
 22 | article, aside, details, figcaption, figure, 
 23 | footer, header, hgroup, menu, nav, section {
 24 |   display: block;
 25 | }
 26 | body {
 27 |   line-height: 1;
 28 | }
 29 | ol, ul {
 30 |   list-style: none;
 31 | }
 32 | blockquote, q {
 33 |   quotes: none;
 34 | }
 35 | blockquote:before, blockquote:after,
 36 | q:before, q:after {
 37 |   content: '';
 38 |   content: none;
 39 | }
 40 | table {
 41 |   border-collapse: collapse;
 42 |   border-spacing: 0;
 43 | }
 44 | body {
 45 |   font-size: 13px;
 46 |   line-height: 1.5; 
 47 |   font-family: 'Helvetica Neue', Helvetica, Arial, serif;
 48 |   color: #000;
 49 | }
 50 | 
 51 | a {
 52 |   color: #d5000d;
 53 |   font-weight: bold;
 54 | }
 55 | 
 56 | header {
 57 |   padding-top: 35px;
 58 |   padding-bottom: 10px;
 59 | }
 60 | 
 61 | header h1 {
 62 |   font-weight: bold;
 63 |   letter-spacing: -1px;
 64 |   font-size: 48px;
 65 |   color: #303030;
 66 |   line-height: 1.2;
 67 | }
 68 | 
 69 | header h2 {
 70 |   letter-spacing: -1px;
 71 |   font-size: 24px;
 72 |   color: #aaa;
 73 |   font-weight: normal;
 74 |   line-height: 1.3;
 75 | }
 76 | #downloads {
 77 |   display: none;
 78 | }
 79 | #main_content {
 80 |   padding-top: 20px;
 81 | }
 82 | 
 83 | code, pre {
 84 |   font-family: Monaco, "Bitstream Vera Sans Mono", "Lucida Console", Terminal;
 85 |   color: #222;
 86 |   margin-bottom: 30px;
 87 |   font-size: 12px;
 88 | }
 89 | 
 90 | code {
 91 |   padding: 0 3px;
 92 | }
 93 | 
 94 | pre {
 95 |   border: solid 1px #ddd;
 96 |   padding: 20px;
 97 |   overflow: auto;
 98 | }
 99 | pre code {
100 |   padding: 0;
101 | }
102 | 
103 | ul, ol, dl {
104 |   margin-bottom: 20px;
105 | }
106 | 
107 | 
108 | /* COMMON STYLES */
109 | 
110 | table {
111 |   width: 100%;
112 |   border: 1px solid #ebebeb;
113 | }
114 | 
115 | th {
116 |   font-weight: 500;
117 | }
118 | 
119 | td {
120 |   border: 1px solid #ebebeb;
121 |   text-align: center; 
122 |   font-weight: 300;
123 | }
124 | 
125 | form {
126 |   background: #f2f2f2;
127 |   padding: 20px;
128 |   
129 | }
130 | 
131 | 
132 | /* GENERAL ELEMENT TYPE STYLES */
133 | 
134 | h1 {
135 |   font-size: 2.8em;
136 | } 
137 | 
138 | h2 {
139 |   font-size: 22px;
140 |   font-weight: bold;
141 |   color: #303030;
142 |   margin-bottom: 8px;
143 | } 
144 | 
145 | h3 {
146 |   color: #d5000d;
147 |   font-size: 18px;
148 |   font-weight: bold;
149 |   margin-bottom: 8px;
150 | } 
151 |  
152 | h4 {
153 |   font-size: 16px;
154 |   color: #303030;
155 |   font-weight: bold;
156 | } 
157 | 
158 | h5 {
159 |   font-size: 1em;
160 |   color: #303030;
161 | } 
162 | 
163 | h6 {
164 |   font-size: .8em;
165 |   color: #303030;
166 | } 
167 | 
168 | p {
169 |   font-weight: 300;
170 |   margin-bottom: 20px;
171 | }
172 |  
173 | a {
174 |   text-decoration: none;
175 | }
176 | 
177 | p a {
178 |   font-weight: 400;
179 | }
180 | 
181 | blockquote {
182 |   font-size: 1.6em;
183 |   border-left: 10px solid #e9e9e9;
184 |   margin-bottom: 20px;
185 |   padding: 0 0 0 30px;
186 | }
187 | 
188 | ul li {
189 |   list-style: disc inside;
190 |   padding-left: 20px;
191 | }
192 | 
193 | ol li {
194 |   list-style: decimal inside;
195 |   padding-left: 3px;
196 | }
197 | 
198 | dl dd {
199 |   font-style: italic;
200 |   font-weight: 100;
201 | }
202 | 
203 | footer {
204 |   margin-top: 40px;
205 |   padding-top: 20px;
206 |   padding-bottom: 30px;
207 |   font-size: 13px;
208 |   color: #aaa;
209 | }
210 | 
211 | footer a {
212 |   color: #666;
213 | }
214 | 
215 | /* MISC */
216 | .clearfix:after {
217 |   clear: both;
218 |   content: '.';
219 |   display: block;
220 |   visibility: hidden;
221 |   height: 0;
222 | }
223 | 
224 | .clearfix {display: inline-block;}
225 | * html .clearfix {height: 1%;}
226 | .clearfix {display: block;}


--------------------------------------------------------------------------------
/docs/stylesheets/pygment_trac.css:
--------------------------------------------------------------------------------
 1 | .highlight  { background: #ffffff; }
 2 | .highlight .c { color: #999988; font-style: italic } /* Comment */
 3 | .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
 4 | .highlight .k { font-weight: bold } /* Keyword */
 5 | .highlight .o { font-weight: bold } /* Operator */
 6 | .highlight .cm { color: #999988; font-style: italic } /* Comment.Multiline */
 7 | .highlight .cp { color: #999999; font-weight: bold } /* Comment.Preproc */
 8 | .highlight .c1 { color: #999988; font-style: italic } /* Comment.Single */
 9 | .highlight .cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */
10 | .highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
11 | .highlight .gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */
12 | .highlight .ge { font-style: italic } /* Generic.Emph */
13 | .highlight .gr { color: #aa0000 } /* Generic.Error */
14 | .highlight .gh { color: #999999 } /* Generic.Heading */
15 | .highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
16 | .highlight .gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */
17 | .highlight .go { color: #888888 } /* Generic.Output */
18 | .highlight .gp { color: #555555 } /* Generic.Prompt */
19 | .highlight .gs { font-weight: bold } /* Generic.Strong */
20 | .highlight .gu { color: #800080; font-weight: bold; } /* Generic.Subheading */
21 | .highlight .gt { color: #aa0000 } /* Generic.Traceback */
22 | .highlight .kc { font-weight: bold } /* Keyword.Constant */
23 | .highlight .kd { font-weight: bold } /* Keyword.Declaration */
24 | .highlight .kn { font-weight: bold } /* Keyword.Namespace */
25 | .highlight .kp { font-weight: bold } /* Keyword.Pseudo */
26 | .highlight .kr { font-weight: bold } /* Keyword.Reserved */
27 | .highlight .kt { color: #445588; font-weight: bold } /* Keyword.Type */
28 | .highlight .m { color: #009999 } /* Literal.Number */
29 | .highlight .s { color: #d14 } /* Literal.String */
30 | .highlight .na { color: #008080 } /* Name.Attribute */
31 | .highlight .nb { color: #0086B3 } /* Name.Builtin */
32 | .highlight .nc { color: #445588; font-weight: bold } /* Name.Class */
33 | .highlight .no { color: #008080 } /* Name.Constant */
34 | .highlight .ni { color: #800080 } /* Name.Entity */
35 | .highlight .ne { color: #990000; font-weight: bold } /* Name.Exception */
36 | .highlight .nf { color: #990000; font-weight: bold } /* Name.Function */
37 | .highlight .nn { color: #555555 } /* Name.Namespace */
38 | .highlight .nt { color: #000080 } /* Name.Tag */
39 | .highlight .nv { color: #008080 } /* Name.Variable */
40 | .highlight .ow { font-weight: bold } /* Operator.Word */
41 | .highlight .w { color: #bbbbbb } /* Text.Whitespace */
42 | .highlight .mf { color: #009999 } /* Literal.Number.Float */
43 | .highlight .mh { color: #009999 } /* Literal.Number.Hex */
44 | .highlight .mi { color: #009999 } /* Literal.Number.Integer */
45 | .highlight .mo { color: #009999 } /* Literal.Number.Oct */
46 | .highlight .sb { color: #d14 } /* Literal.String.Backtick */
47 | .highlight .sc { color: #d14 } /* Literal.String.Char */
48 | .highlight .sd { color: #d14 } /* Literal.String.Doc */
49 | .highlight .s2 { color: #d14 } /* Literal.String.Double */
50 | .highlight .se { color: #d14 } /* Literal.String.Escape */
51 | .highlight .sh { color: #d14 } /* Literal.String.Heredoc */
52 | .highlight .si { color: #d14 } /* Literal.String.Interpol */
53 | .highlight .sx { color: #d14 } /* Literal.String.Other */
54 | .highlight .sr { color: #009926 } /* Literal.String.Regex */
55 | .highlight .s1 { color: #d14 } /* Literal.String.Single */
56 | .highlight .ss { color: #990073 } /* Literal.String.Symbol */
57 | .highlight .bp { color: #999999 } /* Name.Builtin.Pseudo */
58 | .highlight .vc { color: #008080 } /* Name.Variable.Class */
59 | .highlight .vg { color: #008080 } /* Name.Variable.Global */
60 | .highlight .vi { color: #008080 } /* Name.Variable.Instance */
61 | .highlight .il { color: #009999 } /* Literal.Number.Integer.Long */
62 | 
63 | .type-csharp .highlight .k { color: #0000FF }
64 | .type-csharp .highlight .kt { color: #0000FF }
65 | .type-csharp .highlight .nf { color: #000000; font-weight: normal }
66 | .type-csharp .highlight .nc { color: #2B91AF }
67 | .type-csharp .highlight .nn { color: #000000 }
68 | .type-csharp .highlight .s { color: #A31515 }
69 | .type-csharp .highlight .sc { color: #A31515 }
70 | 


--------------------------------------------------------------------------------
/docs/stylesheets/stylesheet.css:
--------------------------------------------------------------------------------
  1 | * {
  2 |   box-sizing: border-box; }
  3 | 
  4 | body {
  5 |   padding: 0;
  6 |   margin: 0;
  7 |   font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
  8 |   font-size: 16px;
  9 |   line-height: 1.5;
 10 |   color: #606c71; }
 11 | 
 12 | a {
 13 |   color: #1e6bb8;
 14 |   text-decoration: none; }
 15 |   a:hover {
 16 |     text-decoration: underline; }
 17 | 
 18 | .btn {
 19 |   display: inline-block;
 20 |   margin-bottom: 0.4rem;
 21 |   color: rgba(255, 255, 255, 0.7);
 22 |   background-color: rgba(255, 255, 255, 0.08);
 23 |   border-color: rgba(255, 255, 255, 0.2);
 24 |   border-style: solid;
 25 |   border-width: 1px;
 26 |   border-radius: 0.3rem;
 27 |   transition: color 0.2s, background-color 0.2s, border-color 0.2s; }
 28 |   .btn + .btn {
 29 |     margin-left: 0.2rem; }
 30 | 
 31 | .btn:hover {
 32 |   color: rgba(255, 255, 255, 0.8);
 33 |   text-decoration: none;
 34 |   background-color: rgba(255, 255, 255, 0.2);
 35 |   border-color: rgba(255, 255, 255, 0.3); }
 36 | 
 37 | @media screen and (min-width: 64em) {
 38 |   .btn {
 39 |     padding: 0.2rem 0.4rem;
 40 |     font-size: 0.9rem;
 41 |   } }
 42 | 
 43 | @media screen and (min-width: 42em) and (max-width: 64em) {
 44 |   .btn {
 45 |     padding: 0.2rem 0.4rem;
 46 |     font-size: 0.9rem; } }
 47 | 
 48 | @media screen and (max-width: 42em) {
 49 |   .btn {
 50 |     display: block;
 51 |     width: 100%;
 52 |     padding: 0.2rem;
 53 |     font-size: 0.9rem; }
 54 |     .btn + .btn {
 55 |       margin-top: 0.4rem;
 56 |       margin-left: 0; } }
 57 | 
 58 | .page-header {
 59 |   color: #fff;
 60 |   text-align: center;
 61 |   background-color: #363899;
 62 |   background-image: linear-gradient(90deg, #000000, #99120f); }
 63 | 
 64 | .header-image {
 65 |   align: middle;
 66 |   height: 140px;
 67 | }
 68 | 
 69 | @media screen and (min-width: 64em) {
 70 |   .page-header {
 71 |     padding: 1rem 1rem; } }
 72 | 
 73 | @media screen and (min-width: 42em) and (max-width: 64em) {
 74 |   .page-header {
 75 |     padding: 1rem 1rem; } }
 76 | 
 77 | @media screen and (max-width: 42em) {
 78 |   .page-header {
 79 |     padding: 0rem 0rem; } }
 80 | 
 81 | .project-name {
 82 |   margin-top: 0;
 83 |   margin-bottom: 0.1rem; }
 84 | 
 85 | @media screen and (min-width: 64em) {
 86 |   .project-name {
 87 |     font-size: 3.25rem; } }
 88 | 
 89 | @media screen and (min-width: 42em) and (max-width: 64em) {
 90 |   .project-name {
 91 |     font-size: 2.25rem; } }
 92 | 
 93 | @media screen and (max-width: 42em) {
 94 |   .project-name {
 95 |     font-size: 1.75rem; } }
 96 | 
 97 | .project-tagline {
 98 |   margin-bottom: 0rem;
 99 |   font-weight: normal;
100 |   opacity: 0.7; }
101 | 
102 | @media screen and (min-width: 64em) {
103 |   .project-tagline {
104 |     font-size: 1.25rem; } }
105 | 
106 | @media screen and (min-width: 42em) and (max-width: 64em) {
107 |   .project-tagline {
108 |     font-size: 1.15rem; } }
109 | 
110 | @media screen and (max-width: 42em) {
111 |   .project-tagline {
112 |     font-size: 1rem; } }
113 | 
114 | .main-content :first-child {
115 |   margin-top: 0; }
116 | .main-content img {
117 |   max-width: 100%; }
118 | .main-content h1, .main-content h2, .main-content h3, .main-content h4, .main-content h5, .main-content h6 {
119 |   margin-top: 2rem;
120 |   margin-bottom: 1rem;
121 |   font-weight: normal;
122 |   color: #159957; }
123 | .main-content p {
124 |   margin-bottom: 1em; }
125 | .main-content code {
126 |   padding: 2px 4px;
127 |   font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
128 |   font-size: 0.9rem;
129 |   color: #383e41;
130 |   background-color: #f3f6fa;
131 |   border-radius: 0.3rem; }
132 | .main-content pre {
133 |   padding: 0.8rem;
134 |   margin-top: 0;
135 |   margin-bottom: 1rem;
136 |   font: 1rem Consolas, "Liberation Mono", Menlo, Courier, monospace;
137 |   color: #567482;
138 |   word-wrap: normal;
139 |   background-color: #f3f6fa;
140 |   border: solid 1px #dce6f0;
141 |   border-radius: 0.3rem; }
142 |   .main-content pre > code {
143 |     padding: 0;
144 |     margin: 0;
145 |     font-size: 0.9rem;
146 |     color: #567482;
147 |     word-break: normal;
148 |     white-space: pre;
149 |     background: transparent;
150 |     border: 0; }
151 | .main-content .highlight {
152 |   margin-bottom: 1rem; }
153 |   .main-content .highlight pre {
154 |     margin-bottom: 0;
155 |     word-break: normal; }
156 | .main-content .highlight pre, .main-content pre {
157 |   padding: 0.8rem;
158 |   overflow: auto;
159 |   font-size: 0.9rem;
160 |   line-height: 1.45;
161 |   border-radius: 0.3rem; }
162 | .main-content pre code, .main-content pre tt {
163 |   display: inline;
164 |   max-width: initial;
165 |   padding: 0;
166 |   margin: 0;
167 |   overflow: initial;
168 |   line-height: inherit;
169 |   word-wrap: normal;
170 |   background-color: transparent;
171 |   border: 0; }
172 |   .main-content pre code:before, .main-content pre code:after, .main-content pre tt:before, .main-content pre tt:after {
173 |     content: normal; }
174 | .main-content ul, .main-content ol {
175 |   margin-top: 0; }
176 | .main-content blockquote {
177 |   padding: 0 1rem;
178 |   margin-left: 0;
179 |   color: #819198;
180 |   border-left: 0.3rem solid #dce6f0; }
181 |   .main-content blockquote > :first-child {
182 |     margin-top: 0; }
183 |   .main-content blockquote > :last-child {
184 |     margin-bottom: 0; }
185 | .main-content table {
186 |   display: block;
187 |   width: 100%;
188 |   overflow: auto;
189 |   word-break: normal;
190 |   word-break: keep-all; }
191 |   .main-content table th {
192 |     font-weight: bold; }
193 |   .main-content table th, .main-content table td {
194 |     padding: 0.5rem 1rem;
195 |     border: 1px solid #e9ebec; }
196 | .main-content dl {
197 |   padding: 0; }
198 |   .main-content dl dt {
199 |     padding: 0;
200 |     margin-top: 1rem;
201 |     font-size: 1rem;
202 |     font-weight: bold; }
203 |   .main-content dl dd {
204 |     padding: 0;
205 |     margin-bottom: 1rem; }
206 | .main-content hr {
207 |   height: 2px;
208 |   padding: 0;
209 |   margin: 1rem 0;
210 |   background-color: #eff0f1;
211 |   border: 0; }
212 | 
213 | @media screen and (min-width: 64em) {
214 |   .main-content {
215 |     padding: 2rem 6rem;
216 |     margin: 0 auto;
217 |     font-size: 1.1rem; } }
218 | 
219 | @media screen and (min-width: 42em) and (max-width: 64em) {
220 |   .main-content {
221 |     padding: 2rem 4rem;
222 |     font-size: 1.1rem; } }
223 | 
224 | @media screen and (max-width: 42em) {
225 |   .main-content {
226 |     padding: 2rem 1rem;
227 |     font-size: 1rem; } }
228 | 
229 | .site-footer {
230 |   padding-top: 2rem;
231 |   margin-top: 2rem;
232 |   border-top: solid 1px #eff0f1; }
233 | 
234 | .site-footer-owner {
235 |   display: block;
236 |   font-weight: bold; }
237 | 
238 | .site-footer-credits {
239 |   color: #819198; }
240 | 
241 | @media screen and (min-width: 64em) {
242 |   .site-footer {
243 |     font-size: 1rem; } }
244 | 
245 | @media screen and (min-width: 42em) and (max-width: 64em) {
246 |   .site-footer {
247 |     font-size: 1rem; } }
248 | 
249 | @media screen and (max-width: 42em) {
250 |   .site-footer {
251 |     font-size: 0.9rem; } }
252 | 


--------------------------------------------------------------------------------
/docs/stylesheets/table.css:
--------------------------------------------------------------------------------
 1 | table#compare tr:nth-child(even) {
 2 |   background-color: #eee;
 3 | }
 4 | table#compare tr:nth-child(odd) {
 5 |   background-color: #fff;
 6 | }
 7 | table#compare th {
 8 |   color: white;
 9 |   background-color: black;
10 | }
11 | 


--------------------------------------------------------------------------------
/docs/why.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | layout: default
  3 | ---
  4 | 
  5 | ## Why Parallel Minion?
  6 | 
  7 | We recently re-wrote a Golang service in Ruby. The service worked well, but we had
  8 | no one to support it since our Golang engineers left to run Golang conferences.
  9 | 
 10 | The first iteration in Ruby used a single thread and was about twice as slow
 11 | as the Go service. The Go service was creating upwards of 30 go-routines to perform
 12 | concurrent database calls, and then perform subsequent calculations with all the results.
 13 | 
 14 | The go service made extensive use of channels and go routines. Since our application
 15 | runs on JRuby it made sense to keep this concurrency.
 16 | 
 17 | Several concurrency frameworks were considered:
 18 | 
 19 | - [Celluloid](http://celluloid.io)
 20 | - [Agent](https://github.com/igrigorik/agent)
 21 | - [Qwirk](https://github.com/bpardee/qwirk)
 22 | - [jruby-go](https://gist.github.com/michaelfairley/4140714)
 23 | 
 24 | All of the above approaches did not meet our requirement for a pragmatic solution
 25 | to simple concurrency.
 26 | 
 27 | For significantly more complex scenarios where Software Engineers are intimately
 28 | familiar with concurrency and it's challenges the above frameworks do offer a viable solution.
 29 | 
 30 | To meet the pragmatic requirement we built a thin layer on top of the Thread class,
 31 | called Parallel Minion. JRuby already has extensive support for thread pooling,
 32 | so we did not have to write our own.
 33 | 
 34 | In practice we have found that minions can be used by just about any Rails developer.
 35 | 
 36 | Parallel Minion allows you to take existing blocks of code and wrap them in a minion
 37 | so that they can run asynchronously in a separate thread. The minion then passes
 38 | back the result to the caller when or if requested. If any exceptions were
 39 | thrown during the minion processing, it will be re-raised in the callers thread
 40 | so that no additional work needs to be done when converting existing code to use minions.
 41 | 
 42 | ```ruby
 43 | minion = ParallelMinion::Minion.new(10.days.ago, description: 'Doing something else in parallel', timeout: 1000) do |date|
 44 |   MyTable.where('created_at <= ?', date).count
 45 | end
 46 | 
 47 | # Do other work here...
 48 | 
 49 | # Retrieve the result of the minion
 50 | count = minion.result
 51 | 
 52 | puts "Found #{count} records"
 53 | ```
 54 | 
 55 | After changing the Ruby replacement to use minions to break out many different
 56 | code blocks to run concurrently from a single method, it ended up running faster
 57 | than the equivalent Go service. We are not sure why it ran faster other than by
 58 | using Parallel Minion it gave us greater visibility through its built-in logging to
 59 | make re-organizing blocks of code for greatest efficiency very straight forward.
 60 | 
 61 | The processing time is significantly reduced since the various blocks within the code
 62 | can be run at the same time. No understanding of channels, go-routines,
 63 | inter-thread communication, or even threads is required to use minions.
 64 | 
 65 | To ensure that the minions work seamlessly in Rails applications Parallel Minion
 66 | also performs the following transparently:
 67 | 
 68 | - any logging tags defined in the current thread are passed onto the minion's thread
 69 | - Active Record scopes are copied to the new thread, to ensure that dynamic scoping
 70 |   within Rails is honored by minions.
 71 | - minion processing times are logged to help with refining which blocks to run in
 72 |   which order, or even to break blocks up into multiple blocks each in their own minion.
 73 | - if the main thread has to wait for one or more minions to complete the name of the
 74 |   minion and the wait time are logged.
 75 | - the name of the minion is assigned to its thread name so that any log entries
 76 |   written during the execution of the minion are immediately identifiable as coming
 77 |   from that minion.
 78 | - returns Active Record database connections to it's connection pool when the
 79 |   minion is done with the connection.
 80 | 
 81 | Something that is very important to us is the ability to timeout waiting for a minion
 82 | to complete. If for example a minion is responsible for communicating with an
 83 | external vendor, those calls can sometimes take too long, so we want the application
 84 | to be able to continue with a sub-set of the information available rather than fail
 85 | entirely. When the minion eventually completes it can still save any information
 86 | returned even though it may not be used by the current call. As a result the minion
 87 | is not killed or stopped when we timeout waiting for it, although it could be killed
 88 | if required.
 89 | 
 90 | Parallel Minion does not enforce "pass-by-copy" for all data passed to a minion
 91 | so it is possible to have two threads operate on the same data. It is therefore
 92 | highly recommended to copy all data passed to minions, or freezing them so that
 93 | minions do not have the ability to write to the same objects at the same time.
 94 | 
 95 | In this way locking is removed, and converting existing code to minions is very easy.
 96 | 
 97 | Parallel Minion runs on both Ruby and JRuby, allowing for development using Ruby
 98 | and then testing and deploying on JRuby for greatest performance and concurrency.
 99 | 
100 | We are now using minions in several key processing intensive parts of our production
101 | application and have already seen a 30% reduction in processing time.
102 | Over time we expect further reductions as we adopt minions throughout our extensive code-base.
103 | 
104 | The key with minions is that they make it very simple to introduce concurrency
105 | without re-writing existing code, or having to train Ruby developers on complex
106 | concurrency frameworks. The level of risk with implementing minions is very low
107 | because it returns existing return values and exceptions from blocks of code.
108 | 
109 | For an in-depth example of how minions can reduce latency: [Example](example.html)
110 | 


--------------------------------------------------------------------------------
/gemfiles/rails_5.1.gemfile:
--------------------------------------------------------------------------------
 1 | # This file was generated by Appraisal
 2 | 
 3 | source "https://rubygems.org"
 4 | 
 5 | gem "activerecord", "~> 5.1.5"
 6 | gem "minitest"
 7 | gem "rake"
 8 | gem "sqlite3", "~> 1.3.0", platform: :ruby
 9 | gem "amazing_print"
10 | gem "appraisal"
11 | gem "activerecord-jdbcsqlite3-adapter", "~> 51.0", platform: :jruby
12 | 
13 | gemspec path: "../"
14 | 


--------------------------------------------------------------------------------
/gemfiles/rails_5.2.gemfile:
--------------------------------------------------------------------------------
 1 | # This file was generated by Appraisal
 2 | 
 3 | source "https://rubygems.org"
 4 | 
 5 | gem "activerecord", "~> 5.2.0"
 6 | gem "minitest"
 7 | gem "rake"
 8 | gem "sqlite3", "~> 1.3.0", platform: :ruby
 9 | gem "amazing_print"
10 | gem "appraisal"
11 | gem "activerecord-jdbcsqlite3-adapter", "~> 52.0", platform: :jruby
12 | 
13 | gemspec path: "../"
14 | 


--------------------------------------------------------------------------------
/gemfiles/rails_6.0.gemfile:
--------------------------------------------------------------------------------
 1 | # This file was generated by Appraisal
 2 | 
 3 | source "https://rubygems.org"
 4 | 
 5 | gem "activerecord", "~> 6.0.0"
 6 | gem "minitest"
 7 | gem "rake"
 8 | gem "sqlite3", "~> 1.4.0", platform: :ruby
 9 | gem "amazing_print"
10 | gem "appraisal"
11 | gem "activerecord-jdbcsqlite3-adapter", "~> 60.0", platform: :jruby
12 | 
13 | gemspec path: "../"
14 | 


--------------------------------------------------------------------------------
/gemfiles/rails_6.1.gemfile:
--------------------------------------------------------------------------------
 1 | # This file was generated by Appraisal
 2 | 
 3 | source "https://rubygems.org"
 4 | 
 5 | gem "activerecord", "~> 6.1.0"
 6 | gem "minitest"
 7 | gem "rake"
 8 | gem "sqlite3", "~> 1.4.0", platform: :ruby
 9 | gem "amazing_print"
10 | gem "appraisal"
11 | gem "activerecord-jdbcsqlite3-adapter", "~> 61.0", platform: :jruby
12 | 
13 | gemspec path: "../"
14 | 


--------------------------------------------------------------------------------
/gemfiles/rails_7.0.gemfile:
--------------------------------------------------------------------------------
 1 | # This file was generated by Appraisal
 2 | 
 3 | source "https://rubygems.org"
 4 | 
 5 | gem "activerecord", "~> 7.0"
 6 | gem "minitest"
 7 | gem "rake"
 8 | gem "sqlite3", "~> 1.4.0", platform: :ruby
 9 | gem "amazing_print"
10 | gem "appraisal"
11 | 
12 | gemspec path: "../"
13 | 


--------------------------------------------------------------------------------
/lib/parallel_minion.rb:
--------------------------------------------------------------------------------
1 | require "semantic_logger"
2 | 
3 | module ParallelMinion
4 |   autoload :Minion, "parallel_minion/minion"
5 | end
6 | 
7 | require "parallel_minion/railtie" if defined?(Rails)
8 | 


--------------------------------------------------------------------------------
/lib/parallel_minion/minion.rb:
--------------------------------------------------------------------------------
  1 | # Instruct a Minion to perform a specific task in a separate thread
  2 | module ParallelMinion
  3 |   class Minion
  4 |     include SemanticLogger::Loggable
  5 | 
  6 |     # Returns [String] the description supplied on the initializer
  7 |     attr_reader :description
  8 | 
  9 |     # Returns [Exception] the exception that was raised otherwise nil
 10 |     attr_reader :exception
 11 | 
 12 |     # Returns [Integer] the maximum duration in milli-seconds that the Minion may take to complete the task
 13 |     attr_reader :timeout
 14 | 
 15 |     # Returns [Array<Object>] list of arguments in the order they were passed into the initializer
 16 |     attr_reader :arguments
 17 | 
 18 |     # Returns [Float] the number of milli-seconds the the minion took to complete
 19 |     # Returns nil if the minion is still running
 20 |     attr_reader :duration
 21 | 
 22 |     # Metrics [String]
 23 |     attr_reader :metric, :wait_metric
 24 | 
 25 |     attr_reader :on_timeout, :log_exception, :start_time, :on_exception_level
 26 | 
 27 |     # Give an infinite amount of time to wait for a Minion to complete a task
 28 |     INFINITE = 0
 29 | 
 30 |     # Sets whether Minions should run in a separate thread.
 31 |     #
 32 |     # By Setting _enabled_ to false all Minions that have not yet been created
 33 |     # will run in the thread in which it is created.
 34 |     # - Development:
 35 |     #    Use a debugger, since the code will run in the current thread.
 36 |     # - Test:
 37 |     #     Keep test execution in the current thread.
 38 |     #     Supports rolling back database changes after each test, since all changes are
 39 |     #     performed on the same database connection.
 40 |     # - Production:
 41 |     #     Batch processing in Rocket Job where throughput is more important than latency.
 42 |     #       http://rocketjob.io
 43 |     class << self
 44 |       attr_writer :enabled
 45 |     end
 46 | 
 47 |     # Returns whether minions are enabled to run in their own threads
 48 |     def self.enabled?
 49 |       @enabled
 50 |     end
 51 | 
 52 |     # The list of classes for which the current scope must be copied into the
 53 |     # new Minion (Thread)
 54 |     #
 55 |     # Example:
 56 |     #   ...
 57 |     class << self
 58 |       attr_reader :scoped_classes
 59 |     end
 60 | 
 61 |     def self.scoped_classes=(scoped_classes)
 62 |       @scoped_classes = scoped_classes.dup
 63 |     end
 64 | 
 65 |     # Change the log level for the Started log message.
 66 |     #
 67 |     # Default: :info
 68 |     #
 69 |     # Valid levels:
 70 |     #   :trace, :debug, :info, :warn, :error, :fatal
 71 |     def self.started_log_level=(level)
 72 |       raise(ArgumentError, "Invalid log level: #{level}") unless SemanticLogger::LEVELS.include?(level)
 73 | 
 74 |       @started_log_level = level
 75 |     end
 76 | 
 77 |     class << self
 78 |       attr_reader :started_log_level
 79 |     end
 80 | 
 81 |     # Change the log level for the Completed log message.
 82 |     #
 83 |     # Default: :info
 84 |     #
 85 |     # Valid levels:
 86 |     #   :trace, :debug, :info, :warn, :error, :fatal
 87 |     def self.completed_log_level=(level)
 88 |       raise(ArgumentError, "Invalid log level: #{level}") unless SemanticLogger::LEVELS.include?(level)
 89 | 
 90 |       @completed_log_level = level
 91 |     end
 92 | 
 93 |     class << self
 94 |       attr_reader :completed_log_level
 95 |     end
 96 | 
 97 |     self.started_log_level   = :info
 98 |     self.completed_log_level = :info
 99 |     self.enabled             = true
100 |     self.scoped_classes      = []
101 | 
102 |     # Create a new Minion
103 |     #
104 |     #   Creates a new thread and logs the time for the supplied block to complete processing.
105 |     #   The exception without stack trace is logged whenever an exception is thrown in the thread.
106 |     #
107 |     #   Re-raises any unhandled exception in the calling thread when `#result` is called.
108 |     #   Copies the logging tags and specified ActiveRecord scopes to the new thread.
109 |     #
110 |     # Parameters
111 |     #   *arguments
112 |     #     Any number of arguments can be supplied that are passed into the block
113 |     #     in the order they are listed.
114 |     #
115 |     #     Note:
116 |     #       All arguments must be supplied by copy and not by reference.
117 |     #       For example, use `#dup` to create copies of passed data.
118 |     #       Pass by copy is critical to prevent concurrency issues when multiple threads
119 |     #       attempt to update the same object at the same time.
120 |     #
121 |     #   Proc / lambda
122 |     #     A block of code must be supplied that the Minion will execute.
123 |     #
124 |     #     Note:
125 |     #       This block will be executed within the scope of the created minion instance
126 |     #       and _not_ within the scope of where the Proc/lambda was originally created.
127 |     #       This is done to force all parameters to be passed in explicitly
128 |     #       and should be read-only or duplicates of the original data.
129 |     #
130 |     #   :description [String]
131 |     #     Description for this task that the Minion is performing.
132 |     #     Written to the log file along with the time take to complete the task.
133 |     #
134 |     #   :timeout [Integer]
135 |     #     Maximum amount of time in milli-seconds that the task may take to complete
136 |     #     before #result times out.
137 |     #     Set to 0 to give the thread an infinite amount of time to complete.
138 |     #     Default: 0 ( Wait forever )
139 |     #
140 |     #     Notes:
141 |     #     - :timeout does not affect what happens to the Minion running the
142 |     #       the task, it only affects how long #result will take to return.
143 |     #     - The Minion will continue to run even after the timeout has been exceeded
144 |     #     - If :enabled is false, or ParallelMinion::Minion.enabled is false,
145 |     #       then :timeout is ignored and assumed to be Minion::INFINITE
146 |     #       since the code is run in the calling thread when the Minion is created
147 |     #
148 |     #   :on_timeout [Exception]
149 |     #     The class to raise on the minion when the minion times out.
150 |     #     By raising the exception on the running thread it ensures that the thread
151 |     #     ends due to the exception, rather than continuing to execute.
152 |     #     The exception is only raised on the running minion when #result is called.
153 |     #     The current call to #result will complete with a result of nil, future
154 |     #     calls to #result will raise the supplied exception on the current thread
155 |     #     since the thread will have terminated with that exception.
156 |     #
157 |     #     Note: :on_timeout has no effect if not #enabled?
158 |     #
159 |     #   :metric [String]
160 |     #     Name of the metric to forward to Semantic Logger when measuring the minion execution time.
161 |     #     Example: inquiry/address_cleansing
162 |     #
163 |     #     When a metric is supplied the following metrics will also be generated:
164 |     #     - wait
165 |     #         Duration waiting for a minion to complete.
166 |     #
167 |     #     The additional metrics are added to the supplied metric name. For example:
168 |     #     - inquiry/address_cleansing/wait
169 |     #
170 |     #   :log_exception [Symbol]
171 |     #     Control whether or how an exception thrown in the block is
172 |     #     reported by Semantic Logger. Values:
173 |     #      :full
174 |     #        Log the exception class, message, and backtrace
175 |     #      :partial
176 |     #        Log the exception class and message. The backtrace will not be logged
177 |     #      :off
178 |     #        Any unhandled exception raised in the block will not be logged
179 |     #      Default: :partial
180 |     #
181 |     #   :on_exception_level [:trace | :debug | :info | :warn | :error | :fatal]
182 |     #     Override the log level only when an exception occurs.
183 |     #     Default: ParallelMinion::Minion.completed_log_level
184 |     #
185 |     #   :enabled [Boolean]
186 |     #     Override the global setting: `ParallelMinion::Minion.enabled?` for this minion instance.
187 |     #
188 |     # The overhead for moving the task to a Minion (separate thread) vs running it
189 |     # sequentially is about 0.3 ms if performing other tasks in-between starting
190 |     # the task and requesting its result.
191 |     #
192 |     # The following call adds 0.5 ms to total processing time vs running the
193 |     # code in-line:
194 |     #   ParallelMinion::Minion.new(description: 'Count', timeout: 5) { 1 }.result
195 |     #
196 |     # Note:
197 |     #   On JRuby it is recommended to add the following setting to .jrubyrc
198 |     #     thread.pool.enabled=true
199 |     #
200 |     # Example:
201 |     #   ParallelMinion::Minion.new(
202 |     #     10.days.ago,
203 |     #     description: 'Doing something else in parallel',
204 |     #     timeout:     1000
205 |     #   ) do |date|
206 |     #     MyTable.where('created_at <= ?', date).count
207 |     #   end
208 |     #
209 |     # Example, when the result is being ignored, log full exception as an error:
210 |     #   ParallelMinion::Minion.new(
211 |     #     customer,
212 |     #     description:        "We don't care about the result",
213 |     #     log_exception:      :full,
214 |     #     on_exception_level: :error
215 |     #   ) do |customer|
216 |     #     customer.save!
217 |     #   end
218 |     def initialize(*arguments,
219 |                    description: "Minion",
220 |                    metric: nil,
221 |                    log_exception: nil,
222 |                    on_exception_level: self.class.completed_log_level,
223 |                    enabled: self.class.enabled?,
224 |                    timeout: INFINITE,
225 |                    on_timeout: nil,
226 |                    wait_metric: nil,
227 |                    &block)
228 |       raise "Missing mandatory block that Minion must perform" unless block
229 | 
230 |       @start_time         = Time.now
231 |       @exception          = nil
232 |       @arguments          = arguments
233 |       @timeout            = timeout.to_f
234 |       @description        = description.to_s
235 |       @metric             = metric
236 |       @log_exception      = log_exception
237 |       @on_exception_level = on_exception_level
238 |       @enabled            = enabled
239 |       @on_timeout         = on_timeout
240 | 
241 |       @wait_metric        = (wait_metric || "#{metric}/wait") if @metric
242 | 
243 |       # When minion is disabled make it obvious in the logs by setting the name to 'Inline' instead of 'Minion'.
244 |       unless @enabled
245 |         l           = self.class.logger.dup
246 |         l.name      = "Inline"
247 |         self.logger = l
248 |       end
249 | 
250 |       @enabled ? run(&block) : run_inline(&block)
251 |     end
252 | 
253 |     # Returns the result when the thread completes
254 |     # Returns nil if the thread has not yet completed
255 |     # Raises any unhandled exception in the thread, if any
256 |     #
257 |     # Note: The result of any thread cannot be nil
258 |     def result
259 |       # Return nil if Minion is still working and has time left to finish
260 |       if working?
261 |         ms = time_left
262 |         logger.measure(
263 |           self.class.completed_log_level,
264 |           "Waited for Minion to complete: #{description}",
265 |           min_duration: 0.01,
266 |           metric:       wait_metric
267 |         ) do
268 |           if @thread.join(ms.nil? ? nil : ms / 1000).nil?
269 |             @thread.raise(@on_timeout.new("Minion: #{description} timed out")) if @on_timeout
270 |             logger.warn("Timed out waiting for: #{description}")
271 |             return
272 |           end
273 |         end
274 |       end
275 | 
276 |       # Return the exception, if any, otherwise the task result
277 |       exception.nil? ? @result : Kernel.raise(exception)
278 |     end
279 | 
280 |     # Returns [Boolean] whether the minion is still working on the assigned task
281 |     def working?
282 |       enabled? ? @thread.alive? : false
283 |     end
284 | 
285 |     # Returns [Boolean] whether the minion has completed working on the task
286 |     def completed?
287 |       enabled? ? @thread.stop? : true
288 |     end
289 | 
290 |     # Returns [Boolean] whether the minion failed while performing the assigned task
291 |     def failed?
292 |       !exception.nil?
293 |     end
294 | 
295 |     # Returns the amount of time left in milli-seconds that this Minion has to finish its task
296 |     # Returns 0 if no time is left
297 |     # Returns nil if their is no time limit. I.e. :timeout was set to Minion::INFINITE (infinite time left)
298 |     def time_left
299 |       return nil if timeout.zero? || (timeout == -1)
300 | 
301 |       duration = timeout - ((Time.now - start_time) * 1000)
302 |       duration <= 0 ? 0 : duration
303 |     end
304 | 
305 |     # Returns [Boolean] whether this minion is enabled to run in a separate thread
306 |     def enabled?
307 |       @enabled
308 |     end
309 | 
310 |     # Returns the current scopes for each of the models for which scopes will be
311 |     # copied to the Minions
312 |     if defined?(ActiveRecord)
313 |       if ActiveRecord::VERSION::MAJOR >= 4
314 |         def self.current_scopes
315 |           scoped_classes.collect(&:all)
316 |         end
317 |       else
318 |         def self.current_scopes
319 |           scoped_classes.collect(&:scoped)
320 |         end
321 |       end
322 |     end
323 | 
324 |     private
325 | 
326 |     # rubocop:disable Lint/RescueException
327 | 
328 |     # Run the supplied block of code in the current thread.
329 |     # Useful for debugging, testing, and when running in batch environments.
330 |     def run_inline(&block)
331 |       logger.public_send(self.class.started_log_level, "Started #{description}")
332 |       logger.measure(
333 |         self.class.completed_log_level,
334 |         "Completed #{description}",
335 |         log_exception:      log_exception,
336 |         on_exception_level: on_exception_level,
337 |         metric:             metric
338 |       ) do
339 |         @result = instance_exec(*arguments, &block)
340 |       end
341 |     rescue Exception => e
342 |       @exception = e
343 |     ensure
344 |       @duration = Time.now - start_time
345 |     end
346 | 
347 |     # rubocop:enable Lint/RescueException
348 | 
349 |     def run(&block)
350 |       # Capture tags from current thread
351 |       tags = SemanticLogger.tags
352 |       tags = tags.nil? || tags.empty? ? nil : tags.dup
353 | 
354 |       named_tags = SemanticLogger.named_tags
355 |       named_tags = named_tags.nil? || named_tags.empty? ? nil : named_tags.dup
356 | 
357 |       # Captures scopes from current thread. Only applicable for AR models
358 |       scopes     = self.class.current_scopes if defined?(ActiveRecord::Base)
359 | 
360 |       @thread = Thread.new(*arguments) do
361 |         Thread.current.name = "#{description}-#{Thread.current.object_id}"
362 | 
363 |         # Copy logging tags from parent thread, if any
364 |         SemanticLogger.tagged(*tags) do
365 |           SemanticLogger.named_tagged(named_tags) do
366 |             logger.public_send(self.class.started_log_level, "Started #{description}")
367 |             # rubocop:disable Lint/RescueException
368 |             begin
369 |               proc = proc { run_in_scope(scopes, &block) }
370 |               logger.measure(
371 |                 self.class.completed_log_level,
372 |                 "Completed #{description}",
373 |                 log_exception:      log_exception,
374 |                 on_exception_level: on_exception_level,
375 |                 metric:             metric,
376 |                 &proc
377 |               )
378 |             rescue Exception => e
379 |               @exception = e
380 |               nil
381 |             ensure
382 |               @duration = Time.now - start_time
383 |               # Return any database connections used by this thread back to the pool
384 |               ActiveRecord::Base.clear_active_connections! if defined?(ActiveRecord::Base)
385 |             end
386 |             # rubocop:enable Lint/RescueException
387 |           end
388 |         end
389 |       end
390 |     end
391 | 
392 |     def run_in_scope(scopes, &block)
393 |       if scopes.nil? || scopes.empty?
394 |         @result = instance_exec(*@arguments, &block)
395 |       else
396 |         # Use the captured scope when running the block.
397 |         # Each Class to scope requires passing a block to .scoping.
398 |         proc  = proc { instance_exec(*@arguments, &block) }
399 |         first = scopes.shift
400 |         scopes.each { |scope| proc = proc { scope.scoping(&proc) } }
401 |         @result = first.scoping(&proc)
402 |       end
403 |     end
404 |   end
405 | end
406 | 


--------------------------------------------------------------------------------
/lib/parallel_minion/railtie.rb:
--------------------------------------------------------------------------------
 1 | module ParallelMinion # :nodoc:
 2 |   class Railtie < Rails::Railtie # :nodoc:
 3 |     #
 4 |     # Make the ParallelMinion config available in the Rails application config
 5 |     #
 6 |     # Example: Make debugging easier
 7 |     #    in file config/environments/development.rb
 8 |     #
 9 |     #   Rails::Application.configure do
10 |     #
11 |     #     # Run Minions in the current thread to make debugging easier
12 |     #     config.parallel_minion.enabled = false
13 |     #
14 |     #     # Change the log level for the started log messages to :debug,
15 |     #     # so that they do not show up in production when log level is :info.
16 |     #     config.parallel_minion.started_log_level = :debug
17 |     #
18 |     #     # Change the log level for the completed log messages to :debug,
19 |     #     # so that they do not show up in production when log level is :info.
20 |     #     config.parallel_minion.completed_log_level = :debug
21 |     #
22 |     #     # Add a model so that its current scope is copied to the Minion
23 |     #     config.after_initialize do
24 |     #       # Perform in an after_initialize so that the model has been loaded
25 |     #       config.parallel_minion.scoped_classes << MyScopedModel
26 |     #     end
27 |     #   end
28 |     config.parallel_minion = ::ParallelMinion::Minion
29 |   end
30 | end
31 | 


--------------------------------------------------------------------------------
/lib/parallel_minion/version.rb:
--------------------------------------------------------------------------------
1 | module ParallelMinion
2 |   VERSION = "1.3.0".freeze
3 | end
4 | 


--------------------------------------------------------------------------------
/parallel_minion.gemspec:
--------------------------------------------------------------------------------
 1 | $LOAD_PATH.push File.expand_path("lib", __dir__)
 2 | 
 3 | # Maintain your gem's version:
 4 | require "parallel_minion/version"
 5 | 
 6 | # Describe your gem and declare its dependencies:
 7 | Gem::Specification.new do |spec|
 8 |   spec.name                  = "parallel_minion"
 9 |   spec.version               = ParallelMinion::VERSION
10 |   spec.platform              = Gem::Platform::RUBY
11 |   spec.authors               = ["Reid Morrison"]
12 |   spec.homepage              = "https://github.com/reidmorrison/parallel_minion"
13 |   spec.summary               = "Wrap Ruby code with a minion so that it is run on a parallel thread"
14 |   spec.files                 = Dir["lib/**/*", "LICENSE.txt", "Rakefile", "README.md"]
15 |   spec.license               = "Apache License V2.0"
16 |   spec.required_ruby_version = ">= 2.5"
17 |   spec.add_dependency "semantic_logger", ">= 4.0"
18 |   spec.metadata["rubygems_mfa_required"] = "true"
19 | end
20 | 


--------------------------------------------------------------------------------
/test/config/database.yml:
--------------------------------------------------------------------------------
1 | test:
2 |   adapter:  sqlite3
3 |   database: test/test_db.sqlite3
4 |   pool:     5
5 |   timeout:  5000
6 | 


--------------------------------------------------------------------------------
/test/minion_scope_test.rb:
--------------------------------------------------------------------------------
 1 | require_relative "test_helper"
 2 | require "erb"
 3 | require "active_record"
 4 | 
 5 | ActiveRecord::Base.logger         = SemanticLogger[ActiveRecord]
 6 | ActiveRecord::Base.configurations = YAML.safe_load(ERB.new(File.read("test/config/database.yml")).result)
 7 | ActiveRecord::Base.establish_connection(:test)
 8 | 
 9 | ActiveRecord::Schema.define version: 0 do
10 |   create_table :people, force: true do |t|
11 |     t.string :name
12 |     t.string :state
13 |     t.string :zip_code
14 |   end
15 | end
16 | 
17 | class Person < ActiveRecord::Base
18 | end
19 | 
20 | class MinionScopeTest < Minitest::Test
21 |   describe ParallelMinion::Minion do
22 |     [false, true].each do |enabled|
23 |       describe ".new with enabled: #{enabled.inspect}" do
24 |         before do
25 |           Person.create(name: "Jack", state: "FL", zip_code: 38_729)
26 |           Person.create(name: "John", state: "FL", zip_code: 35_363)
27 |           Person.create(name: "Jill", state: "FL", zip_code: 73_534)
28 |           Person.create(name: "Joe", state: "NY", zip_code: 45_325)
29 |           Person.create(name: "Jane", state: "NY", zip_code: 45_325)
30 |           Person.create(name: "James", state: "CA", zip_code: 123_123)
31 |           # Instruct Minions to adhere to any dynamic scopes for Person model
32 |           ParallelMinion::Minion.scoped_classes << Person
33 |           ParallelMinion::Minion.enabled = enabled
34 |         end
35 | 
36 |         after do
37 |           Person.destroy_all
38 |           ParallelMinion::Minion.scoped_classes.clear
39 |           SemanticLogger.flush
40 |         end
41 | 
42 |         it "copy across model scope" do
43 |           assert_equal 6, Person.count
44 | 
45 |           Person.unscoped.where(state: "FL").scoping { Person.count }
46 | 
47 |           Person.unscoped.where(state: "FL").scoping do
48 |             assert_equal 3, Person.count
49 |             minion = ParallelMinion::Minion.new(description: "Scope Test", log_exception: :full) do
50 |               Person.count
51 |             end
52 |             assert_equal 3, minion.result
53 |           end
54 |         end
55 |       end
56 |     end
57 |   end
58 | end
59 | 


--------------------------------------------------------------------------------
/test/minion_test.rb:
--------------------------------------------------------------------------------
  1 | require_relative "./test_helper"
  2 | 
  3 | # Test ParallelMinion standalone without Rails
  4 | # Run this test standalone to verify it has no Rails dependencies
  5 | class MinionTest < Minitest::Test
  6 |   describe ParallelMinion::Minion do
  7 |     let(:logger) do
  8 |       l      = SemanticLogger::Test::CaptureLogEvents.new
  9 |       l.name = "Minion"
 10 |       l
 11 |     end
 12 | 
 13 |     [false].each do |enabled|
 14 |       describe enabled ? "enabled" : "disabled" do
 15 |         before do
 16 |           ParallelMinion::Minion.enabled = enabled
 17 |         end
 18 | 
 19 |         it "without parameters" do
 20 |           minion = ParallelMinion::Minion.new { 196 }
 21 |           assert_equal 196, minion.result
 22 |         end
 23 | 
 24 |         it "with a description" do
 25 |           minion = ParallelMinion::Minion.new(description: "Test") { 197 }
 26 |           assert_equal 197, minion.result
 27 |         end
 28 | 
 29 |         it "with an argument" do
 30 |           p1     = {name: 198}
 31 |           minion = ParallelMinion::Minion.new(p1, description: "Test") do |v|
 32 |             v[:name]
 33 |           end
 34 |           assert_equal 198, minion.result
 35 |         end
 36 | 
 37 |         it "raise exception" do
 38 |           minion = ParallelMinion::Minion.new(description: "Test") { raise "An exception" }
 39 |           assert_raises RuntimeError do
 40 |             minion.result
 41 |           end
 42 |         end
 43 | 
 44 |         # TODO: Blocks still have access to their original scope if variables cannot be
 45 |         #      resolved first by the parameters, then by the values in Minion itself
 46 |         #        it 'not have access to local variables' do
 47 |         #          name = 'Jack'
 48 |         #          minion = ParallelMinion::Minion.new(description: 'Test') { puts name }
 49 |         #          assert_raises NameError do
 50 |         #            minion.result
 51 |         #          end
 52 |         #        end
 53 | 
 54 |         it "run minion" do
 55 |           hash   = {value: 23}
 56 |           value  = 47
 57 |           minion = ParallelMinion::Minion.new(hash, description: "Test") do |h|
 58 |             value     = 321
 59 |             h[:value] = 123
 60 |             456
 61 |           end
 62 |           assert_equal 456, minion.result
 63 |           assert_equal 123, hash[:value]
 64 |           assert_equal 321, value
 65 |         end
 66 | 
 67 |         it "copy across logging tags" do
 68 |           minion = nil
 69 |           SemanticLogger.tagged("TAG") do
 70 |             assert_equal "TAG", SemanticLogger.tags.last
 71 |             minion = ParallelMinion::Minion.new(description: "Tag Test") do
 72 |               logger.info "Tag Test"
 73 |               logger.tags.last
 74 |             end
 75 |           end
 76 |           assert_equal "TAG", minion.result
 77 |         end
 78 | 
 79 |         it "copy across named tags" do
 80 |           minion = nil
 81 |           SemanticLogger.named_tagged(tag: "TAG") do
 82 |             assert_equal({tag: "TAG"}, SemanticLogger.named_tags)
 83 |             minion = ParallelMinion::Minion.new(description: "Named Tags Test") do
 84 |               logger.info "Named Tags Test"
 85 |               SemanticLogger.named_tags
 86 |             end
 87 |           end
 88 |           assert_equal({tag: "TAG"}, minion.result)
 89 |         end
 90 | 
 91 |         it "copy across tags and named tags" do
 92 |           SemanticLogger.tagged("TAG") do
 93 |             SemanticLogger.named_tagged(tag: "TAG") do
 94 |               assert_equal({tag: "TAG"}, SemanticLogger.named_tags)
 95 |               assert_equal "TAG", SemanticLogger.tags.last
 96 |               minion = ParallelMinion::Minion.new(description: "Tags Test") do
 97 |                 logger.info "Tags Test"
 98 |                 [SemanticLogger.named_tags, SemanticLogger.tags.last]
 99 |               end
100 | 
101 |               assert_equal({tag: "TAG"}, minion.result.first)
102 |               assert_equal "TAG", minion.result.last
103 |             end
104 |           end
105 |         end
106 | 
107 |         it "logs messages" do
108 |           minion = nil
109 |           ParallelMinion::Minion.stub(:logger, logger) do
110 |             minion = ParallelMinion::Minion.new(hash, description: "Test", metric: "model/method") do |_h|
111 |               sleep 1
112 |               1234
113 |             end
114 |             minion.result
115 |           end
116 | 
117 |           messages = minion.logger.events
118 |           name     = enabled ? "Minion" : "Inline"
119 |           count    = enabled ? 3 : 2
120 |           assert_equal count, messages.count, messages
121 |           assert_equal "Started Test", messages[0].message
122 |           assert_equal :info, messages[0].level
123 |           assert_equal name, messages[0].name
124 | 
125 |           assert_equal "Completed Test", messages[1].message
126 |           assert_equal :info, messages[1].level
127 |           assert_equal "model/method", messages[1].metric
128 |           assert_equal name, messages[1].name
129 | 
130 |           if enabled
131 |             assert_equal "Waited for Minion to complete: Test", messages[2].message
132 |             assert_equal :info, messages[2].level
133 |             assert_equal "model/method/wait", messages[2].metric
134 |             assert_equal name, messages[2].name
135 |           end
136 |         end
137 | 
138 |         it ":on_exception_level" do
139 |           minion = nil
140 |           ParallelMinion::Minion.stub(:logger, logger) do
141 |             minion = ParallelMinion::Minion.new(
142 |               description:        "Test",
143 |               on_exception_level: :error,
144 |               metric:             "class/method"
145 |             ) do |_h|
146 |               sleep 1
147 |               raise "Oh No"
148 |             end
149 |             # Wait for thread to complete
150 |             assert_raises RuntimeError do
151 |               minion.result
152 |             end
153 |           end
154 | 
155 |           messages = minion.logger.events
156 |           name     = enabled ? "Minion" : "Inline"
157 |           count    = enabled ? 3 : 2
158 |           assert_equal count, messages.count, messages
159 |           assert_equal "Started Test", messages[0].message
160 |           assert_equal :info, messages[0].level
161 |           assert_equal name, messages[0].name
162 | 
163 |           assert_equal "Completed Test -- Exception: RuntimeError: Oh No", messages[1].message
164 |           assert_equal :error, messages[1].level
165 |           refute messages[1].backtrace.empty?
166 |           assert_equal "class/method", messages[1].metric
167 |           assert_equal name, messages[1].name
168 | 
169 |           if enabled
170 |             assert_equal "Waited for Minion to complete: Test", messages[2].message
171 |             assert_equal :info, messages[2].level
172 |             assert_equal "class/method/wait", messages[2].metric
173 |             assert_equal name, messages[2].name
174 |           end
175 |         end
176 | 
177 |         it "handle multiple minions concurrently" do
178 |           # Start 10 minions
179 |           minions = Array.new(10) do |i|
180 |             # Each Minion returns its index in the collection
181 |             ParallelMinion::Minion.new(i, description: "Minion:#{i}") { |counter| counter }
182 |           end
183 |           assert_equal 10, minions.count
184 |           # Fetch the result from each Minion
185 |           minions.each_with_index do |minion, index|
186 |             assert_equal index, minion.result
187 |           end
188 |         end
189 | 
190 |         it "timeout" do
191 |           if enabled
192 |             minion = ParallelMinion::Minion.new(description: "Test", timeout: 100) { sleep 1 }
193 |             assert_nil minion.result
194 |           end
195 |         end
196 | 
197 |         it "timeout and terminate thread with Exception" do
198 |           if enabled
199 |             minion = ParallelMinion::Minion.new(description: "Test", timeout: 100, on_timeout: Timeout::Error) { sleep 1 }
200 |             assert_nil minion.result
201 |             # Give time for thread to terminate
202 |             sleep 0.1
203 |             assert_equal Timeout::Error, minion.exception.class
204 |             assert_equal false, minion.working?
205 |             assert_equal true, minion.completed?
206 |             assert_equal true, minion.failed?
207 |             assert_equal 0, minion.time_left
208 |           end
209 |         end
210 | 
211 |         it "make description instance variable available" do
212 |           minion = ParallelMinion::Minion.new(description: "Test") do
213 |             description
214 |           end
215 |           assert_equal "Test", minion.result
216 |         end
217 | 
218 |         it "make timeout instance variable available" do
219 |           minion = ParallelMinion::Minion.new(description: "Test", timeout: 1000) do
220 |             timeout
221 |           end
222 |           assert_equal 1000, minion.result
223 |         end
224 | 
225 |         it "make enabled? method available" do
226 |           minion = ParallelMinion::Minion.new(description: "Test") do
227 |             enabled?
228 |           end
229 |           assert_equal enabled, minion.result
230 |         end
231 | 
232 |         it "keep the original arguments" do
233 |           minion = ParallelMinion::Minion.new(1, "data", 14.1, description: "Test") do |num, _str, float|
234 |             num + float
235 |           end
236 |           assert_equal 15.1, minion.result
237 |           assert_equal [1, "data", 14.1], minion.arguments
238 |         end
239 |       end
240 |     end
241 |   end
242 | end
243 | 


--------------------------------------------------------------------------------
/test/test_helper.rb:
--------------------------------------------------------------------------------
1 | require "minitest/autorun"
2 | require "amazing_print"
3 | require "semantic_logger"
4 | require "parallel_minion"
5 | 
6 | SemanticLogger.default_level = :trace
7 | SemanticLogger.add_appender(file_name: "test.log", formatter: :color)
8 | 


--------------------------------------------------------------------------------