bootsnap 0.2.15 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b0de1ff4a8bdd4478f422a07fba3981778828604
-  data.tar.gz: d9b7d5cc09e58be7bc31382be47d72870c60bf7f
+  metadata.gz: 77b33ef59e01f0ddaa1de86a002ce286018b870d
+  data.tar.gz: 958ec1e45c50803261866ade91f9300dd6975d03
 SHA512:
-  metadata.gz: f153d3e9591eb2fb8d2efecb958cbe21f61d93040f891ef63809285418cf76b3883d5490b3aa60d656bd066f96d7489317b13833bdf465058f7a339547177f6c
-  data.tar.gz: be2f217b2481c5d3eb44226d9861d2890dc7901143ab056e0d1f2fbd5e4f152ef497fb1cd67481ae44c4723dc5b0c93a6f6f6faebd705f4ce321aa0e5949bd2f
+  metadata.gz: bcb190169610158178bff1fbf16ed6d43a4f986d06c7e07c16c5199aa658512749490b43e42b1e2e431a1099aa5ebd50e5905a35a0170f75e2cc2d468037eca1
+  data.tar.gz: 17fe5e20e585fce572bc39a47febe146abba4ec0aea70934c9d39f88fd271f158b3dd0fc3b0fe103e3060c97ade3bd890cf9e74d28f7ba4fb6b7836a401dac14

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# 1.0.0
+
+* (none)
+
+# 0.3.2
+
+* Minor performance savings around checking validity of cache in the presence of relative paths.
+* When coverage is enabled, skips optimization instead of exploding.
+
+# 0.3.1
+
+* Don't whitelist paths under `RbConfig::CONFIG['prefix']` as stable; instead use `['libdir']` (#41).
+* Catch `EOFError` when reading load-path-cache and regenerate cache.
+* Support relative paths in load-path-cache.
+
+# 0.3.0
+
+* Migrate CompileCache from xattr as a cache backend to a cache directory
+    * Adds support for Linux and FreeBSD
+
 # 0.2.15
 
 * Support more versions of ActiveSupport (`depend_on`'s signature varies; don't reiterate it)

data/README.md

@@ -2,9 +2,6 @@
 
 **Beta-quality. See [the last section of this README](#trustworthiness).**
 
-**`compile_cache_*` features are only supported on MacOS (extremely likely to error on Linux;
-won't even compile on other platforms).**
-
 Bootsnap is a library that plugs into a number of Ruby and (optionally) `ActiveSupport` and `YAML`
 methods to optimize and cache expensive computations. See [the How Does This Work section](#how-does-this-work) for more information.
 
@@ -15,6 +12,8 @@ methods to optimize and cache expensive computations. See [the How Does This Wor
 
 ## Usage
 
+This gem works on MacOS and Linux.
+
 Add `bootsnap` to your `Gemfile`:
 
 ```ruby
@@ -120,7 +119,8 @@ 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)).*
+*(A more readable 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
@@ -134,9 +134,8 @@ implementation. We use the same strategy of compilation caching for YAML documen
 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. 
+These compilation results are stored in a cache directory, with filenames generated by taking a hash
+of the full expanded path of the input file (FNV1a-64).
 
 Whereas before, the sequence of syscalls generated to `require` a file would look like:
 
@@ -158,32 +157,36 @@ With bootsnap, we get:
 ```
 open      /c/foo.rb -> n
 fstat64   n
-fgetxattr n
-fgetxattr n
+close     n
+open      /c/foo.rb -> n
+fstat64   n
+open      (cache) -> m
+read      m
+read      m
+close     m
 close     n
 ```
 
-Bootsnap writes two `xattrs` attached to each file read:
+This may look worse at a glance, but underlies a large performance difference.
 
-* `user.aotcc.value`, the binary compilation result; and
-* `user.aotcc.key`, a cache key to determine whether `user.aotcc.value` is still valid.
+*(The first three syscalls in both listings -- `open`, `fstat64`, `close` -- are not inherently
+useful. [This ruby patch](https://bugs.ruby-lang.org/issues/13378) optimizes them out when coupled
+with bootsnap.)*
 
-The key includes several fields:
+Bootsnap writes a cache file containing a 64 byte header followed by the cache contents. The header
+is a cache key including several fields:
 
 * `version`, hardcoded in bootsnap. Essentially a schema version;
+* `os_version`, A hash of the current kernel version (on macOS, BSD) or glibc version (on Linux);
 * `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.
+* `ruby_revision`, the version of Ruby this was compiled with;
+* `size`, the size of the source file;
+* `mtime`, the last-modification timestamp of the source file when it was compiled; and
+* `data_size`, the number of bytes following the header, which we need to read it into a buffer.
 
 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:
@@ -227,8 +230,13 @@ With bootsnap, we get:
 ```
 open      /c/foo.rb -> n
 fstat64   n
-fgetxattr n
-fgetxattr n
+close     n
+open      /c/foo.rb -> n
+fstat64   n
+open      (cache) -> m
+read      m
+read      m
+close     m
 close     n
 ```
 
@@ -253,8 +261,8 @@ open    /c/nope.bundle -> -1
 
 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.
+The `compile_cache_*` features work well for us in development on macOS. It should work on Linux,
+and we intend to deploy it in production, but haven't we haven't yet.
 
 `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.
@@ -264,5 +272,5 @@ use tools that make use of `trace` instructions.
 | `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 |
+| `compile_cache_iseq` | development, but probably safe to use everywhere |
+| `compile_cache_yaml` | development, but probably safe to use everywhere |