bootsnap 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 021403c5730eaf97a0e8e8a1b31f4b5fd0a24af3
-  data.tar.gz: 63951a0464d36619d7695cfeceb2a6e806db6a9e
+  metadata.gz: 81a66a32929d05c86f053bc76267669c86b21223
+  data.tar.gz: 02fa45efd635633dc2faf44793b22c99b2a9b966
 SHA512:
-  metadata.gz: 0f152d961214408b1c75e5f7288f411c70fc0eba8697e2b7646b767fa0cc7238c58ad2b68e5e63b9b2fac37f26d73b2093a9ad77bb8a77e57cb1495e3fa37e73
-  data.tar.gz: 6b0b6812411caefaf659bbd1375009a2b3b55a37428ce6d7a29115c40b30a3047b7bdb41710519ba4b6db9b4d889c1473ca87bba121243f21ab7b63e507a0b53
+  metadata.gz: ee53dc7664efb6727862745fcece02da6661db07d2dfba9370e78fcc196f4699bf99d6b1beb718638d208e0e3452d8d12ae5bab1c12b20a811af36afafd31bd6
+  data.tar.gz: 64273db79d1d0b4ff5dd1796141772f478520cffa4bd5a5f3e6351cea88211d9a0bffe2a53a586d97b7c98fabc4373da17fc8278effd0c9708ea7fcbc1e3f811

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2017 Shopify
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,29 +1,213 @@
 # Bootsnap
 
-> Beta version
+**Beta-quality. See [the last section of this README](#trustworthiness).**
 
-Bootsnap is a library that overrides `Kernel#require`, `Kernel#load`, `Module#autoload` and in the case that `ActiveSupport` is used, it will also override a number of `ActiveSupport` methods.
+Bootsnap is a library that plugs into a number of ruby and (optionally) `ActiveSupport` and `YAML`
+methods. These methods are modified to cache results of expensive computations, and can be grouped
+into two broad categories:
 
-Bootsnap creates 2 kinds of caches, a stable, long lived cache out of Ruby and Gem directories. These are assumed to never change and so we can cache more aggresively. Application code is expected to change frequently, so it is cached with little aggression (short lived bursts that should last only as long as the app takes to boot). This is the “volatile” cache.
+* [Path Pre-Scanning](#path-pre-scanning)
+    * `Kernel#require` and `Kernel#load` are modified to eliminate `$LOAD_PATH` scans.
+    * `ActiveSupport::Dependencies.{autoloadable_module?,load_missing_constant,depend_on}` are
+      overridden to eliminate scans of `ActiveSupport::Dependencies.autoload_paths`.
+* [Compilation caching](#compilation-caching)
+    * `RubyVM::InstructionSequence.load_iseq` is implemented to cache the result of ruby bytecode
+      compilation.
+    * `YAML.load_file` is modified to cache the result of loading a YAML object in MessagePack format
+      (or Marshal, if the message uses types unsupported by MessagePack).
 
-Below is a diagram explaining how the overrides work.
+### Path Pre-Scanning
 
-![Flowchart explaining Bootsnap](https://cloud.githubusercontent.com/assets/3074765/24532120/eed94e64-158b-11e7-9137-438d759b2ac8.png)
+*(This work is a minor evolution of [bootscale](https://github.com/byroot/bootscale)).*
 
-In this diagram, you might notice that we refer to cache and autoload_path_cache as the main points of override. 
+Upon initialization of bootsnap or modification of the path (e.g. `$LOAD_PATH`),
+`Bootsnap::LoadPathCache` will fetch a list of requirable entries from a cache, or, if necessary,
+perform a full scan and cache the result.
 
-# How it works
+Later, when we run (e.g.) `require 'foo'`, ruby *would* iterate through every item on our
+`$LOAD_PATH` `['x', 'y', ...]`,  looking for `x/foo.rb`, `y/foo.rb`, and so on. Bootsnap instead
+looks at all the cached requirables for each `$LOAD_PATH` entry and substitutes the full expanded
+path of the match ruby would have eventually chosen.
 
-Caching paths is the main function of bootsnap. There are 2 types of caches:
+If you look at the syscalls generated by this behaviour, the net effect is that what would
+previously look like this:
 
-- Stable: For Gems and Rubies since these are highly unlikely to change
-- Volatile: For everything else, like your app code, since this is likely to change
+```
+open  x/foo.rb # (fail)
+# (imagine this with 500 $LOAD_PATH entries instead of two)
+open  y/foo.rb # (success)
+close y/foo.rb
+open  y/foo.rb
+...
+```
+
+becomes this:
+
+```
+open y/foo.rb
+...
+```
+
+Exactly the same strategy is employed for methods that traverse
+`ActiveSupport::Dependencies.autoload_paths` if the `autoload_paths_cache` option is given to
+`Bootsnap.setup`.
+
+The following diagram flowcharts the overrides that make the `*_path_cache` features work.
 
-This path is shown in the flowchart below. In a number of instances, scan is mentioned. 
+![Flowchart explaining
+Bootsnap](https://cloud.githubusercontent.com/assets/3074765/24532120/eed94e64-158b-11e7-9137-438d759b2ac8.png)
+
+Bootsnap classifies path entries into two categories: stable and volatile. Volatile entries are
+scanned each time the application boots, and their caches are only valid for 30 seconds. Stable
+entries do not expire -- once their contents has been scanned, it is assumed to never change.
+
+The only directories considered "stable" are things under the Ruby install prefix
+(`RbConfig::CONFIG['prefix']`, e.g. `/usr/local/ruby` or `~/.rubies/x.y.z`), and things under the
+`Gem.path` (e.g. `~/.gem/ruby/x.y.z`). Everything else is considered "volatile".
+
+In addition to the [`Bootsnap::LoadPathCache::Cache`
+source](https://github.com/Shopify/bootsnap/blob/master/lib/bootsnap/load_path_cache/cache.rb),
+this diagram may help clarify how entry resolution works:
 
 ![How path searching works](https://cloud.githubusercontent.com/assets/3074765/24532143/18278cd6-158c-11e7-8250-78d831df70db.png)
 
-# Usage
+It's also important to note how expensive `LoadError`s can be. If ruby invokes
+`require 'something'`, but that file isn't on `$LOAD_PATH`, it takes `2 *
+$LOAD_PATH.length` filesystem accesses to determine that. Bootsnap caches this
+result too, raising a `LoadError` without touching the filesystem at all.
+
+### Compilation Caching
+
+*(A simpler implementation of this concept can be found in [yomikomu](https://github.com/ko1/yomikomu)).*
+
+Ruby has complex grammar and parsing it is not a particularly cheap operation. Since 1.9, Ruby has
+translated ruby source to an internal bytecode format, which is then executed by the Ruby VM. Since
+2.2, Ruby [exposes an API](https://ruby-doc.org/core-2.3.0/RubyVM/InstructionSequence.html) that
+allows caching that bytecode. This allows us to bypass the relatively-expensive compilation step on
+subsequent loads of the same file.
+
+We also noticed that we spend a lot of time loading YAML documents during our application boot, and
+that MessagePack and Marshal are *much* faster at deserialization than YAML, even with a fast
+implementation. We use the same strategy of compilation caching for YAML documents, with the
+equivalent of Ruby's "bytecode" format being a MessagePack document (or, in the case of YAML
+documents with types unsupported by MessagePack, a Marshal stream).
+
+These compilation results are stored using `xattr`s on the source files. This is likely to change in
+the future, as it has some limitations (notably precluding Linux support except where the user feels
+like changing mount flags). However, this is a very performant implementation. 
+
+Whereas before, the sequence of syscalls generated to `require` a file would look like:
+
+```
+open    /c/foo.rb -> m
+fstat64 m
+close   m
+open    /c/foo.rb -> o
+fstat64 o
+fstat64 o
+read    o
+read    o
+...
+close   o
+```
+
+With bootsnap, we get:
+
+```
+open      /c/foo.rb -> n
+fstat64   n
+fgetxattr n
+fgetxattr n
+close     n
+```
+
+Bootsnap writes two `xattrs` attached to each file read:
+
+* `user.aotcc.value`, the binary compilation result; and
+* `user.aotcc.key`, a cache key to determine whether `user.aotcc.value` is still valid.
+
+The key includes several fields:
+
+* `version`, hardcoded in bootsnap. Essentially a schema version;
+* `compile_option`, which changes with `RubyVM::InstructionSequence.compile_option` does;
+* `data_size`, the number of bytes in `user.aotcc.value`, which we need to read it into a buffer
+  using `fgetxattr(2)`;
+* `ruby_revision`, the version of Ruby this was compiled with; and
+* `mtime`, the last-modification timestamp of the source file when it was compiled.
+
+If the key is valid, the result is loaded from the value. Otherwise, it is regenerated and clobbers
+the current cache.
+
+This diagram may help illustrate how it works:
+
+![Compilation Caching](https://burkelibbey.s3.amazonaws.com/bootsnap-compile-cache.png)
+
+### Putting it all together
+
+Imagine we have this file structure:
+
+```
+/
+├── a
+├── b
+└── c
+    └── foo.rb
+```
+
+And this `$LOAD_PATH`:
+
+```
+["/a", "/b", "/c"]
+```
+
+When we call `require 'foo'` without bootsnap, Ruby would generate this sequence of syscalls:
+
+
+```
+open    /a/foo.rb -> -1
+open    /b/foo.rb -> -1
+open    /c/foo.rb -> n
+close   n
+open    /c/foo.rb -> m
+fstat64 m
+close   m
+open    /c/foo.rb -> o
+fstat64 o
+fstat64 o
+read    o
+read    o
+...
+close   o
+```
+
+With bootsnap, we get:
+
+```
+open      /c/foo.rb -> n
+fstat64   n
+fgetxattr n
+fgetxattr n
+close     n
+```
+
+If we call `require 'nope'` without bootsnap, we get:
+
+```
+open    /a/nope.rb -> -1
+open    /b/nope.rb -> -1
+open    /c/nope.rb -> -1
+open    /a/nope.bundle -> -1
+open    /b/nope.bundle -> -1
+open    /c/nope.bundle -> -1
+```
+
+...and if we call `require 'nope'` *with* bootsnap, we get...
+
+```
+# (nothing!)
+```
+
+## Usage
 
 Add `bootsnap` to your `Gemfile`:
 
@@ -31,19 +215,40 @@ Add `bootsnap` to your `Gemfile`:
 gem 'bootsnap'
 ```
 
-Next, add this to your boot setup after `require 'bundler/setup'` but before the end.
+Next, add this to your boot setup immediately after `require 'bundler/setup'` (i.e. as early as
+possible: the sooner this is loaded, the sooner it can start optimizing things)
 
 ```ruby
 require 'bootsnap'
 Bootsnap.setup(
-  cache_dir:            'tmp/cache',                      ## Path to your cache
+  cache_dir:            'tmp/cache', # Path to your cache
   development_mode:     ENV['MY_ENV'] == 'development',
-  load_path_cache:      true,                             ## Should we optimize the LOAD_PATH with a cache?
-  autoload_paths_cache: true,                             ## Should we optimize the AUTOLOAD_PATH with a cache?
-  disable_trace:        false,                            ## Sets `RubyVM::InstructionSequence.compile_option = { trace_instruction: false }`
-  compile_cache_iseq:   true,                             ## Should compile Ruby code into iSeq cache?
-  compile_cache_yaml:   true                              ## Should compile YAML into a cache?
+  load_path_cache:      true,        # Should we optimize the LOAD_PATH with a cache?
+  autoload_paths_cache: true,        # Should we optimize ActiveSupport autoloads with cache?
+  disable_trace:        false,       # Sets `RubyVM::InstructionSequence.compile_option = { trace_instruction: false }`
+  compile_cache_iseq:   true,        # Should compile Ruby code into ISeq cache?
+  compile_cache_yaml:   true         # Should compile YAML into a cache?
 )
 ```
 
-**Protip:** You can replace `require 'bootsnap'` with `BootLib::Require.from_gem('bootsnap', 'bootsnap')` using [this trick](https://github.com/Shopify/bootsnap/wiki/Bootlib::Require). This will help optimize boot time.
+**Protip:** You can replace `require 'bootsnap'` with `BootLib::Require.from_gem('bootsnap',
+'bootsnap')` using [this trick](https://github.com/Shopify/bootsnap/wiki/Bootlib::Require). This
+will help optimize boot time further if you have an extremely large `$LOAD_PATH`.
+
+## Trustworthiness
+
+We use the `*_path_cache` features in production and haven't experienced any issues in a long time.
+
+The `compile_cache_*` features work well for us in development on macOS, but probably don't work on
+Linux at all.
+
+`disable_trace` should be completely safe, but we don't really use it because some people like to
+use tools that make use of `trace` instructions.
+
+| feature | where we're using it |
+|-|-|
+| `load_path_cache` | everywhere |
+| `autoload_path_cache` | everywhere |
+| `disable_trace` | nowhere, but it's safe unless you need tracing |
+| `compile_cache_iseq` | development, unlikely to work on Linux |
+| `compile_cache_yaml` | development, unlikely to work on Linux |

data/lib/bootsnap/load_path_cache/cache.rb

@@ -1,6 +1,5 @@
 require_relative '../load_path_cache'
 require_relative '../explicit_require'
-Bootsnap::ExplicitRequire.from_archdir('thread')
 
 module Bootsnap
   module LoadPathCache
@@ -49,7 +48,7 @@ module Bootsnap
           # doesn't correspond to any entry on the filesystem. Ruby lies. So we
           # lie too, forcing our monkeypatch to return false like ruby would.
           when ""
-            raise LoadPathCache::ReturnFalse if feature == 'enumerator'
+            raise LoadPathCache::ReturnFalse if feature == 'enumerator' || feature == 'thread'
             nil
           # Ruby allows specifying native extensions as '.so' even when DLEXT
           # is '.bundle'. This is where we handle that case.

data/lib/bootsnap/version.rb

@@ -1,3 +1,3 @@
 module Bootsnap
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bootsnap
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Burke Libbey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-31 00:00:00.000000000 Z
+date: 2017-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -120,6 +120,7 @@ files:
 - ".rubocop.yml"
 - CONTRIBUTING.md
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - bin/console