faster_path 0.3.9 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a5d299440e18a99c763e17b085b7962bfca0f2555b0adf8eb053c77b2d8d282
-  data.tar.gz: fee3ac374b164a25d1af43e0e8cd36ea68f57421db38637b7275a504e38bb391
+  metadata.gz: 5e04d827e927a1e405d74ccf0fe49946faaf67650c935ad1e5a5dec744254d27
+  data.tar.gz: '067897cef2171835830c97c8340397ad2d4a97ad1c72b15a88c0876bf58a1690'
 SHA512:
-  metadata.gz: 79d7b3931800982e78cc7f00c2fd2281932a2ac3775784f5f9d5c59bf974cd41f30d2d03c6216ce210fdc1754659b714cda6c19cca84e39a464e2bb62f7afa9c
-  data.tar.gz: 1a5b56dff703996bdcf60838ad9881528e51867aa2e9c5d996ff9c28996fb1297e7dacc9380a42def9ff9358e87ac4576a2f7536d5c73b685332b73b9e687122
+  metadata.gz: 16298d55d4cd08d92555ed02e995a55520430527e37d057d7372182e7b9f12758bbf730d2f5969740f806e4bc3221b32843e2a90a8aacb96a57d95500995e477
+  data.tar.gz: c09f83ba8f3687b3dc509536fbf985435528a160161795285baf612edf965f409bbac07f6b6de7075be3b5df29d23263de41176ad478d90ade20a567e1fb2a8d

data/Cargo.lock

@@ -1,64 +1,39 @@
-[[package]]
-name = "array_tool"
-version = "1.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
 
 [[package]]
 name = "faster_path"
-version = "0.0.1"
+version = "0.1.0"
 dependencies = [
- "array_tool 1.0.3 (registry+https://github.com/rust-lang/crates.io-index)",
- "lazy_static 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)",
- "memchr 2.0.1 (registry+https://github.com/rust-lang/crates.io-index)",
- "ruby-sys 0.3.0 (git+https://github.com/danielpclark/ruby-sys?branch=playground)",
- "ruru 0.9.3 (git+https://github.com/danielpclark/ruru?branch=playground)",
+ "memchr",
+ "rutie",
 ]
 
 [[package]]
 name = "lazy_static"
-version = "0.2.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-
-[[package]]
-name = "lazy_static"
-version = "1.0.0"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
 
 [[package]]
 name = "libc"
-version = "0.2.39"
+version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 
 [[package]]
 name = "memchr"
-version = "2.0.1"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-dependencies = [
- "libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)",
-]
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
-name = "ruby-sys"
-version = "0.3.0"
-source = "git+https://github.com/danielpclark/ruby-sys?branch=playground#a3d47da5f9d1e597c62a8f03fb7d3a3596393c47"
-dependencies = [
- "libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)",
-]
-
-[[package]]
-name = "ruru"
-version = "0.9.3"
-source = "git+https://github.com/danielpclark/ruru?branch=playground#ab84ad4b97c41bfe6fd6d0f8540b2efd77583561"
+name = "rutie"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a97641d6bd3731d263d914141e960a8b515bf5ff4ca6c961b25ca4b2694c6490"
 dependencies = [
- "lazy_static 0.2.11 (registry+https://github.com/rust-lang/crates.io-index)",
- "ruby-sys 0.3.0 (git+https://github.com/danielpclark/ruby-sys?branch=playground)",
+ "lazy_static",
+ "libc",
 ]
-
-[metadata]
-"checksum array_tool 1.0.3 (registry+https://github.com/rust-lang/crates.io-index)" = "8f8cb5d814eb646a863c4f24978cff2880c4be96ad8cde2c0f0678732902e271"
-"checksum lazy_static 0.2.11 (registry+https://github.com/rust-lang/crates.io-index)" = "76f033c7ad61445c5b347c7382dd1237847eb1bce590fe50365dcb33d546be73"
-"checksum lazy_static 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "c8f31047daa365f19be14b47c29df4f7c3b581832407daabe6ae77397619237d"
-"checksum libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)" = "f54263ad99207254cf58b5f701ecb432c717445ea2ee8af387334bdd1a03fdff"
-"checksum memchr 2.0.1 (registry+https://github.com/rust-lang/crates.io-index)" = "796fba70e76612589ed2ce7f45282f5af869e0fdd7cc6199fa1aa1f1d591ba9d"
-"checksum ruby-sys 0.3.0 (git+https://github.com/danielpclark/ruby-sys?branch=playground)" = "<none>"
-"checksum ruru 0.9.3 (git+https://github.com/danielpclark/ruru?branch=playground)" = "<none>"

data/Cargo.toml

@@ -1,23 +1,21 @@
 [package]
 name = "faster_path"
-version = "0.0.1"
+version = "0.1.0"
 authors = ["Daniel P. Clark <6ftdan@gmail.com>"]
 description = "Alternative to Pathname"
 homepage = "https://github.com/danielpclark/faster_path"
 repository = "https://github.com/danielpclark/faster_path"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
+edition = "2021"
 
 [package.metadata.thermite]
 github_releases = true
 
 [lib]
 name = "faster_path"
-crate-type = ["dylib"]
+crate-type = ["cdylib"]
 
 [dependencies]
-ruby-sys = { git = "https://github.com/danielpclark/ruby-sys", branch = "playground" }
-ruru = { git = "https://github.com/danielpclark/ruru", branch = "playground" }
-array_tool = "1.0"
-lazy_static = "1.0"
-memchr = "2.0.1"
+rutie = "0.10.2"
+memchr = "2"

data/Gemfile

@@ -1,7 +1,4 @@
-source 'https://rubygems.org' do
-  # Specify your gem's dependencies in faster_path.gemspec
-  gemspec
-  group :test do
-    gem 'coveralls', require: false
-  end
-end
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in faster_path.gemspec
+gemspec

data/README.md

@@ -1,14 +1,11 @@
 # FasterPath
 [![Gem Version](https://badge.fury.io/rb/faster_path.svg)](https://badge.fury.io/rb/faster_path)
-[![TravisCI Build Status](https://travis-ci.org/danielpclark/faster_path.svg?branch=master)](https://travis-ci.org/danielpclark/faster_path)
-[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/10ul0gk3cwhlt2lj/branch/master?svg=true)](https://ci.appveyor.com/project/danielpclark/faster-path/branch/master)
+[![CI](https://github.com/danielpclark/faster_path/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/danielpclark/faster_path/actions/workflows/ci.yml)
 [![Latest Tag](https://img.shields.io/github/tag/danielpclark/faster_path.svg)](https://github.com/danielpclark/faster_path/tags)
-[![Commits Since Last Release](https://img.shields.io/github/commits-since/danielpclark/faster_path/v0.3.8.svg)](https://github.com/danielpclark/faster_path/pulse)
+[![Commits Since Last Release](https://img.shields.io/github/commits-since/danielpclark/faster_path/v0.3.10.svg)](https://github.com/danielpclark/faster_path/pulse)
 [![Binary Release](https://img.shields.io/github/release/danielpclark/faster_path.svg)](https://github.com/danielpclark/faster_path/releases)
-[![Coverage Status](https://coveralls.io/repos/github/danielpclark/faster_path/badge.svg?branch=master)](https://coveralls.io/github/danielpclark/faster_path?branch=master)
 [![Inline docs](http://inch-ci.org/github/danielpclark/faster_path.svg?branch=master)](http://inch-ci.org/github/danielpclark/faster_path)
 [![Code Triagers Badge](https://www.codetriage.com/danielpclark/faster_path/badges/users.svg)](https://www.codetriage.com/danielpclark/faster_path)
-[![Tweet This](https://raw.githubusercontent.com/danielpclark/faster_path/master/assets/tweet.png)](https://twitter.com/share?url=https%3A%2F%2Fgithub.com%2Fdanielpclark%2Ffaster_path&via=6ftdan&hashtags=Ruby&text=You%20could%20save%2015%25%20or%20more%20on%20website%20page%20load%20time%20by%20switching%20to%20the%20FasterPath%20gem.)
 
 #### This gem shaves off more than 30% of my Rails application page load time.
 
@@ -94,13 +91,31 @@ I've said this about Sprockets but this required two other gems to be updated as
 |sass 3.2.19|sass 5.0.4|
 |bootstrap-sass 3.3.4.1|bootstrap-sass 3.3.6|
 
+## Performance Specifics
+
+The headline for the amount for improvement on this library is specific to only the improvement made with the method `chop_basename`.  Just so you know; in my initial release I had a bug in which that method immediately returned nothing. Now the good thing about this is that it gave me some very valuable information.  First I found that all my Rails site tests still passed.  Second I found that all my assets no longer loaded in the website. And third, and most importantly, I found my Rails web pages loaded just more than 66% faster without the cost of time that `chop_basename` took.
+
+**That's right; the path handling for assets in your website \*consumes more than 2/3rds of your websites page load time.**
+
+So now we have some real numbers to work with  We can be generoues and use 66% as our margin of area to improve over _(for `chop_basename` specifically, not counting the benefit from improving the performance in other file path related methods)_.  That means we want to remove as much of that percentage from the overall systems page load time.  The original headline boasts over 33% performance improvement — that was when `chop_basename` was improved by just over 50%.  Now `chop_basename` is improved by 83.4%.  That alone should make your site run 55.044% faster now _(given your performance profile stats are similar to mine)_.
+
+## What Rails Versions Will This Apply To?
+
+As mentioned earlier Sprockets, which handles assets, changed away from using `Pathname` at all when moving from major version 2 to 3.  So if you're using Sprockets 3 or later you won't reap the biggest performance rewards from using this gem for now _(it's my goal to have this project become a core feature that Rails depends on and yes… that's a big ask)_.  That is unless you write you're own implementation to re-integrate the use of `Pathname` and `FasterPath` into your asset handling library.  For now just know that the Sprockets 2 series primarily works with Rails 4.1 and earlier.  It may work in later Rails versions but I have not investigated this.
+
 ## Status
 
 * Rust compilation is working
 * Methods are stable
 * Thoroughly tested
 * Testers and developers are most welcome
-* Windows & encoding support is underway!
+* Windows: paths follow Ruby's Windows rules (`\` and `/` separators, drive letters, UNC paths)
+* Paths keep their encoding, as with Ruby's own methods
+
+## Requirements
+
+* Ruby 2.5, 2.6 or 2.7 (the Rust extension is built with [Rutie](https://github.com/danielpclark/rutie) 0.10, which supports these)
+* Rust 1.71 or later
 
 ## Installation
 
@@ -109,13 +124,13 @@ Ensure Rust is installed:
 [Rust Downloads](https://www.rust-lang.org/downloads.html)
 
 ```
-curl -sSf https://static.rust-lang.org/rustup.sh | sh
+curl -sSf https://sh.rustup.rs | sh
 ```
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'faster_path', '~> 0.3.8'
+gem 'faster_path', '~> 0.4.0'
 ```
 
 And then execute:
@@ -136,27 +151,35 @@ improvement result  for the `chop_basename` method.
 
 ## Usage
 
+Add the proper require to your project.
+
+```ruby
+require "faster_path"
+```
+
 Current methods implemented:
 
-|FasterPath Rust Implementation|Ruby 2.5.0 Implementation|Time Shaved Off|
-|---|---|:---:|
-| `FasterPath.absolute?` | `Pathname#absolute?` | 95.3% |
-| `FasterPath.add_trailing_separator` | `Pathname#add_trailing_separator` | 48.4% |
-| `FasterPath.basename` | `File.basename` | 12.0% |
-| `FasterPath.children` | `Pathname#children` | 34.4% |
-| `FasterPath.chop_basename` | `Pathname#chop_basename` | 83.4% |
-| `FasterPath.cleanpath_aggressive` | `Pathname#cleanpath_aggressive` | 94.1% |
-| `FasterPath.cleanpath_conservative` | `Pathname#cleanpath_conservative` | 93.5% |
-| `FasterPath.del_trailing_separator` | `Pathname#del_trailing_separator` | 85.4% |
-| `FasterPath.directory?` | `Pathname#directory?` | 6.4% |
-| `FasterPath.dirname` | `File.dirname` | 55.4% |
-| `FasterPath.entries` | `Pathname#entries` | 41.0% |
-| `FasterPath.extname` | `File.extname` | 63.1% |
-| `FasterPath.has_trailing_separator?` | `Pathname#has_trailing_separator` | 88.9% |
-| `FasterPath.plus` | `Pathname#join` | 72.0% |
-| `FasterPath.plus` | `Pathname#plus` | 87.7% |
-| `FasterPath.relative?` | `Pathname#relative?` | 92.6% |
-| `FasterPath.relative_path_from` | `Pathname#relative_path_from` | 93.3% |
+|FasterPath Rust Implementation|Ruby Implementation|Time Shaved Off (Ruby 2.7)|Time Shaved Off (Ruby 2.5)|
+|---|---|:---:|:---:|
+| `FasterPath.absolute?` | `Pathname#absolute?` | 95.7% | 96.7% |
+| `FasterPath.add_trailing_separator` | `Pathname#add_trailing_separator` | 85.4% | 83.0% |
+| `FasterPath.basename` | `File.basename` | 42.4% | 39.1% |
+| `FasterPath.children` | `Pathname#children` | 54.7% | 47.8% |
+| `FasterPath.chop_basename` | `Pathname#chop_basename` | 70.4% | 75.1% |
+| `FasterPath.cleanpath_aggressive` | `Pathname#cleanpath_aggressive` | 90.3% | 90.6% |
+| `FasterPath.cleanpath_conservative` | `Pathname#cleanpath_conservative` | 89.6% | 91.6% |
+| `FasterPath.del_trailing_separator` | `Pathname#del_trailing_separator` | 85.3% | 87.6% |
+| `FasterPath.directory?` | `Pathname#directory?` | 34.3% | 37.5% |
+| `FasterPath.dirname` | `File.dirname` | 56.8% | 54.7% |
+| `FasterPath.entries` | `Pathname#entries` | 38.0% | 33.9% |
+| `FasterPath.extname` | `File.extname` | 74.0% | 73.1% |
+| `FasterPath.has_trailing_separator?` | `Pathname#has_trailing_separator` | 88.5% | 89.1% |
+| `FasterPath.join` | `Pathname#join` | 88.1% | 90.3% |
+| `FasterPath.plus` | `Pathname#plus` | 91.7% | 93.4% |
+| `FasterPath.relative?` | `Pathname#relative?` | 92.8% | 95.2% |
+| `FasterPath.relative_path_from` | `Pathname#relative_path_from` | 92.5% | 93.6% |
+
+See [Benchmarks](#benchmarks) for how these are measured.
 
 You may choose to use the methods directly, or scope change to rewrite behavior on the
 standard library with the included refinements, or even call a method to monkeypatch
@@ -182,14 +205,66 @@ FasterPath.sledgehammer_everything!
 
 These will **not** be included by default in monkey-patches.  To try them with monkeypatching use the environment flag of `WITH_REGRESSION`.  These methods are here to be improved upon.
 
-|FasterPath Implementation|Ruby Implementation|
-|---|---|
-| `FasterPath.entries_compat` | `Pathname.entries` |
-| `FasterPath.children_compat` | `Pathname.children` |
+|FasterPath Implementation|Ruby Implementation|Time Shaved Off (Ruby 2.7)|Time Shaved Off (Ruby 2.5)|
+|---|---|:---:|:---:|
+| `FasterPath.entries_compat` | `Pathname.entries` | 16.8% | 9.2% |
+| `FasterPath.children_compat` | `Pathname.children` | 32.1% | 26.6% |
 
 It's been my observation (and some others) that the Rust implementation of the C code for `File` has similar results but
 performance seems to vary based on CPU cache on possibly 64bit/32bit system environments.  These are not included by default when the monkey patch method `FasterPath.sledgehammer_everything!` is executed.
 
+## Benchmarks
+
+The "Time Shaved Off" figures come from the project's Pinch-bench (`rake pbench`, in
+`test/pbench`): each method runs against Ruby's own implementation, and the result is how much
+less time FasterPath took. They are the median of 3 runs of `LONG_RUN=10 rake pbench` (500,000
+calls of each method, 5 times) on Linux x86_64 with Ruby 2.7.8 and 2.5.7, built with Rust 1.97.
+Expect a few points of difference from run to run.
+
+`rake pbench` is also the performance regression test: each method has a floor in
+`test/pbench/pbench_suite.rb` (about half of the improvement in the table above) and the task
+fails when a method measures below it, so a change that makes a method slower shows up in
+`rake test`. On Windows, where `join` is currently slower than Ruby's
+([#185](https://github.com/danielpclark/faster_path/issues/185)), the floors are reported but not
+enforced.
+
+### Before and after the Rutie 0.10 upgrade
+
+Measured the same way, alternating runs of the code before the upgrade (built with Rutie 0.6)
+and after it. Higher is better; the change is in percentage points.
+
+|Method|Ruby 2.7 before|Ruby 2.7 after|Change|Ruby 2.5 before|Ruby 2.5 after|Change|
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| `absolute?` | 93.3% | 95.7% | +2.4 | 96.1% | 96.7% | +0.6 |
+| `add_trailing_separator` | 66.6% | 85.4% | **+18.8** | 64.3% | 83.0% | **+18.7** |
+| `basename` | 42.4% | 42.4% | 0.0 | 32.1% | 39.1% | **+7.0** |
+| `children` | 52.8% | 54.7% | +1.9 | 46.5% | 47.8% | +1.3 |
+| `children_compat` | −1.2% | 32.1% | **+33.3** | 1.1% | 26.6% | **+25.5** |
+| `chop_basename` | 71.2% | 70.4% | −0.8 | 74.7% | 75.1% | +0.4 |
+| `cleanpath_aggressive` | 90.3% | 90.3% | 0.0 | 92.7% | 90.6% | −2.1 |
+| `cleanpath_conservative` | 89.8% | 89.6% | −0.2 | 91.7% | 91.6% | −0.1 |
+| `del_trailing_separator` | 86.5% | 85.3% | −1.2 | 87.0% | 87.6% | +0.6 |
+| `directory?` | 33.2% | 34.3% | +1.1 | 37.2% | 37.5% | +0.3 |
+| `dirname` | 49.8% | 56.8% | **+7.0** | 51.2% | 54.7% | +3.5 |
+| `entries` | 40.4% | 38.0% | −2.4 | 33.6% | 33.9% | +0.3 |
+| `entries_compat` | −29.8% | 16.8% | **+46.6** | −23.3% | 9.2% | **+32.5** |
+| `extname` | 70.3% | 74.0% | +3.7 | 74.0% | 73.1% | −0.9 |
+| `has_trailing_separator?` | 87.5% | 88.5% | +1.0 | 87.1% | 89.1% | +2.0 |
+| `join` | crashes | 88.1% | | crashes | 90.3% | |
+| `plus` | 92.3% | 91.7% | −0.6 | 93.0% | 93.4% | +0.4 |
+| `relative?` | 90.7% | 92.8% | +2.1 | 93.6% | 95.2% | +1.6 |
+| `relative_path_from` | 92.7% | 92.5% | −0.2 | 94.0% | 93.6% | −0.4 |
+
+Before the upgrade, `FasterPath.join` segfaulted, so its benchmark can't be measured.
+`add_trailing_separator`, `dirname` and the `_compat` methods gained the most:
+`add_trailing_separator` no longer builds a temporary string, no method checks its arguments
+for valid UTF-8 any more, and the `_compat` methods build `Pathname` objects without calling
+`Pathname.new`. `basename` was re-measured after it was made to take a shorter path on Unix
+and skip an empty extension; it was the one method that first measured slower on Ruby 2.5.
+Its timings vary a lot from run to run (Ruby 2.5 before: 40.0%, 32.1%, 28.7%; after: 29.6%,
+39.1%, 39.2%), so its instruction counts from `valgrind --tool=callgrind` are a steadier
+measure. They went from 2439 to 2331 per call on Ruby 2.5 and from 2689 to 2561 on Ruby 2.7.
+
 ## Getting Started with Development
 
 The primary methods to target are mostly listed in the **Why** section above.  You may find the Ruby
@@ -205,8 +280,6 @@ Whenever feasible implement it in Rust.
 After checking out the repo, make sure you have Rust installed, then run `bundle`.
 Run `rake test` to run the tests, and `rake bench` for benchmarks.
 
-Learn and share performance tips on the [wiki](https://github.com/danielpclark/faster_path/wiki)!
-
 ### Building and running tests
 
 First, bundle the gem's development dependencies by running `bundle`.  Rust compilation is included in the current rake commands.

data/Rakefile

@@ -46,7 +46,14 @@ end
 
 desc "Run Rust Tests"
 task :cargo do
-  sh "cargo test -- --nocapture"
+  ruby_lib = RbConfig::CONFIG['libdir']
+  sh(
+    {
+      'LD_LIBRARY_PATH' => ruby_lib,
+      'DYLD_LIBRARY_PATH' => ruby_lib
+    },
+    'cargo -vv test -- --nocapture'
+  )
 end
 
 Rake::TestTask.new(minitest: :build_lib) do |t|
@@ -62,7 +69,9 @@ task :init_mspec do |_t|
 end
 
 task test: [:cargo, :minitest, :lint, :pbench, :init_mspec] do |_t|
-  exec 'spec/mspec/bin/mspec --format spec core/file/basename core/file/extname core/file/dirname library/pathname'
+  # Run through Ruby so this also works on Windows
+  exec Gem.ruby, 'spec/mspec/bin/mspec', '--format', 'spec',
+       'core/file/basename', 'core/file/extname', 'core/file/dirname', 'library/pathname'
 end
 
 desc "Full mspec results w/o encoding"

data/faster_path.gemspec

@@ -24,11 +24,14 @@ Gem::Specification.new do |spec|
   spec.extensions    = ['ext/Rakefile']
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'bundler', '~> 1.12'
-  spec.add_dependency 'rake', '~> 12.0'
+  # Rutie 0.10, which the Rust extension is built with, supports Ruby 2.5 to 2.7
+  spec.required_ruby_version = ['>= 2.5', '< 3.0']
+
+  spec.add_dependency 'bundler', '>= 1.12'
+  spec.add_dependency 'rake', '>= 12.3'
   spec.add_dependency 'thermite', '0.13.0'
   spec.add_development_dependency 'read_source', '~> 0.2.6'
-  spec.add_development_dependency 'minitest', '~> 5.10'
+  spec.add_development_dependency 'minitest', '~> 5.11'
   spec.add_development_dependency 'minitest-reporters', '~> 1.1'
   spec.add_development_dependency 'color_pound_spec_reporter', '~> 0.0.9'
   spec.add_development_dependency 'rubocop', '0.53'

data/lib/faster_path/version.rb

@@ -1,3 +1,3 @@
 module FasterPath
-  VERSION = "0.3.9"
+  VERSION = "0.4.0"
 end

data/lib/faster_path.rb

@@ -6,8 +6,13 @@ require 'fiddle'
 require 'fiddle/import'
 
 # FasterPath module behaves as a singleton object with the alternative method
-# implementations for Pathname, and some for File, available directly on it.
+# implementations for `Pathname`, and some for `File`, available directly on it.
 #
+# New projects are recommend to reference methods defined directly on `FasterPath`.
+# Existing websites may use the `FasterPath.sledgehammer_everything!` method to
+# directly injet the more performant implementations of path handling in to their
+# existing code ecosystem.  To do so you will need to
+# `require 'faster_path/optional/monkeypatches'` beforehand.
 module FasterPath
   FFI_LIBRARY = begin
     toplevel_dir = File.dirname(__dir__)
@@ -17,7 +22,7 @@ module FasterPath
   end
 
   Fiddle::Function.
-    new(Fiddle.dlopen(FFI_LIBRARY)['Init_faster_pathname'], [], Fiddle::TYPE_VOIDP).
+    new(Fiddle.dlopen(FFI_LIBRARY)['Init_faster_pathname'], [], Fiddle::TYPE_VOID).
     call
 
   Public.class_eval do
@@ -35,7 +40,9 @@ module FasterPath
   # The Ruby architecture bit width: 64bits or 32bits
   # @return [Integer]
   def self.ruby_arch_bits
-    1.size * 8
+    # The width of a pointer; `1.size` is the width of a C `long`, which is
+    # 4 bytes on 64-bit Windows.
+    [0].pack('J').bytesize * 8
   end
 
   # A very fast way to check if a string is blank