ruby-ulid 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0aff39d0f8044f373d8dcdea149f26501e0118dfc0876f060b1b757a4d2a49e
-  data.tar.gz: 02df0ea7a5fe5f8dabd1179988cfe4c2574debf3ad7200d11445eef932dd7443
+  metadata.gz: d9517a4c0fe5e9feec91b2d8e19366baed6b8f1c1ccb42640389c1ad11066854
+  data.tar.gz: 24344ffd2549f7eae76f6f344169eb74baf3168e05499a9d7577a18fea63fc4d
 SHA512:
-  metadata.gz: ab036ed40e4f2740de9d37e44d2c6d4d233fa0071f95383accb2334c4d1f85b30b24eea902e0e29c34fefc8749b8caf5d1f9df6c52f93fe2e76c89aa0912d11e
-  data.tar.gz: d8ac11f63e5b301ed8b1eacd0d1211fd4b3a0bd79ccae8fe87050833cf305a7345da1dc136b95ecccfcafc6110cf9a281afb0f15db1fe2e01984bf320f82b7e5
+  metadata.gz: 5420da3cddc622a02a9d84ba398c17f59c733eea62d122aef0e5fb39dfade8e76cb3e4608814a0afb5c2e0251c6ebbbb2a10c6b27ea68b4ff8e32ad9f2e31ee3
+  data.tar.gz: 7bb4f8f941ed3f3ec2d5ebef03b4559b1ba2b07eaf5a9970ee3936ba6157bf5ff818eabc63847ba973536910bd6e8b8c65ae3382b74a368af85e228fec6524dd

data/README.md

@@ -49,7 +49,7 @@ Should be installed!
 Add this line to your application/library's `Gemfile` is needed in basic use-case
 
 ```ruby
-gem 'ruby-ulid', '>= 0.1.0', '< 0.2.0'
+gem 'ruby-ulid', '>= 0.1.1', '< 0.2.0'
 ```
 
 ### Generator and Parser
@@ -146,6 +146,8 @@ sample_ulids_by_the_time.take(5) #=>
 ulids.sort == ulids #=> true
 ```
 
+Same generator does not generate duplicated ULIDs even in multi threads environment. It is implemented with [Thread::Mutex](https://github.com/ruby/ruby/blob/5f8bca32571fa9c651f6903d36f66082363f8879/thread_sync.c#L1572-L1582)
+
 ### Filtering IDs with `Time`
 
 `ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
@@ -401,6 +403,82 @@ NOTE: It is still having precision issue similar as `ulid gem` in the both gener
 1. [Fix to handle timestamp precision in parser](https://github.com/abachman/ulid-ruby/pull/5)
 1. [Fix to handle timestamp precision in generator](https://github.com/abachman/ulid-ruby/pull/4)
 
+### Generating benchmarks
+
+This runs rough benchmarks
+
+```console
+$ rake benchmark_with_other_gems
+(Do not use `bundle exec`!)
+```
+
+<details>
+<summary>One of the result at 2021/05/10 on my machine</summary>
+
+```plaintext
+#### rafaelsales - ulid
+cd ./benchmark/compare_with_othergems/rafaelsales && bundle install --quiet && bundle exec ruby -v ./generate.rb
+ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
+Warming up --------------------------------------
+       ULID.generate     5.560k i/100ms
+Calculating -------------------------------------
+       ULID.generate     52.655k (±11.0%) i/s -    261.320k in   5.029719s
+"`ulid gem - 1.3.0` generated products: 371927 - sample: [\"01F59Y97807D2S67KE6X7ATK7Z\", \"01F59Y9AVRQJFAT5M2N7Z72BVF\", \"01F59Y95Z1042X4Z1K9729BSE3\", \"01F59Y95ZMVDFKD63Y8TT145GQ\", \"01F59Y94YQEZ3PH5STZ8PS1JPG\"]"
+------------------------------------------------------------------------
+#### abachman - ulid-ruby
+cd ./benchmark/compare_with_othergems/abachman && bundle install --quiet && bundle exec ruby -v ./generate.rb
+ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
+Warming up --------------------------------------
+       ULID.generate     3.862k i/100ms
+Calculating -------------------------------------
+       ULID.generate     38.415k (±13.1%) i/s -    189.238k in   5.025788s
+"`ulid-ruby gem - 1.0.0` generated products: 260625 - sample: [\"01F59Y9H9V17EPXTYNZDCXB9EZ\", \"01F59Y9J4S4XZ68MF5DJDWHTAC\", \"01F59Y9J8887VC8E850QSBDCDX\", \"01F59Y9JEJPD088EYXVHB86W3N\", \"01F59Y9GGAZFXGCB92EQD695CZ\"]"
+------------------------------------------------------------------------
+#### kachick - ruby-ulid(This one)
+cd ./benchmark/compare_with_othergems/kachick && bundle install --quiet && bundle exec ruby -v ./generate.rb
+ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
+Warming up --------------------------------------
+  ULID.generate.to_s     3.185k i/100ms
+Calculating -------------------------------------
+  ULID.generate.to_s     31.934k (± 9.1%) i/s -    159.250k in   5.030707s
+"`ruby-ulid gem (this one) - 0.1.0` generated products: 223867 - sample: [\"01F59Y9SPZHM6JCTYP50CHGVAX\", \"01F59Y9VB7X0SX32MMKF78KJR3\", \"01F59Y9W0C83RYCNYVH84R4JG3\", \"01F59Y9V218Q3D4YP3W74ET3EW\", \"01F59Y9X6DD8NX99WBGCR7RNXF\"]"
+```
+
+In another execution, Changed as below. So there doesn't seem to be a big difference.
+
+```plaintext
+#### rafaelsales - ulid
+cd ./benchmark/compare_with_othergems/rafaelsales && bundle install --quiet && bundle exec ruby -v ./generate.rb
+ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
+Warming up --------------------------------------
+       ULID.generate     2.473k i/100ms
+Calculating -------------------------------------
+       ULID.generate     24.101k (±15.9%) i/s -    118.704k in   5.066190s
+"`ulid gem - 1.3.0` generated products: 164763 - sample: [\"01F59YEGPFMXXZWC1YQ49TSK8Y\", \"01F59YEFF7VX5WAW91VTCSE2N9\", \"01F59YEEZ5P9428SDYEDYW8D27\", \"01F59YEHVK56DZBJSNSQK6V1W6\", \"01F59YEHE07M98PVV97ABBAKHM\"]"
+------------------------------------------------------------------------
+#### abachman - ulid-ruby
+cd ./benchmark/compare_with_othergems/abachman && bundle install --quiet && bundle exec ruby -v ./generate.rb
+ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
+Warming up --------------------------------------
+       ULID.generate     2.620k i/100ms
+Calculating -------------------------------------
+       ULID.generate     27.571k (±14.2%) i/s -    136.240k in   5.056272s
+"`ulid-ruby gem - 1.0.0` generated products: 186683 - sample: [\"01F59YEVX6GC9TC0RCZ74RC6Z3\", \"01F59YESJXWYGZ61TXHKRVKS97\", \"01F59YEVQ4QQKBED5T49RTV1MA\", \"01F59YEPJ6MMZY1N63DNW7C4SN\", \"01F59YEQK52K8TKTP1ESC6VC5X\"]"
+------------------------------------------------------------------------
+#### kachick - ruby-ulid(This one)
+cd ./benchmark/compare_with_othergems/kachick && bundle install --quiet && bundle exec ruby -v ./generate.rb
+ruby 3.0.1p64 (2021-04-05 revision 0fb782ee38) [x86_64-darwin20]
+Warming up --------------------------------------
+  ULID.generate.to_s     3.014k i/100ms
+Calculating -------------------------------------
+  ULID.generate.to_s     31.612k (±10.1%) i/s -    156.728k in   5.013432s
+"`ruby-ulid gem (this one) - 0.1.0` generated products: 212293 - sample: [\"01F59YF1WP49TT4GQPDN3E9JTJ\", \"01F59YF1MW1ZDQW93NX4J6RG4G\", \"01F59YF0KRX2CZKHDQQSN5HXHW\", \"01F59YEZVNH8YHP4ZHDK2ZRWSR\", \"01F59YF1J0FV3CVV099SHA2Q9A\"]"
+```
+
+I have an excuse, This gem does not aim `faster than other`.
+So I think the results are acceptable.
+</details>
+
 ## References
 
 - [Repository](https://github.com/kachick/ruby-ulid)

data/lib/ulid.rb

@@ -15,6 +15,7 @@ class ULID
   class Error < StandardError; end
   class OverflowError < Error; end
   class ParserError < Error; end
+  class UnexpectedError < Error; end
 
   # Excluded I, L, O, U, -.
   # This is the encoding patterns.
@@ -239,9 +240,8 @@ class ULID
     end
   end
 
-  # @api private
   # @return [Integer]
-  def self.reasonable_entropy
+  private_class_method def self.reasonable_entropy
     SecureRandom.random_number(MAX_ENTROPY)
   end
 
@@ -266,6 +266,39 @@ class ULID
     string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
   end
 
+  # @param [ULID, #to_ulid] object
+  # @return [ULID, nil]
+  # @raise [TypeError] if `object.to_ulid` did not return ULID instance
+  def self.try_convert(object)
+    begin
+      converted = object.to_ulid
+    rescue NoMethodError
+      nil
+    else
+      if ULID === converted
+        converted
+      else
+        object_class_name = safe_get_class_name(object)
+        converted_class_name = safe_get_class_name(converted)
+        raise TypeError, "can't convert #{object_class_name} to ULID (#{object_class_name}#to_ulid gives #{converted_class_name})"
+      end
+    end
+  end
+
+  # @param [BasicObject] object
+  # @return [String]
+  private_class_method def self.safe_get_class_name(object)
+    fallback = 'UnknownObject'
+
+    begin
+      name = String.try_convert(object.class.name)
+    rescue Exception
+      fallback
+    else
+      name || fallback
+    end
+  end
+
   # @api private
   # @param [Integer] milliseconds
   # @param [Integer] entropy
@@ -424,6 +457,11 @@ class ULID
     super
   end
 
+  # @return [self]
+  def to_ulid
+    self
+  end
+
   # @return [self]
   def dup
     self

data/lib/ulid/monotonic_generator.rb

@@ -4,40 +4,59 @@
 
 class ULID
   class MonotonicGenerator
-    # @api private
-    attr_accessor :latest_milliseconds, :latest_entropy
+    # @return [ULID, nil]
+    attr_reader :prev
+
+    undef_method :instance_variable_set
 
     def initialize
       @mutex = Thread::Mutex.new
-      reset
+      @prev = nil
+    end
+
+    # @return [String]
+    def inspect
+      "ULID::MonotonicGenerator(prev: #{@prev.inspect})"
     end
+    alias_method :to_s, :inspect
 
     # @param [Time, Integer] moment
     # @return [ULID]
     # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
-    # @raise [ArgumentError] if the given moment(milliseconds) is negative number
+    # @raise [UnexpectedError] if the generated ULID is an invalid value in monotonicity spec.
+    #   Basically will not happen. Just means this feature prefers error rather than invalid value.
     def generate(moment: ULID.current_milliseconds)
-      milliseconds = ULID.milliseconds_from_moment(moment)
-      raise ArgumentError, "milliseconds should not be negative: given: #{milliseconds}" if milliseconds.negative?
-
       @mutex.synchronize do
-        if @latest_milliseconds < milliseconds
-          @latest_milliseconds = milliseconds
-          @latest_entropy = ULID.reasonable_entropy
+        unless @prev
+          @prev = ULID.generate(moment: moment)
+          return @prev
+        end
+
+        milliseconds = ULID.milliseconds_from_moment(moment)
+
+        ulid = if @prev.milliseconds < milliseconds
+          ULID.generate(moment: milliseconds)
         else
-          @latest_entropy += 1
+          ULID.from_milliseconds_and_entropy(milliseconds: @prev.milliseconds, entropy: @prev.entropy.succ)
         end
-        ULID.from_milliseconds_and_entropy(milliseconds: @latest_milliseconds, entropy: @latest_entropy)
+
+        unless ulid > @prev
+          base_message = "monotonicity broken from unexpected reasons # generated: #{ulid.inspect}, prev: #{@prev.inspect}"
+          additional_information = if Thread.list == [Thread.main]
+            '# NOTE: looks single thread only exist'
+          else
+            '# NOTE: ran on multi threads, so this might from concurrency issue'
+          end
+
+          raise UnexpectedError, base_message + additional_information
+        end
+
+        @prev = ulid
+        ulid
       end
     end
 
-    # @api private
-    # @return [void]
-    def reset
-      @latest_milliseconds = 0
-      @latest_entropy = ULID.reasonable_entropy
-      nil
-    end
+    undef_method :freeze
 
     # @raise [TypeError] always raises exception and does not freeze self
     # @return [void]

data/lib/ulid/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 class ULID
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/sig/ulid.rbs

@@ -33,6 +33,9 @@ class ULID
   class ParserError < Error
   end
 
+  class UnexpectedError < Error
+  end
+
   module CrockfordBase32
     class SetupError < ScriptError
     end
@@ -47,21 +50,24 @@ class ULID
   end
 
   class MonotonicGenerator
-    attr_accessor latest_milliseconds: Integer
-    attr_accessor latest_entropy: Integer
+    @mutex: Thread::Mutex
+    attr_reader prev: ULID | nil
     def initialize: -> void
     def generate: (?moment: moment) -> ULID
-    def reset: -> void
+    def inspect: -> String
+    alias to_s inspect
     def freeze: -> void
   end
 
+  interface _ULID
+    def to_ulid: () -> ULID
+  end
+
   type octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
   type timestamp_octets = [Integer, Integer, Integer, Integer, Integer, Integer]
   type randomness_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
   type period = Range[Time] | Range[nil] | Range[ULID]
 
-  @milliseconds: Integer
-  @entropy: Integer
   @string: String?
   @integer: Integer
   @timestamp: String?
@@ -75,7 +81,6 @@ class ULID
   def self.milliseconds_from_moment: (moment moment) -> Integer
   def self.range: (period period) -> Range[ULID]
   def self.floor: (Time time) -> Time
-  def self.reasonable_entropy: -> Integer
   def self.parse: (String string) -> self
   def self.from_uuidv4: (String uuid) -> ULID
   def self.from_integer: (Integer integer) -> self
@@ -87,6 +92,8 @@ class ULID
   def self.scan:  (String string) -> Enumerator[self, singleton(ULID)]
                 | (String string) { (self ulid) -> void } -> singleton(ULID)
   def self.from_milliseconds_and_entropy: (milliseconds: Integer, entropy: Integer) -> self
+  def self.try_convert: (_ULID) -> self
+                      | (untyped) -> nil
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
@@ -111,11 +118,14 @@ class ULID
   alias succ next
   def pred: -> ULID?
   def freeze: -> self
+  def to_ulid: -> self
   def dup: -> self
   # Same as https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79
   def clone: (?freeze: bool) -> self
 
   private
+  def self.reasonable_entropy: -> Integer
   def self.milliseconds_from_time: (Time time) -> Integer
+  def self.safe_get_class_name: (untyped object) -> String
   def cache_all_instance_variables: -> void
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-09 00:00:00.000000000 Z
+date: 2021-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rbs