xoroshiro 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 397fae7c723830610f2cc562c915dd25096641940f91feb082f3d48237da6d67
+  data.tar.gz: a1a95dd77003cfb69254432c2639f87934a3950314b218e3a46b1bab970848a6
+SHA512:
+  metadata.gz: b90078aa55ad0b2c093ca1f7bbc1cb2953dea20124bd76574da198428d4714f262a97d5b8758ce42596bcd4afd6ee33853ad4f5c17a400d57cb99aa0762f5cd3
+  data.tar.gz: adee3262f19628655e14a30add4d4f8e08a9256da9657cdda879e08fc2d2e7d827d2a0dd9f4465de80a00a55c3e5911c4d7142696906466cc8e3a0f72a1b43c2

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,28 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+# The default recommendation is 'loop do' rather than
+# 'while true', but is measurably slower. Turn off.
+Style/InfiniteLoop:
+  Enabled: false
+
+# Override for rspec tests
+Metrics/BlockLength:
+  Max: 100
+
+Metrics/MethodLength:
+  Max: 20
+
+Layout/LineLength:
+  Max: 120
+
+require: rubocop-rake

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in xoroshiro.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+gem 'rake-compiler'
+gem 'rubocop-rake', require: false
+
+# gem "", "~> "
+
+gem 'rubocop', '~> 1.21'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Paul J Sanchez
+
+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

@@ -0,0 +1,24 @@
+# Xoroshiro
+
+This gem provides a port of the [Xoroshiro256\*\*](https://prng.di.unimi.it)
+pseudo-random number generator (PRNG) to Ruby. Xoroshiro offers excellent
+statistical performance and speed, matching or exceeding MT19937 (the PRNG
+underpinning Ruby's built-in `Random` class) in both categories.
+
+`Xoroshiro::rand` is intended as a drop-in replacement for `Kernel::rand`, providing
+the same behavior given the same arguments. Enumeration is also provided via `:each`.
+
+Timings on both MacOS and Windows show the gem's performance to be faster than
+`Kernel::rand` for generating both floating point and integer values—substantially
+so for the latter. You can confirm this for yourself by running the `xoroshiro_timings.rb`
+script provided in the gem's `exe` folder.
+
+## Installation
+
+Install the gem by executing:
+
+    $ gem install xoroshiro
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/extensiontask'
+require 'rspec/core/rake_task'
+require 'rubocop-rake'
+require 'rubocop/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new do |task|
+  task.requires << 'rubocop-rake'
+end
+
+desc 'Build the extension'
+task build: :compile
+
+Rake::ExtensionTask.new('xoroshiro') do |ext|
+  ext.lib_dir = 'lib/xoroshiro'
+end
+
+YARD::Rake::YardocTask.new('doc') do |t|
+  t.options = ['--no-private'] # optional
+end
+
+task default: %i[clobber compile spec rubocop doc]

data/exe/xoroshiro_timings.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../lib/xoroshiro'
+require 'benchmark/ips'
+
+x = Xoroshiro::Random.new
+rand_enum = Enumerator.new { |yielder| yielder << rand while true }.lazy
+x_enum = x.each.lazy
+
+puts 'Direct floating point calls...'
+Benchmark.ips do |b|
+  b.report('rand float:') { 1000.times { rand } }
+  b.report('x rand float:') { 1000.times { x.rand } }
+  b.compare!
+end
+
+puts "\nInteger generation w/ high probability of rejection..."
+Benchmark.ips do |b|
+  b.report('  rand P{rej} ~ 1/2:') { rand 0..0x80000000 }
+  b.report('x rand P{rej} ~ 1/2:') { x.rand 0..0x80000000 }
+  b.compare!
+end
+
+puts "\nInteger generation w/ zero probability of rejection..."
+Benchmark.ips do |b|
+  b.report('  rand P{rej} = 0:') { rand 0..0x7fffffff }
+  b.report('x rand P{rej} = 0:') { x.rand 0..0x7fffffff }
+  b.compare!
+end
+
+puts "\nEnumerator.next..."
+Benchmark.ips do |b|
+  b.report('rand next:') { 1000.times { rand_enum.next } }
+  b.report('x next:') { 1000.times { x_enum.next } }
+  b.compare!
+end
+
+puts "\nEnumerator.lazy.first in groups of 1000..."
+Benchmark.ips do |b|
+  b.report('rand first 1k:') { rand_enum.first 1000 }
+  b.report('x first 1k:') { x_enum.first 1000 }
+  b.compare!
+end

data/ext/xoroshiro/extconf.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+
+create_makefile('xoroshiro/xoroshiro')

data/ext/xoroshiro/xoroshiro.c

@@ -0,0 +1,218 @@
+#include "ruby.h"
+#include "xoroshiro256.h"
+
+static void seed_struct_free(seed_struct *self) {
+  if (self->seed != NULL) {
+    free(self->seed);
+  }
+  ruby_xfree(self);
+}
+
+static VALUE rb_seed_struct_alloc(VALUE klass) {
+  return Data_Wrap_Struct(klass, NULL, seed_struct_free, ruby_xmalloc(sizeof(seed_struct)));
+}
+
+/*
+ * Explicitly set the 256 bit state of the generator. Complement to +get_state+.
+ *
+ * *Arguments*::
+ *   @param seeds [Array of 4 Integers]
+ *
+ * @return self
+ */
+static VALUE set_state(VALUE self, VALUE seeds) {
+  Check_Type(seeds, T_ARRAY);
+  long seedsize = RARRAY_LEN(seeds);
+  if (seedsize != 4) {
+    rb_raise(rb_eTypeError, "set_state: Four integer seed values required");
+  }
+
+  seed_struct* seed_values;
+  Data_Get_Struct(self, seed_struct, seed_values);
+
+  seed_values->size = (uint32_t) seedsize;
+  seed_values->seed = (uint64_t *) malloc(seed_values->size * sizeof(uint64_t));
+  for (uint32_t i = 0; i < seedsize; ++i) {
+    seed_values->seed[i] = NUM2ULL(rb_ary_entry(seeds, i));
+  }
+  return self;
+}
+
+/*
+ * Retrieve the current 256 bit state of the generator. Complement to +set_state+.
+ *
+ * @return an array of four integers.
+ */
+static VALUE get_state(VALUE self) {
+  seed_struct* seed_values;
+  Data_Get_Struct(self, seed_struct, seed_values);
+  VALUE state = rb_ary_new();
+  for (uint32_t i = 0; i < seed_values->size; ++i) {
+    rb_ary_push(state, ULL2NUM(seed_values->seed[i]));
+  }
+  return state;
+}
+
+/*
+ * Update the state to the equivalent of 2^128 calls to +rand()+.
+ * This can be used to generate 2^128 non-overlapping subsequences
+ * for parallel computations.
+ */
+static VALUE do_jump(VALUE self) {
+  seed_struct* seed_values;
+  Data_Get_Struct(self, seed_struct, seed_values);
+  jump(seed_values);
+  return self;
+}
+
+/*
+ * Update the state to the equivalent of 2^192 calls to +rand()+.
+ * This can be used to generate 2^64 non-overlapping subsequences
+ * for parallel computations.
+ */
+static VALUE do_long_jump(VALUE self) {
+  seed_struct* seed_values;
+  Data_Get_Struct(self, seed_struct, seed_values);
+  long_jump(seed_values);
+  return self;
+}
+
+/*
+ * Generate a random value as specified by +args+.
+ *
+ * *Arguments*::
+ *   @param *args* [+nil+, +Range+, +Numeric+] specify the range and
+ *   type of the generated value. (default: +nil+)
+ *   - +nil+ -> generate a Uniform(0,1) +Float+ value
+ *   - +Range+ -> generate a uniformly distributed value within the range
+ *     of type:
+ *     - if both bounds are +Integer+ -> +Integer+
+ *     - otherwise -> +Float+
+ *   - +Numeric+ *value* -> evaluated as +Range+ (0..*value*)
+ *
+ * @return a single value consistent with the specified range and type.
+ */
+static VALUE rand_method(int argc, VALUE* argv, VALUE self) {
+  seed_struct* seed_values;
+  Data_Get_Struct(self, seed_struct, seed_values);
+
+  VALUE argument;
+  rb_scan_args(argc, argv, "01", &argument);
+
+  VALUE outcome = Qnil;
+
+  if (rb_obj_is_kind_of(argument, rb_cRange)) {
+    VALUE rb_beg;
+    VALUE rb_end;
+    int excl;
+    if (!rb_range_values(argument, &rb_beg, &rb_end, &excl)) return Qnil;
+    if (NIL_P(rb_beg) || NIL_P(rb_end)) return Qnil;
+    if (rb_obj_is_kind_of(rb_beg, rb_cNumeric) && rb_obj_is_kind_of(rb_end, rb_cNumeric)) {
+      if (RB_FLOAT_TYPE_P(rb_beg) || RB_FLOAT_TYPE_P(rb_end)) {
+        double begin = NUM2DBL(rb_beg);
+        double drange = NUM2DBL(rb_end) - begin;
+        outcome = DBL2NUM(begin + next_double(seed_values) * drange);
+      } else {
+        int64_t begin = NUM2LL(rb_beg);
+        int64_t end = NUM2LL(rb_end);
+        int64_t irange = end - begin;
+        if (!excl) {
+          irange += 1;
+        }
+        if (irange >= 0) outcome = LL2NUM(begin + nearlydivisionless(irange, seed_values));
+      }
+    }
+    return outcome;
+  } else {
+    switch (TYPE(argument)) {
+      case T_NIL:
+        outcome = DBL2NUM(next_double(seed_values));
+        break;
+      case T_FLOAT:
+        outcome = DBL2NUM(next_double(seed_values) * NUM2DBL(argument));
+        break;
+      case T_FIXNUM: {
+        int64_t upper_lim = NUM2LL(argument);
+        if (upper_lim > 0) outcome = ULL2NUM(nearlydivisionless(upper_lim, seed_values));
+        break;
+      }
+      case T_BIGNUM: {
+        uint64_t upper_lim = NUM2ULL(argument);
+        outcome = ULL2NUM(nearlydivisionless(upper_lim, seed_values));
+        break;
+      }
+    }
+    return outcome;
+  }
+}
+
+static VALUE each_u(VALUE self) {
+  if (!rb_block_given_p()) {
+    return rb_enumeratorize_with_size(
+      self, ID2SYM(rb_intern("each_u")), 0, 0, 0
+    );
+  }
+  seed_struct* seed_values;
+  Data_Get_Struct(self, seed_struct, seed_values);
+  for(;;) {
+    rb_yield(DBL2NUM(next_double(seed_values)));
+  }
+  return Qnil;
+}
+
+static VALUE each_u_range(VALUE self) {
+  if (!rb_block_given_p()) {
+    return rb_enumeratorize_with_size(
+      self, ID2SYM(rb_intern("each_u_range")), 0, 0, 0
+    );
+  }
+  seed_struct* seed_values;
+  Data_Get_Struct(self, seed_struct, seed_values);
+
+  VALUE obj_range = rb_ivar_get(self, rb_intern("@range"));
+  VALUE rb_beg;
+  VALUE rb_end;
+  int excl;
+  if (!rb_range_values(obj_range, &rb_beg, &rb_end, &excl)) return Qnil;
+  if (NIL_P(rb_beg) || NIL_P(rb_end)) return Qnil;
+  if (rb_obj_is_kind_of(rb_beg, rb_cNumeric) && rb_obj_is_kind_of(rb_end, rb_cNumeric)) {
+    if (RB_FLOAT_TYPE_P(rb_beg) || RB_FLOAT_TYPE_P(rb_end)) {
+      double begin = NUM2DBL(rb_beg);
+      double range = NUM2DBL(rb_end) - begin;
+      for(;;) {
+        rb_yield(DBL2NUM(begin + next_double(seed_values) * range));
+      }
+    } else {
+      int64_t begin = NUM2LL(rb_beg);
+      int64_t end = NUM2LL(rb_end);
+      int64_t range = end - begin;
+      if (!excl) {
+        range += 1;
+      }
+      if (range >= 0) {
+        for(;;) {
+          rb_yield(LL2NUM(begin + nearlydivisionless(range, seed_values)));
+        }
+      }
+    }
+  }
+  return Qnil;
+}
+
+VALUE rb_mXoroshiro = Qnil;
+VALUE rb_cXgenerator = Qnil;
+VALUE rb_cXrandom = Qnil;
+
+void Init_xoroshiro(void) {
+  rb_mXoroshiro = rb_define_module("Xoroshiro");
+  rb_cXrandom = rb_define_class_under(rb_mXoroshiro, "Random", rb_cObject);
+
+  rb_define_alloc_func(rb_cXrandom, rb_seed_struct_alloc);
+  rb_define_method(rb_cXrandom, "set_state", set_state, 1);
+  rb_define_method(rb_cXrandom, "get_state", get_state, 0);
+  rb_define_private_method(rb_cXrandom, "each_u", each_u, 0);
+  rb_define_private_method(rb_cXrandom, "each_u_range", each_u_range, 0);
+  rb_define_method(rb_cXrandom, "rand", rand_method, -1);
+  rb_define_method(rb_cXrandom, "jump", do_jump, 0);
+  rb_define_method(rb_cXrandom, "long_jump", do_long_jump, 0);
+}

data/ext/xoroshiro/xoroshiro256.c

@@ -0,0 +1,147 @@
+#include <stdint.h>
+#include "xoroshiro256.h"
+
+static const double SCALE_VALUE = 0x1.0p-53;
+
+double next_double(seed_struct* seed_values) {
+  return (next(seed_values) >> 11) * SCALE_VALUE;
+}
+
+/*
+  Fast nearly divisionless method for generating unbiased uniforms in any range.
+  Sourced from the appendix of:
+
+  Daniel Lemire. 2019. Fast Random Integer Generation in an Interval.
+  ACM Trans. Model. Comput. Simul. 29, 1, Article 3 (February 2019),
+  12 pages. DOI:https://doi.org/10.1145/3230636
+*/
+uint64_t nearlydivisionless(uint64_t bound, seed_struct* seed_values) {
+  uint64_t r_val = next(seed_values);
+  __uint128_t result = (__uint128_t) r_val * (__uint128_t) bound;
+  uint64_t l = (uint64_t) result;
+  if (l < bound) {
+    // uint64_t t = -bound % bound;
+    uint64_t t = (0xFFFFFFFFFFFFFFFFull - bound + 1) % bound;
+    while (l < t) {
+      r_val = next(seed_values);
+      result = (__uint128_t) r_val * (__uint128_t) bound;
+      l = (uint64_t) result;
+    }
+  }
+  return result >> 64;
+}
+
+/* XOROSHIRO */
+
+/*
+  Written in 2018 by David Blackman and Sebastiano Vigna (vigna@acm.org)
+
+  To the extent possible under law, the author has dedicated all copyright
+  and related and neighboring rights to this software to the public domain
+  worldwide. This software is distributed without any warranty.
+
+  See <http://creativecommons.org/publicdomain/zero/1.0/>.
+*/
+
+/* 
+   This is xoshiro256** 1.0, one of our all-purpose, rock-solid
+   generators. It has excellent (sub-ns) speed, a state (256 bits) that is
+   large enough for any parallel application, and it passes all tests we
+   are aware of.
+
+   For generating just floating-point numbers, xoshiro256+ is even faster.
+
+   The state must be seeded so that it is not everywhere zero. If you have
+   a 64-bit seed, we suggest to seed a splitmix64 generator and use its
+   output to fill seed_values->seed.
+*/
+
+/* 
+  Modified for Ruby extension use in 2023 by Paul J Sanchez (pjs@alum.mit.edu)
+*/
+
+static inline uint64_t rotl(const uint64_t x, int k) {
+  return (x << k) | (x >> (64 - k));
+}
+
+uint64_t next(seed_struct *seed_values) {
+  const uint64_t result = rotl(seed_values->seed[1] * 5, 7) * 9;
+
+  const uint64_t t = seed_values->seed[1] << 17;
+
+  seed_values->seed[2] ^= seed_values->seed[0];
+  seed_values->seed[3] ^= seed_values->seed[1];
+  seed_values->seed[1] ^= seed_values->seed[2];
+  seed_values->seed[0] ^= seed_values->seed[3];
+
+  seed_values->seed[2] ^= t;
+
+  seed_values->seed[3] = rotl(seed_values->seed[3], 45);
+
+  return result;
+}
+
+
+/*
+   This is the jump function for the generator. It is equivalent
+   to 2^128 calls to next(); it can be used to generate 2^128
+   non-overlapping subsequences for parallel computations.
+*/
+
+void jump(seed_struct *seed_values) {
+  static const uint64_t JUMP[] = { 0x180ec6d33cfd0aba, 0xd5a61266f0c9392c, 0xa9582618e03fc9aa, 0x39abdc4529b1661c };
+
+  uint64_t s0 = 0;
+  uint64_t s1 = 0;
+  uint64_t s2 = 0;
+  uint64_t s3 = 0;
+  for(uint32_t i = 0; i < sizeof JUMP / sizeof *JUMP; i++)
+    for(int b = 0; b < 64; b++) {
+      if (JUMP[i] & UINT64_C(1) << b) {
+        s0 ^= seed_values->seed[0];
+        s1 ^= seed_values->seed[1];
+        s2 ^= seed_values->seed[2];
+        s3 ^= seed_values->seed[3];
+      }
+      next(seed_values); 
+    }
+    
+  seed_values->seed[0] = s0;
+  seed_values->seed[1] = s1;
+  seed_values->seed[2] = s2;
+  seed_values->seed[3] = s3;
+}
+
+
+
+/*
+   This is the long-jump function for the generator. It is equivalent to
+   2^192 calls to next(); it can be used to generate 2^64 starting points,
+   from each of which jump() will generate 2^64 non-overlapping
+   subsequences for parallel distributed computations.
+*/
+
+void long_jump(seed_struct *seed_values) {
+  static const uint64_t LONG_JUMP[] = { 0x76e15d3efefdcbbf, 0xc5004e441c522fb3, 0x77710069854ee241, 0x39109bb02acbe635 };
+
+  uint64_t s0 = 0;
+  uint64_t s1 = 0;
+  uint64_t s2 = 0;
+  uint64_t s3 = 0;
+  for(uint32_t i = 0; i < sizeof LONG_JUMP / sizeof *LONG_JUMP; i++)
+    for(int b = 0; b < 64; b++) {
+      if (LONG_JUMP[i] & UINT64_C(1) << b) {
+        s0 ^= seed_values->seed[0];
+        s1 ^= seed_values->seed[1];
+        s2 ^= seed_values->seed[2];
+        s3 ^= seed_values->seed[3];
+      }
+      next(seed_values); 
+    }
+    
+  seed_values->seed[0] = s0;
+  seed_values->seed[1] = s1;
+  seed_values->seed[2] = s2;
+  seed_values->seed[3] = s3;
+}
+

data/ext/xoroshiro/xoroshiro256.h

@@ -0,0 +1,15 @@
+#ifndef XOROSHIRO256_H
+#define XOROSHIRO256_H 1
+
+typedef struct {
+	uint64_t *seed;
+	uint32_t size;
+} seed_struct;
+
+uint64_t nearlydivisionless(uint64_t bound, seed_struct *seed_values);
+double next_double(seed_struct *seed_values);
+uint64_t next(seed_struct *seed_values);
+void jump(seed_struct *seed_values);
+void long_jump(seed_struct *seed_values);
+
+#endif /* XOROSHIRO256_H */

data/lib/xoroshiro/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Xoroshiro
+  VERSION = '0.2.0'
+end

data/lib/xoroshiro.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative 'xoroshiro/version'
+require_relative 'xoroshiro/xoroshiro'
+
+require 'openssl'
+require 'securerandom'
+
+##
+# The +Xoroshiro256\*\*+ pseudo-random number generator implemented as a Ruby
+# C extension. For more information about the Xoroshiro family of generators
+# see https://prng.di.unimi.it
+#
+module Xoroshiro
+  class Error < StandardError; end
+
+  private_constant
+  BITMASK64 = (1 << 64) - 1
+
+  # @private
+  def self.gen_seed_state(seed)
+    if seed.nil?
+      # seed values from entropy via SecureRandom
+      Array.new(4) { SecureRandom.hex(8).to_i(16) }
+    else
+      # seed values by sha26 digest of provided value
+      digest = OpenSSL::Digest.hexdigest('sha256', seed.to_s).to_i(16)
+      Array.new(4) { |i| (digest >> (i * 64)) & BITMASK64 }
+    end
+  end
+
+  ##
+  # Provides pseudo-random variate generation based on +Xoroshiro256\*\*+.
+  #
+  # Quoting the original Xoroshiro creators:
+  # >>>
+  #   ...xoshiro256** 1.0 [is] one of our all-purpose, rock-solid
+  #   generators. It has excellent (sub-ns) speed, a state (256 bits) that is
+  #   large enough for any parallel application, and it passes all tests we
+  #   are aware of.
+  #
+  # This generator outperforms MT19937, the underlying engine for
+  # +Kernel::rand+, in both speed and statistical performance.
+  #
+  class Random
+    ##
+    # *Arguments*::
+    #   @param *range* [+nil+, +Range+, +Numeric+] specify the range and
+    #   type of the values produced by +:each+. (default: +nil+)
+    #   - +nil+ -> generate Uniform(0,1) +Float+ values
+    #   - +Range+ -> generate uniformly distributed values within the range
+    #     of type:
+    #     - if both bounds are +Integer+ -> +Integer+
+    #     - otherwise -> +Float+
+    #   - +Numeric+ *value* -> evaluated as +Range+ 0..*value*
+    #   @param *seed:* [+nil+, +Numeric+] initialize the generator state for
+    #   reproducibility. (default: +nil+)
+    #   - +nil+ -> use system entropy via +SecureRandom+ to generate
+    #     256 bits of initial state.
+    #   - +Numeric+ *value* -> calculate SHA256 hash of *value* to use
+    #     as the initial state.
+    #
+    def initialize(range = nil, seed: nil)
+      set_state(Xoroshiro.gen_seed_state(seed))
+      gen_method = method(:each_u_range)
+      case range
+      when nil
+        gen_method = method(:each_u)
+      when Numeric
+        @range = 0..range
+      when Range
+        @range = range
+      else
+        warn "Invalid range argument: #{range}"
+        gen_method = method(:each_u)
+      end
+      @generator = gen_method.call
+    end
+
+    ##
+    # Yields random values determined by the *range* argument of +initialize+.
+    # @return an +Enumerator+.
+    def each
+      @generator
+    end
+  end
+
+  private_constant
+  CLASS_RAND = Xoroshiro::Random.new
+
+  ##
+  # Module-level +rand+ method which can be used as a drop-in replacement
+  # for +Kernel::rand+.
+  #
+  # *Arguments*::
+  #   @param *range* [+nil+, +Range+, +Numeric+] as described in the
+  #   +Xoroshiro::Random.rand+ instance method.
+  #
+  # @return a random value corresponding to the +range+ specification.
+  #
+  def self.rand(range = nil)
+    CLASS_RAND.rand(range)
+  end
+end

data/sig/xoroshiro.rbs

@@ -0,0 +1,4 @@
+module Xoroshiro
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/xoroshiro.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/xoroshiro/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'xoroshiro'
+  spec.version = Xoroshiro::VERSION
+  spec.authors = ['Paul J Sanchez']
+  spec.email = ['pjs@alum.mit.edu']
+
+  spec.summary = 'Port of Xoroshiro256** PRNG to a ruby C-extension.'
+  # spec.description = "TODO: Write a longer description or delete this line."
+  spec.homepage = 'https://bitbucket.org/paul_j_sanchez/xoroshiro_ruby_gem'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata = {
+    'rubygems_mfa_required' => 'true',
+    'homepage_uri' => spec.homepage,
+    'documentation_uri' => 'https://www.rubydoc.info/gems/xoroshiro'
+  }
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.extensions = ['ext/xoroshiro/extconf.rb']
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: xoroshiro
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Paul J Sanchez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-05-22 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- pjs@alum.mit.edu
+executables:
+- xoroshiro_timings.rb
+extensions:
+- ext/xoroshiro/extconf.rb
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/xoroshiro_timings.rb
+- ext/xoroshiro/extconf.rb
+- ext/xoroshiro/xoroshiro.c
+- ext/xoroshiro/xoroshiro256.c
+- ext/xoroshiro/xoroshiro256.h
+- lib/xoroshiro.rb
+- lib/xoroshiro/version.rb
+- sig/xoroshiro.rbs
+- xoroshiro.gemspec
+homepage: https://bitbucket.org/paul_j_sanchez/xoroshiro_ruby_gem
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://bitbucket.org/paul_j_sanchez/xoroshiro_ruby_gem
+  documentation_uri: https://www.rubydoc.info/gems/xoroshiro
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.13
+signing_key:
+specification_version: 4
+summary: Port of Xoroshiro256** PRNG to a ruby C-extension.
+test_files: []