diff --git a/CHANGELOG.md b/CHANGELOG.md index 3325bc6..7dc944f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,4 @@ -## [Unreleased] - -## [0.1.0] - 2022-02-21 +# Changelog +## v1.0.0 - 2022-02-26 - Initial release diff --git a/Gemfile.lock b/Gemfile.lock index 92c13b8..6ecd8f8 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ PATH remote: . specs: - clusterid (0.1.0) + clusterid (1.0.0) GEM remote: https://rubygems.org/ diff --git a/README.md b/README.md index 238341c..8a9e789 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,20 @@ # ClusterID -TODO: Delete this and the text above, and describe your gem +Create unique identifiers for entities in distributed systems. +[![Gem Version](https://badge.fury.io/rb/clusterid.svg)](https://badge.fury.io/rb/clusterid) ## What's in the Box? -TODO: Write this. +✅ Simple usage documentation written to get started fast. [Check it out!](#usage) + +⚡ A fast implementation in pure ruby. [Check it out!](#benchmarks) + +📚 YARD generated API documentation for the library. [Check it out!](https://tinychameleon.github.io/clusterid/) + +🤖 RBS types for your type checking wants. [Check it out!](./sig/clusterid.rbs) + +💎 Tests against many Ruby versions. [Check it out!](#ruby-versions) + +🔒 MFA protection on all gem owners. [Check it out!](https://rubygems.org/gems/clusterid) ## Installation @@ -22,6 +33,18 @@ Or install it yourself as: $ gem install clusterid +### Ruby Versions +This gem is tested against the following Ruby versions: + +- 2.6.0 +- 2.6.9 +- 2.7.0 +- 2.7.5 +- 3.0.0 +- 3.0.3 +- 3.1.0 +- 3.1.1 + ## Usage Create an intance of `ClusterId::V1::Generator` and then use the `generate` method to create `ClusterId::V1::Value` instances. @@ -206,3 +229,55 @@ Finally, update the documentation hosted on GitHub Pages: - Generate the documentation with `bundle exec rake yard` - Commit the documentation on the `gh-pages` branch - Push the new documentation so GitHub Pages can deploy it + +## Benchmarks +Benchmarking is tricky and the goal of a benchmark should be clear before attempting performance improvements. The goal of this library for performance is as follows: + +> This library should be capable of generating new values and instantiating existing values at a rate which does not make it a bottleneck for the majority of web APIs. + +Given the above goal statement, these benchmarks run on the following environment: + +| Attribute | Value | +|:--|--:| +| Ruby Version | 3.1.0 | +| MacOS Version | Catalina 10.15.7 (19H1615) | +| MacOS Model Identifier | MacBookPro10,1 | +| MacOS Processor Name | Quad-Core Intel Core i7 | +| MacOS Processor Speed | 2.7 GHz | +| MacOS Number of Processors | 1 | +| MacOS Total Number of Cores | 4 | +| MacOS L2 Cache (per Core) | 256 KB | +| MacOS L3 Cache | 6 MB | +| MacOS Hyper-Threading Technology | Enabled | +| MacOS Memory | 16 GB | + +### `ClusterId::V1` +The performance is approximately as follows when run using: + +- The default byte generator and clock +- Simple serializer and deserializer classes +- A constant 16 bytes of data for `Value` instantiation + +``` +~/…/clusterid› bundle exec rake benchmark +date; bundle exec ruby test/benchmarks/current.rb +Sat Feb 26 17:47:17 PST 2022 +Warming up -------------------------------------- + generate 23.924k i/100ms + from_byte_string 129.369k i/100ms + value 135.606k i/100ms +Calculating ------------------------------------- + generate 241.890k (± 2.8%) i/s - 1.220M in 5.048294s + from_byte_string 1.270M (± 5.2%) i/s - 6.339M in 5.004944s + value 1.358M (± 6.2%) i/s - 6.780M in 5.014634s +``` + +Being conservative in estimation and assuming: + +- all nodes in a cluster have identical millisecond timestamp values +- 240 generated clusterid values per millisecond +- approximately 150,000 values generated for a 5 byte value yields a 1% collision rate + +The `generate` method supports approximately 625 machines in a given cluster before the chance of a value collision reaches 1%. +The `value` instantiation has ample performance and should not be a bottleneck for generation of new values. +The `from_byte_string` API is nearly as fast as the value constructor and therefore should also not be a bottleneck. diff --git a/lib/clusterid/version.rb b/lib/clusterid/version.rb index 48e6bd5..bd12db6 100644 --- a/lib/clusterid/version.rb +++ b/lib/clusterid/version.rb @@ -1,8 +1,8 @@ # frozen_string_literal: true # Create unique identifiers for entities in distributed systems. -# @since 0.1.0 +# @since 1.0.0 module ClusterId # The gem version. - VERSION = "0.1.0" + VERSION = "1.0.0" end